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但实际上你不填 keyopencode 自带的官方网关也能让你先体验一把。也就是说你只要选择一个官方默认模型它内部会自动完成路由你不需要注册任何厂商账号也不需要配置任何环境变量就能在终端里跟它对话。这个设计很聪明降低了上手的心理门槛。等你自己有特定模型的需求再去配置自己的 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.jsonWindows 下是%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 编程代理但侧重点有明显差异。维度opencodeClaude CodeCodex模型灵活性高支持任意 OpenAI 兼容服务低绑定 Claude 系列中以 GPT 系列为主配置复杂度中JSON 文件可完全控制低官方开箱即用低绑定 ChatGPT 账号项目接管能力强工具链完整强但受模型限制中偏代码生成免费体验官方网关免配置可接免费模型基本无免费额度有少量免费额度扩展生态skills、memory、IDE 插件插件较少与 GitHub 深度绑定与 IDE 协作有 VSCode 和 JetBrains 插件官方 CLI 为主有 GitHub Copilot 生态说说我的实际选择日常主力是 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 目录下创建好之后在对话中提及生成接口文档或者引用这个 skillopencode 就会按照你写好的步骤执行。这个机制的本质是约束行为让 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的形式反馈出来。排查链路我建议从这几步开始确认 API Key 是否有效额度是否耗尽。很多模型的 API 在额度耗尽时返回的不是 401而是 500 或 502这就会触发 unexpected server error。检查 baseURL 是否正确。特别是你手动填写了一个不存在的路径或者漏掉了/v1后缀服务端会返回 404而 opencode 的容错会把这个错误也归类到 unexpected server error。尝试用 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 的历史会话是有状态的旧会话里的错误操作有时会在你打开新会话时继承。我的习惯是每完成一个独立任务就清掉会话记录新建一个干净的会话开始下一个任务。这能避免很多奇怪的状态干扰。 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但实际上你不填 keyopencode 自带的官方网关也能让你先体验一把。也就是说你只要选择一个官方默认模型它内部会自动完成路由你不需要注册任何厂商账号也不需要配置任何环境变量就能在终端里跟它对话。这个设计很聪明降低了上手的心理门槛。等你自己有特定模型的需求再去配置自己的 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.jsonWindows 下是%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 编程代理但侧重点有明显差异。维度opencodeClaude CodeCodex模型灵活性高支持任意 OpenAI 兼容服务低绑定 Claude 系列中以 GPT 系列为主配置复杂度中JSON 文件可完全控制低官方开箱即用低绑定 ChatGPT 账号项目接管能力强工具链完整强但受模型限制中偏代码生成免费体验官方网关免配置可接免费模型基本无免费额度有少量免费额度扩展生态skills、memory、IDE 插件插件较少与 GitHub 深度绑定与 IDE 协作有 VSCode 和 JetBrains 插件官方 CLI 为主有 GitHub Copilot 生态说说我的实际选择日常主力是 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 目录下创建好之后在对话中提及生成接口文档或者引用这个 skillopencode 就会按照你写好的步骤执行。这个机制的本质是约束行为让 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的形式反馈出来。排查链路我建议从这几步开始确认 API Key 是否有效额度是否耗尽。很多模型的 API 在额度耗尽时返回的不是 401而是 500 或 502这就会触发 unexpected server error。检查 baseURL 是否正确。特别是你手动填写了一个不存在的路径或者漏掉了/v1后缀服务端会返回 404而 opencode 的容错会把这个错误也归类到 unexpected server error。尝试用 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 的历史会话是有状态的旧会话里的错误操作有时会在你打开新会话时继承。我的习惯是每完成一个独立任务就清掉会话记录新建一个干净的会话开始下一个任务。这能避免很多奇怪的状态干扰。