企业官网建设流程全解析

opencode 最近在开发者圈子里讨论度确实高，尤其是命令行 AI 编程助手这个赛道，Claude Code、Codex CLI 之后，opencode 算是热度起来得比较快的一个。我自己的感受是，它把"开源、可配置、模型自由"这几个点踩得很准，加上 Skills 机制和 IDE 插件生态补得也快，已经不是那种"尝鲜玩两天就删"的项目了。这篇就围绕 opencode 的安装、配置、模型接入、Skills 开发、插件使用和实战场景，把我实际跑过的流程和踩过的坑都整理出来。

1. opencode 到底是什么：定位与核心能力拆解

1.1 和 Claude Code、Codex CLI 站在一起的命令行 Agent

opencode 本质上是跑在终端里的 AI 编程代理（Agent），你给它一个任务，比如"修复登录页面的样式问题"、"给这个接口补单元测试"，它会自己读代码、改文件、跑命令、看结果，然后迭代直到任务完成。这个模式大家应该不陌生，Claude Code 是 Anthropic 官方的，Codex CLI 是 OpenAI 的，而 opencode 是开源社区的项目，主打一个"模型无关"。

所谓"模型无关"，意思是它不像 Claude Code 那样深度绑定 Claude 模型，而是通过 OpenAI SDK 兼容的接口标准来对接各种模型。也就是说，你配置文件里指向哪个模型的 API，它就调哪个模型来干活。这个自由度对国内开发者尤其友好，因为你完全可以接本地跑的 Ollama、LM Studio，也可以用有合规服务渠道的 OpenAI 兼容网关，不强制你必须用某一家。

我最早注意到 opencode，是因为它的仓库里明确写了支持自定义 Agent、Skills、Memory，以及 VSCode 和 JetBrains 的插件。这几个词放在一起，说明它不是一个"只能聊天改代码"的玩具，而是奔着"可编程的 AI 开发助手"去的。实际用下来，它确实做到了：终端里跑opencode，进入交互界面，可以切换模式、调用工具、加载技能，体验上跟 Claude Code 的交互逻辑很接近，但配置自由度高很多。

1.2 真正让我留下来用的几个理由

先说结论：如果你已经在用 Claude Code 或 Codex CLI，并且用得挺顺手，那 opencode 不一定需要换；但如果你是"既要 Claude Code 的体验，又不想被模型绑定，还想在 IDEA 里直接用"的人，opencode 值得认真试试。

我留下来用的理由有三个：

第一个是 Skills 机制。你可以给 opencode 写技能文件，定义一组 prompt 和工具调用逻辑，它会在处理相关任务时自动加载。这有点像给 Agent 装"外挂模块"，比如我写了一个"前端项目代码审查"的 Skill，它会在启动审查任务时自动带上我在技能文件里写的检查清单、项目结构约定、常见坑位说明，出来的结果明显比裸 prompt 要专业。

第二个是对接旧项目的"接盘能力"。opencode 支持读项目的 AGENTS.md（类似 Claude Code 的 CLAUDE.md），你可以在里面写清楚项目的技术栈、目录约定、启动命令、测试命令，Agent 干起活来就不会瞎猜。这个对"用 AI 接手别人遗留代码"的场景太关键了。

第三个是插件生态跟进及时。VSCode 插件、JetBrains 插件、桌面版都已经有了，虽然成熟度还在爬坡，但基本流程已经能跑通。我之前在 IDEA 里主力用，体验比预期的好。

2. 安装 opencode：Node 版和 Go 版怎么选，以及最常见的安装报错怎么破

2.1 两种安装方式与适合人群

opencode 目前主流的安装方式有两条线：一条是 Node.js / npm 路线，一条是 Go 路线。这也是社区里讨论"opencode"和"opencode go"时最常见的分歧点。

npm 安装的命令很简单：

npm install -g opencode-ai

装完之后在终端里输入opencode就能启动。npm 版的优势是安装快、跟前端生态天然亲近，如果你机器上本来就有 Node.js 环境（大概率有），这是最省事的路子。

Go 版则是通过 Go 工具链安装：

go install github.com/sst/opencode@latest

Go 版的好处是编译成单一二进制，启动速度快，内存占用相对低，而且不依赖 Node 运行时。但有一个隐藏问题：Go 版需要把$GOPATH/bin（默认是~/go/bin）加到系统 PATH 里，否则装完你也找不到命令。社区里很多人抱怨"opencode go 装完用不了"，八成就是这一步没做。

我的建议是：日常开发用 npm 版就行，别折腾；如果你有洁癖，不想在机器上装一堆 Node 全局包，或者你在用 nvm 且频繁切换 Node 版本导致全局命令失效，那就用 Go 版，省心。

2.2 PowerShell 报"无法识别 opencode"的解决思路

Windows 上非常高频的一个报错，就是你在 PowerShell 里敲opencode，它回你一句：

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

这个报错看着吓人，其实就一个原因：命令所在的目录没有加到 PATH 环境变量里。npm 全局包的安装目录默认是%APPDATA%\npm（也就是C:\Users\你的用户名\AppData\Roaming\npm），PowerShell 找不到这个路径，自然就识别不了。

解决办法分两步：

第一步，确认 opencode 确实装上了，执行：

npm list -g --depth=0

看列表里有没有opencode-ai。如果有，说明装成功了，只是 PATH 的问题。

第二步，把 npm 全局路径加进用户 PATH。PowerShell 里执行：

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

然后重开一个终端窗口，再跑opencode --version，能输出版本号就说明通了。如果还是不行，就去"系统设置 -> 系统 -> 关于 -> 高级系统设置 -> 环境变量"，手动把%APPDATA%\npm追加到 Path 里。注意，改完了必须新开终端，因为已经打开的窗口不会刷新环境变量。

2.3 启动报"unexpected server error"的排查路径

另一个高频报错是启动时直接给你一句：

opencode error: unexpected server error. check server logs

这个问题我碰到过两次，第一次是在公司电脑上，第二次是我自己把配置文件里模型网关的 Base URL 写错了。排查思路其实跟普通后端服务调试差不多，按三层来查：

第一层，查配置。opencode 的配置文件在用户目录下，路径是~/.config/opencode/opencode.json（Windows 在C:\Users\你的用户名\.config\opencode\opencode.json）。打开看里面的 provider 配置，重点检查 baseURL 有没有写错、API Key 有没有填对、模型名跟服务商提供的是不是一致。很多"server error"其实是 401 或 404，只是 opencode 没把底层状态码透传出来，统一包装成了这个提示。

第二层，查网络。如果你用的是远程模型 API，确认当前网络能正常访问对应的服务地址。可以用 curl 测一下接口通不通：

curl -X POST https://你的模型API地址/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"你的模型名","messages":[{"role":"user","content":"hi"}]}'

能返回正常 JSON 就说明网络和密钥没问题，问题就在 opencode 的配置写法上。

第三层，查日志。opencode 会在~/.local/share/opencode/log/目录下写日志（Windows 在%LOCALAPPDATA%\opencode\log）。报错的时候去看最新的日志文件，里面一般会打印出真正的错误原因，比如401 Unauthorized还是model not found，定位准确很多。

3. 模型接入与免费方案：配置文件里到底该写什么

3.1 opencode.json 的基础结构

opencode 的模型接入思路是"一个 provider 一套配置"，所有 provider 都走 OpenAI SDK 兼容协议。所以你最需要搞懂的就是opencode.json里的 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": "你的密钥" }, "models": { "my-model": { "name": "My Model" } } } } }

这里npm字段指定的是模型 SDK 包，opencode 内部基于 Vercel 的 AI SDK，所以@ai-sdk/openai-compatible就是用来对接任何 OpenAI 兼容接口的。options.baseURL填服务商的接口地址，options.apiKey填密钥，models下面列出你要用的模型名。

如果你用的是 Anthropic 官方 API，也可以直接配：

{ "provider": { "anthropic": { "options": { "apiKey": "你的Anthropic密钥" }, "models": { "claude-sonnet-4-20250514": {} } } } }

opencode 内置了 anthropic 这个 provider 类型，不需要额外指定npm字段。平时用opencode进入交互界面后，按快捷键或输入命令切换模型，就能在配置好的多个模型之间跳。

3.2 免费模型怎么接：本地模型与合规第三方接口

热词里"opencode 免费模型"的搜索量很高，可见这是刚需。免费模型我实际跑过两条路线，都能用，但体验差异很大。

第一条是本地模型。用 Ollama 跑一个代码能力还行的模型，比如qwen2.5-coder:14b（看你机器配置，7b 更轻、32b 更聪明），然后 opencode 里配 Ollama provider：

{ "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen Coder 14B" } } } } }

本地模型的好处是不要钱、数据不出机器，坏处是对硬件要求不低，14B 模型在 16G 内存的 Mac 上跑得动但速度一般，在纯 CPU 的 Windows 老机器上基本没法用。我的实测经验是：本地模型适合做代码解释、简单重构、单元测试这类任务，让它复杂跨文件改代码，效果跟云端强模型差距明显。

第二条是用一些提供免费额度的 OpenAI 兼容 API 服务。这块我不展开推荐具体商家，只提醒几个判断标准：接口稳定不稳定、免费额度够不够日常用、模型名跟文档是否一致、有没有并发限制。配置方式跟 3.1 里的一模一样，把 baseURL 和 apiKey 换成对应服务的信息即可。

你可以先用curl测通再写进配置，别一上来就在 opencode 里折腾。我踩过的坑是：某服务商的接口文档写的是完整地址，但实际得去掉/v1后面那段，导致我一直 404。

3.3 配合 CC Switch 做模型统一管理

热词里出现了"opencode go 需要配合 cc switch"、"ccswitch 配置 opencode"，这里说清楚是怎么回事。

CC Switch 是一个开源的模型网关切换工具，最早是为了解决 Claude Code 里快速切换不同 API 服务商的问题。它在你本地起一个代理服务，统一暴露一个 OpenAI 兼容接口（默认端口一般是 127.0.0.1:7897 或类似），你在它的面板里配置好各个服务商，然后所有 AI 工具都指向这个本地地址就行，不用每个工具单独改 baseURL 和 apiKey。

用 CC Switch 配合 opencode 的配置长这样：

{ "provider": { "cc-switch": { "npm": "@ai-sdk/openai-compatible", "name": "CC Switch", "options": { "baseURL": "http://127.0.0.1:7897/v1", "apiKey": "sk-local" }, "models": { "default": {} } } } }

这样做的好处是：你想切模型服务商，只需要在 CC Switch 面板里点一下，opencode 不用动。而且不止 opencode，Claude Code、Cline、Cherry Studio 等工具都能共用这一个网关。对经常折腾模型的人来说，这确实是省事方案。

关键词"opencode go 需要配合 cc switch"，我的理解是 Go 版 opencode 在模型切换体验上不如 npm 版顺畅，用 CC Switch 统一管理可以补上这个短板。实际用下来，npm 版配合 CC Switch 也挺好，所以这条建议对两个版本都适用。

4. Skills、Memory 与自主模式：把 opencode 调教成懂你项目的 Agent

4.1 Skills 机制与 AGENTS.md

opencode 的 Skills 机制，是我觉得它区别于其他终端 Agent 的最大亮点。简单说，Skills 就是一组"预置专家知识"，你在里面声明"当你做某类任务时，必须遵守这些规则、参考这些资料、按这个流程执行"，Agent 在匹配到对应场景时会自动加载。

创建 Skill 的方式很直接。在项目的.opencode/skills/目录下建一个子目录，里面放一个SKILL.md文件，写上技能名、适用场景、指令模板就行。举个例子，我写了一个"后端 API 代码审查"技能：

--- name: backend-review description: 适用于后端 API 接口代码审查，重点检查参数校验、鉴权、异常处理、SQL 注入风险 --- 当执行后端代码审查任务时，必须按以下清单逐项检查： 1. 所有对外接口是否有参数边界校验 2. 涉及用户数据操作时是否校验权限 3. 异常是否被统一处理，避免堆栈信息直接暴露 4. SQL 拼接是否使用参数化查询，禁止拼字符串 5. 响应体是否符合团队的统一包装格式

配置好之后，在 opencode 交互界面里输入开启技能的命令，比如/skills或指定 skill 名称，它会加载这些规则再开始干活。你也可以在AGENTS.md里写项目级别的通用约定，比如目录结构说明、代码风格规范、启动和测试命令，这样 Agent 在理解项目时不至于太没谱。

我的实际感受是，市值越大的项目，Skill 的收益越明显。你写一个技能花 10 分钟，但之后每轮对话都在帮你校准方向，省下的返工时间远不止 10 分钟。

4.2 Memory 记忆功能怎么用

opencode 的 Memory 机制解决的是"AI 记不住事"的问题。默认情况下，每次会话都是独立的，Agent 不会记得你上次做过什么偏好设置。开启 Memory 后，它会把你明确要求记住的关键信息写入一个记忆文件，之后的会话自动读取。

使用方式比较顺手。你在对话里告诉它"记住我们这个项目的测试命令是pnpm test:unit"，它会把这条记到 memory 文件里。下次新开会话，你直接说"跑一下测试"，它知道该用什么命令，不用重新解释。也可以手动打开记忆文件直接编辑，相当于给 Agent 写备忘。

我在团队项目里常用的做法是，把下面几类信息写进 Memory：

• 项目的启动命令、测试命令、构建命令
• 团队约定的命名规范（组件用大驼峰、接口文件用api/xxx.ts）
• 当前迭代的重点模块和已知技术债
• 用户偏好（比如"不要自动格式化代码"、"改动前后端交互必须先确认接口定义"）

但要注意，Memory 不是万能的，它只对 opencode 自己有效，不会同步给其他工具，而且记忆文件如果堆太多无效信息，反而会干扰 Agent 的注意力。定期清理是必要的。

4.3 模式切换：Plan、Agent、Autonomous

opencode 的交互模式主要分三种，理解它们的区别能帮你少走弯路。

Plan 模式（规划模式）下，Agent 只做分析和方案设计，不改任何文件。适合用来做代码审查、架构梳理、风险评估。比如你接了一个旧项目，先切到 Plan 模式让它读一遍代码，输出结构梳理和改造建议，确认方向没问题再进入执行阶段。

Agent 模式（代理模式）是默认模式，也是最常用的。Agent 会自主地读文件、改代码、跑命令，一步步完成任务。这个模式下你要做的就是给清楚任务描述，然后观察它的输出，必要时打断纠正。

Autonomous 模式（自主模式）是"放手让人干"的模式，Agent 会连续执行多步操作，直到任务完成为止。这个模式效率最高，但对任务的清晰度要求也最高。我一般是在改动范围明确、测试链路清晰的时候才用，比如"把所有接口返回的code字段类型从 string 改成 number，改完跑一遍全部单测"。

实际用下来，我养成的工作习惯是：Plan 模式看方案，Agent 模式做常规开发，Autonomous 模式处理机械性的批量修改。别一上来就 Autonomous，让它自主跑，跑偏了反而更难拉回来。

5. IDE 插件与桌面版：从终端到鼠标的体验补齐

5.1 VSCode 插件

opencode 的 VSCode 插件，让不习惯纯终端操作的人也能用上这套 Agent 能力。插件安装后，左侧边栏会出现一个 opencode 面板，可以直接选模型、发起对话、查看 Agent 的实时操作。它跟终端的会话是打通的，你在终端里开了一个会话，切到 VSCode 插件也能看到同一个上下文。

我比较常用的场景是：在主编辑器里选中一段代码，右键选择发送给 opencode，让它解释或重构这段代码。这样不用切窗口，省事不少。插件还支持在代码文件里直接预览 Agent 的 diff 修改，确认无误再接受，这个比终端里看纯文本 diff 舒服。

不过说实话，VSCode 插件目前的完成度还没有到"丝滑"的程度，偶尔会出现连接会话失败、面板加载慢的问题，重载窗口基本能解决。用来日常辅助开发没毛病，但如果你指望它能完全替代 JetBrains 自家插件的体验，还需要再观望几个版本。

5.2 JetBrains IDEA 插件

IDEA 插件我用的时间更长一些，因为我的主力 IDE 就是 IntelliJ IDEA。在插件市场搜 opencode 就能找到，安装后右侧会增加一个 opencode 工具窗口。交互逻辑跟 VSCode 版本类似，但针对 JetBrains 生态做了一些适配，比如可以直接读取项目模块、运行配置、测试类的上下文。

一个很实用的功能是，在 IDEA 里你可以直接在方法名上右键，让 opencode 生成这个方法的单元测试。它会自动读取方法签名、依赖注入情况、项目里已有的测试规范，生成的单测基本能直接跑通，手动补几个断言边界就行。

IDEA 插件的坑主要是：大项目里 Agent 扫描文件时，会把 IDE 的索引任务挤占掉，导致 IDE 变卡。我一般会在 Agent 跑任务的时候把"自动构建"关掉，等它改完代码再手动触发构建，体验会好很多。

5.3 桌面版

opencode 桌面版（Desktop）也出现了，适合完全不想碰命令行的人使用。桌面版本质上是把终端 Agent 包装成了 GUI 应用，左侧是会话列表，中间是对话窗口，右边能看到 Agent 的文件操作记录和命令输出。它内置了终端模拟器，Agent 执行命令的过程是可视化的，相当于把 opencode 的终端界面搬到了 App 里。

桌面版目前比较适合做"学习观摩"：你可以清楚地看到 Agent 每一步在做什么——读了哪个文件、改了哪一行、跑了什么命令、报了什么错。这个对理解 Agent 的工作方式很有帮助，也可以当调试工具用。真正常态化开发，我个人还是推荐终端版或 IDE 插件，效率和集成度更高。

6. 实战：让 opencode 接手开发项目，并用 Playwright 测前端 Bug

6.1 接手旧项目的工作流

"用 opencode 接手开发项目"是热词里让我觉得最有价值的一条，因为这确实是 AI Agent 最擅长的场景。我拿一个真实例子来走一遍流程。

项目是一个内部管理系统，前后端分离，前端 Vue 3 + TypeScript，后端 Java Spring Boot，仓库代码量大概 20 万行。我接手时的需求是"修复用户管理页面中，角色分配保存后接口返回成功但页面数据未刷新"的 Bug。

第一步，在项目根目录写一个AGENTS.md，把关键信息塞进去：

# 项目约定 - 前端目录：frontend/，使用 pnpm 安装依赖，启动命令 `pnpm dev` - 后端目录：backend/，使用 Maven，启动命令 `mvn spring-boot:run` - 接口定义：前端调用后端接口统一走 frontend/src/api/ 下的模块，禁止直接写 URL - 测试：前端单测用 Vitest，后端单测用 JUnit - 代码风格：前端组件命名大驼峰，后端类名大驼峰，方法名小驼峰

第二步，启动 opencode，先切到 Plan 模式，让它分析问题定位：

opencode --model 你的模型名

在交互界面里输入：

项目里有一个Bug：用户管理页面中，角色分配保存后接口返回成功，但页面上的角色列表没有刷新。请先定位可能的代码路径，不要改任何文件，输出分析结果。

Plan 模式下它会读相关代码，找到保存角色和刷新列表的调用链，指出问题可能出在哪里。这个环节我拿到的是一个比较准的定位报告，大概指向"保存角色成功后，前端没有重新请求用户列表接口，而是直接操作了本地数组但数据源没变"。

第三步，确认定位没问题，切到 Agent 模式，让它修复：

定位方向我认可。请修复这个问题。要求：保存角色成功后，重新从后端获取最新的用户列表并刷新页面数据。改完后跑前端单测验证。

它会自动找到用户列表接口的定义、角色保存的响应处理逻辑、页面数据绑定的位置，一次性把修改做完，然后跑单测。中途如果遇到测试用例失败，它会自己看失败原因再迭代。整个过程我基本不用插手，最后它把改动 diff 列出来，我 review 一遍确认没问题。

这个工作流的关键在于，第一步的AGENTS.md一定要写好。没有项目约定的情况下，Agent 会猜测试命令、猜目录结构，废掉很多时间。

6.2 用 Playwright 复现前端 Bug

热词里"opencode playwright 怎么测试前端 bug"指向的是 opencode 结合 Playwright（自动化浏览器测试工具）来做前端 Bug 复现和验证。这个玩法在 AI 编程里越来越常见，因为让 Agent 自己"打开页面 -> 操作 -> 截图 -> 看现象"比纯静态代码分析更接近真实用户体验。

opencode 支持通过 MCP（Model Context Protocol）接入 Playwright。所谓 MCP，你可以理解为给 Agent 装了一个"浏览器操作手柄"，Agent 可以通过标准化的工具接口去控制无头浏览器，执行点击、输入、截图、抓取控制台日志等操作。

接入步骤大致是：先全局安装 Playwright：

npm install -g playwright npx playwright install

然后在 opencode 的配置里启用 Playwright MCP（具体配置项看对应版本的文档，一般是在 MCP servers 配置块里加一条指向本地 Playwright 服务的记录）。

配置好之后，你可以给 opencode 一条这样的任务：

用 Playwright 访问 http://localhost:5173，登录后进入用户管理页面，点击某个用户的"编辑角色"按钮，选择一个新的角色并点击保存，等待接口响应后，检查页面上的角色列表是否更新。如果没更新，截图并把控制台的错误信息贴出来。

Agent 会自己开浏览器、执行每一步操作、等接口返回，然后告诉你页面上实际发生了什么。这比传统方式（人肉点一遍 + 手动看 Network 面板）快太多了，尤其适合回归测试。

我在实战中发现一个坑：如果页面需要登录态，而 opencode 用的浏览器上下文是干净的（没有 cookie），第一次访问会跳转到登录页，Agent 自己不一定能反应得过来。解决办法是，先把登录这一步也写进任务描述里，或者给 Playwright 配置带上已登录的存储状态，这样 Agent 跑起来不用每次都从登录开始。

这个玩法我第一次跑通的时候还挺震撼的——Agent 不只是"写代码"，它真的能像一个测试工程师一样，打开浏览器、点按钮、看现象、报问题。虽然目前它处理复杂交互（比如拖拽、上传文件）偶尔还是会卡壳，但对付绝大多数前端 Bug 复现是完全够用的。

7. 常见问题速查表

把前面提到的和没展开的高频问题整理成一张表，方便你遇到事了直接查。

其他几个零碎的高频问题：

"opencode hy3-free 下线了吗"——这类免费模型是否可用，变化很快，判断方式就是实际去服务商的接口文档看一眼，或者直接 curl 测一下，比看任何二手消息都准。

"opencode 2.0"——版本升级后交互界面和配置结构可能有变化，升级前先看官方 changelog，我一般会备份一份旧版配置再动。

"opencode codex claude code 哪个 agent 好用"——这个问题没有标准答案，我的经验是：模型绑定少就选 opencode，深度用 Claude 就选 Claude Code，跟 GitHub 生态贴得紧就选 Codex CLI。工具是手段，不是目的。

最后再分享一个我个人的小习惯：每次把 opencode 接入一个新项目，我都会先花 15 分钟把 AGENTS.md 写扎实，再把项目根目录的常用命令整理成一条 prompt 模板存着。这套动作做完，后面所有和 Agent 的协作效率都会上一个台阶。工具好不好用，一半看工具本身，一半看你给它喂了什么上下文，这个道理放在 opencode 上尤其成立。