企业官网建设流程全解析

如果你打开终端，看到的还只是 git、node、npm 这三件套，那你可能还没意识到 2025 年的编码代理已经能替你跑完一整个“复现 bug → 定位根因 → 改代码 → 跑测试”的循环。上个月我接手一个几千行没有测试的 React 老项目，需求是两天内修一个只在特定浏览器出现的登录跳转问题，最终是 opencode 帮我把排查时间从大半天压缩到了四十分钟。这篇文章就围绕 opencode 写一份完整记录：从为什么选它、怎么安装，到模型接入、TUI 操作习惯，再到 Skills、LSP、Playwright 这些让 agent 真正“长手”的配置，最后是几个高频报错的排查链路。适合刚听说 opencode、准备替换手头 CLI 编码工具，或者已经装上但还在当普通聊天框用的朋友。

1. 为什么我最终把 opencode 留在了日常开发流里

1.1 终端里到底缺一个什么样的编码代理

在 Claude Code 把“终端 AI 编程助手”这个概念带火之后，我陆陆续续试过好几个同类工具。但真正用下来，问题很集中：要么强绑定某一家模型，要么只能在特定编辑器里用，要么配置体系黑盒到让人不敢在生产环境碰。我需要的不是又一个聊天窗口，而是一个开着终端就能用、能自由切换模型、能读项目代码、能调用外部工具，并且在关键节点上允许我随时插手干预的编码代理。opencode 恰好满足这些要求，而且它足够“轻”——不强迫你迁移到某个 IDE，不锁死模型，所有配置就是一份 JSON 文件。

1.2 opencode 和其他 CLI 编码代理的差异

先放一个我当时做选型对比时参考的表格，覆盖我实际用过的几个工具。需要说明的是这类工具迭代非常快，具体能力以各家官方仓库为准，但这个维度对选型依然有参考价值。

opencode 最让我舒服的一点是“模型中立”。同一个交互界面，前端任务我切到 Claude，后端重构我换成 GPT，本地小模型跑一些简单格式化也不心疼。你不用因为换模型而换工具，只需要在 TUI 里按一个斜杠命令。

1.3 它的定位：不是取代 IDE，而是接手“脏活累活”

我见过不少人把 opencode 当成“自动写完整项目”的魔法棒，然后失望而归。实际上这类代理最适合干的，是那些高度重复、上下文明确、又非常花时间的活：跨文件搜索定位、解释一段陌生代码、按团队规范生成 commit message、在报错栈里找根因。说得直白点，它像一个随时能叫来的实习生，你需要给它清晰的任务边界，也要在它给出方案后自己拍板。这篇文章里所有配置和技巧，都是围绕“让这个实习生更可靠”展开的。

2. 安装与第一跑：从 Windows 报错到终端里出现交互界面

2.1 三分钟安装：脚本、npm、brew 三条路怎么选

opencode 的安装方式有好几种，官方文档里写得很全，我实际验证过三条路。

macOS 用户建议直接用 Homebrew：

brew install sst/tap/opencode

Linux 或者想在 Docker 环境里快速试用的，可以用官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

Windows 用户我更推荐 npm 全局安装，方便处理 PATH：

npm install -g opencode-ai

安装完先验证版本：

opencode --version

有一点必须提醒：如果你用官方脚本，建议先 curl 下来看一眼内容再执行，这是一个基础但重要的安全意识，尤其是工作电脑。npm 和 brew 方式因为走包管理器，校验链相对完整，风险低很多。

2.2 Windows 上“无法将 opencode 识别为 cmdlet”的根因与修复

这是搜索热词里最经典的问题，几乎每个用 npm 装全局工具的 Windows 用户都会遇到一次。报错长这样：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

原因非常简单：npm 的全局安装目录不在你的 PATH 环境变量里。也就是说，opencode 这个可执行文件已经装好了，但 PowerShell 不知道去哪找它。

修复分两步。先看 npm 全局目录在哪：

npm config get prefix

绝大多数情况下会输出C:\Users\你的用户名\AppData\Roaming\npm。然后把%APPDATA%\npm加进用户 PATH。在 PowerShell 里可以这样操作：

[Environment]::SetEnvironmentVariable( "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";%APPDATA%\npm", "User" )

重新打开终端再执行opencode --version就能看到版本号了。这个问题本身不难，但很容易让人误以为安装失败，所以我把它单独拎出来讲清楚。

2.3 首次启动、登录与最小可用配置

安装完成后，在项目目录里直接输入opencode，会进入一个全屏 TUI 界面。第一次启动通常会提示你登录模型服务商，默认支持的包括 Anthropic、OpenAI、Google 等。如果你有官方 API key，直接在 TUI 里走登录流程即可；如果你用的是第三方兼容服务，可以先用Esc退出交互界面，手动写配置文件。

最小的可用配置长这样，放在~/.config/opencode/opencode.json（Windows 在%USERPROFILE%\.config\opencode\opencode.json）：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4" }

$schema字段是为了在编辑器里拿到补全和校验。写完之后重新进入 TUI，如果没有报错，就可以开始第一次对话了。建议先问一个非常简单的项目问题，比如“这个项目的技术栈是什么”，确认链路通畅后再干正事。

3. 模型接入是灵魂：三种配置路径与踩坑对照

3.1 官方模型服务商直连：API key 别写死在配置里

接官方模型时，很多人一开始会直接在 JSON 里写apiKey，这在小项目里能用，但一旦配置文件被同步到 git，就等于把 key 公开了。opencode 支持从环境变量读取密钥，写法是：

{ "provider": { "openai": { "options": { "apiKey": "{env:OPENAI_API_KEY}" } } } }

这样 key 只存在于你的 shell 环境变量或系统密钥管理工具中。我用的是 direnv 在项目目录里自动加载.env，效果不错。配置完成后，进入 TUI 输入/models，可以实时查看当前可用的模型列表并切换。

3.2 通过 OpenAI 兼容接口接入聚合订阅或本地模型

opencode 支持任何 OpenAI 兼容的服务端点，这是它接入生态最广的地方。包括本地 Ollama、各类聚合订阅服务（比如很多人提到的 opencode go），本质上都是给你一个baseURL和apiKey，然后你把它配成一个自定义 provider。

一个典型的配置结构如下：

{ "$schema": "https://opencode.ai/config.json", "provider": { "my-gateway": { "npm": "@ai-sdk/openai-compatible", "name": "My Gateway", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:MY_GATEWAY_API_KEY}" }, "models": { "my-model": { "name": "My Model" } } } }, "model": "my-gateway/my-model" }

逐个字段解释一下：

• npm字段告诉 opencode 用哪个 SDK 去连接这个服务。@ai-sdk/openai-compatible是通用的 OpenAI 兼容包，覆盖大多数网关。
• name是显示在界面里的供应商名字，方便你同时配多个 provider 时区分。
• options.baseURL是接口地址，一般网关都会在文档里给出完整的/v1路径。
• options.apiKey用{env:变量名}引用环境变量，避免明文。
• models里声明你在这个网关下要用的模型 ID，这个 ID 必须和网关侧定义的一致。

Ollama 本地模型也是一样的逻辑，baseURL改成http://localhost:11434/v1，model改成类似ollama/qwen2.5-coder。唯一要注意的是本地模型能力差异大，简单补全可以，复杂重构容易翻车。

3.3 不同模型在编码场景下的表现差异与选择建议

用了一段时间后，我个人的体感可以归纳成下面这张表：

这个表不是定论，因为模型迭代太快。我想强调的是：opencode 的价值恰恰在于它不绑定模型，你可以在同一个会话里切换对照，找到当前任务的最优解。不要因为某一个模型在某次任务表现差就否定整个工具，先/models换一个再说。

4. TUI 操作：真正提高生产力的终端会话习惯

4.1 斜杠命令和工作区模型：从 /new 到 /agents

opencode 的 TUI 看起来像一个聊天界面，但它更像一个“终端里的 IDE 工作台”。进入界面后直接输入/能看到全部斜杠命令，我高频使用的大概这几个：

• /new：开一个新会话，清空上下文。换任务一定要开新会话，不然旧上下文会影响判断。
• /models：实时切换模型。
• /agents：切换不同工作角色，比如普通编码员、代码审查员、脚本专家。
• /mcp：查看当前配置的 MCP 工具连接状态。
• /config：打开配置文件快速编辑。
• /share：生成当前会话的分享链接，方便团队协作时把上下文甩给同事。

这些命令本身不复杂，但“什么时候用”决定了效率。我的习惯是：每个任务开始前先/new，然后花十秒钟在第一条消息里把任务背景写清楚，而不是让 agent 从上一段对话里猜。

4.2 Agent 模式下如何交代任务、确认计划和审阅 diff

opencode 的 agent 模式不是让你把需求一句话丢过去然后等结果。我实践下来效率最高的沟通方式是“先规划，后执行，再审查”三步：

1. 先让 agent 读代码、解释现状，不要让它直接改。比如：“先不要改任何文件，告诉我登录跳转的逻辑链路是什么样的，涉及哪些文件。”
2. 拿到解释后，再给它明确任务边界：“修复跳转 404，只改路由相关代码，不要动样式。”
3. 执行完后，不要直接接受全部 diff。先让它列出每个文件的改动和原因，再自己过一遍关键文件。

每一步之间你是控制者，agent 是执行者。这听起来像废话，但很多人把 agent 当自动编程机用，结果 diff 一塌糊涂，最后反而花更多时间擦屁股。

4.3 把 TUI 嵌进日常 Git 工作流：提交信息、Code Review、重构

我现在的日常流程里，opencode 最常用的三个场景都在 Git 旁边。

生成 commit message 时，我会先暂存所有改动，然后跑：

opencode run "根据 git diff 生成符合 conventional commits 规范的提交信息"

非交互模式opencode run适合这种一次性的任务，不需要起一个完整 TUI。输出的提交信息直接复制用，比自己憋半天强。

Code Review 时，我会在 TUI 里粘贴git diff的输出，让 agent 从“可读性、边界条件、测试覆盖”三个角度给我挑毛病。相比专门的 review 机器人，这种方式上下文更准，因为它看到的就是你这一次改动。

重构时我习惯让 agent 给方案而不是直接上手：“如果要把这个组件拆成三个子组件，给出拆分方案和影响范围，先别改。”让它先讲思路，等于帮你做了一次设计评审。

5. Skills、LSP 与 Playwright：把 opencode 从聊天框变成开发环境

5.1 Skills 的目录结构与一个完整示例

Skills 是 opencode 最有价值的扩展机制，本质上是给 agent 预置一组“技能”。每个技能是一个目录，里面有一个SKILL.md描述文件，以及若干辅助脚本。

目录结构大概这样：

~/.config/opencode/skills/ └── code-review/ ├── SKILL.md └── review.sh

SKILL.md的内容类似：

--- name: code-review description: 对指定文件或 git diff 做代码审查，按严重程度输出问题列表 type: opencode --- 当用户要求审查代码时，执行以下步骤： 1. 读取目标文件或 git diff。 2. 按严重程度分类：阻断、重要、建议。 3. 输出修改建议和涉及文件路径。

当模型判断当前任务和这个技能匹配时，它会读取并遵循里面的流程。你可以把自己重复做的工作沉淀成技能，比如“写 Rust 单元测试”“按团队风格生成前端页面骨架”“修复 lint 报错”。这等于把团队规范从人脑搬到了配置里，新队员接手也不会跑偏。

5.2 挂上 LSP 后 agent 能看懂语法错误和类型问题

没有 LSP 的 agent 就像没有编译器的程序员，只能靠肉眼猜代码哪里有问题。opencode 支持挂 LSP（Language Server Protocol），让 agent 能实时拿到语法、类型、诊断信息。

以 Python 项目为例，在配置文件里加上：

{ "lsp": { "ruff": { "command": "ruff", "args": ["server"] } } }

前提是你已经安装了对应的 language server：

pip install ruff

前端项目可以挂 TypeScript 的 LSP，需要先安装typescript-language-server，然后类似地配置。挂上之后，agent 在改代码时会自己检查类型错误和格式问题，而不需要你把报错信息复制粘贴给它。这大大减少了来回沟通的轮次。

5.3 用 Playwright 跑前端回归：复现“只在前端出现的 bug”

搜索热词里有人问“opencode playwright 怎么测试前端 bug”，这确实是它特别能干的一类活。实现方式是通过 MCP 把 Playwright 接到 opencode 上，让 agent 能直接操作浏览器。

在 opencode 配置里加一个 MCP 服务：

{ "mcp": { "playwright": { "type": "local", "command": ["npx", "@playwright/mcp@latest"], "enabled": true } } }

配置完成后，进入 TUI 用/mcp确认 Playwright 处于连接状态。然后你可以直接对 agent 说：

“用 Playwright 打开 http://localhost:5173，进入登录页，输入测试账号和密码，点击登录按钮。如果出现跳转 404，把浏览器 console 的报错信息截给我，并定位到对应路由文件。”

agent 会调用 Playwright 工具完成打开页面、点击、截图、读取 console 等操作。这个能力特别适合那些“只在浏览器交互中复现”的问题，省去了你手动操作、肉眼观察、再翻译成文字描述给 agent 的冗长过程。要注意的一点是，本地开发服务器必须先启动，agent 不会替你启动项目。

6. VSCode / JetBrains 插件与接手老项目的实战姿势

6.1 官方插件怎么用：面板会话、@文件引用、右键上下文

虽然 TUI 已经很好用，但很多人在编辑器里的时间更长。opencode 官方提供了 VSCode 和 JetBrains 插件，装完之后可以在编辑器侧边栏里开一个会话面板。它和终端 TUI 共用同一套配置和会话能力，相当于在 IDE 里嵌了一个 agent 界面。

我使用插件的核心技巧有两个。

第一，用@引用文件。在插件会话里输入@src/components/Login.tsx，agent 就会把那个文件作为上下文读取，省去手动复制粘贴。这个操作在 TUI 里同样支持，但插件里因为能看到文件树，用起来更顺手。

第二，右键选中代码发送给 agent。选中一段代码，右键选择“发送到 opencode”，可以带着选区上下文提问，比如“这段代码有什么边界问题”。这比切到终端再描述上下文高效得多。

6.2 拿到一个陌生仓库后的四步阅读法

接手老项目是 opencode 的高频场景，我自己总结了一套“四步阅读法”，帮助 agent 快速理解仓库：

第一步，让 agent 通读项目入口文档和配置文件，输出项目地图：“请列出这个项目的技术栈、目录结构、主要模块和启动方式。”这一步能得到一张总览图。

第二步，让 agent 找到测试与构建命令：“这个项目怎么跑测试？我运行 npm test 报错，请分析原因。”先让工具链跑通，后续工作才有基础。

第三步，针对目标 bug 让 agent 做一个“最小复现”，而不是直接改。比如让它在代码里找出登录跳转的触发点，把相关路由链路画出来（文字链路就行），确认影响范围。

第四步，确认修复方案后，让 agent 分步执行，每步都要你确认。我通常会让它先给出改动清单，再动代码。

这套流程下来，即使是完全没接触过的仓库，也能在较短时间内梳理清楚。

6.3 团队的 opencode 规范：项目级配置、自定义 Agent、共享 Skills

一个人用好 opencode 不难，难的是整个团队用它还能保持代码一致性。我建议在项目根目录维护一份项目级配置，团队所有人都能共享。

项目级配置可以控制默认模型、LSP、MCP、Skills 等。比如团队统一用某个网关的模型做日常任务，就可以写进项目配置，避免每个人各配一套，导致行为不一致。还可以在项目里放一个AGENTS.md，像给新员工写 onboarding 文档一样，把项目约定、代码风格、构建命令写清楚，agent 在读取上下文时会优先参考这个文件。

Skills 也可以放进项目仓库，让所有成员共享。比如团队有一个“登录模块开发规范”的技能，放在.opencode/skills/目录下，任何人在这个项目里使用 opencode 时都能调用。这样团队的隐性知识就逐渐沉淀成了显式配置。

7. 高频报错的排查链路：从 cmdlet 识别失败到模型区域限制

7.1 “unexpected server error. check server logs”排查链路

这条报错在搜索热词里出现了，实际使用中也很常见。看到unexpected server error. check server logs时，千万别急着重装。这个错误绝大多数情况下是模型网关或 API 返回了异常，而不是 opencode 本身坏了。

我的排查顺序固定是这样：

第一步，在 TUI 里输入/status，看当前模型服务和连接状态。如果显示连接异常，大概率是网络或服务端问题。

第二步，看 opencode 自己的日志。日志目录在：

~/.local/share/opencode/log/

找到最新的日志文件，tail -n 50看具体的错误信息，通常能看到 HTTP 状态码或网关返回的具体错误。

第三步，用 curl 手动打一次同一个模型的 API，确认网关本身是否健康。命令大致是：

curl http://localhost:11434/v1/models

如果是远程网关，用它的地址。

第四步，把模型切换成另一个，确定问题是模型独有还是整个网关都有。这一步能快速缩小范围。

如果你用的是本地模型服务，还要额外检查服务是否真的在运行、端口是否被占用、显存是否足够。很多时候报错并不是代理工具的问题，而是它背后的模型服务挂了。

7.2 “this model is not available in your country” 的正确处理姿势

另一个高频报错是this model is not available in your country，字面意思很清楚：模型服务商对某些区域有授权限制，你在当前区域没有使用该模型的权限。这个限制是模型服务商的策略，不是 opencode 的问题，也不该试图绕过。

正确的处理姿势有三种：

一是换一个在当前区域可用的模型。opencode 是模型中立的，/models切一下就行，这个报错也可以看成它在提醒你“别在这个任务上死磕一个模型”。

二是如果你是直接使用官方模型服务，去查阅该服务商的可用区域和条款，确认自己的账号是否满足条件。

三是如果你是经第三方聚合服务接入的，直接找客服或文档确认这个模型在你所在区域是否有授权，让他们提供一个可用的替代模型 ID。

记住一点：出现这个报错时，openccode 本身的配置通常没问题，不要瞎改 baseURL 或者换 key，那样解决不了授权层面的问题。

7.3 日志、状态检查与最小复现模板

排查任何工具问题，我都推荐一套“最小复现”思路：先把配置砍到只剩一个模型一个 provider，再让问题稳定复现，而不是带着一堆自定义技能和 LSP 去找原因。

具体做法是：临时把配置文件的lsp、mcp、skills相关配置全部注释掉，只保留一个官方模型。如果问题消失，再逐项加回来，用二分法定位。多数情况下你会发现，问题出在某个 MCP 服务没启动或者某个自定义模型的 ID 写错了，而不是 opencode 本身。

这个思路同样适用于写 bug 反馈。如果你要向官方仓库提 issue，附上最小配置、复现步骤、日志文件，维护者几分钟内就能定位。这比贴一张完整配置截图有用得多。

8. 用一个真实修复任务完整走一遍 opencode 的闭环

8.1 任务背景与 agent 计划

我在开头提的那个登录跳转 404 的 React 项目，用 opencode 的完整流程大概是这样的。先说背景：项目使用 React Router，登录成功后从Login.tsx跳转到/dashboard，但在某个浏览器版本下用户会落到 404 页面。

我进入项目目录，启动 opencode，先输入：

请先不要改代码。阅读 src 目录结构，找到登录跳转相关代码，解释完整链路。

agent 通过目录扫描和文件读取，很快定位到src/pages/Login.tsx里的跳转逻辑，并给出了链路说明：

Login.tsx 中 handleLogin 成功后调用 navigate('/dashboard')， 路由配置在 src/App.tsx 中， /dashboard 对应 DashboardPage， 但 DashboardPage 外层被 AuthGuard 包裹，AuthGuard 里做了重定向。

它还指出，404 更可能出现在 AuthGuard 的判空逻辑里，而不是 React Router 本身。

8.2 执行过程中的工具调用与人工介入

拿到解释后，我给出了明确指令：

修复 AuthGuard 中导致 Dashboard 页面重定向到 404 的问题。只改鉴权逻辑，不要动 UI 样式。改完跑一次相关测试。

agent 开始修改代码，并使用 LSP 检查类型错误。修改完成后，它尝试运行npm test，发现 test 脚本没有覆盖 AuthGuard 的分支，于是主动建议补充一个测试用例。我同意后，它生成了测试用例骨架，我补了两个关键输入，测试通过。

整个过程里，我真正介入的节点只有两个：一次是确认修复方向，一次是补充测试输入。其他搜索、读取、修改、运行测试的动作，都在终端里自动完成了。

如果想要更稳，可以在这中间加一轮“review”操作：让 agent 先把 diff 列出来，我确认每个文件改动合理后再让它合并。对于核心业务代码，我强烈建议保留这一步。

8.3 最终结果与我的使用建议

那次修复最终在四十分钟内完成，大部分时间花在确认业务逻辑上，而不是翻代码。之后我养成了一个固定习惯：任何陌生项目的第一课，都是让 opencode 给我讲一遍“这个项目的骨架”，而不是自己从 package.json 开始手撕。

根据我的经验，opencode 的最佳使用姿势可以总结成三条：任务拆小，每步确认；让 agent 先解释再动手；把重复工作沉淀成 Skills。如果你能做到这三点，它就不再是一个偶尔拿来生成代码的玩具，而是一个真正能替你处理脏活的终端搭档。

如果你刚装好 opencode，我建议你今天就可以找一个“查 log、修 bug、补测试”的小任务完整走一遍流程，体验一次从报错到验证通过的全过程。工具本身不复杂，复杂的是你愿不愿意把一部分工作方式交给它。