opencode 最近在开发者圈子里讨论度确实高尤其是命令行 AI 编程助手这个赛道Claude Code、Codex CLI 之后opencode 算是热度起来得比较快的一个。我自己的感受是它把开源、可配置、模型自由这几个点踩得很准加上 Skills 机制和 IDE 插件生态补得也快已经不是那种尝鲜玩两天就删的项目了。这篇就围绕 opencode 的安装、配置、模型接入、Skills 开发、插件使用和实战场景把我实际跑过的流程和踩过的坑都整理出来。1. opencode 到底是什么定位与核心能力拆解1.1 和 Claude Code、Codex CLI 站在一起的命令行 Agentopencode 本质上是跑在终端里的 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. 安装 opencodeNode 版和 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/opencodelatestGo 版的好处是编译成单一二进制启动速度快内存占用相对低而且不依赖 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\npmPowerShell 找不到这个路径自然就识别不了。解决办法分两步第一步确认 opencode 确实装上了执行npm list -g --depth0看列表里有没有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.jsonWindows 在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 不用动。而且不止 opencodeClaude Code、Cline、Cherry Studio 等工具都能共用这一个网关。对经常折腾模型的人来说这确实是省事方案。关键词opencode go 需要配合 cc switch我的理解是 Go 版 opencode 在模型切换体验上不如 npm 版顺畅用 CC Switch 统一管理可以补上这个短板。实际用下来npm 版配合 CC Switch 也挺好所以这条建议对两个版本都适用。4. Skills、Memory 与自主模式把 opencode 调教成懂你项目的 Agent4.1 Skills 机制与 AGENTS.mdopencode 的 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、Autonomousopencode 的交互模式主要分三种理解它们的区别能帮你少走弯路。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 测前端 Bug6.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 支持通过 MCPModel Context Protocol接入 Playwright。所谓 MCP你可以理解为给 Agent 装了一个浏览器操作手柄Agent 可以通过标准化的工具接口去控制无头浏览器执行点击、输入、截图、抓取控制台日志等操作。接入步骤大致是先全局安装 Playwrightnpm 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. 常见问题速查表把前面提到的和没展开的高频问题整理成一张表方便你遇到事了直接查。问题现象可能原因解决思路PowerShell 提示无法识别 opencodenpm 全局目录不在 PATH把%APPDATA%\npm加到用户 PATH重开终端启动报unexpected server error模型网关地址/密钥/模型名配置错误按配置 - 网络 - 日志顺序排查Go 版装完找不到命令$GOPATH/bin不在 PATH把~/go/bin加入 PATH重新登录 shell模型响应特别慢模型本身推理慢或网络不稳定换小模型或检查网关链路Agent 改代码乱改无关文件缺少项目约定文件上下文不明确写 AGENTS.md明确改动范围VSCode 插件连不上会话插件与终端版本不匹配升级到同版本重载窗口前端页面自动化测试总是跳登录浏览器上下文没有登录态任务描述里加登录步骤或提前配置存储状态免费模型效果差改不明白代码小模型上下文理解能力有限调整任务粒度拆分成具体子任务其他几个零碎的高频问题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 上尤其成立。