OpenCode 让我把 Claude Code 彻底扔进了垃圾桶先说结论OpenCode 是我目前用过的所有 AI 编程终端工具里最接近测试驱动开发直觉的一个。它不像 Claude Code 那样动不动就自作主张改文件也去掉了一堆华而不实的交互特效反而把playwright跑前端回归、终端内直接看 git diff、LSP 报错实时注入这几个场景做到了让人拍大腿的程度。这篇不是官方文档复读是我过去两周拿它接手一个真实项目的完整记录包括怎么装、怎么配模型、怎么让它别乱改我的代码、以及那几个报错到底是什么意思。1. 先说这玩意儿到底是什么以及它和 Claude Code / Codex 的区别OpenCode 是一个运行在终端里的 AI 编程代理Terminal AI Agent核心逻辑是你给它一个任务它自己读代码、自己想步骤、自己调工具执行然后停下来给你看结果。它支持任意 OpenAI 兼容的模型接口也内置了对 Anthropic、Google 模型的支持而且最友好的一点不需要你非得有 ChatGPT Plus 或者 Claude 订阅才能用只要你手里有任何一家能调通的模型 API 就行。我为什么会从 Claude Code 迁过来不是因为它功能不够而是用久了会发现两个问题Claude Code 的默认行为偏主动很多时候我只是让它看一段代码它已经开始重构了。终端对话界面太重上下文的记忆特别容易乱会话一长就像在跟一个喝了三杯咖啡的人聊天跳跃性极强。OpenCode 的结构更像一个懂命令行的结对程序员。它默认不会在你没确认之前动任何文件所有动作写文件、改文件、跑命令都会先给你一个计划你按y它才执行。这个心智模型非常适合接盘老项目——你先让它读、让它解释、让它出方案再逐步放开修改权限。1.1 OpenCode 是哪家公司的为什么这个问法本身就有误区opencode 是哪家公司的是最近一个很火的热搜词。其实 OpenCode 最初的作者是SSTServerless Stack团队一个做全栈 Serverless 框架的老牌开源团队。但这里有个特别容易踩的信息差SST 团队的 OpenCode一个开源 Terminal AI AgentGitHub 上直接能下。OpenCode 这个产品名本身在 AI 工具爆发期很多团队都起了类似名字你搜出来的可能是个 IDE 插件、也可能是个模型网关甚至可能是个文本编辑器。不要跟 codex、Codex CLI 混淆OpenAI 的 Codex 是闭源产品线OpenCode 是开源社区项目两个完全独立。所以当你搜 opencode 是哪家的 时核心问题其实是我下载的到底是哪个 opencode。最简单可靠的分辨方法看安装命令是不是npm i -g opencode-ai。凡是让你装opencode或opencode-ai的基本都是 SST 这个生态的。1.2 和 Claude Code、Codex CLI、Pi 相比它到底赢在哪我最近同时装了四个工具日常交叉使用Claude Code、Codex CLI、opencode、pi这是另一个开源 agent。直接说结论避免你浪费时间对比维度Claude CodeCodex CLIopencodepi默认是否直接改文件偏主动容易自作主张谨慎但有边界问题默认只读按确认才写也是确认制但工具链浅多模型切换强绑 Claude 订阅强绑 OpenAI任意兼容接口支持有限浏览器自动测试无无内置 Playwright无终端 git 体验一般一般diff 直接内嵌终端弱对老项目的读取理解优秀中优秀中我最看重的其实是它跟 Playwright 的配合方式。传统做法是你得单独写测试脚本、单独跑命令行opencode 是直接让 agent 调浏览器帮你看页面表现相当于它自己就能亲手验证前端 bug 是否修复。2. 安装和第一个报错无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名这是搜索热度最高的一个报错几乎每个 Windows 用户第一次装都会撞上。我在 Windows 11 上实操时也踩了一遍完整复盘一下。2.1 正确安装流程Windows / macOS / Linux官方推荐的方式是直接用 npm 全局安装npm install -g opencode-aimacOS 也可以走 Homebrewbrew install sst/tap/opencodeLinux 用户如果不想用 npm还可以直接下载二进制包GitHub Releases 页面有opencode-linux-x64.zip之类的文件解压后扔到/usr/local/bin。装完之后验证opencode --version注意这里有个坑。早期版本的包名叫opencode后来为了跟其他同名项目做区分改成了opencode-ai。如果你按老教程装了npm install -g opencode装的是一个可能完全不同的包。所以无论你看到什么教程第一件事先确认你装的是opencode-ai。2.2 报错的根因不是你没装而是 PATH 没生效如果你明明执行过 npm install 且没有任何报错但新开终端输入 opencode 提示无法识别问题基本出在npm 全局安装目录没有加入系统 PATH或者当前终端会话没有重新加载环境变量。排查步骤先找到 npm 全局目录到底在哪npm prefix -g在 Windows 上我这里是C:\Users\你的用户名\AppData\Roaming\npm。看这个目录下有没有opencode.cmd或opencode可执行文件dir C:\Users\你的用户名\AppData\Roaming\npm如果你看到了opencode相关文件说明装成功了只是 PATH 问题。把该目录手动加进系统环境变量Win R 输入sysdm.cpl打开系统属性高级 → 环境变量在用户变量里找到 Path编辑新增一行填上面那个 npm 全局目录确定保存然后彻底关掉终端重新开假如你在 Windows Terminal 里更新完 PATH 还是不行试试refreshenv如果这个命令也提示不存在那就老老实实重开终端。不要只关标签页要完全退出 Windows Terminal 进程再重开因为终端的环境变量缓存是继承自父进程的。2.3 第二个高频坑error: unexpected server error. check server logs这个报错我搜了一下英文社区的讨论热度也很高。它的出现场景通常是你已经能执行opencode命令了但输入任务后没反应几秒就报这个。根因如下opencode 本身是一个客户端它需要跟模型 API 服务通信。凡是出现unexpected server error基本都是模型服务端返回了一个客户端无法识别的错误格式。最常见的情况是你配置了错误的基础 URLbaseURL或者 API Key 所属的服务商不兼容 opencode 的请求格式。其次可能是你选中的模型名在服务商那边根本不存在比如你写的是gpt-5但实际接口只提供gpt-5.1。解决思路运行opencode进入 TUI 后按/models打开模型选择页确认你选的模型在配置里存在。检查配置文件opencode.json在项目根目录或~/.config/opencode/下里的provider字段{ $schema: https://opencode.ai/config.json, provider: { baseURL: https://api.你的服务商.com/v1, apiKey: sk-xxxx, model: gpt-4o } }如果你的服务商其实是 Anthropic 的兼容接口需要看它对外暴露的是 OpenAI 格式还是 Anthropic 原生格式。OpenCode 默认很多 provider 走的是OpenAI 兼容格式这通常是多数报错的源头——你填的是 Anthropic 的 key但 opencode 按 OpenAI 的 Authorization 头去请求服务端自然不认识。3. 模型配置与免费模型的正确姿势opencode 的配置逻辑其实很简单一切以 provider 为维度每个 provider 可以有不同的模型列表。看不懂配置文件没关系TUI 里改是更友好的方式。3.1 首次启动与配置文件生成安装完成后直接在项目目录执行opencode第一次会进入一个欢迎界面让你登录或者选 provider。如果不想交互式配置也可以提前写好配置文件。openCode 的配置文件支持 JSON 和 JSONC 格式默认文件名是opencode.json优先级是项目根目录opencode.json全局用户目录~/.config/opencode/opencode.json环境变量里的默认值3.2 免费模型到底怎么接搜索热度里 opencode 免费模型、opencode 免费模型 下载 都排得很前。坦白讲大模型 API 没有完全免费这一说但确实有免费额度和限时免费渠道。我实测下来免费或低成本方案有这么几个OpenRouter 的免费模型OpenRouter 本身有:free后缀的模型比如deepseek/deepseek-chat:free、qwen/qwen-2.5-72b-instruct:free等。在 opencode 的 provider 里配 OpenRouter 的 API 地址和 key就能白嫖这些。GitHub Copilot 的模型接口如果你有 GitHub Copilot 订阅甚至有的账户有免费试用它底层也是 OpenAI 兼容接口可以把 endpoint 配进去。实际上是绕个道用 Copilot 的模型额度。本地模型Ollama / LM Studio如果你有显卡本地跑qwen2.5-coder:32b或者deepseek-coder-v2这种模型配合 opencode 的本地 baseURL 也是完全可行的。体验取决于你的显存32B 模型至少需要 24G 显存16G 显存只能跑 14B 左右的模型编码能力还行但跟云端旗舰模型差距明显。3.3 我建议的配置模板下面是我目前一直在用的配置接的是 OpenRouter 的免费模型日常用来做代码解释和测试脚本编写完全够用{ $schema: https://opencode.ai/config.json, provider: { baseURL: https://openrouter.ai/api/v1, apiKey: 你的OpenRouterKey, model: deepseek/deepseek-chat:free } }如果你用的是 Claude 官方 API{ $schema: https://opencode.ai/config.json, provider: { type: anthropic, apiKey: 你的ClaudeKey, model: claude-sonnet-4-20250514 } }注意如果你同时配了多个 provider启动 opencode 后按Ctrl P可以在不同 provider 之间快速切换模型不需要改配置重启。这个是开源版就已经有的功能新版还加了 session 级的 provider 记忆。3.4ccswitch与oh-my-claudecode的作用热词里出现了 opencode go 需要配合 cc switch 等工具、oh-my-claudecode。这些其实都是模型代理切换工具链的一部分。ccswitch全称 Claude Code Switch本质上是一个管理 Claude Code 配置的多环境切换工具它可以把你的 Anthropic API Key 按照不同场景公司、个人、代理池自动切换。opencode 本身不依赖 ccswitch但如果你同时用 Claude Code 和 opencode且你通过某个中转站拿 Anthropic 模型那你可以把 ccswitch 生成的环境变量直接喂给 opencode。oh-my-claudecode则是一个开箱即用的 Claude Code 配置增强包里面预置了 CLAUDE.md、skills、MCP 配置等。它的价值在于把很多社区验证过的 prompt 工程实践打包了。opencode 也可以复用里面的一些 skill 目录openCode 的 skills 机制跟 Claude Code 的 skills 目录结构兼容可以直接把~/.claude/skills里的东西复制到~/.config/opencode/skills下。4. 把 OpenCode 变成接手老项目的第一助手这部分是我最想写的。因为工具装上容易真正让它在一个不是你写的项目里产生价值需要掌握几个非常核心的工作流。4.1 不开放写权限先让它读代码接手老项目时我强烈建议你在配置里先把自动写入关掉。在opencode.json里{ permission: { edit: ask, bash: ask } }这样 opencode 任何写文件/执行命令的操作都会先问你不会自作主张。你可以在启动后用/permissions查看当前的权限策略。实测体验让 opencode 先解释项目结构、再定位某个 bug 的可能位置最后提出修改方案。这整个过程完全不会污染代码特别爽。等你对它有信任感了再逐步放开。4.2 Playwright 实测前端 Bug 的正确打开方式开篇提到的 playwright 热词这里必须展开讲。OpenCode 内置了 Playwright MCPModel Context Protocol工具所以它可以直接控制浏览器。实操步骤非常简单在 opencode 对话里输入一个带前端复现路径的任务例如帮我打开 http://localhost:5173 点击登录按钮看控制台有没有报错如果有报错把完整调用栈贴出来。opencode 会自动调用 Playwright 工具启动一个浏览器实例填写表单、点击按钮、监听 console。不需要你自己写任何测试脚本。如果发现了报错它会带着截图和 console 日志继续分析代码找出可能原因。这里有个体验差异Claude Code 没有内置浏览器工具Codex CLI 也没有。你要么写脚本要么另开一个浏览器手动看。OpenCode 把操作浏览器和读代码整合到了同一个 agent loop 里这是真实效率提升。4.3 LSP 报错实时注入相当于让 IDE 的红色波浪线开口说话热词里还有 opencode 如何使用 lsp。这个功能很多新手不知道但它是 opencode 的核心杀手锏之一。它会在后台启动你项目对应的 Language Server比如 TypeScript 的 tsserver、Python 的 pyright然后实时检测代码改动产生的诊断信息errors/warnings并作为上下文注入到对话流中。这意味着什么呢当 opencode 写完一个函数它会立刻看到第 15 行有个 TS2322 错误类型 X 不能赋给类型 Y然后自己继续修改直到诊断干净。使用前需要确保你本机装了对应的 LSP 客户端。以 TypeScript 为例npm install -g typescript-language-server typescript然后在 opencode 里执行/lsp就能看到当前项目检测到的语言服务器列表。如果你用 IDEA 或 VS Code 插件模式它也支持相同的 LSP 能力配置。IDEA 的 opencode 插件可以直接复用 IDE 内建的语言分析能力体验和终端版基本一致。4.4 Memory 和 Skills让工具记住项目的潜规则热词里的opencode memory、opencode skills指的是两块独立能力Memory保存跨会话的历史决策。比如你告诉过它本项目不允许使用 any 类型、测试文件必须放在 tests/ 目录等规则这些会写入 memory下次会话自动加载。在 opencode 对话框里可以直接用/memory查看和编辑。Skills一组预定义的工作流技能比如编写 React 组件时遵循某个规范、遇到 API 错误优先看网关日志等。实际上就是一个 markdown 文件目录每个目录里有一个 SKILL.md我用一个简单示例来演示~/.config/opencode/skills/ └── frontend-bugfix/ ├── SKILL.md └── references/ └── debug-workflow.mdSKILL.md 内容--- name: frontend-bugfix description: 修复前端 bug 时先复现再定位再修复再回归 --- 当用户反馈前端问题时 1. 先用 playwright 打开对应页面复现 2. 查看控制台报错 3. 根据调用栈定位组件文件 4. 修复后重新跑一遍 playwright 流程确认配置好之后当任务符合触发条件时opencode 会自动加载这个 skill 作为行为指导。这比在对话里反复强调规则要稳定得多相当于把团队的开发规范内化成了 agent 的肌肉记忆。5. 高频报错的排查链路从识别不了到模型不可用搜索热词里有一串报错我来逐一拆解这些报错我基本全都撞过有些至今还在踩。5.1this model is not available in your country这个报错几乎都是因为模型服务商根据 IP 做了地区限制。解决办法事实上只有两条路换一个地区可用的模型例如把claude-opus-4-20250514换成claude-sonnet-4-20250514换一个不做地区限制的服务商比如某些国内大厂的兼容接口或自建网关。5.2opencode go 订阅模型选择/opencode go 套餐opencode go现在有两个含义一个是 opencode 团队推出的托管云版OpenCode Go类似 Claude Code 的订阅服务提供他们自建的模型网关和套餐另一个是社区里用 go 语言重新实现的某个客户端项目。搜索时要看清楚你问的是哪个。如果你用的是 OpenCode Go模型选择一般直接写opencode/go这种命名格式。但如果你配置的是第三方网关模型名要以网关提供的模型列表为准这个没法统一必须去你自己的服务商后台查。5.3mvn配置与 Java 项目的集成热词里还有opencode mvn配置。OpenCode 本身没有 maven 的专属指令但是它可以调用终端命令所以对 Java 项目的处理逻辑是让它读 pom.xml然后执行mvn test或mvn compile来验证自己的修改是否通过编译。你不需要额外装任何 MCP 工具只需要让 opencode 保留终端执行权限bash: allow即可。相比其他 agent 对 Java 项目生态的不熟悉opencode 的优势在于它可以自己读 Maven 报错并修正依赖问题比如补全缺失的 dependency、调整 Java 版本我实测在 Maven 项目里还挺稳。5.4 排查链路遇到unexpected server error时我一般按这个顺序查确认网络可达在终端里直接curl一下你的 API baseURL看能不能通。确认 API Key 所属服务商跟 endpoint 匹配用 OpenAI 的 key 去请求 Anthropic 的地址必然失败。确认模型名精确匹配很多网关模型名带版本后缀漏一个点都会 400。查看 opencode 自己的日志opencode 的日志默认打在~/.local/share/opencode/log/Linux/macOS或%USERPROFILE%\.local\share\opencode\log\Windows。把异常 stack 贴给模型服务商客服基本能快速定位。切换 provider 再切回来有些情况下是 opencode TUI 的会话状态坏了重开一个 session 就能好。6. 桌面版、VSCode 插件和 IDEA 插件从终端走向编辑器很多人不习惯纯终端操作热搜词里的opencode desktop、vscode opencode插件、idea opencode插件覆盖的就是这个需求。6.1 OpenCode Desktop 和 VS Code / IDEA 插件的区别桌面版本质是把 TUI 封装成了独立窗口适合不想开终端的人底层逻辑跟命令行版完全一致。VS Code 插件能在编辑器侧边栏直接跟 agent 对话可看到内联 diff、逐行接受修改适合 VS Code 用户。IDEA 插件JetBrains 全家桶用户使用的版本跟 IDEA 的本地索引、LSP 诊断集成度更高。这三个端我都在用日常主力是 IDEA 插件因为我的 Java 项目多IDEA 的索引和理解能力比独立 LSP 更好。但要说纯粹的速度和轻量感终端版始终是最顺手的。6.2 IDE 插件里的权限设置和对话流程以 VS Code 插件为例装完后需要先在插件设置里配置 provider 信息插件的配置跟终端版是独立的不要把两者混为一谈。我建议在 IDE 插件里把权限设置为全 ask因为你既然在编辑器里会有更强烈的确认意愿。而在纯终端里为了效率可以放得更宽。6.3 Desktop 版的隐藏优势多会话管理和后台任务桌面版有一个终端版没有的体验后台运行 agent 任务。终端版如果关闭窗口任务就断了Desktop 可以最小化继续跑。比如我在让 opencode 批量重构时切到浏览器等其他工作等它跑完给我全局通知体验很接近 CI 任务。7. 一个完整的实操案例用 OpenCode 从零跑通前端 Bug 修复最后用我这周的真实操作来做一次完整复盘。项目是一个 React TypeScript Vite 的中台系统接手时已知两个 bug一是登录按钮点击后偶发无反应二是某个表格在切换筛选条件时会把列搞丢。7.1 让 OpenCode 先做代码勘察项目根目录执行opencode输入先读一下 src/pages/Login 目录下的代码分析登录按钮绑定了什么 handler以及它的依赖数组是否有问题。它先扫了目录然后给出了分析handler 内部用了useCallback但依赖数组漏了form实例导致闭包捕获了旧的 form 值部分浏览器环境下事件触发不稳定。7.2 用 Playwright 复现 bug接着输入启动 dev server用 playwright 打开登录页点击登录按钮 10 次记录 console 是否有错误。它自己执行了npm run dev然后用 Playwright 打开http://localhost:5173点击按钮 10 次。结果捕获到一条Cannot read properties of undefined (reading validate)。它把这条日志跟代码定位关联上了——就是闭包导致 form 变量为 undefined 时抛错。7.3 让它修复并跑回归修复这个问题注意不要改动其他文件修完后重新跑一遍 playwright 验证。它在源码里改了依赖数组加了form。然后重新启动浏览器跑了 10 次点击未再出现该报错并自动运行了项目已有的npm run test确保单测通过。全程我只在关键节点按了确认键没有手动改一行代码。7.4 关于表格列丢失的问题表格问题它定位到了columns的 useMemo 依赖项没有包含筛选条件字段于是切换条件下生成的 columns 组件因为引用未变而跳过重渲染直接显示空白。修复逻辑同样是补依赖项。两个 bug 的根因都是 React hooks 闭包/缓存的老问题OpenCode 的 LSP 注入在这个案例里起了很大作用——它能在改完代码的瞬间看到类型和逻辑诊断是否有异常。8. 关于 OpenCode 2.0 和后续扩展热词里出现的opencode 2.0其实指代的是最近的较大版本更新核心变化包括更稳定的 LSP 集成、Playwright 工具链的增强、以及新增了对更多 provider 的原生支持。如果你之前用过 1.x 版本觉得卡顿2.0 的整体响应流畅度提升很明显。更进一步你可以把 opencode 接到自己的自动化流程里比如在 CI 里用opencode run 修复 lint 错误这种方式做自动修码配合 GitHub Actions 让它自动 review PR 并给出修改建议配合 superpower热词里的接入superpower这类 MCP 增强插件扩展它读取数据库结构、调用内部 API 的能力Superpower 本身是一个 MCP 服务集合给 opencode 加上之后它就能看到你的数据库表结构和内部接口文档这对于写业务代码的准确性提升非常大。配置方法就是在 opencode 的 MCP 设置里加上 superpower 提供的 endpoint它会自动把工具注册进 agent 的工具列表。最后说点个人体会OpenCode 不是那种装上就能一夜变强的神器它更像一把好用的瑞士军刀——真正决定效率的是你怎么定义任务、怎么设置权限、怎么把团队的规范沉淀成 skills。我用它接手老项目两周最大的变化是我跟代码库之间的沟通成本明显降低了以前要让新人读懂一个模块要花半小时讲解现在直接让 opencode 读一遍再解释给我听我自己只需要验证它的理解是否正确。如果你准备从 Claude Code 迁过来我的建议是先跑一周只读模式手写确认等摸清它的脾气再放开权限。如果你只是想找一个开箱即用的 AI 编程助手那它也是目前学习曲线最平滑的一个。装好之后记得多试试/lsp和内置的 playwright这两个功能才是它区别于其他终端 agent 的真正分水岭。