opencode 实战：模型路由、LSP 与 Playwright

1. 为什么我在一堆编码智能体里留下了 opencode

先交代背景。我日常的工作流基本已经离不开编码智能体（coding agent），从 GitHub Copilot 到 Cursor，再到后来的 Claude Code、Codex CLI，基本上每出来一个能跑命令行的 Agent 我都会装来试试。open code 这个项目最早是社区里一个比较小众的终端 AI 助手，因为名字就叫 opencode，当时我还以为是某个开源项目的代号，没太在意。直到有一次在改一个老项目的 bug，用 Claude Code 改完一轮发现上下文被撑爆了，换到 opencode 重新起会话，发现它居然能保持更清晰的上下文管理，而且对 LSP 的支持是内置的，这才开始认真研究它。

如果你还不了解 opencode 是什么，简单说：它是一个开源的、跑在终端里的 AI 编码代理，你可以通过对话让它读取项目代码、修改文件、执行命令、跑测试，甚至自己开浏览器去验证前端页面。它和 Claude Code、Codex CLI 属于同一类工具，但它在模型接入上更灵活，既可以用 Anthropic 的模型，也可以用 OpenAI、Gemini、本地模型，甚至走 OpenAI 兼容接口。这个特性对国内开发者尤其重要，因为不同时期可用的模型不一样，能自由切换就多了一条活路。

这篇文章不是官方文档翻译，是我自己从安装、配置、日常使用到踩坑的一个完整记录。适合几类人读：一是正准备从 Claude Code / Codex 转到 opencode 的人，二是已经在用但被配置文件、插件和 IDE 集成弄得头大的新手，三是想看看 opencode 和 codex、claude code、pi 这些 Agent 到底差在哪、值不值得切换的老手。

2. 装完 opencode 第一件事不是跑 demo，而是把模型通道理清楚

很多人第一次接触 opencode 会犯一个错误：装好之后直接敲一句"帮我写个贪吃蛇"，然后发现要么报错没有 API Key，要么模型不受支持，要么请求超时。我建议先别急着跑 demo，把模型通道搞清楚再说。opencode 本身只是一个壳，真正干活的是背后的模型，所以模型通道配好了，后面所有功能才会顺畅。

2.1 三种模型接入方式：官方 Key、网关订阅、本地模型

我实际用过的主流接入方式有下面三种，各有各的适用场景：

• 官方 API Key 直连：在 opencode 里直接配置 Anthropic、OpenAI 或 Google 的官方 Key，适合有海外支付条件、且项目对数据隐私要求不高的团队。优点是稳定、上下文支持好、新功能跟得快；缺点是贵，而且在国内直连官方服务的体验经常波动。
• 第三方网关或订阅服务：这类服务通常提供一个 OpenAI 兼容的 baseURL，你只要把 opencode 的 provider 指向它就行。有段时间我用的就是一个聚合了多个模型供应商的网关，一份订阅能同时用 Claude、GPT 和 Gemini，切换模型非常方便。网上常说的"opencode go 订阅"和"CC Switch 配置切换工具"都是围绕这种场景出现的。这类方案的核心价值是把多个平台的 Key 集中管理，在 opencode 里只需要配一套 OpenAI 兼容端点，然后通过模型名区分供应商。
• 本地模型：通过 Ollama、LM Studio 跑 Qwen、Llama 等开源模型，opencode 也支持。本地模型的好处是隐私安全、完全免费、离线可用；缺点是代码理解能力比商用模型有明显差距，长上下文容易崩。我留了一套本地模型配置作为断网情况下的备用方案。

三种方式我都长期用过，先说结论：如果只是个人玩、想体验 Agent 写代码的快感，找个稳定的 OpenAI 兼容网关是最省事的；如果是团队正式项目，建议至少配一个官方 Key + 一个网关兜底，免得某个通道出问题就完全干不了活。

2.2 model 路由配置：provider、model 与环境变量一次说清

opencode 的全局配置文件在~/.config/opencode/opencode.json（Windows 下是用户目录下的AppData对应路径，macOS 和 Linux 都一样），项目根目录下也可以用opencode.json做局部覆盖。配置的核心就两个字段：provider 和 model。

我想用一个实际的例子说明，假设你要同时使用 Anthropic 和 OpenAI 兼容网关：

{ "$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" } } }, "mygateway": { "npm": "@ai-sdk/openai-compatible", "name": "My Gateway", "options": { "baseURL": "https://your-gateway.example.com/v1", "apiKey": "{env:GATEWAY_API_KEY}" }, "models": { "gpt-4o": { "name": "GPT-4o" }, "claude-3-5-sonnet-20241022": { "name": "Claude 3.5 Sonnet" }, "gemini-1.5-pro": { "name": "Gemini 1.5 Pro" } } } }, "model": "mygateway/claude-3-5-sonnet-20241022" }

这里最关键的是model字段，它的格式是provider/model-id。省掉 provider 前缀直接用"model": "claude-sonnet-4-20250514"也可以，opencode 会去各个 provider 里找匹配的模型名。我自己习惯写成全限定名，因为多 provider 环境下避免歧义。

环境变量的方式强烈建议用，不要把 Key 直接写进 JSON 文件，尤其是项目根目录下的opencode.json很容易被 git 提交上去。我见过不止一次有人把 API Key 提交到公开仓库，最后被脚本扒下来刷爆额度的惨案。

2.3 常见报错“this model is not available in your country”的正确处理姿势

这个报错我遇到太多次了，尤其当你在网关里配置了一些海外模型，而网关服务商在某些区域有使用限制时，opencode 会在请求时报出：

this model is not available in your country.

很多人的第一反应是去找各种"加速通道"，我劝你不要这么做。一方面这类操作违反服务商条款，另一方面也不是解决问题的根本办法。我的处理思路是：

• 先确认这个模型是否真的必须用。很多场景下换一个同级别的可用模型，代码生成效果差距并不大。
• 如果团队中确实有同事依赖某个受限模型，优先通过正规渠道联系网关服务商，看有没有合规的区域节点或白名单方案。
• 在自己不熟悉的合规边界内，尽量使用明确支持你所在区域的模型。opencode 的好处是切模型只要改一个model字段，不像其他工具那么麻烦。

我也见过有人在 opencode.json 里通过自定义 provider 指向第三方中转来规避这个报错，这属于灰色操作，我不会在文章里展开，也不建议你这么做。工具本身没有错，但使用方式要符合服务条款，这是长期稳定使用的前提。

3. 命令行日常：从 /skills 到 /memory 再到 LSP，opencode 的进阶玩法

模型通道搞定之后，opencode 的日常使用才真正开始。很多人把它当成一个高级 ChatGPT 终端，其实是浪费了。opencode 的会话内命令、技能系统、记忆机制和 LSP 支持才是它区别于普通聊天工具的杀手锏。这一节我按我自己每周的使用频率从高到低讲。

3.1 会话内命令：init、skills、memory、undo 这样用

opencode 的交互式终端里，斜杠命令是最高频的入口。我每天必用的有这么几个：

• /init：在项目根目录初始化一个opencode.json，同时生成AGENTS.md文件。这个文件是给 Agent 看的项目说明，你可以在里面写清楚项目结构、代码规范、常用命令。每次新会话 opencode 都会自动读它，相当于给 Agent 补了一课。
• /skills：技能列表管理。opencode 的技能（skills）和 Claude 的 Skills 概念类似，但实现方式更轻量，本质上是在.opencode/skills目录下的一组 markdown + 脚本，每个 skill 是一个可复用的指令包。
• /memory：长期记忆管理。opencode 会把重要信息写到~/.config/opencode/memory目录下，比如你的代码风格偏好、常用技术栈、项目的关键约束等。下次新会话它会自动加载这些记忆，不用每次重新交代。
• /undo：撤销 Agent 上一次的文件修改。这个贼好用，尤其当 Agent 改飞了几个文件时。
• /tabs：查看当前会话中 Agent 打开/修改过的文件列表，方便你快速判断它动了哪些地方。

我举一个实际场景：在一个 Java 项目里，首次用/init生成AGENTS.md后，我在里面写了一句"本项目使用 Maven 管理依赖，所有新依赖必须添加在 pom.xml 的 dependencies 节点内，不要使用 Gradle"。之后每次让 opencode 加依赖，它都会先去看pom.xml，而不是凭空生成 build 脚本。这就是AGENTS.md的力量，它把 Agent 从一个"随机生成器"变成了"懂项目协作的实习生"。

3.2 LSP 加持下的上下文理解

opencode 对 LSP（Language Server Protocol）的支持是我选择它的一个重要原因。简单说，LSP 就是让编辑器/工具能真正"理解"代码语言的协议。你在 VSCode 里看到的跳转定义、查找引用、错误提示，都是 LSP 的功劳。opencode 内置了 LSP 客户端，它能在 Agent 分析代码时主动获取符号定义、类型信息、引用关系。

这意味着什么？我用一个例子说明。你让 opencode 重构一个函数，它不只是靠"读文件内容"来猜，而是通过 LSP 知道这个函数在哪些地方被调用了、返回类型是什么、有没有重载。这样重构出来的代码才靠谱。比如我给一个 TypeScript 项目重命名接口字段，opencode 通过 LSP 找到了所有引用位置，顺便把 mock 数据、测试文件里相关字段也一起改了，而不是只改定义处。

如果你想在 opencode 里用 LSP，需要保证项目里有对应语言的 LSP server。它支持 TypeScript、Python、Go、Java、Rust 等主流语言。opencode 会尝试自动检测项目语言并启动对应的 LSP server，如果没检测到，可以在配置文件的lsp字段里手动指定。

3.3 用 Playwright 让 Agent 自己打开浏览器修前端 bug

这是我最近才试用的功能，体验很惊喜。opencode 内置了 Playwright 支持，可以让 Agent 打开浏览器、模拟用户操作、截图、读控制台报错，然后根据这些信息修 bug。热搜词里"opencode playwright 怎么测试前端 bug"说的就是这个场景。

我遇到的一个实际案例：客户报了一个登录页在移动端布局错乱的问题。以前我得先自己打开浏览器、用开发者工具模拟机型、截图、再一层层改 CSS。现在直接在 opencode 里输入：

帮我看看登录页在 iPhone 14 Pro 尺寸下的布局问题，用 Playwright 打开 http://localhost:3000/login 模拟一下，然后把问题修复。

opencode 会调用 Playwright 打开页面，模拟移动端视口，截图并读取控制台错误信息，然后自己定位到那几个 CSS 文件，修改后用npm run build验证。整个过程我只需要在关键节点确认一下它改的内容。这个功能对快速验证前端交互问题非常实用，省掉了很多来回切换的琐碎步骤。

不过要注意，Playwright 功能需要项目里有playwright依赖，并且 opencode 启动时有权限拉起浏览器进程。在无头服务器上跑的话，还要确认 Playwright 的浏览器二进制已安装，否则 Agent 会报错。

4. 从终端到 IDE：VSCode、JetBrains 和桌面版的集成方案

很多人习惯在 IDE 里写代码，终端只是偶尔打开跑命令。opencode 显然也考虑到了这点，目前有 VSCode 插件、JetBrains 系列插件，还有单独的桌面版应用。我三个都用过，这一节说说实际差异和使用建议。

4.1 VSCode 插件怎么选、怎么配

VSCode 插件是 opencode 用户最熟悉的入口。装上插件后在侧边栏或编辑器面板打开 opencode 视图，可以新建会话、查看会话历史、直接在当前选中文件上下文里提问。它的天然优势是能直接读取当前打开的文件和编辑器里的选中内容，比在终端里手动输入文件路径方便得多。

配置上，如果你已经在终端里配好了opencode.json，VSCode 插件会自动读取全局和项目配置，不需要重新配。有一点要注意：插件的配置里默认会走opencodeCLI 的可执行文件，如果 CLI 更新了但插件没重启，可能会出现版本不匹配导致功能异常。我每次升级 opencode 之后会顺手重启一下 VSCode，避免这种诡异问题。

VSCode 插件还有一个我非常喜欢的功能：可以在编辑器中直接选中一段代码，右键发送给 opencode，让它解释、优化或写测试。这个交互比切到终端复制粘贴自然多了。

4.2 JetBrains IDEA 插件的使用体验

JetBrains 系插件（IDEA、PyCharm、WebStorm）相比 VSCode 插件起步晚一点，但核心功能都到位了。我在 IDEA 里开发 Java 项目时用 opencode 插件，最大的感受是它对项目结构的理解更贴合 IDE：能感知到当前 module 的类路径、Maven/Gradle 配置，甚至能直接调Ctrl+Enter把生成的代码插入到编辑器光标位置。

实际配置也很简单，在插件市场搜 opencode 安装后，它会要求指定 CLI 路径。如果你用brew install opencode或 npm 全局安装，一般能自动找到。IDEA 里我常用的场景是：让 Agent 根据一个 JUnit 测试类生成对应的 Mock 类和方法，生成后直接在代码里Alt+Enter优化导入，非常顺滑。

需要提醒的一点是，JetBrains 插件对超大项目的索引敏感，如果你的项目有几十个 module，Agent 在读取文件树时可能会卡。这时候最好在AGENTS.md里明确告诉它只关注哪个 module，别让它扫描全仓库。

4.3 opencode 桌面版适合谁

opencode Desktop 是官方出的桌面应用，本质上是把终端版套了一层 GUI，内置了会话面板、文件查看器和设置界面。我用了几天后就把它卸载了，不是说它不好，而是我的主力场景都在终端和 IDE 里，桌面版反而多了一层切换成本。

但它适合另一类人：不喜欢命令行、但想让 Agent 帮忙改代码的同事。桌面版的好处是安装就是可点击的图标，不需要记任何命令；而且它的设置界面把模型、Key、代理等配置做成了表单，不用手改 JSON。我团队里一个前端同事就是桌面版的重度用户，他完全不碰命令行，但用桌面版配合 VSCode 插件也能跑通整套工作流。

如果你已经有完整的终端 + IDE 工作流，桌面版不是必需品；如果你想把它推荐给不太熟悉命令行的队友，或者你需要在多台电脑间快速同步配置，桌面版的图形化配置会更友好。

5. 真实项目中的踩坑记录与排查思路

工具再顺手也会有翻车的时候。这一节记录几个我真实踩过、且搜索热度挺高的坑，包括 Windows 下的命令识别报错、服务器端报错排查、以及 Linux 下直接改 JSON 的注意事项。每一个我都尽量按"问题现象 -> 排查过程 -> 最终解决"的顺序写，方便你复现排查思路。

5.1 Windows 下“无法将 opencode 项识别为 cmdlet”的常见原因

热搜词里有一条很典型：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

这个报错在 Windows PowerShell 下太常见了。我第一次在 Windows 机器上装 opencode 就遇到过。原因基本上就两类：

• 安装没有真正成功，或者安装后的可执行文件不在 PATH 里。比如你用了npm install -g opencode-ai，但 npm 的全局 bin 目录没有加到系统 PATH。
• PowerShell 因为脚本执行策略（ExecutionPolicy）限制，无法运行某些命令行工具。这个情况在pnpm、yarn这类 npm 工具上也会遇到。

我建议按下面顺序排查：

1. 先确认安装方式对应的可执行文件在哪里。npm 全局安装的话，运行npm root -g找到全局 node_modules，然后看node_modules/.bin/opencode是否存在。
2. 检查 PATH 是否包含 npm 全局 bin 目录。PowerShell 里运行$env:PATH -split ';'可以看到所有路径。
3. 如果是执行策略问题，用管理员身份打开 PowerShell，运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，然后重开终端。

还有个小坑：如果你用brew install opencode（Windows 上可以通过 WSL 或 git bash 用），那在原生 PowerShell 里不一定能找到，因为 brew 安装路径在/home/linuxbrew/.linuxbrew/bin，属于 Linux 子系统，和 Windows PATH 不互通。我后来直接在 Windows 上用scoop install opencode或官方安装脚本才彻底解决。

5.2 unexpected server error 排查链路

另一个高热度报错是：

error: unexpected server error. check server logs

这个报错在 opencode 里非常笼统，问题可能出在模型服务端、网关、本地代理、甚至是网络波动。我第一次遇到时在项目群里发消息求助，得到的回答是"看看日志"，但新手根本不知道 logs 在哪。

opencode 的日志分两部分：一部分是 CLI 本身的日志（~/.local/share/opencode/log或运行opencode --debug查看详细输出），另一部分是模型服务端的日志（如果你跑本地模型，去看 Ollama 的日志；如果用网关，去看网关控制台）。

我的排查顺序是这样的：

1. 先用opencode --debug跑一遍同样的问题，看有没有更具体的报错信息。比如它可能会明说 HTTP 429（限流）、HTTP 401（鉴权失败）、超时等。
2. 如果报的是 5xx，换个模型再试，排除特定模型的问题。
3. 如果用网关，直接用 curl 测一下网关的 /v1/chat/completions 接口是否通、响应正常。curl 一下能快速判断是本机网络问题还是上游服务问题。
4. 如果本地代理工具在运行，试着临时停掉再测，排除本地网络工具对请求的干扰。

有一次我查了很久，最后发现是网关连接数满了，换个网关节点就恢复正常。这也是我为什么前面建议至少准备两个模型通道，遇到上游故障不至于完全瘫痪。

5.3 Linux 下直接改 JSON 配置的注意事项

opencode 在 Linux 服务器上的使用很常见，因为很多人会在远程开发机或 CI 环境里跑 Agent。linux 修改 json 这个热搜词对应的场景通常是：在服务器上装好后想改模型配置，直接用vim opencode.json编辑，结果启动时提示配置格式错误。

需要注意的细节有几点：

• JSON 不支持注释。很多从 JSONC（比如 VSCode 的 settings.json）迁移过来的人会习惯性写//注释，opencode 解析时会直接报错。
• 字符串里的转义问题。Windows 路径C:\\Users\\...在 JSON 里要写成双反斜杠，Linux 路径则用/。我见过有人把 Windows 的 key 文件路径直接贴到 Linux 配置文件里，结果 Agent 怎么都读不到密钥。
• 配置文件加载顺序。全局配置和项目配置会合并，项目配置优先级更高。如果你改了全局配置没生效，看看是不是项目根目录下也有一个opencode.json覆盖了它。

在 Linux 上我的习惯是：先cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak备份，再用python3 -m json.tool opencode.json校验格式，最后才启动 opencode。这个习惯帮我避免了好几次因为少个逗号导致的启动失败。

6. 和其他 Agent 的横向对比：codex、claude code、pi 与 opencode

很多人搜 opencode 的时候会带着一个对比问题：opencode、codex、claude code、pi 到底哪个 Agent 好用。这几个工具我都实际用过一段时间，这里不吹不黑，说说我的体感差异和选型逻辑。

6.1 这些工具体验上的差异

我按四个维度比较：模型接入灵活度、上下文管理、终端交互体验、IDE 集成成熟度。

先说 Claude Code。如果你主力用 Claude 模型，Claude Code 的体验其实非常顺滑，尤其是长对话的上下文续接做得比 opencode 默认状态好。但问题也明显：它对非 Anthropic 模型的支持基本为零，一旦 Anthropic 官方服务不稳定或额度受限，想切到别的模型很麻烦。opencode 则可以通过配置不同的 provider 在同一个会话里切换模型，这个灵活度在真实项目中太重要了。

再说 Codex CLI。OpenAI 出的这个工具在代码补全和重构上很聪明，而且它和 GitHub 生态结合得紧密，可以在终端里直接提 PR。但它的定位更像一个"命令行编码助手"，而不是一个可深度定制的 Agent 框架。opencode 的 skills、memory、LSP 这些机制让它可以被"教育"成符合自己项目习惯的工具，Codex 在这方面比较封闭。

pi 我理解是另一个开源的 agent 类项目，它的特点是更底层，适合想自己组装工具链的开发者。但普通用户直接用它日常写代码，学习成本会比 opencode 高不少。

6.2 我的选型结论与适用场景

如果你让我给一个简单结论：opencode 更适合"想用一个 Agent 同时面对多个模型供应商、多个项目类型、且愿意花点时间把配置和技能调教好"的人。Claude Code适合"重度使用 Anthropic 模型、不想折腾配置"的人。Codex CLI 适合"已经深度绑定 OpenAI 生态、主要在 GitHub 工作流里用"的人。pi 适合"想研究 Agent 底层原理、准备自己二次开发"的人。

我个人的主力工作流现在是：日常开发用 opencode + 网关订阅，需要高强度长上下文重构时切到 Claude Code，跑轻量任务时用一个便宜模型。这种组合方式下，opencode 是核心调度器，其他工具是特定场景的补充。

如果你正在从 Claude Code 或 Codex 迁移到 opencode，我建议先别急着删旧工具，而是同时在两个环境里跑同一个任务，对比它们的上下文管理和生成质量，一周后再决定去留。这个迁移成本不算高，但能让你真正理解不同 Agent 的差异，而不是只看宣传。

7. 最后分享几个我自己用出来的小习惯

opencode 这类工具最怕的不是配置复杂，而是你不会把它融入日常节奏。我不打算做那种"看完这篇文章你就能精通 opencode"的承诺，就分享几个我用顺手的习惯，你挑着试即可。

第一，把AGENTS.md当成团队文档对待。我每接手一个新项目，第一件事不是急着让 Agent 干活，而是先手动写一遍AGENTS.md，把项目的目录结构、构建命令、代码风格、容易踩的坑都写进去。这花不了半小时，但带来的收益是之后每次和 Agent 协作都能少重复解释一堆背景信息。如果你觉得手写麻烦，可以用/init先自动生成草稿，再人工补全。

第二，给常用的技能建立模板。比如"生成单元测试"、"修复 lint 报错"、"优化查询性能"这类频繁任务，我都会在.opencode/skills下建一个 markdown 模板，把约束条件和输出格式写清楚。之后在会话里输入/skills就能一键复用。我团队里新来的同事第一次看到这个功能时很惊讶，说原来 Agent 也能按公司规范干活。

第三，留意免费模型的下线频率。社区里经常有人分享"xx 免费模型上线了"，但没过多久又有人问"xx 免费版下线了吗"。免费模型当玩具可以，但别把关键项目的自动化流程绑定在免费模型上。我的原则是：核心流程用付费稳定模型，免费模型只用来跑不影响交付的探索性任务。

第四，在 IDE 插件和终端 CLI 之间分配好任务边界。我现在习惯在 VSCode 插件里做代码解释、修复、重构这类需要"看代码"的事情；在终端里做批量文件处理、跑测试、跨模块重构这类"面向项目"的事情。桌面版则留着给偶尔需要图形化看配置的同事用。三个入口各司其职，比一开始想把所有功能塞进一个入口高效得多。

opencode 还在快速迭代，2.0 版本之后桌面版、插件体系、LSP 支持都比早期完善不少。如果你看完这篇还是不确定要不要入坑，找一个周末项目，装上它，配好一个模型，让它帮你从头写一个小工具，跑完全流程你就有自己的判断了。工具是越用越顺手，配置是越改越趁手，真正把它变成自己工作流的一部分，才是这篇文章想传达的东西。