最近我几乎把日常写代码的终端从编辑器自带终端换成了 opencode这一个多月用下来,最大的感受是它比我之前折腾过的很多命令行 AI 编程工具都更贴近把 AI 当结对程序员的状态。简单说opencode 是一个跑在终端里的 AI 编程代理你给它一个任务它能自己读项目文件、改代码、跑命令、看报错、再改直到把事情做完。它不是聊天窗口而是一个能上手干活的工具。这篇文章我会围绕 opencode 的安装、模型接入、Skills 技能包、LSP 集成、Playwright 前端 Bug 复现、编辑器插件这些层面把我踩过的坑和验证过能用的方案全部写出来。适合正在纠结要不要从 Claude Code 或 Codex CLI 切换过来的人也适合刚下载 opencode 但卡在 无法识别 cmdlet 或模型配置上的新手。内容以实际操作为主每段都能直接照着做。1. 先搞清楚 opencode 是什么以及它和同类工具差在哪1.1 一个跑在终端里的 AI 编程代理不完全等于聊天机器人opencode 最核心的定位是终端里的 AI 代理。你启动它之后不是一问一答的对话窗口而是你给它一个任务描述它会自己规划步骤、读取项目文件、调用工具、执行终端命令然后根据命令输出继续调整。这种工作方式和 GitHub Copilot 那种补全式辅助完全不同也和你直接复制粘贴到 ChatGPT 里问完全不同。它本质上做的是自我驱动循环读代码、定位问题、修改、编译/测试、看结果再迭代。你更像是项目经理它才是执行者。比如我经常让它帮我把用户列表接口的超时时间从 3s 改成可配置它自己会找到配置文件、找到 HTTP 客户端封装、改掉硬编码、跑测试最后把 diff 展示给你确认。这种体验我觉得已经非常接近一个初级但极其勤奋的结对开发者。和同类工具对比opencode 的特点有两个一是模型无关理论上兼容任何 OpenAI 格式的 API所以你能用自己的 key也能接本地模型二是开源社区驱动迭代速度快热词里那些 opencode skillsopencode memoryopencode desktop 基本都是社区功能这也意味着你遇到问题至少能翻源码查原因。1.2 为什么值得从 Claude Code / Codex 切过来试试我之前主力是 Claude Code 和 Codex CLI各有各的优势但它们都有一个共性默认绑定官方模型或者想换模型时配置很绕。opencode 把模型接入做成了配置项而不是写死在代码里这一点在实际使用中非常重要。你可以自由选择性价比高的第三方模型、公司内部的模型网关、或者本地 Ollama 起的开源模型。就拿我自己举例日常写业务代码我用一个便宜的中转模型做前端精细化调试时切到 Claude 4 级别的模型跑本地小项目修复时直接切 Ollama 里的 qwen 系列。它们都能在 opencode 里通过切换 profile 实现不需要开两个工具。热词里有一条是 opencode codex claude code pi 哪个 agent 好用。我的观点是选择哪个工具取决于你手里有什么模型资源。如果你只有官方订阅Claude Code 体验最好如果你想让一个工具通吃多个模型来源opencode 优势非常明显。而 Pi 这类更轻量的工具适合只想在单文件场景快速改点东西的人。工具没有绝对好坏只有和你的使用场景匹不匹配。2. 安装 opencode先解决 Windows 下最典型的两个报错2.1 安装方式选哪种脚本安装最快Go 工具链装法适合折腾党opencode 的安装方式在官方文档里有几种但大多数人推荐用脚本安装。在 Linux 和 macOS 上基本一条命令就能搞定。Windows 上麻烦一点但也不是不能解决。我在 Windows 上实测可行的方案是先用管理员权限打开 PowerShell执行irm https://opencode.ai/install.ps1 | iex如果网络环境允许这条命令会自动下载二进制文件并加入用户 PATH。装完后关掉当前终端重开输入opencode --version验证。热词里反复出现的 opencode go其实还有一种方式就是用 Go 工具链直接安装最新版。如果你机器上已经有 Go 环境也可以这样go install github.com/opencode-ai/opencodelatest这种方式的优点是可以直接拿到当前最新提交的版本缺点是你需要确保%GOPATH%\bin或者~/go/bin在 PATH 里。而且后续升级会麻烦一点需要手动再跑一次 go install。我个人建议日常使用用第一种脚本安装开发调试用 Go 工具链安装。两种方案并不冲突装完以后核心的命令和配置方式完全一样不用担心版本隔阂。2.2 无法将 opencode 项识别为 cmdlet 到底怎么解决这是热词里被搜索最多的问题也是新手最容易卡住的地方。这个报错本身并不复杂含义是终端在当前 PATH 环境变量里找不到 opencode 这个可执行文件。常见原因有三个。第一安装脚本执行完以后当前终端窗口的环境变量没有刷新。你不需要重启电脑直接关掉当前终端窗口重新开一个就行。第二安装脚本写入的目录一般是%USERPROFILE%\bin或者%LOCALAPPDATA%\opencode并没有出现在系统的 PATH 里。这种情况需要手动补充环境变量。你可以打开编辑系统环境变量在用户变量的 Path 里手动加上对应路径。第三安装过程被安全软件拦截了导致二进制文件根本没写进去重新以管理员身份执行安装脚本即可。如果是用 Go 方式安装那十有八九是 GOPATH 或 GOBIN 没在 PATH 里。你可以在 PowerShell 里先执行go env GOBIN和go env GOPATH看看路径然后手动把%GOPATH%\bin加进 PATH。2.3 安装完怎么验证环境是好的验证安装不需要跑复杂的 demo先跑一个opencode --version再跑一个opencode --help看看帮助信息能不能正常输出。如果你的终端提示版本号和基本命令列表说明环境没问题。然后进到一个项目目录里执行opencode直接进入 REPL 模式。首次启动会让你选择模型提供商。这里需要注意如果你的提供商列表是空的别慌下一章我会详细讲怎么配置模型包括免费模型和订阅模型的接入方式。opencode 首次启动的引导界面非常简洁如果你不想选也可以直接 CtrlC 退出先完成配置文件的手动编辑再进来。3. 模型接入免费模型、订阅模型、本地模型一网打尽3.1 opencode 的模型配置逻辑一切皆 APIopencode 对模型的处理方式和我用过的大多数现代 AI 工具不太一样。它把模型提供商抽象成统一的 OpenAI 兼容格式你只需要配置 base URL、API key、模型 ID就能接入几乎任何模型服务。配置文件默认在用户目录下Linux/macOS 是~/.config/opencode/opencode.jsonWindows 是%USERPROFILE%\.config\opencode\opencode.json。如果你打开发现整个目录都是空的不用担心先创建这个文件。下面是我的一个精简配置示例帮助你理解结构{ $schema: https://opencode.ai/config.json, provider: { default: myproxy, myproxy: { npm: ai-sdk/openai-compatible, name: myproxy, options: { baseURL: https://your-model-gateway.example.com/v1, apiKey: sk-your-key-here }, models: { claude-3-5-sonnet: { name: Claude 3.5 Sonnet }, qwen3-coder: { name: Qwen3 Coder } } } } }这里的npm字段是让 opencode 知道这个 provider 走的是 openai-compatible SDK。models下面是你想暴露给 opencode 的模型列表名字要和 base URL 提供商那边的模型 ID 一致。配好以后在 opencode 里用/models命令就能切换。3.2 免费模型的接入姿势热词里有 opencode 免费模型实际上 opencode 本身是开源软件不收费但模型 API 是否免费取决于你接的模型服务。目前比较靠谱的免费方案有几条路。第一条路是本地跑 Ollama。先在本地安装 Ollama拉一个 qwen3-coder 之类的模型然后 opencode 的 provider 配置 baseURL 指向http://localhost:11434/v1API key 随便填一个占位符就行。这种方案的好处是隐私性极好坏处是你得有一个性能还行的 GPU不然推理速度会比较难受。第二条路是用一些提供免费额度的在线模型服务。你只需要申请一个 API key然后把 baseURL 填成对应服务的地址。具体哪个服务稳定、现在还有没有免费额度变化非常快我建议以官方最新公告为准不要盲目囤 key。第三条路是热词里提到的 Muse Spark 1.3 FR 这类模型。我在测试时第一次接入也报错 this model is not available in your country这个后面我会专门讲怎么排查。这类模型通常也是 OpenAI 兼容接口配置方式和上面完全一样。区别是你要注意它的模型 ID 千万别填错。3.3 opencode go 订阅模型 ccswitch 到底指什么热词里反复出现 opencode go 订阅模型选择opencode go 需要配合 ccswitch 等工具这里面的 go 其实是某种订阅服务的名字。简单理解这是一种通过第三方订阅服务获取多个模型 API 访问权的方式。ccswitch 是一个用来管理这些订阅配置的小工具它可以把多个订阅服务统一管理生成环境变量或者配置文件。opencode 对这种场景支持得很好因为你完全可以在多个 provider 之间用/provider命令随时切换。但这种订阅服务有一个必须注意的安全问题永远不要在公共仓库里提交包含 apiKey 的 opencode.json。我建议把敏感信息放到环境变量里例如{ provider: { myproxy: { options: { baseURL: https://your-endpoint.example.com/v1, apiKey: {env:MODEL_API_KEY} } } } }然后在终端设置里提前导出MODEL_API_KEY环境变量。这样即使配置文件不小心被上传到 Git也不会直接泄露秘钥。3.4 接入 superpowers 增强包让 opencode 更像一个资深开发者热词里有 opencode 接入 superpower这个 superpowers 实际上是一套社区维护的提示词和技能增强包。装完之后opencode 会获得一套更系统的工程方法比如在改代码之前先分析影响范围、写更细的测试用例、以及更规范的 commit message 生成方式。我个人的体验是它确实能减少 AI 一上来就乱改代码的坏毛病。安装方式通常是把对应的 skill 目录放到~/.config/opencode/skills/下然后在 opencode 里通过superpowers引用。具体到版本可能有点差异建议装完以后用/skills命令查看当前是否识别到了技能。需要提醒的是superpowers 对 model 的要求略高我用便宜模型时出现过分析阶段做得很好、但执行阶段卡住的情况。建议这只在主力模型上开启跑弱模型时可以暂时禁用。4. Skills、Memory 和 LSP把 opencode 调教成老司机4.1 Skills 到底是什么别把它想复杂了Skills 在 opencode 里的定位很简单把一段固定的使用说明或者指令打包成一个可复用的技能。它和你在终端里打一段长 prompt 没什么本质区别但好处是封装后可以随时复用也能分享给团队其他人。我以前经常让 opencode 帮我写 commit message但每次都要在 prompt 里解释一遍要遵循 conventional commits 格式body 要写清楚影响范围。后来我建了一个 skill名字叫commit-helper内容就是一个 Markdown 文件写明规则和示例。之后我只需要打commit-helper 帮我提交当前改动它就会按照规则执行。整体结构一般是这样的~/.config/opencode/skills/ commit-helper/ SKILL.md run.shSKILL.md 里写清楚触发条件和规则run.sh 是可选的可执行脚本。opencode 里通过/skills可以查看所有已经加载的 skills。这个机制非常适合团队统一规范比如让所有成员都使用同样的代码审查清单、同样的发布检查流程。4.2 Memory 功能让 opencode 记住你的项目偏好官方开着 Memory 功能之后opencode 会把一些长期有用的上下文保存在磁盘上下一次启动时自动加载。比如你的项目喜欢用 pnpm 而不是 npm测试框架用的是 vitest 不是 jest发布流程走的是某个 CI 脚本。这些约定如果每次都得重新说一遍非常浪费 token。我的用法是在项目根目录维护一个AGENTS.md或者.opencode/memory.md文件里面写清楚项目结构、关键命令、编码规范。opencode 会在启动时自动读取。如果你不想手动维护也可以在对话里直接告诉它记住这个项目的测试命令是 pnpm vitest run它会自动写入记忆文件。这里有一个经验Memory 内容宁精勿多。如果文件里什么信息都有AI 在处理任务时分不清优先级反而可能把噪音当重要约束。我只记录会直接影响代码正确性或工程流程的信息。4.3 LSP 集成让 opencode 具备真正的代码分析能力热词里有 opencode 如何使用 lsp。LSPLanguage Server Protocol这个机制如果你用过 VSCode 应该不陌生它就是给编辑器提供代码补全、跳转、诊断信息的一整套协议。opencode 接入了 LSP 之后AI 不再只能靠正则或盲读来理解代码而是能像 IDE 一样拿到准确的语法错误、类型错误和符号定义。举个真实场景。我让 opencode 把某个 TypeScript 接口里新增一个字段它以前可能会改错引用的类型或者漏改其他调用处。但接入了typescript-language-server之后它会先通过 LSP 拿到所有引用点再逐个修改。这种准确率提升是质的飞跃尤其在中大型项目里。我目前用的 LSP 配置大概长这样{ lsp: { typescript: { command: typescript-language-server, args: [--stdio] } } }具体语言对应的 server 命名和参数可能不同建议启动 opencode 后用/lsp命令查看连接状态确保对应的 language server 显示为 connected。4.4 自己动手做一个 skill输出强制走团队规范最后分享一个我搭建代码审查 skill的过程你可以照着改成自己的规范。我的需求是让 opencode 在提交代码前做一轮自检比如检查是否有 console.log 残留、是否有硬编码的 API 地址、是否有 TODO 没处理。做法是创建code-review-checker目录SKILL.md 里写上检查清单。注意skill 的指令要尽量具体。不要说检查代码质量要说找出所有 console.log 语句并列出文件路径和行号。然后我再加了一个可选的run.sh让 opencode 执行一些简单命令来自动收集可疑信息。比如用grep -rn console.log src/快速定位日志输出。这样 AI 在开始分析前就有一份证据清单回答质量会高很多。这个 skill 配合 Memory 里的项目规范基本就等于给团队配了一个不会累的代码审查员。5. 编辑器集成与桌面版从纯终端走向日常开发流程5.1 VSCode 插件怎么选和直接在终端用有什么区别opencode 的一大优势是它不光能在终端里跑还提供了 VSCode 插件和 JetBrains IDEA 插件。很多人的疑问是既然终端里已经能用了为什么还要装插件我的体会是插件最大的价值在于上下文联动。比如你在 VSCode 里打开了一个文件选中了一段代码然后让 opencode 基于当前选区和整个 worktree 修复这个 bug它能直接拿到编辑器的选区信息和当前文件路径不需要复制粘贴路径也不用手动cd到目录。这在处理跨文件重构时非常有用。对于 JetBrains IDEA 用户opencode 的插件体验其实也不错。你可以把它当成一个智能终端面板直接在 IDE 里开一个 opencode 的会话让 AI 改代码的同时你还能继续在编辑器里浏览代码。插件和 CLI 后端共享同一套配置你在插件里的操作和命令行里是一致的不会有割裂感。5.2 桌面版 opencode desktop 值得用吗热词里有 opencode 桌面版。这个桌面版本质上是把终端 UI 包了一层图形界面依然不是网上那些上传代码文件然后聊天的网页工具。它适合那些不喜欢黑底白字终端、但想保留 opencode 全部能力的人。我个人的偏好是日常重度使用还是在真实的终端里因为终端里我可以同时开多个标签页配合 tmux 分屏更灵活。桌面版适合给那些刚接触 opencode、还不习惯命令行操作的同事用界面更友好一些上下文和会话管理的入口也更直观。不过无论你用哪种界面底层的配置、Skills、Memory、LSP 都是完全相通的。这一点很重要意味着你从终端切到桌面版不会有任何学习成本。5.3 把 opencode 接进日常 Git 工作流对我来说opencode 真正提升效率的场景不是让它一次性写一个巨大功能而是把它当成 Git 工作流里的中间人。比如我经常执行这样的流程写完代码后在终端里输入opencode然后说看一下当前 git diff帮我找出潜在 bug并补充缺失的测试用例。这种用法比让 AI 直接写登录功能要可靠得多因为任务边界非常清晰AI 只需要做 review 和补充而不是思考一个庞大需求的实现方案。我还习惯让它自动生成 PR 描述基于实际 diff 整理出改动模块、影响范围、测试情况这比手动写 PR 描述快太多。热词里有 opencode 接手开发项目这个场景其实也是基于 Git 工作流来理解。你先用git log --oneline把近期的提交历史喂给 opencode再让它读 README 和核心模块代码它能很快建立起对这个项目的认知。但别指望它一次读懂大型遗留系统耐心拆分任务才是正确用法。6. 实战让 opencode 用 Playwright 复现并定位前端 Bug6.1 为什么 AI 编程代理要配合浏览器自动化前端 Bug 是 AI 编程代理最容易翻车的场景原因是很多问题只有真实运行页面才能暴露出来。AI 光看代码经常觉得逻辑没问题但实际渲染出来的页面布局已经乱了。opencode 的解决方案是支持通过 Playwright 启动浏览器自动操作页面观察控制台报错和界面表现等于把用户实际操作搬到了 AI 面前。这个过程听起来很玄实际上就是在 opencode 的会话里让 AI 调用一个 Playwright 工具。它自己编写脚本、打开测试页面、点击按钮、输入表单、读取 console 日志然后把问题反馈回主对话里。我这里说的不是让 AI 单独写一个测试用例而是让 AI 为了定位 bug 而去主动调查页面。6.2 一个真实案例按钮点击无响应有次我遇到一个很诡异的问题页面上有个保存按钮点击后没有报错但请求一直没有发出去。我看代码看了很久没找到原因于是让 opencode 配合 Playwright 去复现。它做的事大概如下启动浏览器访问本地开发地址打开页面后控制台执行点击观察 network 面板发现点击事件根本没有触发网络请求。接着它检查了按钮上的事件绑定最后定位到是父组件的一个stopPropagation把点击事件拦截了导致子组件的监听器根本没机会执行。整个过程它只用了几分钟。如果靠我自己手动调试可能要在 React 组件树里一个个单位查看至少要多花两倍时间。这个案例让我真正认可了AI 编程代理 浏览器自动化的组合威力。6.3 Playwright 相关配置注意点要让 opencode 能用 Playwright核心要保证两点一是本机有可用的 Chromium 内核二是 opencode 有权限启动浏览器进程。我遇到过在 Linux 服务器上权限不够导致浏览器无法启动的问题解决办法是安装系统依赖并加上--no-sandbox参数。如果你只是想在本地开发环境里排查问题直接用正常工作目录启动 opencode 即可。如果你想让 opencode 访问需要登录的页面建议先在 Playwright 的持久化上下文里登录一次或者把 cookie 导入。没做这一步的话AI 打开的可能是一个未登录状态的页面复现不了真实问题。这里额外说一句opencode 在执行 Playwright 脚本时会产生大量中间输出如果模型上下文窗口不够大可能会忽略关键 console 日志。遇到这种情况我建议明确告诉它把 console 输出作为单独文本文件保存到 /tmp 下再分析。7. 常见问题排查与配置救急手册7.1 高频报错一unexpected server error这个报错在热词里也出现过error: unexpected server error. check server logs。通常原因是你配置的模型服务端出问题了。优先检查三件事。第一你的 API key 是否有效额度是否用完。第二baseURL 是否正确是否需要带/v1后缀。第三模型 ID 是否和该服务商实际支持的完全一致。很多时候模型 ID 只差一个点或者一个横线就会报 server error。排障时可以先用curl直接请求一次 API看看是不是 opencode 之外的问题。7.2 高频报错二this model is not available in your country这个报错我之前也遇到过是模型服务商根据 IP 或者账号归属地做的区域限制。解决办法不是去动模型服务商的后台而是换一个不做区域限制的模型商或者使用 中转网关 把请求转发到可用区域。在 opencode 里你需要检查两处一是 provider 的 baseURL 指向是否走对了网关二是 model 的 ID 是否填成了只对特定区域开放的版本。比如热词里的 Muse Spark 1.3 FR这类带明显区域标识的模型 ID在受限网络中尤其容易触发这个提示。不要和网络代理混淆这纯粹是模型服务本身的授权限制。7.3 高频报错三模型配好了但一直不可用如果你发现 opencode 里/models能看到模型名但发消息时一直转圈或者报错大概率是 provider 配置没有被正确加载。我的经验是每次改完配置文件后完全退出 opencode 再重新启动确保配置被重新读取。另外要注意如果配置了多个 provider一定要确认你当前选中的不是 tuned model比如配置里写了带特定后缀的微调版本实际不存在。排版和命名带来的这种问题非常隐蔽建议简化 provider 配置模型列表只留正在用的几个。7.4 建立自己的配置备份意识opencode 的配置分散在opencode.json、Skills 目录、Memory 文件里如果你花了很多精力调出一套好用的配置建议把这些都纳入 Git 管理。我是单独建了一个 dotfiles 仓库专门保存这些配置文件并且通过脚本一键生成软链接。这样做的最大好处是换机器时不需要重新折腾。另外opencode 更新频率很快有些字段可能在新版本里被废弃定期看一下官方 release notes 能省掉不少排障时间。8. 几个 Agent 的横向对比opencode、Codex、Claude Code、Pi 怎么选对比维度opencodeClaude CodeCodex CLIPi 工具模型来源灵活任意 OpenAI 兼容 API / 本地模型绑定 Claude 官方绑定 OpenAI 模型部分场景绑定特定服务多模型切换支持多 provider切换方便基本不支持或很麻烦不支持看版本通常有限Skills 机制有支持自定义类似功能较封闭有限轻量Playwright/工具调用支持配置清晰支持支持较弱上手成本中等配置稍多低开箱即用低最低适合人群喜欢自己掌控一切的技术爱好者官方订阅用户OpenAI 重度用户快速单文件修改看到这个表你可能会觉得opencode 怎么什么都占优势。其实不是它的成本隐藏在配置和调教上。如果你完全不想管模型、不想折腾 JSON 配置文件Claude Code 的开箱体验确实更省心。opencode 的理念是用户拥有完全的灵活性所以它把选择权和复杂度都交给了你。我的建议很简单如果你手里有多张模型 key 或者公司有自己的模型网关值得多花一小时把 opencode 配好如果你只是个人自费用户且主力就是 Claude那继续用 Claude Code 也没什么问题。工具是手段不是目的。最后说一个我在实际使用中最受益的小习惯每次接手一个新项目我会先在项目里维护一份高质量 AGENTS.md告诉 opencode 项目结构、启动命令、测试规范、部署注意点。这比任何模型参数调优都更能提升最终效果。opencode 强在它是开放的你可以把它塑造成适合你团队工作流的样子而不是强迫自己去适应一个既定工具。这种自由度我觉得是它这轮热度能一直维持下去的真正原因。
opencode 终端 AI 编程代理：从安装到配置、Skills 与 LSP 实战指南
最近我几乎把日常写代码的终端从编辑器自带终端换成了 opencode这一个多月用下来,最大的感受是它比我之前折腾过的很多命令行 AI 编程工具都更贴近把 AI 当结对程序员的状态。简单说opencode 是一个跑在终端里的 AI 编程代理你给它一个任务它能自己读项目文件、改代码、跑命令、看报错、再改直到把事情做完。它不是聊天窗口而是一个能上手干活的工具。这篇文章我会围绕 opencode 的安装、模型接入、Skills 技能包、LSP 集成、Playwright 前端 Bug 复现、编辑器插件这些层面把我踩过的坑和验证过能用的方案全部写出来。适合正在纠结要不要从 Claude Code 或 Codex CLI 切换过来的人也适合刚下载 opencode 但卡在 无法识别 cmdlet 或模型配置上的新手。内容以实际操作为主每段都能直接照着做。1. 先搞清楚 opencode 是什么以及它和同类工具差在哪1.1 一个跑在终端里的 AI 编程代理不完全等于聊天机器人opencode 最核心的定位是终端里的 AI 代理。你启动它之后不是一问一答的对话窗口而是你给它一个任务描述它会自己规划步骤、读取项目文件、调用工具、执行终端命令然后根据命令输出继续调整。这种工作方式和 GitHub Copilot 那种补全式辅助完全不同也和你直接复制粘贴到 ChatGPT 里问完全不同。它本质上做的是自我驱动循环读代码、定位问题、修改、编译/测试、看结果再迭代。你更像是项目经理它才是执行者。比如我经常让它帮我把用户列表接口的超时时间从 3s 改成可配置它自己会找到配置文件、找到 HTTP 客户端封装、改掉硬编码、跑测试最后把 diff 展示给你确认。这种体验我觉得已经非常接近一个初级但极其勤奋的结对开发者。和同类工具对比opencode 的特点有两个一是模型无关理论上兼容任何 OpenAI 格式的 API所以你能用自己的 key也能接本地模型二是开源社区驱动迭代速度快热词里那些 opencode skillsopencode memoryopencode desktop 基本都是社区功能这也意味着你遇到问题至少能翻源码查原因。1.2 为什么值得从 Claude Code / Codex 切过来试试我之前主力是 Claude Code 和 Codex CLI各有各的优势但它们都有一个共性默认绑定官方模型或者想换模型时配置很绕。opencode 把模型接入做成了配置项而不是写死在代码里这一点在实际使用中非常重要。你可以自由选择性价比高的第三方模型、公司内部的模型网关、或者本地 Ollama 起的开源模型。就拿我自己举例日常写业务代码我用一个便宜的中转模型做前端精细化调试时切到 Claude 4 级别的模型跑本地小项目修复时直接切 Ollama 里的 qwen 系列。它们都能在 opencode 里通过切换 profile 实现不需要开两个工具。热词里有一条是 opencode codex claude code pi 哪个 agent 好用。我的观点是选择哪个工具取决于你手里有什么模型资源。如果你只有官方订阅Claude Code 体验最好如果你想让一个工具通吃多个模型来源opencode 优势非常明显。而 Pi 这类更轻量的工具适合只想在单文件场景快速改点东西的人。工具没有绝对好坏只有和你的使用场景匹不匹配。2. 安装 opencode先解决 Windows 下最典型的两个报错2.1 安装方式选哪种脚本安装最快Go 工具链装法适合折腾党opencode 的安装方式在官方文档里有几种但大多数人推荐用脚本安装。在 Linux 和 macOS 上基本一条命令就能搞定。Windows 上麻烦一点但也不是不能解决。我在 Windows 上实测可行的方案是先用管理员权限打开 PowerShell执行irm https://opencode.ai/install.ps1 | iex如果网络环境允许这条命令会自动下载二进制文件并加入用户 PATH。装完后关掉当前终端重开输入opencode --version验证。热词里反复出现的 opencode go其实还有一种方式就是用 Go 工具链直接安装最新版。如果你机器上已经有 Go 环境也可以这样go install github.com/opencode-ai/opencodelatest这种方式的优点是可以直接拿到当前最新提交的版本缺点是你需要确保%GOPATH%\bin或者~/go/bin在 PATH 里。而且后续升级会麻烦一点需要手动再跑一次 go install。我个人建议日常使用用第一种脚本安装开发调试用 Go 工具链安装。两种方案并不冲突装完以后核心的命令和配置方式完全一样不用担心版本隔阂。2.2 无法将 opencode 项识别为 cmdlet 到底怎么解决这是热词里被搜索最多的问题也是新手最容易卡住的地方。这个报错本身并不复杂含义是终端在当前 PATH 环境变量里找不到 opencode 这个可执行文件。常见原因有三个。第一安装脚本执行完以后当前终端窗口的环境变量没有刷新。你不需要重启电脑直接关掉当前终端窗口重新开一个就行。第二安装脚本写入的目录一般是%USERPROFILE%\bin或者%LOCALAPPDATA%\opencode并没有出现在系统的 PATH 里。这种情况需要手动补充环境变量。你可以打开编辑系统环境变量在用户变量的 Path 里手动加上对应路径。第三安装过程被安全软件拦截了导致二进制文件根本没写进去重新以管理员身份执行安装脚本即可。如果是用 Go 方式安装那十有八九是 GOPATH 或 GOBIN 没在 PATH 里。你可以在 PowerShell 里先执行go env GOBIN和go env GOPATH看看路径然后手动把%GOPATH%\bin加进 PATH。2.3 安装完怎么验证环境是好的验证安装不需要跑复杂的 demo先跑一个opencode --version再跑一个opencode --help看看帮助信息能不能正常输出。如果你的终端提示版本号和基本命令列表说明环境没问题。然后进到一个项目目录里执行opencode直接进入 REPL 模式。首次启动会让你选择模型提供商。这里需要注意如果你的提供商列表是空的别慌下一章我会详细讲怎么配置模型包括免费模型和订阅模型的接入方式。opencode 首次启动的引导界面非常简洁如果你不想选也可以直接 CtrlC 退出先完成配置文件的手动编辑再进来。3. 模型接入免费模型、订阅模型、本地模型一网打尽3.1 opencode 的模型配置逻辑一切皆 APIopencode 对模型的处理方式和我用过的大多数现代 AI 工具不太一样。它把模型提供商抽象成统一的 OpenAI 兼容格式你只需要配置 base URL、API key、模型 ID就能接入几乎任何模型服务。配置文件默认在用户目录下Linux/macOS 是~/.config/opencode/opencode.jsonWindows 是%USERPROFILE%\.config\opencode\opencode.json。如果你打开发现整个目录都是空的不用担心先创建这个文件。下面是我的一个精简配置示例帮助你理解结构{ $schema: https://opencode.ai/config.json, provider: { default: myproxy, myproxy: { npm: ai-sdk/openai-compatible, name: myproxy, options: { baseURL: https://your-model-gateway.example.com/v1, apiKey: sk-your-key-here }, models: { claude-3-5-sonnet: { name: Claude 3.5 Sonnet }, qwen3-coder: { name: Qwen3 Coder } } } } }这里的npm字段是让 opencode 知道这个 provider 走的是 openai-compatible SDK。models下面是你想暴露给 opencode 的模型列表名字要和 base URL 提供商那边的模型 ID 一致。配好以后在 opencode 里用/models命令就能切换。3.2 免费模型的接入姿势热词里有 opencode 免费模型实际上 opencode 本身是开源软件不收费但模型 API 是否免费取决于你接的模型服务。目前比较靠谱的免费方案有几条路。第一条路是本地跑 Ollama。先在本地安装 Ollama拉一个 qwen3-coder 之类的模型然后 opencode 的 provider 配置 baseURL 指向http://localhost:11434/v1API key 随便填一个占位符就行。这种方案的好处是隐私性极好坏处是你得有一个性能还行的 GPU不然推理速度会比较难受。第二条路是用一些提供免费额度的在线模型服务。你只需要申请一个 API key然后把 baseURL 填成对应服务的地址。具体哪个服务稳定、现在还有没有免费额度变化非常快我建议以官方最新公告为准不要盲目囤 key。第三条路是热词里提到的 Muse Spark 1.3 FR 这类模型。我在测试时第一次接入也报错 this model is not available in your country这个后面我会专门讲怎么排查。这类模型通常也是 OpenAI 兼容接口配置方式和上面完全一样。区别是你要注意它的模型 ID 千万别填错。3.3 opencode go 订阅模型 ccswitch 到底指什么热词里反复出现 opencode go 订阅模型选择opencode go 需要配合 ccswitch 等工具这里面的 go 其实是某种订阅服务的名字。简单理解这是一种通过第三方订阅服务获取多个模型 API 访问权的方式。ccswitch 是一个用来管理这些订阅配置的小工具它可以把多个订阅服务统一管理生成环境变量或者配置文件。opencode 对这种场景支持得很好因为你完全可以在多个 provider 之间用/provider命令随时切换。但这种订阅服务有一个必须注意的安全问题永远不要在公共仓库里提交包含 apiKey 的 opencode.json。我建议把敏感信息放到环境变量里例如{ provider: { myproxy: { options: { baseURL: https://your-endpoint.example.com/v1, apiKey: {env:MODEL_API_KEY} } } } }然后在终端设置里提前导出MODEL_API_KEY环境变量。这样即使配置文件不小心被上传到 Git也不会直接泄露秘钥。3.4 接入 superpowers 增强包让 opencode 更像一个资深开发者热词里有 opencode 接入 superpower这个 superpowers 实际上是一套社区维护的提示词和技能增强包。装完之后opencode 会获得一套更系统的工程方法比如在改代码之前先分析影响范围、写更细的测试用例、以及更规范的 commit message 生成方式。我个人的体验是它确实能减少 AI 一上来就乱改代码的坏毛病。安装方式通常是把对应的 skill 目录放到~/.config/opencode/skills/下然后在 opencode 里通过superpowers引用。具体到版本可能有点差异建议装完以后用/skills命令查看当前是否识别到了技能。需要提醒的是superpowers 对 model 的要求略高我用便宜模型时出现过分析阶段做得很好、但执行阶段卡住的情况。建议这只在主力模型上开启跑弱模型时可以暂时禁用。4. Skills、Memory 和 LSP把 opencode 调教成老司机4.1 Skills 到底是什么别把它想复杂了Skills 在 opencode 里的定位很简单把一段固定的使用说明或者指令打包成一个可复用的技能。它和你在终端里打一段长 prompt 没什么本质区别但好处是封装后可以随时复用也能分享给团队其他人。我以前经常让 opencode 帮我写 commit message但每次都要在 prompt 里解释一遍要遵循 conventional commits 格式body 要写清楚影响范围。后来我建了一个 skill名字叫commit-helper内容就是一个 Markdown 文件写明规则和示例。之后我只需要打commit-helper 帮我提交当前改动它就会按照规则执行。整体结构一般是这样的~/.config/opencode/skills/ commit-helper/ SKILL.md run.shSKILL.md 里写清楚触发条件和规则run.sh 是可选的可执行脚本。opencode 里通过/skills可以查看所有已经加载的 skills。这个机制非常适合团队统一规范比如让所有成员都使用同样的代码审查清单、同样的发布检查流程。4.2 Memory 功能让 opencode 记住你的项目偏好官方开着 Memory 功能之后opencode 会把一些长期有用的上下文保存在磁盘上下一次启动时自动加载。比如你的项目喜欢用 pnpm 而不是 npm测试框架用的是 vitest 不是 jest发布流程走的是某个 CI 脚本。这些约定如果每次都得重新说一遍非常浪费 token。我的用法是在项目根目录维护一个AGENTS.md或者.opencode/memory.md文件里面写清楚项目结构、关键命令、编码规范。opencode 会在启动时自动读取。如果你不想手动维护也可以在对话里直接告诉它记住这个项目的测试命令是 pnpm vitest run它会自动写入记忆文件。这里有一个经验Memory 内容宁精勿多。如果文件里什么信息都有AI 在处理任务时分不清优先级反而可能把噪音当重要约束。我只记录会直接影响代码正确性或工程流程的信息。4.3 LSP 集成让 opencode 具备真正的代码分析能力热词里有 opencode 如何使用 lsp。LSPLanguage Server Protocol这个机制如果你用过 VSCode 应该不陌生它就是给编辑器提供代码补全、跳转、诊断信息的一整套协议。opencode 接入了 LSP 之后AI 不再只能靠正则或盲读来理解代码而是能像 IDE 一样拿到准确的语法错误、类型错误和符号定义。举个真实场景。我让 opencode 把某个 TypeScript 接口里新增一个字段它以前可能会改错引用的类型或者漏改其他调用处。但接入了typescript-language-server之后它会先通过 LSP 拿到所有引用点再逐个修改。这种准确率提升是质的飞跃尤其在中大型项目里。我目前用的 LSP 配置大概长这样{ lsp: { typescript: { command: typescript-language-server, args: [--stdio] } } }具体语言对应的 server 命名和参数可能不同建议启动 opencode 后用/lsp命令查看连接状态确保对应的 language server 显示为 connected。4.4 自己动手做一个 skill输出强制走团队规范最后分享一个我搭建代码审查 skill的过程你可以照着改成自己的规范。我的需求是让 opencode 在提交代码前做一轮自检比如检查是否有 console.log 残留、是否有硬编码的 API 地址、是否有 TODO 没处理。做法是创建code-review-checker目录SKILL.md 里写上检查清单。注意skill 的指令要尽量具体。不要说检查代码质量要说找出所有 console.log 语句并列出文件路径和行号。然后我再加了一个可选的run.sh让 opencode 执行一些简单命令来自动收集可疑信息。比如用grep -rn console.log src/快速定位日志输出。这样 AI 在开始分析前就有一份证据清单回答质量会高很多。这个 skill 配合 Memory 里的项目规范基本就等于给团队配了一个不会累的代码审查员。5. 编辑器集成与桌面版从纯终端走向日常开发流程5.1 VSCode 插件怎么选和直接在终端用有什么区别opencode 的一大优势是它不光能在终端里跑还提供了 VSCode 插件和 JetBrains IDEA 插件。很多人的疑问是既然终端里已经能用了为什么还要装插件我的体会是插件最大的价值在于上下文联动。比如你在 VSCode 里打开了一个文件选中了一段代码然后让 opencode 基于当前选区和整个 worktree 修复这个 bug它能直接拿到编辑器的选区信息和当前文件路径不需要复制粘贴路径也不用手动cd到目录。这在处理跨文件重构时非常有用。对于 JetBrains IDEA 用户opencode 的插件体验其实也不错。你可以把它当成一个智能终端面板直接在 IDE 里开一个 opencode 的会话让 AI 改代码的同时你还能继续在编辑器里浏览代码。插件和 CLI 后端共享同一套配置你在插件里的操作和命令行里是一致的不会有割裂感。5.2 桌面版 opencode desktop 值得用吗热词里有 opencode 桌面版。这个桌面版本质上是把终端 UI 包了一层图形界面依然不是网上那些上传代码文件然后聊天的网页工具。它适合那些不喜欢黑底白字终端、但想保留 opencode 全部能力的人。我个人的偏好是日常重度使用还是在真实的终端里因为终端里我可以同时开多个标签页配合 tmux 分屏更灵活。桌面版适合给那些刚接触 opencode、还不习惯命令行操作的同事用界面更友好一些上下文和会话管理的入口也更直观。不过无论你用哪种界面底层的配置、Skills、Memory、LSP 都是完全相通的。这一点很重要意味着你从终端切到桌面版不会有任何学习成本。5.3 把 opencode 接进日常 Git 工作流对我来说opencode 真正提升效率的场景不是让它一次性写一个巨大功能而是把它当成 Git 工作流里的中间人。比如我经常执行这样的流程写完代码后在终端里输入opencode然后说看一下当前 git diff帮我找出潜在 bug并补充缺失的测试用例。这种用法比让 AI 直接写登录功能要可靠得多因为任务边界非常清晰AI 只需要做 review 和补充而不是思考一个庞大需求的实现方案。我还习惯让它自动生成 PR 描述基于实际 diff 整理出改动模块、影响范围、测试情况这比手动写 PR 描述快太多。热词里有 opencode 接手开发项目这个场景其实也是基于 Git 工作流来理解。你先用git log --oneline把近期的提交历史喂给 opencode再让它读 README 和核心模块代码它能很快建立起对这个项目的认知。但别指望它一次读懂大型遗留系统耐心拆分任务才是正确用法。6. 实战让 opencode 用 Playwright 复现并定位前端 Bug6.1 为什么 AI 编程代理要配合浏览器自动化前端 Bug 是 AI 编程代理最容易翻车的场景原因是很多问题只有真实运行页面才能暴露出来。AI 光看代码经常觉得逻辑没问题但实际渲染出来的页面布局已经乱了。opencode 的解决方案是支持通过 Playwright 启动浏览器自动操作页面观察控制台报错和界面表现等于把用户实际操作搬到了 AI 面前。这个过程听起来很玄实际上就是在 opencode 的会话里让 AI 调用一个 Playwright 工具。它自己编写脚本、打开测试页面、点击按钮、输入表单、读取 console 日志然后把问题反馈回主对话里。我这里说的不是让 AI 单独写一个测试用例而是让 AI 为了定位 bug 而去主动调查页面。6.2 一个真实案例按钮点击无响应有次我遇到一个很诡异的问题页面上有个保存按钮点击后没有报错但请求一直没有发出去。我看代码看了很久没找到原因于是让 opencode 配合 Playwright 去复现。它做的事大概如下启动浏览器访问本地开发地址打开页面后控制台执行点击观察 network 面板发现点击事件根本没有触发网络请求。接着它检查了按钮上的事件绑定最后定位到是父组件的一个stopPropagation把点击事件拦截了导致子组件的监听器根本没机会执行。整个过程它只用了几分钟。如果靠我自己手动调试可能要在 React 组件树里一个个单位查看至少要多花两倍时间。这个案例让我真正认可了AI 编程代理 浏览器自动化的组合威力。6.3 Playwright 相关配置注意点要让 opencode 能用 Playwright核心要保证两点一是本机有可用的 Chromium 内核二是 opencode 有权限启动浏览器进程。我遇到过在 Linux 服务器上权限不够导致浏览器无法启动的问题解决办法是安装系统依赖并加上--no-sandbox参数。如果你只是想在本地开发环境里排查问题直接用正常工作目录启动 opencode 即可。如果你想让 opencode 访问需要登录的页面建议先在 Playwright 的持久化上下文里登录一次或者把 cookie 导入。没做这一步的话AI 打开的可能是一个未登录状态的页面复现不了真实问题。这里额外说一句opencode 在执行 Playwright 脚本时会产生大量中间输出如果模型上下文窗口不够大可能会忽略关键 console 日志。遇到这种情况我建议明确告诉它把 console 输出作为单独文本文件保存到 /tmp 下再分析。7. 常见问题排查与配置救急手册7.1 高频报错一unexpected server error这个报错在热词里也出现过error: unexpected server error. check server logs。通常原因是你配置的模型服务端出问题了。优先检查三件事。第一你的 API key 是否有效额度是否用完。第二baseURL 是否正确是否需要带/v1后缀。第三模型 ID 是否和该服务商实际支持的完全一致。很多时候模型 ID 只差一个点或者一个横线就会报 server error。排障时可以先用curl直接请求一次 API看看是不是 opencode 之外的问题。7.2 高频报错二this model is not available in your country这个报错我之前也遇到过是模型服务商根据 IP 或者账号归属地做的区域限制。解决办法不是去动模型服务商的后台而是换一个不做区域限制的模型商或者使用 中转网关 把请求转发到可用区域。在 opencode 里你需要检查两处一是 provider 的 baseURL 指向是否走对了网关二是 model 的 ID 是否填成了只对特定区域开放的版本。比如热词里的 Muse Spark 1.3 FR这类带明显区域标识的模型 ID在受限网络中尤其容易触发这个提示。不要和网络代理混淆这纯粹是模型服务本身的授权限制。7.3 高频报错三模型配好了但一直不可用如果你发现 opencode 里/models能看到模型名但发消息时一直转圈或者报错大概率是 provider 配置没有被正确加载。我的经验是每次改完配置文件后完全退出 opencode 再重新启动确保配置被重新读取。另外要注意如果配置了多个 provider一定要确认你当前选中的不是 tuned model比如配置里写了带特定后缀的微调版本实际不存在。排版和命名带来的这种问题非常隐蔽建议简化 provider 配置模型列表只留正在用的几个。7.4 建立自己的配置备份意识opencode 的配置分散在opencode.json、Skills 目录、Memory 文件里如果你花了很多精力调出一套好用的配置建议把这些都纳入 Git 管理。我是单独建了一个 dotfiles 仓库专门保存这些配置文件并且通过脚本一键生成软链接。这样做的最大好处是换机器时不需要重新折腾。另外opencode 更新频率很快有些字段可能在新版本里被废弃定期看一下官方 release notes 能省掉不少排障时间。8. 几个 Agent 的横向对比opencode、Codex、Claude Code、Pi 怎么选对比维度opencodeClaude CodeCodex CLIPi 工具模型来源灵活任意 OpenAI 兼容 API / 本地模型绑定 Claude 官方绑定 OpenAI 模型部分场景绑定特定服务多模型切换支持多 provider切换方便基本不支持或很麻烦不支持看版本通常有限Skills 机制有支持自定义类似功能较封闭有限轻量Playwright/工具调用支持配置清晰支持支持较弱上手成本中等配置稍多低开箱即用低最低适合人群喜欢自己掌控一切的技术爱好者官方订阅用户OpenAI 重度用户快速单文件修改看到这个表你可能会觉得opencode 怎么什么都占优势。其实不是它的成本隐藏在配置和调教上。如果你完全不想管模型、不想折腾 JSON 配置文件Claude Code 的开箱体验确实更省心。opencode 的理念是用户拥有完全的灵活性所以它把选择权和复杂度都交给了你。我的建议很简单如果你手里有多张模型 key 或者公司有自己的模型网关值得多花一小时把 opencode 配好如果你只是个人自费用户且主力就是 Claude那继续用 Claude Code 也没什么问题。工具是手段不是目的。最后说一个我在实际使用中最受益的小习惯每次接手一个新项目我会先在项目里维护一份高质量 AGENTS.md告诉 opencode 项目结构、启动命令、测试规范、部署注意点。这比任何模型参数调优都更能提升最终效果。opencode 强在它是开放的你可以把它塑造成适合你团队工作流的样子而不是强迫自己去适应一个既定工具。这种自由度我觉得是它这轮热度能一直维持下去的真正原因。
