OpenCode安装配置实战：如何用它接管老项目并替代Claude Code

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 最初的作者是SST（Serverless Stack）团队，一个做全栈 Serverless 框架的老牌开源团队。但这里有个特别容易踩的信息差：

• SST 团队的 OpenCode：一个开源 Terminal AI Agent，GitHub 上直接能下。
• 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）。直接说结论，避免你浪费时间：

我最看重的其实是它跟 Playwright 的配合方式。传统做法是你得单独写测试脚本、单独跑命令行，opencode 是直接让 agent 调浏览器帮你看页面表现，相当于它自己就能"亲手验证"前端 bug 是否修复。

2. 安装和第一个报错：无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名

这是搜索热度最高的一个报错，几乎每个 Windows 用户第一次装都会撞上。我在 Windows 11 上实操时也踩了一遍，完整复盘一下。

2.1 正确安装流程（Windows / macOS / Linux）

官方推荐的方式是直接用 npm 全局安装：

npm install -g opencode-ai

macOS 也可以走 Homebrew：

brew install sst/tap/opencode

Linux 用户如果不想用 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，或者当前终端会话没有重新加载环境变量。

排查步骤：

1. 先找到 npm 全局目录到底在哪：

npm prefix -g

在 Windows 上我这里是C:\Users\你的用户名\AppData\Roaming\npm。

2. 看这个目录下有没有opencode.cmd或opencode可执行文件：

dir C:\Users\你的用户名\AppData\Roaming\npm

如果你看到了opencode相关文件，说明装成功了，只是 PATH 问题。

3. 把该目录手动加进系统环境变量：

• Win + R 输入sysdm.cpl打开系统属性
• 高级 → 环境变量
• 在"用户变量"里找到 Path，编辑，新增一行填上面那个 npm 全局目录
• 确定保存，然后彻底关掉终端重新开

4. 假如你在 Windows Terminal 里更新完 PATH 还是不行，试试：

refreshenv

如果这个命令也提示不存在，那就老老实实重开终端。不要只关标签页，要完全退出 Windows Terminal 进程再重开，因为终端的环境变量缓存是继承自父进程的。

2.3 第二个高频坑：error: unexpected server error. check server logs

这个报错我搜了一下，英文社区的讨论热度也很高。它的出现场景通常是：你已经能执行opencode命令了，但输入任务后没反应几秒就报这个。

根因如下：

• opencode 本身是一个客户端，它需要跟模型 API 服务通信。凡是出现unexpected server error，基本都是模型服务端返回了一个客户端无法识别的错误格式。
• 最常见的情况是你配置了错误的基础 URL（baseURL），或者 API Key 所属的服务商不兼容 opencode 的请求格式。
• 其次可能是你选中的模型名在服务商那边根本不存在，比如你写的是gpt-5但实际接口只提供gpt-5.1。

解决思路：

1. 运行opencode进入 TUI 后，按/models打开模型选择页，确认你选的模型在配置里存在。
2. 检查配置文件opencode.json（在项目根目录或~/.config/opencode/下）里的provider字段：

{ "$schema": "https://opencode.ai/config.json", "provider": { "baseURL": "https://api.你的服务商.com/v1", "apiKey": "sk-xxxx", "model": "gpt-4o" } }

3. 如果你的服务商其实是 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，优先级是：

1. 项目根目录opencode.json
2. 全局用户目录~/.config/opencode/opencode.json
3. 环境变量里的默认值

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 MCP（Model Context Protocol）工具，所以它可以直接控制浏览器。实操步骤非常简单：

1. 在 opencode 对话里输入一个带前端复现路径的任务，例如：

帮我打开 http://localhost:5173 ，点击登录按钮，看控制台有没有报错，如果有报错把完整调用栈贴出来。

2. opencode 会自动调用 Playwright 工具，启动一个浏览器实例，填写表单、点击按钮、监听 console。不需要你自己写任何测试脚本。

3. 如果发现了报错，它会带着截图和 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.md

SKILL.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时我一般按这个顺序查

1. 确认网络可达：在终端里直接curl一下你的 API baseURL，看能不能通。
2. 确认 API Key 所属服务商跟 endpoint 匹配：用 OpenAI 的 key 去请求 Anthropic 的地址，必然失败。
3. 确认模型名精确匹配：很多网关模型名带版本后缀，漏一个点都会 400。
4. 查看 opencode 自己的日志：opencode 的日志默认打在~/.local/share/opencode/log/（Linux/macOS）或%USERPROFILE%\.local\share\opencode\log\（Windows）。把异常 stack 贴给模型服务商客服，基本能快速定位。
5. 切换 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 的真正分水岭。