opencode 这阵子热度确实高尤其是 2.x 版本发布之后我身边不少之前死磕 Claude Code 的人都转过来试它。说白了opencode 就是一个跑在终端里的开源 AI 编程 Agent和你熟悉的 Claude Code、Codex CLI 属于同一类东西但它有两个很不一样的点模型不锁死配置全透明。你可以把它理解成“自带调度器的 AI 开发助理”帮你在项目里读代码、改文件、跑命令、查日志甚至驱动浏览器复现前端 bug。这篇文章我从安装、配置、模型接入一直写到 skills、LSP、Playwright 这些进阶玩法最后再把我踩过的坑按报错排一遍。不管你是刚听说 opencode 想尝鲜还是已经装上但卡在某个模型报错里都可以照着往下看。1. opencode 到底是个什么东西凭什么火1.1 一个不绑死模型的终端 AI 编码助手opencode 最早是 SST 团队开源出来的后面逐渐演变成一个独立项目现在由专门团队在维护代码一直保持开源。它做的事情和 Claude Code、Codex CLI 很像你在终端里启动它它拿到你的自然语言指令后会自己去读工作区里的文件、搜索代码上下文、调用对应的模型接口、生成修改方案然后帮你执行命令、写文件、跑测试整个过程里你只需要在关键节点确认一下。它最吸引我的一点是“模型中立”。Claude Code 偏向 Anthropic 系模型Codex CLI 默认圈在 OpenAI 生态里而 opencode 自己只做调度和工具链模型层面完全交给配置决定。你可以填一个官方 Anthropic key也可以填 OpenAI 兼容端点还能接第三方的网关订阅服务。这意味着什么意味着同一套 Agent 工具链你能在不同模型之间横跳白天用强模型写核心逻辑晚上用便宜的模型跑批量任务甚至拿它当多模型测评的壳子用。这在团队里尤其划算不用因为换模型就换工具。1.2 和 Claude Code、Codex CLI、Pi 的横向对比很多人第一次接触 opencode 都会问它和已有的几个 Agent 到底差在哪我把自己实际用下来的感受整理成了表格你可以直接对照着选维度opencodeClaude CodeCodex CLIPi开源状态开源社区活跃闭源但免费可用开源偏实验开源社区项目模型绑定不绑定全凭配置默认 Claude 系默认 OpenAI 系不绑定配置方式opencode.json透明可版本化管理命令和少数设置项配置文件较简配置文件Skills支持可自定义可分享支持 Agent Skills正在补齐有限支持LSP原生支持有限有限/实验视实现而定浏览器调试通过 Playwright MCP 打通也可接 MCP较少见较少见上手成本中配置好后很顺低开箱即用中中从这个表能看出来opencode 最大的优势是“可塑性”它对周边工具链的接入方式更开放skills、LSP、MCP 这些概念它都原生支持。代价就是你需要花一点时间把配置跑通但跑通之后的收益是实打实的尤其适合喜欢自己掌控流程的开发者。1.3 哪些人适合现在开始用 opencode我推荐三类人尝试。第一类是手上有多家模型 API不想被单一厂商绑定的开发者opencode 就是你统一入口。第二类是天天跟前端 bug 打交道的人它配合 Playwright 能自己打开页面复现问题这一段后面会详细写。第三类是团队里希望沉淀开发规范的人你可以在项目里放一份 AGENTS.md 和一批 skills新同事接手项目时可以让 Agent 直接按团队套路干活。反过来如果你完全不想碰配置文件、只想无脑跑通一个模型那 Claude Code 的开箱体验可能更适合你。opencode 的定制能力是把双刃剑配置越灵活前期的学习成本越高。但只要过了这道坎后面基本是一劳永逸。2. 安装、上线与初始配置2.1 三种安装方式总有一种适合你opencode 的安装方式很多官方推荐的是直接跑安装脚本一条命令搞定curl -fsSL https://opencode.ai/install | bash这段脚本会检测你的系统下载对应的二进制然后自动放进用户目录。如果你在 macOS 上并且装了 Homebrew也可以这样brew install sst/tap/opencode用 Node 生态的人还能走 npmnpm install -g opencode-ai顺手说一句如果你平时用 Go 开发也可以直接go install github.com/sst/opencodelatest不过我个人不太推荐这个方式原因很简单终端 AI Agent 的迭代速度很快用包管理器安装的版本往往不是最新的后面升级还得自己手动拉。相比之下官方脚本装的版本自带 update 提示体验好不少。另外 opencode 现在也出了桌面版本质上是一个带图形界面的壳方便你把它当成本地 AI 工具跟 IDE 配合使用。如果你有大量时间在浏览器里操作桌面版会舒服一些但我个人还是更依赖终端里的原始交互。2.2 Windows 用户最容易踩的坑cmdlet 识别不到热词榜里有一条非常显眼“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这不是 opencode 本身坏了而是 Windows 环境变量没有把安装目录加进 PATH。以官网安装脚本为例默认会装到%USERPROFILE%\.opencode\bin下。你装完之后如果直接开一个全新终端按理说应该能识别到但如果你终端是从旧窗口继承过来的PATH 还是老的自然就报这个错。解决办法很简单先确认安装文件在哪正常情况下是C:\Users\你的用户名\.opencode\bin\opencode.exe。按下 Win 键搜索“编辑系统环境变量”打开后点“环境变量”。在用户变量里找到 Path点编辑新增条目%USERPROFILE%\.opencode\bin。确认保存关掉所有终端窗口重新打开。如果你急着用临时办法是直接用npx opencode-ai启动这样不依赖 PATH 变量也能跑。但注意npx 每次会走一次包解析启动速度会比原生二进制慢一些只适合应急。我第一次在 Windows 上装这个工具的时候也在这里卡了十分钟后来发现就是终端没重开属于安装阶段最容易忽略的细节。2.3 opencode.json改模型、换 Provider、开 LSP 都看它opencode 的配置文件采用 JSON 格式默认读取两个位置全局配置在~/.config/opencode/opencode.json项目配置在当前项目根目录下的opencode.json。项目配置会覆盖全局配置这跟很多编辑器的配置层级思路一致。一份最小可用的配置长这样{ $schema: https://opencode.ai/config.json, model: gpt-5, provider: { my-gateway: { npm: ai-sdk/openai-compatible, name: My Gateway, options: { baseURL: https://your-gateway.example.com/v1, apiKey: sk-xxxx }, models: { my-model: { name: My Fast Model } } } } }这里的关键是provider字段。opencode 通过不同的 npm 包来适配不同模型商的 SDK像ai-sdk/openai-compatible这种名字就是“OpenAI 兼容协议”的适配器。你只要把某个网关服务或者模型厂商给的 baseURL 填进去再把对应的模型名写进models里就能在model字段切换了。很多刚上手的人喜欢到处找“推荐配置”其实理解了这个 JSON 结构你就能自己写任何一家模型的接入方式。2.4 编辑器插件VSCode 和 IDEA 都能接opencode 虽然是个终端工具但官方也提供了 VSCode 插件和 JetBrains IDEA 插件。你在插件市场直接搜 opencode 就能找到。VSCode 插件的使用逻辑是它读取你本地已经装好的 opencode CLI然后在编辑器侧边栏开一个聊天面板你选中的代码会自动作为上下文传到 opencode 会话里。实际操作中我一般会开两个窗口左侧是正常编辑器右侧是 opencode 面板遇到需要多文件修改的任务直接在面板里跟它沟通它能跨文件搜索和修改。JetBrains 系插件的体验类似如果你主力 IDE 是 IDEA 或者 GoLand配好后也能在 IDE 内部直接驱动 Agent。有一点要注意插件只是中转界面底层还是依赖命令行工具。如果你在终端里跑opencode都报错那插件大概率也连不上。所以遇到插件问题第一反应应该是去检查 CLI 是否正常而不是反复重装插件。3. 模型接入opencode go、免费模型与多配置切换3.1 模型接入的三种主流方式opencode 模型接入方式可以分成三类。第一类是直接填模型厂商官方 key比如你在 Anthropic 或者 OpenAI 后台生成一个 key直接用官方 baseURL这种方式最稳定适合个人开发者缺点是你得能正常访问对应厂商的接口。第二类是走第三方网关订阅服务例如大家常说的 opencode go以及 opencode go 这类打包多个模型入口的服务你只需要一个 key 和一个 endpoint就能在同一套配置里切换多个模型。第三类是接本地模型服务比如部署一个本地 OpenAI 兼容接口让 opencode 走 localhost。日常使用里我更推荐第二类方式。原因很简单AI 模型迭代太快今天你用 A 模型跑得不错下周 B 模型出了个更强的版本你不想为了换模型去改一整套配置。网关订阅服务帮你把模型列表都整理好了配置文件基本不用大改换个模型名就完事。这也是为什么 opencode go 这类服务能够在社区里火起来。3.2 网关订阅怎么配以 opencode go 为例opencode go 你可以理解成一种把多个模型打包成订阅接口的服务。它背后对接了不同的模型供应商然后把调用方式统一成 OpenAI 兼容协议你再通过 opencode 的 provider 配置把它接进来。配置的核心就三件事baseURL、apiKey、model。根据你买的正规服务的后台文档把这三个值填对就行。下面是一段我在 opencode.json 里实际用过的占位示例{ provider: { opencode-go: { npm: ai-sdk/openai-compatible, name: OpenCode Go Gateway, options: { baseURL: https://api.your-service.example.com/v1, apiKey: 你的 key }, models: { muse-spark-1.3-fr: { name: Muse Spark 1.3 FR } } } }, model: muse-spark-1.3-fr }需要特别注意配置文件里的apiKey是敏感信息。如果你用 git 管理 dotfiles记得把这份配置加入.gitignore或者改用环境变量注入的方式。还有一点很多人配置完发现“为什么我改了 provider 但没用”大概率是没检查最后的model字段——provider 只是声明了可用的模型model才是真正指定当前需要用哪一个。套餐选择方面我的建议是别一上来就买最高档。先用最低档跑一周观察几个指标响应速度是否满足日常、高峰时段是否频繁报错、模型列表里是否有你想用的主力模型。很多网关服务的套餐档位差异只在并发和次数对个人开发来说中低档通常已经足够。等确认某个模型真正适合你的工作流再升级也不迟。3.3 ccswitch多套配置一键切换如果你同时使用 Claude Code、Codex CLI 和 opencode那你一定会遇到一个问题每套工具各有各的 API 配置切换起来非常麻烦。热词里提到的 ccswitch 就是一个专门解决此问题的工具它可以帮你管理多套工具链的 API profile然后一键切换。在 opencode 里我通常会结合 opencode go 这类网关服务一起用。具体做法是在 ccswitch 里配置好不同的 provider 模板每个模板对应一个 baseURL 和 key 组合需要切换时直接改环境变量或者重新生成配置文件。例如你在 A 项目和 B 项目里用了不同的模型供应商项目根目录各放一份opencode.json再用 ccswitch 管理全局模板切换起来就很顺。这样做的好处是你不需要记住每一家服务的参数所有接入信息集中在一个地方维护团队协作时也能把模板分享给同事。3.4 免费模型为什么会报“this model is not available in your country”在模型接入过程中不少人遇到过this model is not available in your country这个报错尤其是一些免费模型。这里的本质是模型供应商的区域授权控制某个模型可能只在特定地区开放你的请求被判断为不在授权范围内于是返回这个错误。它和你本地的网络设置没有直接关系单纯是模型授权范围的问题。遇到这种报错我的排查顺序是先确认你请求的模型名是否真的在订阅服务提供的模型列表里有些免费模型列表更新不及时名字看着像实际已下架。去网关服务的后台看看有没有关于区域限制的说明。正规服务一般会明说哪些模型有区域约束。如果该模型确实受区域限制最快的办法不是想办法绕而是换一个同能力等级的可用模型。模型市场里有大量替代品大多数场景下你感觉不到明显差别。顺带说一句免费模型的质量和可用性波动很大。之前社区里热传的 hy3-free 等免费通道不少都已经下线或不可用。如果某个模型对你的工作流至关重要我建议至少准备一个付费备用模型避免关键时刻掉链子。免费模型适合做本地小实验真在项目里跑稳定性比省钱重要得多。4. 进阶玩法Skills、LSP、Memory、Playwright4.1 用 Skills 给 opencode 注入团队经验Skills 是 opencode 很核心的一个扩展机制。简单来说你可以在 skills 目录里放一份 SKILL.md里面描述某种特定场景下的处理步骤opencode 在遇到相关任务时会主动读取并使用这些规则。默认的 skills 目录有几个全局的是~/.config/opencode/skills项目级的是.opencode/skills。一个简单的 skills 示例结构是~/.config/opencode/skills/my-lint-fix/ SKILL.mdSKILL.md 内部可以这样写--- name: my-lint-fix description: 当用户要求修复 lint 错误时使用 --- 1. 先运行 lint 命令获取完整错误列表 2. 按文件分组归类错误 3. 逐个文件修复优先修复 error 级别的错误 4. 修复完成后重新运行 lint 确认配置好之后你在对话里提到“修一下 lint”opencode 就会按这个流程执行而不是自由发挥。社区里流行的 superpowers 插件也就是把一系列现成的 skills 打包放进 opencode 配置目录让 Agent 一下子获得项目规划、任务拆解、代码审查等能力。如果你想试直接把 superpowers 仓库克隆到 skills 目录下即可后续按自己的团队习惯增减。我实际用下来最大的感受是Skills 越贴近你的真实开发流程价值越大。别写那种“要写好代码”的空话要写“后端改动必须跑 migration”“前端改动必须跑一遍 build”这种可执行约束效果完全不一样。4.2 LSP让 opencode 读懂代码语义而不是猜opencode 原生支持 LSP这是它相比 Claude Code 的一个明显优势。LSP语言服务器协议简单说就是给 IDE 和 Agent 提供语义级代码能力的一个协议标准。有了 LSPopencode 不再靠关键词硬猜变量含义而是能直接拿到类型信息、定义跳转、引用列表改代码时对影响范围的理解会准确很多。启用 LSP 需要在 opencode.json 里配置常见写法如下{ lsp: { typescript: { command: typescript-language-server, args: [--stdio] } } }这里的command是语言服务器的启动命令前提是你本机已经装好了对应的语言服务器。比如 TypeScript 需要先安装 typescript-language-serverPython 可能是基于 pylsp 的某个命令。opencode 会在需要分析符号时拉取这些服务器进程并把拿到的语义信息合并进上下文。踩过一次坑之后我的建议是先把语言服务器装好并验证能独立运行再去配置 opencode。如果你配置了 LSP 但完全没有生效大概率是语言服务器本身没装对。你可以先用which或者where命令检查一下路径是否存在不要在 Agent 配置里反复猜。4.3 Memory 和 AGENTS.md让 opencode 越用越懂你另一个提升 opencode 体验的重要功能是 Memory它依赖项目里的 AGENTS.md 文件。你可以把 AGENTS.md 理解成给 Agent 的入职手册项目结构、目录约定、常用命令、历史痛点都可以写在里面。opencode 在启动时会读取这个文件并在后续对话中持续参考它。全局的记忆文件也有位置通常在~/.config/opencode/AGENTS.md适合写一些通用的编码规范和个人偏好。项目级的 AGENTS.md 则写项目特有信息。我个人在接手新项目时第一件事就是让 opencode 帮忙生成一份粗略的 AGENTS.md然后我再手动补充团队规范和常见坑。举个例子如果这个项目的前端代码必须跑 lint 才能合入你就直接在 AGENTS.md 里写清楚。后续只要 opencode 跟你聊到这个项目它都会记住这条约束改完代码会主动提醒你跑一遍检查。这种长期记忆能力让我感觉它不是一个每次对话都失忆的工具而更像一个逐渐熟悉业务的新同事。4.4 Playwright 实战让 opencode 自己复现前端 Bug热词里有一条“opencode playwright 怎么测试前端 bug”这个场景我很喜欢因为实际价值真的很高。opencode 支持 MCP而 Playwright 官方提供了 MCP 服务器把两者接起来opencode 就能自己控制浏览器做点击、输入、截图、读取控制台日志。配置方式是在 opencode.json 里加一个 mcp 配置{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }配好之后如果你遇到一个前端 bug比如“点击提交按钮之后页面白屏”你可以让 opencode 打开本地开发地址模拟点击然后把控制台报错拉回来。它能自己打开页面、做断言、截取关键界面再把错误堆栈给你分析。这一套流程对前端调试来说非常省心因为很多 bug 是“偶发”“需要特定步骤才能复现”人工点半天不如让 Agent 按你的描述自动操作几轮。我这里提醒一句Playwright MCP 默认操作的是真实浏览器如果你的项目是内部系统登录态要靠 cookie 之类的信息你得先确认 opencode 能正常访问浏览器上下文不然 Agent 打开页面后可能是个未登录状态复现路径就断了。简单处理方式是先手动登录一次并把 session 信息传给该工具或者让本地开发环境临时屏蔽登录限制。5. 拿 opencode 接手一个陌生项目5.1 先让 Agent 建上下文别急着改代码接手一个陌生项目时大多数人容易犯的错就是立刻让 Agent“把这个 bug 改一下”。如果它对这个项目一无所知很容易管中窥豹改出更严重的问题。我现在的做法是启动 opencode 后先让它扫描项目结构读 README、AGENTS.md、package.json 或 go.mod 这类入口文件产出一份项目结构总结。你可以直接这么问“请先浏览整个项目的目录结构找到核心入口梳理出主要模块之间的关系并用中文给我一份概览。”让 Agent 先跑一遍测试确认基线是绿的再谈改东西。这一步看起来浪费几分钟实际上能帮后面省大量排查时间Agent 对项目有了全局认知它帮你定位问题的时候路径会准确很多。5.2 用“最小改动”原则提需求跟 Agent 协作改代码我的经验是把需求拆小一个会话只改一个点。比如“这个接口超时了帮我看看是不是 SQL 查询的问题”和“帮我优化整个系统性能”这是完全不同的两个需求。后者一定会触发大范围重构而且往往不是你真正想要的。在对话里我会明确告诉 opencode先找到根因给我一个最小改动范围的方案然后再执行。如果它有多个改法让它把方案列出来标注每个方案的改动范围和风险我再决定选哪一个。这种交互方式能有效避免 Agent“自作主张”顺手帮你重构一遍代码。5.3 验收与回滚每次让 opencode 改完代码我都会看一眼 diff然后重新跑受影响路径的测试。不要让它改完就完事Agent 的自信不代表代码正确。我会要求它改完后自动跑一遍测试不行就继续修直到通过。如果改动太大或者跑挂了我会直接从 git 回滚对应文件让 Agent 换个方案再试。这个循环虽然听起来很基础但恰恰是能不能把 AI Agent 投入到实际生产流程的分水岭。6. 高频问题与排查速查表6.1 报错速查表从 cmdlet 到服务端错误把这类工具的各种报错整理成一张可查的速查表能省不少搜索时间。以下是我和周边朋友实际遇到过的高频问题按“现象、原因、解决办法”三列列出报错现象常见原因解决办法无法将“opencode”识别为 cmdletopencode 安装目录不在 PATH把%USERPROFILE%\.opencode\bin加入 PATH重开终端this model is not available in your country模型授权区域限制或模型已不可用检查订阅列表更换同等级可用模型unexpected server error. check server logs网关服务端或 key 配置问题确认 baseURL、apiKey 正确看服务端日志Provider 配置了但模型切换无效配置里 provider 和 model 字段不一致检查model字段是否指向已配置的模型名LSP 配置不生效语言服务器未安装或路径不对先确认语言服务器能独立运行Skills 不加载目录结构或 SKILL.md 格式不对检查 skills 目录和 frontmatter 字段插件连不上 opencodeCLI 本身有问题先在终端跑opencode确认 CLI 正常6.2 遇到 unexpected server error 的前 30 秒怎么排查unexpected server error. check server logs这个报错有点吓人很多人看到就直接懵了。其实它只是在告诉你服务端返回了一个非预期错误具体要往日志里看。第一步先检查你填写的网关 baseURL 是否正确很多网关服务有多个区域的 endpoint填错就会触发这种笼统报错。第二步确认 key 没有过期、配额没有耗尽。有些订阅服务在配额用尽时返回的就是 500 系的错误而不会明确告诉你“欠费了”。第三步看服务商后台的请求日志如果能看到这个请求的具体状态码问题范围就缩小了。这里还有一个比较隐蔽的坑opencode 会默认把某些请求头或额外字段传给服务端如果你的网关服务对请求格式有严格校验就可能拒绝执行并报 server error。遇到这种情况可以先切换一个官方 provider 试试如果同样的 key 在官方接口能用那问题大概率出在网关注入环节上。6.3 配置不生效时先重开终端再怀疑人生配置文件不生效是一个被问烂了的问题。很多时候改了 opencode.json 却发现模型没变原因很简单opencode 是在启动时读取配置的你改完配置后当前正在运行的会话里还停留在旧配置。所以每次修改配置后第一动作是退出当前会话重新启动 opencode或者至少在新窗口里重新跑一次。如果你确认重开还是没生效再去看配置文件路径是否正确。全局配置和项目配置的优先级是项目配置覆盖全局配置如果你在项目目录里放了一个旧的opencode.json它可能默默地覆盖掉了全局配置而你自己并不记得。我曾在某个仓库里踩过一次这个坑排查了十分钟才发现是同事遗留的项目级配置在作怪。写在最后我的实际使用心得如果你问我现在每天是怎么用 opencode 的我会说我把它当成一个“带记忆的实习生”给它写好 AGENTS.md它就越用越懂我的项目给它配好 skills它处理任务时就会按照我认可的流程来把浏览器调试交给它我可以从大量重复的前端复现步骤里解放出来。这套工具最核心的价值不是“自动写代码”而是把项目里那些可重复、可模板化的流程沉淀下来让 Agent 在合适的时候调用帮你把精力留给真正需要判断的地方。最后分享一个小技巧如果你在配置里同时填了好几个模型不要一直手动切换直接在对话里用斜杠命令查看模型列表并切换会比你反复改 opencode.json 高效得多。我试过几次之后已经习惯把常用模型名写在 AGENTS.md 里这样每次新会话启动时它能提醒我当前项目推荐用哪个模型。配置是拿来用的不是拿来供着的。
