opencode：终端里的多模型AI编程代理实战指南

最近好几个读者都在问 opencode，说在 GitHub 趋势上看到它，又被各种帖子刷屏。其实我前几个月就已经在终端里用它跑真实项目了，从修一个简单 bug 到接手新需求，基本每天都在用。opencode 不是一个聊天窗口，而是一个跑在终端里的 AI 编程代理（agent）：你给它一个任务，它能自己读代码、改代码、执行命令、跑测试，甚至打开浏览器帮你复现前端问题。和 Claude Code、Codex、Pi 这类工具是同一赛道，但 opencode 最大的特点是模型自由，OpenAI、Anthropic、Google、本地模型、各种网关都能接，而且配置是纯文件的，好审计、好迁移。

这篇文章我打算从安装踩坑讲起，把配置、插件、Skills、LSP、Playwright 测试这些高频场景都过一遍，最后列一份我长期积攒的报错排查清单。适合谁看？如果你已经在用 Cursor 但想试试终端 agent，或者被 Claude Code 的账号门槛卡住，又或者手里有一堆 API key 想统一管理，opencode 都值得一试。内容会写得比较细，你完全可以照着一步步操作。

1. opencode 是什么：把“改代码”变成“安排任务”的终端 agent

1.1 和 Claude Code / Codex / Pi 的定位差异

很多人第一次看到 opencode 会问：这不就是又一个 Claude Code 吗？事实上这类工具解决的是同一个问题——让 AI 不再只是“问答窗口”，而是能真正接管一部分开发流程。但它们在模型绑定、开放程度和交互方式上有明显区别。

我用过一段时间之后，对这四类工具的定位做过一个粗颗粒度的对比：

opencode 对我来说最大的价值是“不锁死”。我今天的项目可能用 Sonnet 类模型写复杂逻辑，明天跑一个小脚本就用便宜快速的轻量模型，opencode 只要改配置就能切换，不需要重新适应一套交互。这点在真实开发里太重要了，因为模型的强弱并不总是决定产出质量，成本和响应速度同样影响体验。

1.2 本地优先：你的配置和会话都是可读文件

opencode 的另一个设计思路是“本地优先”。配置文件默认放在~/.config/opencode/opencode.json，会话记录、日志都存在本地目录里，而不是全部锁在某个云平台上。这意味着三件很实际的事：

第一，配置可以放进版本管理。我通常会把.opencode/下的团队配置提交到仓库里，新同事克隆下来就能用同一套模型和规则，省去口头同步。

第二，行为可审计。agent 到底改了哪些文件、执行了什么命令，翻开日志一目了然。对于团队协作，这比一个“黑盒聊天窗口”靠谱得多。

第三，迁移成本低。换电脑只要同步配置文件和 key，不需要重新“训练”一个工具。

如果你之前只用过 IDE 内置的 AI 编程插件，第一次用 opencode 可能会不太习惯，因为它没有漂亮的图形界面，只有终端里的 TUI。但适应之后你会发现，终端里的 agent 反而更专注，它能直接操作 shell，天然适合跑测试、查日志、批量改文件这些“脏活”。

2. 安装 opencode：从一行命令到 Windows 报错自救

2.1 三种安装方式和我的选择

opencode 的安装方式主要有三种，你按自己环境挑一个就行。

npm 方式，也是我用得最多的：

npm install -g opencode-ai

curl 脚本方式，适合不想依赖 Node 环境的机器：

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

Go 方式，适合本来就有 Go 工具链的人：

go install github.com/sst/opencode@latest

提示：curl 脚本和 go install 本质都是拉一个可执行文件到本地，npm 方式因为有全局 node_modules 的概念，在 Windows 上最容易出现 PATH 问题，所以我下面的排错重点说 npm。

我自己的习惯是：Windows 上用 npm，Linux 服务器上用 curl 脚本，macOS 上也是 curl 为主。原因很简单，npm 版本更新方便，一条npm update -g opencode-ai就完事，而服务器上我通常不愿意为一个小工具装完整 Node 环境。

2.2 Windows 上“cmdlet 无法识别 opencode”的根因和解决

搜索热词里出现频率最高的问题是这句报错：

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

用大白话解释，这个报错不是说 opencode 没装上，而是说你装好的可执行文件放在了一个 Windows 当前不会去找的目录里。npm 全局安装时，会把可执行文件放到 npm 的全局 bin 目录，通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在 PATH 环境变量里，你在任意路径下敲opencode，PowerShell 自然找不到。

解决步骤很简单：

1. 先看 npm 全局目录在哪，打开 PowerShell 执行：

npm prefix -g

2. 把输出目录加入用户 PATH。假设输出是C:\Users\你的用户名\AppData\Roaming\npm，执行：

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

3. 关掉当前终端，重开一个新的 PowerShell，再执行：

opencode --version

如果能看到版本号，说明安装成功。

这里我再补几个容易忽略的细节。第一，改完 PATH 之后一定要重开终端，不是刷新一下就行的，PowerShell 的环境变量是在启动时加载的。第二，如果你用的是 Windows 下的 WSL，那 PATH 规则完全不同，上面这套只适用于原生 Windows 终端。第三，如果你看到的是EACCES权限报错，那多半是 npm 全局目录权限不够，这时候用管理员身份打开 PowerShell 执行安装，或者干脆把 npm 全局目录改到用户目录下，尽量不要直接去改系统目录权限。

如果上面改动 PATH 太麻烦，还有一个临时方案：直接用npx opencode启动。npx 会临时找到 npm 全局目录里的包来执行，不过每次都要带npx前缀，体验一般，只适合应急验证。

2.3 安装完先做这三件事

装好之后不要急着丢任务给它，先花两分钟做三件基础检查。

第一，确认版本和基本信息：

opencode --version opencode --help

第二，配置 API key。opencode 支持很多模型供应商，你可以用环境变量的方式设置，也可以登录官方服务：

export ANTHROPIC_API_KEY=你的key # 或者 opencode auth login

第三，跑一个最小对话，确认链路通：

opencode "你好，帮我看看当前目录下有哪些文件"

如果这三个环节都正常，说明基础环境已经没问题了，后面就可以进入模型配置的正题。

3. 模型配置：opencode 的灵魂是“模型自由”

3.1 配置文件长什么样

opencode 的配置文件是一个 JSON 文件，路径一般在~/.config/opencode/opencode.json，Linux 和 macOS 都在这个位置，Windows 则是C:\Users\你的用户名\.config\opencode\opencode.json。你用opencode --config也能看到实际加载路径。

一个最小可用的配置大概是这样的：

{ "$schema": "https://opencode.ai/config.json", "model": "sonnet", "provider": { "anthropic": { "api_key": "env:ANTHROPIC_API_KEY" }, "openai": { "api_key": "env:OPENAI_API_KEY" } } }

model字段控制默认模型，provider字段配置各家供应商的 key 和可选的请求地址。没有api_key就用环境变量里的，这是最推荐的做法，因为 key 不会以明文到处散落。

注意：具体字段名和可用取值会随版本迭代变化，写完配置后用opencode doctor或者对着配置文件的 schema 提示检查一遍最稳妥。

这里我特别想说一下“配置即代码”的体验。我见过很多人用图形界面的工具，点来点去把模型设置好了，过一个月换电脑早就忘了当初选了哪个模型。opencode 的 JSON 配置打开就能看懂，还能复制给同事，这种确定性在团队里非常难得。

3.2 不同场景怎么选模型

opencode 支持多家模型，但这把“自由”其实也是把双刃剑，选项太多反而不知道用哪个。我按实际场景给你一套比较稳的选型思路。

我的默认配置是日常用“sonnet”级别的模型跑主任务，一旦任务较小，比如“给这个函数补个注释”，我会在对话里临时指定轻量模型，省钱也省时间。opencode 支持在对话中直接切换模型，这点比很多 IDE 插件都灵活。

如果你买了 opencode go 这类官方订阅服务，选择套餐里的模型时，我的建议是不要只盯着最强的那个。套餐通常包含多个档位的模型，关键是看“主力生成模型 + 轻量模型”的组合是否覆盖你的使用场景。只选最贵的，用得少等于浪费；只选最便宜的，复杂点的需求又跑不动。

3.3 配合 ccswitch 统一管理网关地址

热词里有一条是“opencode go 需要配合 cc switch 等工具”，这里展开说一下。

opencode go 这类托管订阅的本质是：你付一份订阅费，获得统一的多模型调用额度，服务商会给你一个请求入口和密钥。在配置层面，你把入口地址和密钥填进 provider 即可，和自建网关没有本质区别。

ccswitch 这类工具解决的是“太多 key 和入口不好管理”的问题。它本质上是一个本地配置管理工具，把各家服务商的地址、密钥集中存起来，需要时一键切换，省得每次改 JSON 文件。配合 opencode 使用时，你在 ccswitch 里选好目标服务商，把生成的入口地址和 key 复制到 opencode.json 里就行了。

提示：ccswitch 这类工具只是帮你管理 API 配置，不改变 opencode 本身的工作方式。用它之前，先确认手里的订阅套餐支持哪些模型、入口地址是否稳定，别把希望全放在一个随时可能调整的服务上。

3.4 遇到 “this model is not available in your country” 怎么办

这个报错严格来说不是 opencode 的问题，而是模型服务商根据你的访问来源区域做了限制。处理思路有三个维度。

第一，换模型。如果你在配置里填的是某个冷门模型或者特定区域的变体，可以先用opencode models查看当前可用列表，换成服务商明确支持你所在区域的模型。第二，换服务商。不同服务商的支持范围不一样，很多模型在官方渠道和第三方渠道的可达性也不同，你可以选择支持你所在地区的官方 API 服务。第三，检查是否用了不常见渠道。如果你是从非官方渠道“共享”来的入口，服务端随时可能变更限制，这不仅仅是地区报错的问题，还可能涉及数据安全，不建议作为生产依赖。

这里我要特别强调一句：遇到地区限制时，不要去找不明不白的第三方通道。一是稳定性没有保障，今天能用明天就断；二是你的代码和对话会经过别人的服务，风险不可控。正确的做法是选择在你所在区域合法可用的服务商，或者切换到不受影响的模型。

4. 把 opencode 用成生产力工具：插件、Skills、LSP 与浏览器自动化

4.1 VS Code 和 JetBrains 插件安装注意

opencode 虽然核心是终端工具，但很多人希望能在 IDE 里直接用，所以官方和社区都有对应的插件。VS Code 扩展和 JetBrains IDEA 插件我都试过，本质上是把终端里的 opencode 面板嵌进 IDE，你依然要先把命令行版的 opencode 装好。

插件安装有两个容易踩的坑。

第一，IDE 里的 PATH 和终端不一定一致。尤其是 macOS 上通过 Finder 启动的 IDE，不会加载 shell 配置，导致插件找不到 opencode 命令。解决办法是在插件设置里显式指定 opencode 可执行文件的完整路径。

第二，用 WSL 开发时，IDE 跑在 Windows，opencode 装在 WSL 里，两边互相看不见。这种情况下最简单的方式是在 WSL 的终端里直接用 opencode，而不是强行用 IDE 插件。

插件的好处是能一边看代码一边和 agent 对话，上下文更直观；缺点是 IDE 的资源占用本来就高，再跑 agent 对老机器有压力。所以我个人是轻量任务用终端，重活才开 IDE 插件。

4.2 Skills：让 opencode 学会你的团队规范

Skills 是 opencode 里我非常喜欢的一个功能，它和 Claude 系的 Agent Skills 格式类似，本质上是给 agent 提供一份“操作手册”，告诉它在特定任务下应该按什么流程走。

一个 skill 就是一个目录加一个SKILL.md文件。比如我想让 opencode 按照团队规范做代码评审，可以这样组织：

.opencode/skills/code-review/SKILL.md

SKILL.md 内容可以写：

# Code Review 当用户要求“review 代码”或“看看这个 PR”时，执行以下步骤： 1. 先读取当前分支相对主分支的变更文件列表。 2. 逐个文件检查：命名是否清晰、错误处理是否完整、是否存在明显的性能问题。 3. 按“严重问题 / 建议 / 风格”三类输出评审结论。 4. 不修改代码，只输出带文件路径和行号的评审意见。

定义好之后，在对话里让 opencode 执行 code review，它就会按这个流程走，不会再漫无目的地乱看。团队可以把这套 skills 目录提交到仓库，大家共用一套规范，agent 的输出质量会明显更稳定。

社区里已经有类似 oh-my-claudecode 的配置管理器开始支持 opencode，专门帮人统一管理 skills、模型和快捷键，如果你不想手动建目录，可以去看看这类工具是否适配你的版本。

4.3 LSP：让 agent 有“看得懂项目”的能力

LSP（Language Server Protocol）是很多编辑器都在用的协议，本质上是让工具通过语言服务器获取代码的语义信息，比如跳转定义、查找引用、报错诊断。opencode 也支持接入 LSP，这样 agent 在改代码时能像 IDE 一样感知项目结构，而不是只看字符串。

以 TypeScript 项目为例，如果你在配置里启用了对应的 LSP：

{ "lsp": { "typescript": { "command": ["typescript-language-server", "--stdio"] } } }

然后让 opencode 修改一个函数，它就能先通过 LSP 找到这个函数的引用位置，评估改动的影响范围，再动手改。这一点在重构场景里特别关键，没有 LSP 的 agent 常常改一处漏一处，有了语义感知之后，它的“判断力”会上一个台阶。

注意：LSP 服务要提前装好对应的语言服务器，比如 TypeScript 的typescript-language-server、Python 的pyright-langserver。opencode 只是扮演客户端角色，语言服务器本身得靠你在项目环境里装好。

4.4 用 Playwright 让 opencode 自己复现前端 bug

这是我觉得 opencode 最惊艳的使用场景之一。以前测前端 bug，要么手动点开页面一步步复现，要么写一堆测试脚本；现在可以直接把 bug 描述丢给 opencode，让它用 Playwright 打开浏览器去复现。

举个例子。产品反馈说“下单页面的提交按钮点了没反应”，传统排查要自己打开浏览器、打开控制台、点一下按钮看报错。用 opencode 的话，我会这样下指令：

Use the browser tool to open http://localhost:3000/checkout, click the submit button, and check for any console errors or network failures. Then suggest a fix.

opencode 会调用 Playwright 的工具，打开页面、执行点击、查看控制台日志和网络请求，再把结果汇报给你。如果页面有报错，它甚至可以直接定位到对应的前端代码。

我实测下来的感受是：这种“让 agent 自己复现”的方式特别适合那种“偶尔出现”的前端问题，因为它能自动化地反复操作，把不确定性变成可重复的复现步骤。需要注意的一点是，Playwright 工具当前是否可用、支持哪些动作，取决于你安装的 opencode 版本和项目里是否预装了 Playwright。首次使用前，先确认playwright命令在项目里能跑通。

4.5 接手一个陌生项目时怎么用 opencode 提效

很多人接手遗留项目的第一反应是“头大”。代码多、文档少、历史包袱重。opencode 在这种场景下适合当一个“快速上手指南”。

我会先让它做三件事：读 README 和启动文档，梳理项目结构和模块依赖，列出所有 TODO、FIXME 和明显报错。这样不用自己一行行翻代码，就能对项目建立起初步地图。

然后再让它帮我找某个功能的实现位置。比如：

Find where the order status is updated after payment callback, and explain the flow.

agent 会沿着关键字段和调用链去搜索，给出的解释通常比纯 grep 更接近“业务理解”。接手项目的第二天，我往往已经能回答很多历史问题，效率比纯手动翻代码高不少。当然，agent 的理解不一定 100% 正确，关键结论还是要自己核对，但“从零开始”到“有点眉目”的过程被明显缩短了。

5. 常年会踩的坑：报错与修复速查

5.1 error: unexpected server error. check server logs

这个报错在热词里出现得很多，而且通常是在 Windows 终端里敲opencode后直接弹出来。看到这个错误时，我的第一反应不是怀疑 opencode 本身，而是怀疑它连不上下游的模型服务。

排查顺序一般是这样的。先看是否设置了 API key，环境变量名和配置里的 provider 是否对得上。再看你填的请求地址是否正确，如果你配了自建网关或订阅服务，baseURL少了一个斜杠、多了个空格都可能出问题。最后看服务商本身是否稳定，有些免费模型服务高峰期经常返回 5xx，换个时段再试就行。

调试时可以用一个更详细的方式启动：

opencode --log-level debug

日志会打印请求细节，能直接看出是鉴权失败、地址不通还是模型不存在。这里我特别提醒一下：官方服务出问题的概率很低，大部分“unexpected server error”都出在自定义配置或者免费模型服务上。

5.2 免费的 hy3-free 类模型下线了怎么办

社区里经常有人分享一些免费模型，名字后面往往带个-free或者日期标记。这类模型本质上是一些免费频道提供的实验性资源，最大的问题就是生命周期不可控，可能你今天还在用，明天就收到“模型不存在”的报错。

热词里的 hy3-free 就是这个情况。如果你遇到类似问题，处理思路很清楚：先看配置里 model 字段是否还指向那个已下线的模型，换个还在维护的模型；如果是为了省钱才用免费模型，我建议把免费模型用于低价值任务，核心开发流程还是配一个稳定的商用 API。

我的经验是：不要把“能跑通”当成“应该用”。免费模型偶尔用来跑个小测试没问题，但你在它上面沉淀的 prompt 和流程，一旦模型下线就得全部重调，这个隐性成本其实很高。

5.3 版本升级与配置兼容：opencode 2.0 这类迭代中要注意什么

opencode 迭代速度很快，社区里已经有关于 2.0 的讨论，还有 desktop 方向的消息。版本升级最容易出现的问题是旧配置失效，比如某个 provider 字段被改名、默认模型取值变了、命令参数不兼容。

我的建议是：升级前先备份配置文件，然后看官方 changelog。不要一看到新版本就立刻升，尤其是你手头正跑着重要项目时，等一两天看看社区反馈再升也不迟。升级后先用opencode --version和最小对话确认链路正常，再用到真实项目上。

另外，如果你在用第三方配置管理工具管理 skills，升级后也要确认工具的兼容性，否则可能出现“命令还在，skill 加载不出来”的情况。

5.4 报错速查表

这张表是我在社区群里帮人排查时积累下来的，基本覆盖了常见问题的第一现场。遇到新问题，建议先打开 debug 日志看原始信息，再往模型、网络、配置三个方向去拆，大多数问题都逃不出这三类。

6. 个人工作流建议

说实话，工具再强也只是工具，真正有价值的是你对项目的理解。opencode 让我省掉了大量“找文件、读代码、跑测试”的机械劳动，但我每次让它动手前，还是会先把需求和边界说清楚。说得越具体，它交付的结果越接近我想要的，这比换一个更贵的模型有用得多。

最后再分享一个小技巧：把高频动作沉淀成 Skill。我现在的配置里固定有三个自定义 skill，分别是代码评审、补单测、迁移脚本生成，每次遇到对应场景，直接一句话触发，出来的结果比“自由发挥”稳定太多。建议你也从自己的重复劳动里找出两三个最痛的点，先固化成一个 skill，你会发现 opencode 越用越顺手。希望这份实战笔记能帮你把它真正跑起来，少走我当初踩过的弯路。