opencode 实战：统一 Codex、Claude Code 与免费模型的 AI 编码代理指南

我先直接说结论：如果你平时已经在用 Claude Code 或 Codex 这类终端 AI 编程代理，那 opencode 大概率能让你在“模型自由度”和“项目改造”这两件事上打开新世界。我前后折腾了大概一个周末，把把它当成主力工具接进了日常开发流程。这篇文章就是基于这段时间的实测经验写出来的，尽量说人话、给可复现的配置，不搞那些抄文档式的流水账。

1. 先说清楚：opencode 到底是什么，跟 Codex、Claude Code 的差别

很多人第一次看到 opencode 这个名字，第一反应是“又一个 AI 编程 CLI”。这话对了一半。它确实是个跑在终端里的 AI 编码代理，但它的定位和 Claude Code、Codex 有明显的差异点。

1.1 它不是一个模型，而是一个“模型路由器”加“代理框架”

opencode 本身不内置模型。它的核心是提供一个交互层和工作流引擎，通过 provider 配置把不同家的大模型接入到同一个终端界面里。你可以今天用 DeepSeek，明天切 GPT-5，后天再换成本地 Ollama 起的 Qwen，而不需要重新熟悉一套工具。

我用一个类比来解释：Claude Code 像是一把专门为 Claude 调校的瑞士军刀，Codex 像是 OpenAI 出的折叠刀，而 opencode 更像是一个标准刀柄，你往上面装哪种刀片都行。这个“刀柄”的能力上限取决于你接进去的模型有多强，但“换刀片”的体验是 opencode 最值钱的地方。

1.2 为什么这么多人拿它跟 codex、pi 比

在热搜词里能看到大量“opencode codex pi哪个agent好用”“opencode codex claude code”这类对比，说明大家并不是在找一个新玩具，而是在认真评估主力工具。我实际的体感是：

• 如果你重度依赖 Claude 的长上下文和代码风格理解，Claude Code 依然是最顺手的；
• 如果你恰好有 OpenAI 系的 API 配额，Codex 的生态集成（比如沙箱）很省心；
• 但如果你手上有多个模型渠道、需要团队内统一工具链、或者想白嫖一些免费模型额度，opencode 是这几个里最灵活的。

这个“灵活”不是嘴上说说。opencode 的 provider 机制允许你在一个配置文件里维护多套模型接入信息，配合 opencode 自带的模型切换指令，不用每次改环境变量重启进程。我后面会专门讲这块怎么配。

1.3 适合谁来用

如果你属于下面三类人之一，这篇文章值得看完：

• 在 Claude Code 和 Codex 之间来回纠结，想找个统一入口的人；
• 希望在不增加太多成本的情况下，把免费模型或开源模型接入正经开发流程的人；
• 手上有一堆老项目，想用 AI 代理快速“接手”并完成 bug 定位、重构、写测试的人。

至于第一次接触终端 AI 代理的人，我也尽量在关键步骤上给足前置说明，照抄也能跑通。

2. 安装和第一次启动：两条最容易踩的坑

opencode 的安装方式不复杂，但它跨平台的处理细节挺影响体感。很多人卡在第一步就放弃了，其实都是些小问题。

2.1 官方安装脚本与 Go 安装路径

opencode 官方提供了一条安装命令，在类 Unix 系统（macOS、Linux）下执行：

curl -fsSL https://opencode.ai/install | bash

它默认会把二进制放到~/.opencode/bin下，然后在 shell 配置里追加 PATH。如果你习惯了 Go 的生态，也可以用下面的方式安装：

go install github.com/sst/opencode@latest

这里要插一句个人建议：二选一即可，不要两个都装。我最初就是因为先跑了go install，又跑了一次官方脚本，结果两个版本的 opencode 同时在 PATH 里，后续排查问题时根本分不清自己在用哪个版本。

opencode --version

这个命令可以确认当前生效的版本。如果输出结果是opencode: command not found，多半是 PATH 没配对。

2.2 Windows 上“cmdlet 无法识别”的完整修复过程

热搜里有一条很扎眼：“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这句话大概率是 Windows PowerShell 用户在安装完成后，直接开新窗口执行opencode时看到的。

这里必须先解释一下原因，不只是给解决办法。PowerShell 在解析命令时，只会在当前目录和 PATH 环境变量列出的目录里找可执行文件。安装脚本自动加的路径如果没生效，自然就报这个错。常见原因有两个：

• 安装脚本写入的是用户级环境变量，修改后需要完全关闭并重开PowerShell 窗口才会重新读取；
• 脚本写入的路径和你实际安装目录不一致，比如你用了管理员权限安装，但当前用户会话没有该路径的读权限。

处理办法如下：

1. 先确认二进制实际位置。默认在C:\Users\你的用户名\AppData\Local\opencode\bin。
2. 手动把该目录加到用户 PATH：

[Environment]::SetEnvironmentVariable( "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\你的用户名\AppData\Local\opencode\bin", "User" )

3. 重新打开 PowerShell 窗口，运行opencode --version验证。

另外，如果你用的是 Windows Terminal 或 VS Code 集成终端，有时候还需要重启一下编辑器才能识别新环境变量。这不是玄学，是这些应用在启动时缓存了环境变量快照。

2.3 第一次启动：模型配置从哪一步开始

安装完成后直接运行opencode，不一定能立刻用。它需要一个模型来源，常见的做法是先在环境变量里设一个主供应商的 API Key。假设你用的是 Anthropic：

export ANTHROPIC_API_KEY=sk-ant-xxxx opencode

如果你一个 key 都不想配，opencode 也支持通过配置文件里声明的免费模型来跑，具体模型配置放下一章讲。这里先给出一个最基础的雏形，保证你能看到交互界面：

启动后你会看到一个命令行交互界面，底部有一个输入框，直接在>后面输入自然语言任务就行。比如：

> 帮我解析当前目录下的 package.json，并列出所有 scripts

正常情况下，它会调用模型、读取文件、给出结果。对第一次使用的人，这一步跑通的意义比什么都大，因为后续所有高级功能都是在这个交互基础上叠加的。

3. 模型配置与多供应商切换：免费模型到底怎么接

opencode 真正让我愿意长期用的原因，就是它的模型配置层。它没有把“某一家模型”绑死，而是定义了一套 provider 体系。这一部分可能是全网最容易被忽略但又最实用的内容。

3.1 provider 配置文件的基本结构

opencode 的配置文件默认放在~/.config/opencode/opencode.json（macOS/Linux）或%USERPROFILE%\.config\opencode\opencode.json（Windows）。打开后的初始内容类似于：

{ "$schema": "https://opencode.ai/config.json", "provider": {} }

我们需要往里塞模型。以接 DeepSeek 为例：

{ "$schema": "https://opencode.ai/config.json", "provider": { "deepseek": { "npm": "@ai-sdk/deepseek", "name": "DeepSeek", "options": { "baseURL": "https://api.deepseek.com", "apiKey": "{env:DEEPSEEK_API_KEY}" }, "models": { "deepseek-chat": { "name": "DeepSeek V3" } } } } }

这里有三个关键字值得理解：

• npm字段告诉 opencode 需要加载哪个 AI SDK 包来和该服务商通信；
• options.baseURL是接口地址，如果你公司内部有 OpenAI 兼容网关，这里也能指向内网地址；
• models里列出该服务商下可用的模型 ID，ID 必须和 API 实际模型名一致。

配置完成后，设置环境变量DEEPSEEK_API_KEY，重启 opencode，就能在模型选择列表里看到 DeepSeek V3。

3.2 免费模型省钱的实操方案

“opencode免费模型”这个热搜词说明大家都在寻找低成本方案。先说清楚：真正“完全免费且达到生产级别”的模型并不多，但 opencode 在承接这类需求时有一个天然优势——它兼容 Ollama 这类本地模型服务。

本地模型的做法是：先装好 Ollama，拉一个编码能力还行的模型，比如qwen2.5-coder:14b，然后疯狂点击这个地址：

ollama serve

opencode 的配置里加一段：

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "name": "Ollama", "options": { "baseURL": "http://localhost:11434" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen 2.5 Coder 14B" } } } } }

不用设 API Key，直接用。它的接口是 Ollama 原生格式，opencode 内部做了适配。

从我的实测来看，14B 的模型做代码解释、补全、简单重构完全够用；但如果你让它跨多个文件改业务逻辑，它的上下文理解还是不如云端大模型。所以我的建议是：本地免费模型用来跑高频小任务，比如写测试、格式化代码、翻译注释；大活比如跨文件重构、排查诡异线上 bug，切回云端模型。

3.3 用 ccswitch 管理一整套配置

热搜里的“ccswitch配置opencode”其实点出了一个很实际的痛点：模型一多，环境变量就乱。ccswitch 是一款管理 AI 编程工具配置的命令行工具，它可以把 Codex、Claude Code、opencode 各自的模型映射统一维护。具体到 opencode，它的原理是生成或改写 opencode 的配置文件里的 provider 模型映射。

我的使用姿势很简单：把所有 API Key 统一放在 ccswitch 的配置里，然后通过 ccswitch 切换到某个供应商时，它会联动更新 opencode 的配置。这样一来，我不用记住每个模型在哪买了、还剩多少 credit，只要看 ccswitch 当前激活的是哪个 profile 就行。

ccswitch

这是最简单的查看交互界面的命令，图形化列出当前所有 profile。选中后 ccswitch 会提示同步目标工具，选 opencode 即可。

需要提醒的是：ccswitch 本身不是 opencode 的组件，它只是通过改写配置来“指挥” opencode。如果你不想再装一个工具，opencode 也支持运行时直接切换模型列表里的项，只是管理多套 Key 时没 ccswitch 省心。

4. 把 opencode 融入日常开发环境：VSCode、IDEA、桌面版

终端归终端，但大多数人的日常工作还是在 IDE 里。opencode 提供了插件和桌面客户端，让你不用切窗口就能用上代理能力。

4.1 VSCode 插件怎么装、怎么用

在 VSCode 扩展市场搜 opencode，安装官方插件。装完后，左侧侧边栏会出现 opencode 的图标。第一次点击时会要求选择模型来源，它会自动识别你终端配置文件里已有的 provider。

实际使用中的几个高频操作：

• 选中代码后直接 Shift+Command+I（macOS）或 Shift+Ctrl+I（Windows），会打开一个快捷提问框，适配当前选中内容。
• 在会话面板里可以添加文件路径，openccode 会把文件内容作为上下文发送给模型，这点比单纯复制粘贴代码要高效得多。
• 插件会同步你在终端启动的会话历史，所以你可以在终端里开任务，在 IDE 里查看进度，两边数据互通。

我个人更喜欢把 VSCode 插件当成“结果查看器”用：终端里让 opencode 跑一个大重构，同时在 IDE 里打开 Diff 面板看它改了哪些文件。看到不对劲的地方，直接在 IDE 里手动回退，比在终端里跟代理反复拉扯要快。

4.2 JetBrains IDEA 插件的差异点

IDEA 插件最近也在更新，但功能成熟度目前没有 VSCode 版高。最明显的差异是它把 opencode 放在了一个工具窗口里，操作逻辑更像内置 AI 助手，而不是聊天机器人。

IDEA 版目前我用的最多的功能是opencode mvn配置这个场景。这个热搜真正的意思是：在 Maven 项目里让 opencode 帮忙加依赖、改pom.xml，或者生成特定版本的构建配置。这个操作如果直接在终端里跑，它使用的上下文规则跟 IDEA 的依赖解析结果无关，而 IDEA 插件可以直接读取项目 SDK、Maven 配置，所以生成结果更贴合当前项目。

注意一点：IDEA 插件不能在未启动 opencode 服务的情况下独立工作。你需要在终端启动一次opencode，或者在 IDEA 的设置里指定 opencode 可执行文件路径。

4.3 桌面版：给不想碰终端的人

opencode desktop 是一个图形界面版本，底层走的还是同一个工作流，只是把 TUI（终端交互界面）换成了窗口应用。它的出现解决了“团队里有人死活不习惯终端”的问题。

实测体验是：桌面版的模型配置路径和终端版一致，但它有一个优势——可以更方便地查看会话记录、比较不同模型的输出差异、甚至导出会话作为团队知识库。如果你在带团队、想统一管理 AI 工具的使用记录，桌面版值得一试。

不过坦白讲，桌面版目前能以 Cursor 或 Windsurf 的产品完成度来衡量，它还谈不上“国民级”，更多是“终端界面的图形化镜像”。重度用户继续在终端里也完全没问题。

5. 进阶实战：接手老项目、Skills、Playwright 测前端 bug

安装配置只是第一步，真正体现 opencode 价值的是深度使用。这一章讲的都是我验过的场景，不是脑补出来的“最佳实践”。

5.1 用 opencode 接手一个没文档的老项目

新接手一个项目时，最痛苦的不是代码难写，而是“不知道这个项目是怎么转起来的”。opencode 在处理这类“侦探型任务”时，比纯人肉翻代码要高效得多。

我常用的指令模板：

接手这个项目。先做以下事情： 1. 分析根目录的 README、docker-compose.yml、package.json，梳理项目启动流程； 2. 定位入口文件，说明请求链路的大致走向； 3. 找一个最小可运行的用例（例如登录接口），从入口到数据库查询完整走一遍； 4. 输出一份 markdown 格式的技术摘要，放在 docs/onboarding.md。

这里有一个关键技巧：开局就让它输出 markdown 文件，而不是只让它聊天回答。因为这个过程会强制 opencode 进行结构化思考，同时给你留下一个可交给下个同事的文档。执行完后，再让它解释具体模块时，它的准确率会明显提升。原因不难理解：它已经通过写文档把项目的拓扑结构过了一遍。

opencode 写文件的能力默认会读取当前项目的.gitignore，不会乱覆盖你已有的文件。如果你希望某目录可写，需要在配置文件的permission字段里显式声明：

{ "permission": { "edit": ["docs/**"] } }

5.2 Skills 机制：把团队规范变成可复用技能

“opencode skills” 是 opencode 比较有特色的一块能力。它的思路是让用户把一套提示词、工具调用逻辑和检查清单封装为一个“技能”，之后在会话里主动触发。

举个例子，我们团队前端规范里有一条，所有TODO必须关联 issue 号。我做了个 skill，内容大致是：

• 读取当前分支的改动文件；
• 扫描含TODO的行；
• 检查是否包含JIRA-XXX格式文本；
• 如果没有，则列出风险清单，并给出修正建议。

配置好之后，在 opencode 会话里写一句“执行 todo-check skill”，它就能自动跑完这套检查。Skills 对团队最大的价值，是解决“AI 每次生成代码风格不一致”的问题。你只要把团队约定写进 skill，它遵从度就比口头描述要稳定得多。

官方文档里 Skills 的存放位置一般在~/.config/opencode/skills/，每个技能一个文件夹，里面放SKILL.md和可选的脚本文件。

5.3 让 opencode 驱动 Playwright 复现前端 bug

这个场景也是热搜里比较密集的：“opencode playwright 怎么测试前端bug”。大多数人遇到前端 bug 的做法是：自己打开浏览器、手动复现、F12 看 Console。这套流程在 opencode 里可以直接交给代理做。

它的思路是：opencode 提供了一个 Playwright MCP 工具，代理能通过自然语言指令控制浏览器。

我的实测流程：

> 帮我用 playwright 复现这个 bug：访问 localhost:3000，点击登录按钮，填写用户名 admin，密码错误，观察页面是否给出友好提示。

opencode 会调用 Playwright 工具：

1. 启动浏览器并打开指定 URL；
2. 自动寻找输入框和按钮；
3. 填入数据、点击操作；
4. 读取页面 DOM 和控制台输出；
5. 返回操作结果和错误快照。

这个过程省掉了我大量“手动点一遍 + 看网络请求”的时间。尤其是那种只在特定用户流程里出现的 bug，让代理跑一遍完整链路、并把结果带回给模型分析，比人肉复现快得多。

需要提前装好依赖：

npm install -g @playwright/test playwright install chromium

如果你用 VSCode 插件，也可以用图形化方式看到浏览器操作过程。实测下来，越明确的步骤指令（比如指定 CSS 选择器、指定 URL 参数）成功率越高，你把它当成一个能听懂自然语言的自动化测试工人，而不是比你更懂业务的人。

6. 高频报错排查与最终配置建议

这一章写给自己踩过坑的人，也写给准备上生产环境的团队。排查思路比答案更重要，所以我尽量把链路讲清楚。

6.1 “unexpected server error. check server lo...” 的排查链路

热搜里有一条完整的报错：

c:\windows\system32>opencode error: unexpected server error. check server lo...

这个报错在 Windows 和类 Unix 系统都可能出现，最常见的诱因是 opencode 后端进程和 CLI 进程之间的通信出了问题。看到这个信息，不要急着重装，按下面的顺序排查：

1. 确认是不是代理或网络层导致的：如果 opencode 需要访问某个外部的模型网关，网络不通时它可能会返回这种模糊错误。先跑一条最简单的curl看看目标地址通不通。

2. 查看 opencode 日志：终端里启动时加--log-level=debug可以打开调试日志，里面通常会给出具体的 HTTP 状态码或 socket error。

3. 检查端口占用：opencode 的本地服务默认会监听某个端口，如果上一次异常退出导致残留进程占着端口，新进程起不来就会报 server error。Windows 下用：

netstat -ano | findstr :4444

找到 PID 后结束该进程，再重新运行opencode。

4. 重置配置缓存：如果以上都查不出问题，备份一下配置文件，删掉~/.local/share/opencode或对应平台的数据目录，重启试试。

这类问题九成是环境残留或网络层穿透造成的，跟 opencode 本身的逻辑关系不大。耐心一点都能解决。

6.2 模型配置渲染异常：为什么我改了 provider 没生效

改完opencode.json之后重启，发现模型列表没变化。这个坑我踩过两次。原因是 opencode 对配置文件的改动不是实时热加载的，而且它可能额外加载了一个 local 配置文件，优先级覆盖了全局配置。

你需要检查：

• 全局配置：~/.config/opencode/opencode.json
• 项目级配置：当前项目根目录下的opencode.json或opencode.local.json

opencode 的配置合并规则是：项目级覆盖全局级，local 覆盖普通项目级。如果你的项目下恰好也有一个opencode.local.json，里面声明了旧的 provider，那你改全局配置当然没效果。

解决方案：删除或调整项目级配置，或者直接把所有模型配置都放到项目级里统一管理。后者更适合团队协作，因为新成员克隆仓库后就能直接共享同一套模型配置。

6.3 我的最终配置模板，可以直接抄

下面是我目前实际在用的一套配置，兼顾了免费模型和主力模型：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "npm": "@ai-sdk/anthropic", "name": "Anthropic", "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }, "models": { "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" } } }, "deepseek": { "npm": "@ai-sdk/deepseek", "name": "DeepSeek", "options": { "baseURL": "https://api.deepseek.com", "apiKey": "{env:DEEPSEEK_API_KEY}" }, "models": { "deepseek-chat": { "name": "DeepSeek V3" } } }, "ollama": { "name": "Ollama", "options": { "baseURL": "http://localhost:11434" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen 2.5 Coder 14B" } } } }, "permission": { "edit": ["docs/**", "tests/**"], "run": ["npm test", "npm run build"] } }

这套配置覆盖了三个典型场景：

• Claude Sonnet 4是主力，用于复杂需求拆解和跨文件重构；
• DeepSeek V3是平价备用，用来做日常补全、生成单元测试；
• Ollama 的 Qwen 2.5 Coder是最后的免费兜底，断网或者不想耗 API 额度时用。

注意permission字段：它限制了 opencode 能自动改写的目录和能自动执行的命令。这个设置非常重要，尤其是让代理在团队项目里自由活动时，没有这项管控，它可能会尝试修改你根本不想让它碰的文件，或者直接执行数据库迁移之类的危险命令。

写在最后的一个选型观察

我试过 Codex、Claude Code、pi、opencode 这几个主流代理之后，最大的感触是：工具之间的差距正在缩小，生态和自由度才是拉开体验的关键。opencode 目前的杀手锏就是模型无关 + IDE 覆盖全 + 本地服务可扩展，这恰好押中了这个时代很多开发者“不想被一家模型绑架”的心态。

当然，它也不是没有短板——配置门槛比 Claude Code 高一点，社区的成熟案例也没有 OpenAI 系那么多，团队落地时可能要花半小时写培训资料。但它胜在底子干净、扩展路径清晰。如果你现在正在对比各家代理，不妨先花一个下午把 opencode 按我上面的配置跑通，然后拿一个真实需求去测它的边界。很多问题的答案，不是靠看评测看出来的，是上手跑一遍才真正有体感。