opencode终端AI编程代理：安装配置、免费模型接入与项目实战

1. 从一次终端卡顿说起：opencode 到底解决了什么问题

大概两个月前，我在一个多模块的老项目里改需求，来回在编辑器、浏览器、终端三个窗口之间切，同一个上下文要反复说好几遍。当时同行推荐我试试终端 AI 编程代理，也就是把 AI 直接拉进命令行里干活的那类工具。我在 Claude Code、Codex 和其它几个 agent 之间轮了一圈，最后稳定停在 opencode 上，一直用到现在。

opencode 是一个运行在终端里的开源 AI 编程代理，由 SST 团队开源。它最大的特点不是"能写代码"，而是"能直接接管项目"。你可以在项目根目录启动它，让它自己读代码、自己定位问题、自己改文件，改完还能跑测试验证。整个过程中你只需要用自然语言描述意图，剩下的活它自己安排。

这类工具现在并不稀奇，但 opencode 有几点让我觉得顺手。第一，它对模型不挑剔。Claude、GPT、各种国产模型，只要是 OpenAI 兼容接口都能接，不像有些工具绑定单一模型厂商。第二，它同时有终端交互界面、桌面版和 IDE 插件，使用场景覆盖得很全。第三，它原生支持 skills 和 memory，可以让 AI 记住你的项目偏好，也能给它预置一套处理流程。

这篇文章不是官方文档的翻译，而是我实际用了两个月之后整理的使用经验。内容包括安装方式、配置文件的坑、怎么接免费模型、怎么在真实项目里让它干活，以及我踩过的几个具体报错。如果你正准备上手 opencode，或者已经装上但觉得"好像不太会用"，这篇文章应该能帮你少走不少冤枉路。

2. 安装到跑通第一条指令，Windows 用户的坑我帮你踩完了

2.1 三种安装方式，按环境选

opencode 的安装方式不算复杂，常见的有这么几种：

• 通过 npm 全局安装：npm install -g opencode-ai，装完直接有opencode命令。
• 通过 Homebrew 安装：brew install sst/tap/opencode，适合 macOS 用户。
• 直接下载二进制或者用安装脚本，适合没有 Node 环境的 Linux 机器。

我自己主力环境是 macOS，一台 Windows 机器专门用来测兼容性。实际操作下来，npm 方式最通用，Windows 和 macOS 都能用，只要 Node 版本不低于 18 就行。

安装之后验证是否成功，直接在终端输入：

opencode --version

能输出版本号说明装好了。如果这里就报错，别急着往下走，先解决环境变量的问题。

2.2 最常见的 Windows 报错：无法识别 cmdlet

如果你在 Windows 上装完 opencode，输入命令后看到这么一串：

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

这基本可以断定是 npm 全局安装目录没有加进系统 PATH。npm 在 Windows 上的全局包默认装在C:\Users\你的用户名\AppData\Roaming\npm这个目录下，如果这个目录不在 PATH 里，系统就找不到opencode.cmd这个启动文件。

解决办法不复杂：打开系统设置里的"编辑环境变量"，在用户变量 Path 中新增%APPDATA%\npm，然后重新打开一个终端窗口，再执行版本检查。注意，一定要新开终端窗口，因为已经打开的终端不会重新加载环境变量。

提示：改完 PATH 之后，如果还是提示找不到命令，可以用where opencode看看系统实际搜索到的路径。这个命令会列出所有同名可执行文件的位置，方便排查是否装了多份。

2.3 首次启动：不用急着填 API Key

安装好之后，在项目目录里直接运行：

opencode

首次启动会进入一个全屏的交互界面，默认会提示你配置模型提供商。这里有一个容易劝退新人的误解——界面让你填 API Key，但实际上你不填 key，opencode 自带的官方网关也能让你先体验一把。也就是说，你只要选择一个官方默认模型，它内部会自动完成路由，你不需要注册任何厂商账号，也不需要配置任何环境变量，就能在终端里跟它对话。

这个设计很聪明，降低了上手的心理门槛。等你自己有特定模型的需求，再去配置自己的 API Key 也不迟。我的建议是：第一晚先用官方网关跑通流程，第二天再折腾模型接入。先看到效果，后面的事都好说。

这里顺便说明一下，官方网关的体验是完全可以直接用的，你不需要在系统里配置任何 API key。opencode 的官方模型会自动选择路由，用的模型按官方默认配置走，用户无需指定。如果你需要更精细控制或者是某个具体模型，再手动配置不迟。

2.4 跑通第一条指令

进入交互界面之后，随便输入一句指令试试，比如让它看看当前项目是什么技术栈：

看看这个项目里用了哪些框架，列出 package.json 里的主要依赖

opencode 会读文件、分析依赖，然后在对话里给你列出来。这个过程中你能看到它每一步在做什么，读取了哪些文件，调用了什么工具，整个过程完全透明。跑通了这一步，说明你的核心链路没问题，接下来就可以进入正题了——配置你自己的模型、让它真正帮你干活。

3. 模型接入：从官方网关到免费模型，再到 ccswitch 一键切换

3.1 为什么说 opencode 的模型接入是它最大的优势

用过 Claude Code 的人应该能感觉到，它的模型绑定得很死，基本只能用它自家的 Claude。Codex 则绑定 ChatGPT 那套。而 opencode 基于 Vercel 的 AI SDK 构建，天生就是一套"模型无关"的架构。它默认支持 Anthropic、OpenAI、Gemini、DeepSeek、智谱、零一万物、Moonshot 等多家厂商，也可以把任意一个 OpenAI 兼容的服务接进来。

这个特性在实际使用中太重要了。我是在国内网络环境下使用，Claude 虽然能力强但成本高，日常小需求用国产模型就够了，遇到复杂重构再切回 Claude。opencode 让我能在一个工具里完成这种切换，不用换个模型换一个软件。

3.2 在 opencode.json 里配置自定义模型

opencode 的配置文件是opencode.json，可以放在项目根目录，也可以放在全局配置目录。全局配置在 macOS 和 Linux 下是~/.config/opencode/opencode.json，Windows 下是%USERPROFILE%\.config\opencode\opencode.json。

一个最基础的自定义 provider 配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", "name": "My Provider", "options": { "baseURL": "https://你的服务地址/v1", "apiKey": "你的APIKey" }, "models": { "my-model": { "name": "My Model" } } } } }

配置好之后，在 opencode 界面里按快捷键切换模型，就能看到myprovider/my-model这个选项。这里的npm字段用的是 AI SDK 的 provider 包，@ai-sdk/openai-compatible是最通用的，几乎所有支持 OpenAI 格式的服务都能用。

注意：配置文件的 JSON 格式非常严格，多一个逗号、少一个引号都会导致 opencode 启动时报错。修改完配置之后，可以用任意 JSON 校验工具先检查一遍再重启。

3.3 免费模型的实际接入方案

热词里频繁出现"免费模型"和"hy3-free 下线了吗"这类问题，说明很多用户希望低成本跑起来。我的看法是，不要迷信任何一家"永久免费"的服务，因为免费额度说没有就没有。与其到处找免费接口，不如掌握"接任意 OpenAI 兼容接口"这个通用能力，然后选择当前性价比最高的服务。

目前国内几个主流模型开放平台基本都提供 OpenAI 兼容端点，注册之后会给你一个 API Key 和 baseURL。照着上面那个 JSON 模板把地址和 Key 填进去就能用。即便某家免费额度下线了，你只需要把baseURL换成另一家，一分钟就能切换，不需要改任何代码。

我自己当前的策略是：日常小任务用 DeepSeek 或智谱 GLM 这类国产轻量模型，遇到大型重构、疑难 bug、架构设计这类高难度任务，切换到 Claude 或 GPT。以前这样切换要在多个工具间来回倒腾，现在全都在 opencode 里完成，每个模型的表现差异在对话流里一目了然。

3.4 用 ccswitch 管理多套配置

当你手里的模型越来越多，手动改 JSON 就不现实了。这时候就要用到 ccswitch 这类配置管理工具。ccswitch 是一个命令行模型切换工具，最初是为了管理 Claude Code 的多套供应商配置而生的，后来也支持了 opencode。

我的使用方式是这样的：在 ccswitch 里录入多套供应商配置，每个配置包含 baseURL、API Key 和模型名。需要切换时，在终端运行 ccswitch 交互界面选目标配置，工具会自动写入 opencode 的配置文件。之后重启 opencode 就能用到新模型。

ccswitch 和 opencode 配合的关键在于配置的目标路径要正确。在 ccswitch 的配置界面里，选择目标工具为 opencode，它会自动找到opencode.json并更新 provider 部分。你不需要手动确认路径，但要注意 ccswitch 只会修改默认全局配置，如果你在某个项目里用了独立的opencode.json，切换不会对那个项目生效。

提示：ccswitch 在切换配置后，建议在 opencode 里用切换模型快捷键确认一下当前生效的模型，不要凭界面上的显示判断。我遇到过一次 ccswitch 显示切换成功，但 opencode 里实际还在用旧配置的情况，后来发现是两个工具的配置路径指向不一致。遇到这种情况，优先检查全局配置目录下是否有多个opencode.json文件。

4. 在真实项目里干活：从答疑到自主改代码

4.1 让 opencode 先读懂项目，再动手

很多人的用法停留在"在终端里问 AI 问题"，这其实是浪费了 opencode 的能力。它真正厉害的地方在于，能自己探索整个项目，理解模块之间的关系，然后在理解的基础上去改代码。

我通常会这样启动一个任务：

你花点时间看一下这个项目的目录结构，搞清楚这几个模块之间怎么依赖的，然后告诉我如果要调整某个功能，需要注意哪些文件。

这个指令的关键在于前半句——"看一下项目的目录结构"。opencode 会调用它的文件读取工具，扫描目录、查看关键文件，最后给出一个全局理解。这步完成之后，你再丢给它一个具体的修改任务，它的准确率会明显提升。如果一上来就丢任务，它往往需要边做边理解，遇到复杂项目容易改错地方。

这里要特别说明一下 opencode 在复杂仓库中的表现。它和 Claude Code、Codex 这类 agent 的区别在于对上下文的组织方式。opencode 会维护一个会话内的上下文状态，每一次文件读取、搜索、命令执行的产出都会成为后续判断的依据。所以当你给它一个"先读代码再动手"的指令时，它后续的行为是基于真正的代码分析结果，而不是捏造的猜测。

4.2 实际案例：让 opencode 接手改造一个老模块

我用一个实际经历来说明它的工作方式。上个月我在维护一个交易系统里的订单模块，需求是把订单状态的更新逻辑从同步改成异步，同时保留原有的同步入口。这个改动涉及服务层、数据访问层和消息队列三块，业务规则很绕。

我先让 opencode 阅读了这个模块的入口文件，然后一步步追问：同步和异步的差别在哪、哪些地方依赖返回值、消息队列的 topic 命名规范是什么。它给出的回答都比较准确，因为它真的读了代码，连注解注释都看到了。

确认理解一致之后，我才让它开始改。它自己完成了这几件事：

• 把原来的同步更新方法拆成两个版本，保留旧方法不变
• 新增了异步处理方法和消息发送逻辑
• 在入口处加了分支判断，按配置决定走同步还是异步
• 运行了项目现有的测试用例，确认没有破坏原有行为

整个过程大约花了 20 分钟，中途我干预了两次。一次是让它统一错误码格式，一次是提醒它新方法需要补充事务注解。这种"大方向它能搞定，细节需要你把关"的协作状态，我觉得是最理想的人机配合模式。

4.3 和 Claude Code、Codex 的横向对比

既然热词里也有人问"opencode、codex、claude code 哪个 agent 好用"，我结合自己的实际使用体验，给一个主观对比。这三者定位相似，都是终端 AI 编程代理，但侧重点有明显差异。

说说我的实际选择：日常主力是 opencode，原因很简单——模型自由。Claude Code 如果你本身订阅了 Claude 服务，体验其实很流畅，单论 Claude 模型的对话质量甚至比 opencode 里接 Claude 更稳，因为它有官方调优。Codex 对 GitHub 生态的整合很好，如果你重度使用 GitHub Copilot，它的联动体验是三者里最顺的。

但你要让我选一个"全场景通用"的 agent，我还是选 opencode。原因有两个。第一，模型自由意味着成本可控，我能按任务难度选模型，而不是一刀切用最贵的。第二，它的配置和生态是开放的，skills、memory、插件这些能力让它更像一个可以长期打磨的工作台，而不是一个固定输出的工具。

4.4 让 opencode 跑测试和修 bug

除了改代码，opencode 另一个高频用途是跑测试。你可以在对话里直接说"运行这个项目的测试，把失败的用例列出来"。它会自动找到测试命令并执行，然后把失败信息返回给你。

更进阶的玩法是让 opencode 自己修复失败用例。我试过一次，把失败用例的日志丢给它，它能定位到具体是哪个方法的行为和预期不符，然后提出修复方案。有一个用例是因为浮点数精度问题导致的断言失败，它给出的修复是改用toBeCloseTo断言，这确实是标准的处理方式。

至于前端 bug 排查，opencode 配合 Playwright 也很好用。你可以在 opencode 的 skills 里预置一个 Playwright 技能，让它在对话中自动编写测试脚本并运行。比如输入"用 Playwright 测一下这个登录页面的表单校验"，它会自动生成脚本、启动浏览器、跑完测试并把结果反馈回来。原生支持这个能力的好处是，不需要你在终端和浏览器之间来回切换，整个测试过程都在 opencode 的对话流里完成。

5. memory 和 skills：把 opencode 训练成熟悉你项目的搭档

5.1 memory：让 AI 记住项目约定和你的偏好

opencode 的 memory 功能，简单说就是给它一个"长期记忆"。默认情况下，每次会话结束之后，它并不会主动记住你的项目背景、代码规范、命名习惯这些信息。如果你希望它在下一次会话里还能记住，就需要用到 memory。

配置方式比较直接。在全局配置目录下有一个 memory 相关的存储位置，你可以在会话中直接要求 opencode 记住某个信息。比如：

记住：这个项目的错误码统一用 5 位数字，前两位表示模块，后三位表示具体错误。

opencode 会把这类信息写进 memory 文件，之后的对话会自动读取并作为上下文参考。我实际用过之后的感觉是，如果你只在同一个项目里反复工作，这个功能非常值。它等于帮 AI 建了一份"项目手册"，避免每次新会话都要重新交代一遍背景。

需要注意的是，memory 不是万能的。它记录的是显式要求记住的信息，不会主动总结你的操作习惯。所以建议你在项目初期就花点时间，把重要的约定一次性写给它。

5.2 skills：给 AI 预置一套工作流程

skills 是 opencode 里一个更强大的扩展机制。你可以把它理解成"给 AI 预设的技能包"，每个 skill 本质上是一组操作指令和工作流定义。当你在对话中触发某个 skill 时，opencode 会按照预定的流程执行任务，而不是自由发挥。

社区里比较出名的两个 skill 集合是 oh-my-claudecode 和 superpowers。oh-my-claudecode 最初是为 Claude Code 设计的一套增强配置包，现在也有社区成员把它移植到了 opencode。它里面包含大量针对测试、调试、重构的标准流程，能提升 agent 在复杂任务里的表现。superpowers 则是一套更系统的 agent 技能集合，覆盖从需求分析到代码实现再到验证的完整链路。

我自己的习惯是只挑其中几个技能放进配置，而不是全量引入。全量引入的坏处是，技能文件太多时 agent 的响应会变慢，而且有些技能之间的指令可能冲突。与其把技能包装满，不如挑几个真正契合自己工作方式的。

5.3 手动创建自己的 skill

创建自定义 skill 也没有想象中复杂。在 opencode 的配置目录下，有一个专门放 skill 的文件夹。每个 skill 以文件夹为单位，里面包含一个 markdown 文件，描述这个技能的名称、触发场景和执行步骤。

举个例子，如果你经常需要写接口文档，就可以创建一个名为api-doc的 skill，内容大致是：

--- name: api-doc description: 根据项目中的接口定义生成接口文档 --- 当用户要求生成接口文档时，执行以下步骤： 1. 扫描项目中的路由和控制器文件，找出所有接口定义 2. 识别每个接口的路径、方法、请求参数和返回结构 3. 按照项目已有的文档模板生成 markdown 格式的接口文档 4. 将文档保存到 docs/api 目录下

创建好之后，在对话中提及"生成接口文档"或者引用这个 skill，opencode 就会按照你写好的步骤执行。这个机制的本质是"约束行为"，让 AI 的产出更可控。对于团队协作来说，把常用工作流固化成 skill，等于把个人经验沉淀成了团队资产。

5.4 和 IDE 插件的配合

opencode 不是只活在终端里的。它提供了 VSCode 插件和 JetBrains IDEA 插件，安装之后，你可以在编辑器的侧边栏直接打开 opencode 面板，在写代码的同时和它对话。

我的使用方式是混合的：大部分时候在终端里用 opencode，因为它全屏交互界面信息密度高，能看到工具调用过程；当需要在具体文件上下文里讨论问题时，切换到 VSCode 插件，让它在编辑器上下文里帮我分析当前打开的文件。

IDEA 插件和 VSCode 插件的功能对齐度比较高，基本都支持在编辑器内开对话、查看 diff、接受/拒绝代码建议。如果你平时主要用 IDEA，也一样能获得差不多的体验。

6. 排查记录：我遇到的几个典型报错和解决思路

6.1unexpected server error：先查模型服务端，别先怪工具

这个报错应该是最多用户碰到的。热词里有人截图了opencode error: unexpected server error. check server logs ...，我在接第三方模型时也遇到过几次。

先说结论：这个报错的根因基本在模型服务端，不在 opencode 本身。opencode 只是把你发送的请求转发到模型的 API，当 API 返回了非预期的错误状态码时，它就会以unexpected server error的形式反馈出来。

排查链路我建议从这几步开始：

1. 确认 API Key 是否有效，额度是否耗尽。很多模型的 API 在额度耗尽时返回的不是 401，而是 500 或 502，这就会触发 unexpected server error。
2. 检查 baseURL 是否正确。特别是你手动填写了一个不存在的路径，或者漏掉了/v1后缀，服务端会返回 404，而 opencode 的容错会把这个错误也归类到 unexpected server error。
3. 尝试用 curl 直接调用模型 API，看是否能返回正常响应。这一步能快速定位问题到底出在模型服务端还是出在 opencode 配置上。

我遇到过一次比较隐蔽的情况：我用了一个中转服务，那个服务在正常时段一切正常，但晚间高峰期会随机返回 503。直接测试时可能没问题，但 opencode 在并发请求或长响应时会触发它的异常。这种情况下没有别的办法，只能换更稳定的服务商，或者避开高峰期。

6.2 配置文件不生效：检查是不是路径优先级搞错了

opencode 的配置有多个层级：命令行参数、项目级opencode.json、全局配置文件。优先级从高到低，命令行参数最高，其次是项目级，最后才是全局。如果你在全局配置里设了一个模型，但项目里的配置覆盖了它，就会看到一个对不上的现象。

我踩过的坑是：在项目根目录放了一个opencode.json，里面只写了项目专用的模型，但全局配置里设的是另一个模型。我明明在全局里切换了模型，但实际跑起来没变化，因为项目配置覆盖了全局配置。

排查方式很简单，在 opencode 界面里查看当前载入的配置来源。如果发现不是你想要的那一份，检查项目目录下是否有独立的opencode.json文件。

6.3 环境变量改动后重启会话，配置未生效

另一个高频问题：改了环境变量之后，打开新的 opencode 会话，模型没有变化。这通常是因为 opencode 在启动时读取了一次环境变量，之后不会动态刷新。你需要完全退出 opencode 进程，确认终端里的环境变量已经更新，再重新启动。

在 Windows 上这个坑特别明显，因为系统环境变量的修改不会自动传播到已经打开的终端。改完系统环境变量一定要重新打开终端，再启动 opencode，否则它读到的还是旧值。

6.4 Playwright 测试跑不起来

如果你按照我前面的方法让 opencode 配合 Playwright 做前端测试，可能会遇到测试脚本生成了但浏览器启动不了的问题。最常见的两个原因：

第一，系统没有安装 Playwright 的浏览器内核。需要在终端执行npx playwright install安装对应浏览器。第二，Playwright 执行时需要依赖系统的一些运行库，在 Linux 服务器上跑还需要安装额外的依赖，比如npx playwright install-deps。

opencode 生成的测试脚本本身通常问题不大，报错大多出在环境上。根据我的经验，先检查浏览器内核是否装好，再检查系统依赖，能解决绝大多数 Playwright 相关的问题。

7. 桌面版和 Go 版本的定位，以及你该怎么选

7.1 桌面版适合哪些场景

热词里也出现了"opencode 桌面版"和"opencode desktop"。和终端交互界面相比，桌面版把同样的能力封装进了图形界面，对话记录管理更直观，适合不习惯终端操作的同学。但我个人还是更推荐终端版，原因在于 agent 工作流的核心价值是"透明"，终端版能直接看到它执行每一步调用的指令和返回的结果，这种透明度对排查问题很有帮助。

桌面版适合的场景是：你主要是为了和 AI 对话，不关心底层的工具调用过程。它把复杂度隐藏得更好，更像一个聊天工具。而对于真正的项目开发，建议还是用终端版，或者 IDE 插件。

7.2 Go 版本和 ccswitch 的配合

opencode Go 是社区开发的一个 Go 语言实现的版本，用途和官方版基本一致，但启动速度更快、内存占用更小。热词里提到"opencode go 需要配合 cc switch 等工具"，这个说法基本准确。因为 Go 版默认的配置文件路径和官方版不完全一样，ccswitch 需要做一些适配才能正确写入配置。

我的建议是，如果没有特殊的性能需求，优先用官方版，因为生态更新最快，新功能最先上线，社区的提问和文档也主要围绕官方版展开。Go 版适合对性能敏感、或者在低配机器上跑的场景，但它并不是一个完全替代官方版的方案。

7.3 从搜索结果看大家最关心的是什么

我大致看了一下搜索热词，发现关注点主要集中在几类：安装报错、免费模型、配置方法、IDE 插件、和同类工具的对比。这说明大部分用户还处在"正在尝试把它用起来"的阶段，而不是深度使用。如果你也刚接触 opencode，建议按这个顺序走：先跑通官方网关的默认对话，再接入自己常用的模型，接着把 skills 和 memory 配起来，最后再考虑 IDE 插件和桌面版。这个路径可以保证每一步都有可感知的效果，不容易被中途的各种报错劝退。

8. 一些零碎但实用的收尾经验

最后分享几个我在实际使用中总结的小技巧，不一定成体系，但都比较实用。

第一个是善用"先分析后执行"的指令。这是让 opencode 在复杂任务中保持高准确率的关键。不管任务看起来多简单，先让它说明计划，你确认之后再加一句"按这个方案执行"，效果会比直接下命令好很多。原因是 agent 的执行链路比较长，一旦方向错了，后面每一步都要返工。

第二个是对话上下文管理。opencode 的单次会话是有上下文长度限制的，如果项目代码量很大，它可能忽略一些早期的指令。我的做法是：和项目相关的关键约定写进 memory，每次会话开头只强调当前任务的增量信息。这样既能保持上下文精简，又能确保重要信息不丢失。

第三个是善用自定义模型切换。我在前面的配置里建立了大约五个模型入口，覆盖从轻量到重型的任务需求。日常改文案、写简单脚本用便宜的轻量模型；大范围重构、调试多模块的时候切到最强的模型。这种"按需付费"的策略让我的每月 API 成本控制在一个非常低的水平，同时又保证了复杂任务的完成质量。

第四个是定期清理会话。opencode 的历史会话是有状态的，旧会话里的错误操作有时会在你打开新会话时继承。我的习惯是每完成一个独立任务就清掉会话记录，新建一个干净的会话开始下一个任务。这能避免很多奇怪的状态干扰。