1. opencode 到底是个什么东西1.1 一句话先给你定位清楚如果你平时用 Claude Code 或者 OpenAI Codex CLI那第一次见到 opencode 的界面应该会觉得非常眼熟——一个跑在终端里的 AI 编程助手能读你的代码、执行命令、生成 diff、帮你修 bug。但 opencode 跟它们有个最重要的区别它是开源的而且模型不锁定。你可以把 Anthropic、OpenAI、Google 的模型接进去也可以接 Ollama 跑本地模型甚至接各家网关服务的统一接口。这项目我实际用了大概三四个月从命令行到 VSCode 插件再到桌面版都折腾过一遍最大的感受是opencode 不是一个“玩具 Agent”它更像是把 “Claude Code 式的工作流” 重新做了一套然后故意把模型层做成了可替换。很多人在选型时纠结“opencode、codex、claude code、pi 哪个 agent 好用”我的结论很直接如果你希望以后换模型不换工具或者想白嫖一些免费模型额度那 opencode 的性价比和自由度明显更高。1.2 和 Claude Code、Codex、Pi 相比它凭什么值得用先别急着听我吹咱们把这类工具横向拉出来看一遍工具模型锁定开源生态/插件适合场景Claude Code基本锁定 Claude 系列否弱Anthropic 全家桶用户Codex CLI偏 OpenAI 系列否弱OpenAI 生态重度用户Pi部分终端 Agent各家不同部分开源一般轻度尝鲜opencode不锁定是Skills、Memory、LSP、Playwright 等多模型混用、深度定制、想看懂每一步做了什么的人opencode 的优势在我看来有三点。第一配置透明。它把模型 provider、API Key、temperature、系统提示词全都放在一个 JSON 文件里改起来非常直观不像某些工具把配置散落在 GUI 的犄角旮旯。你甚至可以把它当做一个“模型网关客户端”来用同一个项目里白天用贵的强模型干活晚上用便宜的模型做简单重构切来切去不用换工具。第二Skills 机制。这是它区别于很多 AI Agent 的核心设计。你可以把一段反复使用的提示词、一套固定的操作流程、甚至一个外部脚本封装成“技能”让 Agent 灵活调用。社区里有人做了专门做 Code Review 的 skill也有人做了自动写提交信息的 skill装上之后的效果比在聊天窗口里每次重新打字强太多了。第三能进 IDE也能不进 IDE。它既有 VSCode 插件、JetBrains IDEA 插件也有桌面版但最稳的主战场还是终端。这种“终端为主、IDE 为辅”的设计特别适合我这种习惯在终端里操作 git、跑构建、看日志的人Agent 能直接看到我命令行的上下文减少了很多来回解释的废话。2. 安装与启动从零开始跑通2.1 三种安装方式按你的环境选先说最主流的方式。opencode 的安装路径官方文档里写了三种我挨个试过给你梳理一下区别。第一种是npm 全局安装适合已经装了 Node.js 的人。命令很简单npm install -g opencode-ai注意包名是opencode-ai不是opencode因为 npm 上opencode这个名字被别人占了。装完之后终端里直接敲opencode就能启动。第二种是官方一键安装脚本适合 macOS 和 Linux 用户不需要 Node 环境也能装脚本会自己处理依赖和 PATHcurl -fsSL https://opencode.ai/install | bash第三种是桌面版 / Release 安装包。Windows 用户可以去 GitHub Releases 页面下载安装包或者直接找官网的 desktop 入口。桌面版的本质就是把终端 Agent 包了一层 GUI但对不熟悉命令行的朋友友好很多后面我会专门写。2.2 我踩过最多的坑cmdlet 识别报错Windows 上最经典的报错搜索量常年排在第一opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错不是我夸张几乎每个用 npm 安装的 Windows 用户都会遇到。原因特别简单npm 的全局安装目录没有加到系统 PATH 里。解决办法分三步走先找到 npm 全局目录npm prefix -g我机器上输出的是C:\Users\你的用户名\AppData\Roaming\npm这个目录里应该能看到opencode.cmd文件。把这个目录加到系统环境变量 PATH。Win 键搜索“编辑账户的环境变量”在“系统变量”里找到 Path新增一行C:\Users\你的用户名\AppData\Roaming\npm。打开新的终端窗口验证一下opencode --version如果加了 PATH 还是不行检查一下是不是用了公司电脑、有组策略锁住了环境变量或者干脆把 Node 卸载了重装 LTS 版本再用 nvm 管理 Node 版本避免权限问题。我个人在 Windows 上更推荐用官方安装包而不是 npm省去一堆环境变量的破事。2.3 安装完成后先别急着干活做一次体检装好之后我建议先跑两个命令opencode --version opencode --help--help输出的内容不多但主要子命令都在里面opencode直接启动交互式终端opencode run可以非交互式跑一次性任务适合脚本调用opencode auth用来登录或者管理凭证opencode agent可以创建独立会话。首次启动时opencode 会让你选择模型商和填入 API Key。这里有个细节如果你在配置文件里已经写好了 provider启动时它会自动读取不会反复问你。配置文件的路径和写法我放到下一节详细讲。3. 配置与模型接入把模型装进你的终端3.1 配置文件到底在哪怎么改opencode 的配置路径不同系统不一样macOS / Linux~/.config/opencode/opencode.jsonWindows%USERPROFILE%\.config\opencode\opencode.json我的建议是不要急着改全局配置。每个项目下可以放一个.opencode.json项目的配置优先级更高适合按仓库自定义模型和提示词。比如某个仓库要求必须用某个模型跑测试就在项目根目录写一个 .opencode.json团队其他人 clone 下来也能读到非常方便。一个最基础的配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { options: { apiKey: sk-ant-..., model: claude-sonnet-4-20250514 } }, openai: { options: { apiKey: sk-proj-..., model: gpt-4.1 } } } }如果你担心 key 泄露就不要直接把 key 写进 JSON改成引用环境变量{ provider: { openai: { options: { apiKey: {env:OPENAI_API_KEY} } } } }这样 key 只存在于 shell 的环境变量里配置文件即使提交到 git 也不怕。3.2 免费模型怎么选别被“免费”俩字带偏很多人搜“opencode 免费模型”其实是希望不花钱先体验一遍。我实测下来有两条路比较靠谱。一条是接 Ollama 跑本地模型。比如qwen2.5-coder:7b、llama3.1:8b本地推理完全免费但速度取决于你机器配置7B 模型在 16G 内存的 Mac 上还能用在 8G 的 Windows 老机器上就明显卡了。本地模型适合做代码补全、简单重构复杂的跨文件改动基本别指望。另一条是用各家云服务商的免费额度。Google Gemini 的 API 目前对个人开发者非常大方免费额度够日常玩OpenAI 新账号有时会送一些初始额度还有些模型网关平台注册即送使用金。具体到 opencode 里就是在 config.json 里配一个支援对应模型的 provider然后把 apiKey 填成你注册到的 key。这里我要泼一盆冷水“免费模型”不等于“能用得爽”。很多免费接口有每分钟请求次数限制还经常高延迟。在 opencode 里跑长任务比如让它批量修 lint 错误一小时内就能把免费额度烧光。我的建议是免费模型只用来熟悉工具和做简单任务真正常态化使用还是得准备一个付费的强模型。3.3 go 套餐与订阅模型选择我的建议热词里出现频率很高的“opencode go 订阅模型选择”我理解指的是现在市面上一些模型网关/聚合服务提供的“go 套餐”——一个账号、一个 Key然后可以在套餐范围内切换多家模型按量计费。这类服务的好处是显而易见的你不需要为 Anthropic 和 OpenAI 分别充值、分别管理 Key在 opencode 里也只需把 provider 指向网关的 OpenAI 兼容接口就行。配置大概是{ provider: { custom: { npm: ai-sdk/openai-compatible, name: go-gateway, options: { baseURL: https://api.example.com/v1, apiKey: {env:GO_API_KEY} }, models: { claude-sonnet: { name: Claude Sonnet (Gateway) }, gpt-4o: { name: GPT-4o (Gateway) } } } } }选择 go 套餐时我不只看单价还会看三件事上下文窗口是否和原版一致。有些网关会把 64k 上下文偷偷缩水成 32k长文件处理时非常容易出问题。是否有超额熔断。没有熔断的网关一旦你代码里出现死循环调用费用可能瞬间爆表。好在 opencode 自己可以限制最大请求数。模型同步是否及时。很多网关更新模型版本很慢原版都已经发布一个月了它还挂着旧版本回答质量自然差一截。至于热词里提到的“opencode go 需要配合 cc switch 等工具”这类配置切换工具主要就是帮你维护多套网关/多套 Key 的配置避免手动改 JSON 改到直接改坏。用过ccswitch 这类配置切换工具的朋友应该知道它本质上是一个集中管理配置、快速切换方案的工具。我自己的态度是如果你只用一个网关完全没必要加这一层复杂度网关一多用它确实能省心但必须注意账号与 Key 的合规性不要把多个账号的凭证混在同一台公共机器上。提示无论用哪家网关建议都在服务商后台开启“消费上限”和“单 Key 限额”这是我认为最值得养成的习惯。3.4 “this model is not available in your country” 怎么处理搜索词里有一条很典型的报错this model is not available in your country。第一次遇到的人很容易慌以为是 opencode 的问题其实这只是模型服务商侧的账号限制或区域限制。例如某些模型明确只面向特定区域开放当你的账号归属区域、IP 区域或服务商配置不符合条件时接口会直接返回这个错误。我处理这类问题的原则很简单也强烈建议你这么做先确认账号本身的区域设置是不是选错了很多平台在注册时可以选择区域但后期不允许修改。确认 API Key 对应的模型名称拼写是否正确有些报错会被网关包装成“not available”实际只是因为模型 ID 不匹配。如果确实是区域限制不要动歪脑筋去规避。正确做法是换一个对当前区域开放的模型或者改用其他提供商的同类型模型再或者在 go 套餐里找替代模型。也可以直接联系服务商客服问清楚该模型对你的账号是否开放以及是否需要单独申请权限。记住任何通过不合理方式绕过区域限制的做法既违反服务条款也可能导致账号被封。为了用一个模型冒这个风险完全不值。4. 核心玩法Skills、Memory、LSP 与自动化测试4.1 Skills 才是 opencode 的灵魂如果说 opencode 比其他终端 Agent 高出一截的地方我首推 Skills。你可以把它理解为“预置的最佳实践包”当 Agent 判断任务匹配某个 skill 的描述时就会加载这个 skill 的提示词、步骤和工具按固定流程执行而不是每次都自由发挥。比如我写了一个“前端 Bug 复现”的 skill内容大致是当用户报告前端问题时按以下流程处理 1. 先读取 package.json 确认构建工具和框架。 2. 运行 tests 或启动 dev server。 3. 使用 Playwright 打开相关页面尝试复现。 4. 输出步骤、实际表现和期望表现的对比。在 opencode 里skills 其实就是一个放在~/.config/opencode/skills或项目.opencode/skills目录下的目录里面有一个SKILL.md文件描述触发条件和行为。这种机制比较适合团队标准化A 写了 skillB 直接复用不用把经验反复口头交代。社区里现在比较火的还包括oh-my-claudecode这类配置集它本质是把 Claude Code 时代的一些技巧迁移到 opencode 上比如更细粒度的提示词模板、git 提交规范、命名建议等。我装过之后最大的感受是别全盘照搬。每个人工作流不一样逐个 skill 看一遍留几个适合的比一股脑全塞进去更有效。4.2 Memory让 Agent 记住你的项目搜索词里出现opencode memory说明很多人跟我一样遇到的核心痛点是Agent 每次会话都是“失忆”的上轮说好的架构约定下轮就忘了。opencode 的 Memory 机制可以理解成两类。第一类是项目级长期记忆。在项目根目录放一个AGENTS.md里面写清楚项目结构、常用命令、代码风格。opencode 每次启动时会自动读取这个文件相当于一睁眼就看到了“项目使用手册”。比如我有个 Java Spring 项目AGENTS.md 里写- 模块结构api / service / dao 三层。 - 新增接口必须在 controller 包下写 OpenAPI 注解。 - 数据库变更必须写 changelog 文件不允许手动改表。这样 Agent 生成的代码就不会跑偏。第二类是用户级偏好记忆。opencode 的全局配置里可以放instructions字段写你希望它始终遵守的规则比如“所有错误信息要同时给出中文和英文”或者“提交信息必须遵循 conventional commits”。这比每次对话开头都要重复一遍要求舒服太多了。我实际测试下来Memory 对“接手开发项目”这个场景帮助最大。新进入一个老项目让 opencode 先读 AGENTS.md 和 README再让它汇总 TODO、标出明显坏味道最后让它跑一遍测试。半小时的时间能顶我以前大半天熟悉代码的时间。4.3 让 Agent 真正“会读代码”LSP 接入很多人在搜索“opencode 如何使用 LSP”其实是因为发现 Agent 在理解代码符号时经常出错——变量重命名它总是漏掉引用跳转定义也会找错地方。这时候接入 Language Server ProtocolLSP就是正解。LSP 本来是编辑器用来提供智能提示的协议opencode 把 LSP 能力搬到了终端 Agent 里在修改代码前Agent 可以通过语言服务器拿到准确的符号定义、引用和诊断信息而不是靠纯文本猜。配置 LSP 并不复杂。opencode 内置了对常见语言服务器的支持比如 TypeScript 的typescript-language-server、Python 的pyright、Java 的jdtls。以 Python 项目为例你只需要保证本地装了 pyrightnpm install -g pyright然后在 opencode 的配置里启用 LSP 服务即可{ lsp: { python: { server: [pyright-langserver, --stdio], extensions: [.py] } } }启用后你在对话里让 Agent 重构某个函数它会先通过 LSP 识别该函数的所有调用点再给出改动方案准确率比我早期纯靠正则和猜测的方式高出一大截。用一句话总结LSP 是 opencode 从“会聊天的编辑器”变成“懂代码的同事”的关键一步。4.4 用 Playwright 测试前端 Bug别只会截图搜索词里有opencode playwright和opencode playwright 怎么测试前端 bug这绝对是前端开发者最感兴趣的功能。opencode 对 Playwright 的支持就是让 Agent 在对话中直接启动浏览器、访问页面、点击按钮、提交表单、截图记录。你不再需要自己手动复现 bug 路径只需要把 bug 描述清楚Agent 自己跑一遍复现流程。我踩过几次坑之后总结出几个比较高效的做法把复现步骤写进 skill。让每次 bug 排查都从固定 URL、固定账号开始避免 Agent 自己创造路径。给它明确的断言目标。比如“点击登录按钮后如果提示用户名不存在请截图如果跳转成功再执行下一步”。没有明确目标Agent 容易在页面上乱逛白白消耗 token。让它输出操作轨迹。不只看最终截图还要让它记录点击了哪个按钮、填了什么值。前端 bug 往往在某一个交互细节里操作轨迹比结论更有用。一个典型的命令是这样的使用 Playwright 打开 http://localhost:5173/login 输入邮箱 testexample.com 和密码 123456 点击登录 如果出现错误提示截图并读取提示文本如果成功跳转截图首页 最后把整个操作轨迹写进 /tmp/bug-report.mdopencode 会按步骤执行并返回每一步的结果。有了这套流程很多“在我电脑上没问题”的 bug终于可以在一个可复现的环境里暴露出来了。4.5 接手开发项目和 Maven 配置实战关于“opencode 接手开发项目”和“opencode mvn 配置”不少人单独搜过其实这俩是同一个场景——把 Agent 拉进一个老项目让它边理解边干活。以 Java Maven 项目为例我常用的配置是先确保 Agent 能用正确的方式执行 Maven 命令。首先确认本机JAVA_HOME和mvn都在 PATH 里java -version mvn -version然后我一般会先让 Agent 跑一次编译把存量错误暴露出来运行 mvn -q compile把编译错误列表汇总分类为 1. 缺少依赖 2. 语法错误 3. 类型不匹配 4. 其他这一步非常关键因为后续 Agent 改代码时如果编译错误拖着一大堆它很容易在错误的上下文里越改越乱。先把问题缩减到最小集合再逐类解决效率最高。Maven 项目还有一个常见的坑Agent 只会读 pom.xml但并不知道“哪个模块是入口”。所以我会在 AGENTS.md 里写清楚模块依赖关系和启动入口再让它干活。实战案例我上个季度接手的一个老项目600 多个 Java 文件没有文档README 是五年前的。我的操作顺序是opencode run 请扫描整个项目结构找出模块间依赖关系输出一份简短的架构说明。让 Agent 读取pom.xml标注哪些依赖已经过时、哪些版本号冲突。mvn -DskipTests package构建一次把失败信息全部抛给 Agent。逐条让它修复编译错误、单元测试失败。一个下午的时间项目基本可以跑起来了。换作以前光理清模块关系就得花一天。注意Agent 批量修改 Maven 配置时一定要让它改完就执行mvn validate检查。我曾经让 Agent 升级一个依赖版本结果版本号写错了Agent 还自信满满地说“已修复”。所以任何涉及构建配置的修改都必须跑命令验证别轻信“改完了”三个字。5. 编辑器插件与桌面版把 opencode 嵌进工作流5.1 VSCode 插件终端 Agent 和编辑器的缝合点装 opencode 的 VSCode 插件后左侧会多出一个面板可以直接在编辑器里发起对话、查看 diff、接收代码改动。底层调用的还是同一个 opencode 配置——你在配置文件里写的模型和 key在插件里完全复用不用二次配置。但这里我想重点提醒一句插件默认可能会让 Agent 直接修改你在编辑器中打开的文件。我建议在代码审查环节不要偷懒让它把所有改动都生成 diff你逐段看再决定是否接受。尤其是被 Agent “顺手改掉”的无关代码一定要在 diff 阶段拦下来。VSCode 插件适合的场景是你不想在终端和编辑器之间来回切或者你需要一边看文档一边看 diff。日常的重度操作比如批量替换、跨文件重构我依然更推荐切回终端用命令行版本——终端里 Agent 能看到更多上下文出错率反而更低。5.2 JetBrains IDEA 插件Java/Kotlin 项目的正确姿势JetBrains 家族里IDEA 插件对 Java 和 Kotlin 项目的支持会更好一些毕竟它能够借助 IDEA 的导入和索引信息对 Maven 项目、Gradle 项目的结构理解得更准。安装方式很简单Settings Plugins搜索 “opencode”安装后重启。重启完打开右侧工具窗口它会让你选择当前项目的语言模型服务——这里跟终端版一样直接复用全局配置即可。IDEA 插件里给我印象最深的是“把报错直接丢给 Agent”的路径。IDEA 的 Problems 面板会显示红波浪线点一下就复制了具体编译错误然后在 opencode 面板里自动带上文件路径和错误信息让 Agent 直接给修复方案。省了把错误复制来复制去的过程。不过说实话IDEA 插件目前的功能完整度还比不上 VSCode 插件偶尔会出现索引不同步、改动不刷新的情况。如果你的主力语言是 Java用它做辅助没问题如果你指望它在 IDEA 里完成所有复杂重构估计还得等几个版本。5.3 桌面版给不爱敲命令的人一个入口热词里还有opencode desktop和opencode桌面版。桌面版我装过一段时间它的核心就是把终端界面换成独立窗口左侧是会话列表右边是对话和工具输出视觉上更像一个聊天软件。桌面版最大的优点是降低门槛不用记命令、不用看终端配色方案下载安装包、登录、选模型就能用。适合刚接触 AI 编程工具的朋友也适合项目经理、产品经理这类要“看效果但不想碰终端”的人。但它现在还不是我的主力。原因有两点一是桌面版的日志输出不如终端版详实出问题的时候很难定位二是快捷键和脚本集成不如终端版灵活比如我要把 opencode 接进 shell 脚本做自动 commit桌面版就帮不上忙。我的建议是桌面版用来演示和入门正式干活还是用终端版 编辑器插件组合。6. 常见问题速查与避坑心得6.1 高频报错对照表我把这段时间在网上看到过的高频报错整理成了一张表都是我或者朋友实际遇到的问题你可以直接对照着排查报错现象常见原因解决思路无法将“opencode”项识别为 cmdletnpm 全局目录不在 PATH 里把npm prefix -g的目录加进系统 PATHerror: unexpected server error服务端返回异常可能是网络抖动或模型商故障看 opencode 启动日志确认是哪个 provider 报错再等一会重试this model is not available in your country账号区域 / 服务区域限制选择合规的替代模型或联系服务商确认开放范围配置文件改了没生效改错了路径项目级配置和全局配置混淆项目根目录放.opencode.json确认当前工作目录免费模型突然不可用限流或额度用完降低请求频率换备用模型或升级套餐执行 Maven/Shell 命令提示找不到命令Agent 环境变量不全在配置里显式指定 JAVA_HOME、PATH中文路径或中文内容乱码Windows 终端编码问题终端里执行chcp 65001切换到 UTF-86.2 “Unexpected server error” 到底怎么查有些报错一眼就能看出原因但unexpected server error属于最让人头大的一类因为它太笼统了。我的排查逻辑是确认 opencode 版本是不是最新的有些服务端接口更新后老版本客户端容易触发兼容性报错。执行opencode upgrade或重新安装。查看详细日志。opencode 会把日志写到~/.local/share/opencode/log或%USERPROFILE%\.local\share\opencode\log下找错误信息里有没有timeout、403、429这些关键词。如果是timeout大概率是网络到模型服务端的链路不稳或者模型商本身在过载。这种时候别反复重试先休息两分钟或者直接换一个模型。如果是429说明触发了限流。检查是不是并发请求太多把 Agent 的单次对话任务拆小一点。如果错误信息里什么有效内容都没有可以把日志尾部截下来去 GitHub Issues 搜一下相同关键字通常能找到解决方案。这种报错十有八九不是 opencode 本身的问题而是模型服务商不稳定。我的备用方案是配置里写两个 provider一个 primary 一个 fallback遇到持续性故障就切过去不耽误活儿。6.3 配置不生效、JSON 改错后的恢复有搜索词提到“opencode linux 修改 json”八成是改了配置之后发现没生效然后想找正确的修改姿势。这里有个容易被忽略的点opencode 读取配置文件是根据当前工作目录去定位的。如果你在/home/user/projectA目录下启动它优先读/home/user/projectA/.opencode.json如果项目里没有配置文件它才去找~/.config/opencode/opencode.json。很多人在根目录改了半天全局配置结果跑到项目目录下启动发现根本不读就是这个原因。JSON 配置写错了启动时会直接报 JSON 解析错误。解决办法是先在系统里安装一个 jq 工具做语法校验jq . ~/.config/opencode/opencode.json如果返回的不是 JSON 结构而是一段报错说明你的配置文件有语法问题。这时候把高手写的完整配置备份一份放到旁边改错了随时对照。我个人习惯是用 VSCode 打开配置文件配合 JSON Schema 校验可以实时提示字段错误比用记事本硬写稳得多。6.4 免费模型下线或失效时的切换思路搜索词里有“opencode hy3-free 下线了吗”说明大家都在关心手里正在用的免费模型还能撑多久。这类免费模型下线的场景我见得太多了每次都是厂商调整政策、突然移出列表用户一脸懵。应对思路只有一个不要把免费模型当成唯一依赖。我提前做了三件事另一个 provider 里常备一个本地 Ollama 模型比如qwen2.5-coder:7b。免费模型挂了至少还能靠本地模型做轻量任务。把关键的工作流写进 skill这样换模型时不用重新教 Agent“你要怎么做”它自动会按同一套流程跑。定期检查 opencode 的模型列表看看哪些新增了免费额度。很多平台对新手有“首月免费 xx 额度”这种东西错过真的很可惜。如果你发现某个模型真的下线了最急的不是抱怨而是先检查旧会话里有没有缓存下来的“模型配置片段”改几个字段就能切到替代模型其次才是去社区问替代方案。把切换成本降到最低才是长期稳定使用的王道。我自己的使用习惯是每天早上开工前先看一眼 opencode 的配置有没有报错再跑一次轻量任务“热热身”。这个习惯帮我躲过了好几次“今天模型没法用”的尴尬时刻。工具这东西省心比炫技重要稳定比花哨重要。最后再分享一个小技巧opencode 的会话里可以同时开多个任务遇到一个任务卡住别急着终止开个新会话继续干别的等它自己恢复。这个“多开”思路比反复重试效率高得多。 开源终端AI编程助手opencode：多模型接入与配置实战指南
1. opencode 到底是个什么东西1.1 一句话先给你定位清楚如果你平时用 Claude Code 或者 OpenAI Codex CLI那第一次见到 opencode 的界面应该会觉得非常眼熟——一个跑在终端里的 AI 编程助手能读你的代码、执行命令、生成 diff、帮你修 bug。但 opencode 跟它们有个最重要的区别它是开源的而且模型不锁定。你可以把 Anthropic、OpenAI、Google 的模型接进去也可以接 Ollama 跑本地模型甚至接各家网关服务的统一接口。这项目我实际用了大概三四个月从命令行到 VSCode 插件再到桌面版都折腾过一遍最大的感受是opencode 不是一个“玩具 Agent”它更像是把 “Claude Code 式的工作流” 重新做了一套然后故意把模型层做成了可替换。很多人在选型时纠结“opencode、codex、claude code、pi 哪个 agent 好用”我的结论很直接如果你希望以后换模型不换工具或者想白嫖一些免费模型额度那 opencode 的性价比和自由度明显更高。1.2 和 Claude Code、Codex、Pi 相比它凭什么值得用先别急着听我吹咱们把这类工具横向拉出来看一遍工具模型锁定开源生态/插件适合场景Claude Code基本锁定 Claude 系列否弱Anthropic 全家桶用户Codex CLI偏 OpenAI 系列否弱OpenAI 生态重度用户Pi部分终端 Agent各家不同部分开源一般轻度尝鲜opencode不锁定是Skills、Memory、LSP、Playwright 等多模型混用、深度定制、想看懂每一步做了什么的人opencode 的优势在我看来有三点。第一配置透明。它把模型 provider、API Key、temperature、系统提示词全都放在一个 JSON 文件里改起来非常直观不像某些工具把配置散落在 GUI 的犄角旮旯。你甚至可以把它当做一个“模型网关客户端”来用同一个项目里白天用贵的强模型干活晚上用便宜的模型做简单重构切来切去不用换工具。第二Skills 机制。这是它区别于很多 AI Agent 的核心设计。你可以把一段反复使用的提示词、一套固定的操作流程、甚至一个外部脚本封装成“技能”让 Agent 灵活调用。社区里有人做了专门做 Code Review 的 skill也有人做了自动写提交信息的 skill装上之后的效果比在聊天窗口里每次重新打字强太多了。第三能进 IDE也能不进 IDE。它既有 VSCode 插件、JetBrains IDEA 插件也有桌面版但最稳的主战场还是终端。这种“终端为主、IDE 为辅”的设计特别适合我这种习惯在终端里操作 git、跑构建、看日志的人Agent 能直接看到我命令行的上下文减少了很多来回解释的废话。2. 安装与启动从零开始跑通2.1 三种安装方式按你的环境选先说最主流的方式。opencode 的安装路径官方文档里写了三种我挨个试过给你梳理一下区别。第一种是npm 全局安装适合已经装了 Node.js 的人。命令很简单npm install -g opencode-ai注意包名是opencode-ai不是opencode因为 npm 上opencode这个名字被别人占了。装完之后终端里直接敲opencode就能启动。第二种是官方一键安装脚本适合 macOS 和 Linux 用户不需要 Node 环境也能装脚本会自己处理依赖和 PATHcurl -fsSL https://opencode.ai/install | bash第三种是桌面版 / Release 安装包。Windows 用户可以去 GitHub Releases 页面下载安装包或者直接找官网的 desktop 入口。桌面版的本质就是把终端 Agent 包了一层 GUI但对不熟悉命令行的朋友友好很多后面我会专门写。2.2 我踩过最多的坑cmdlet 识别报错Windows 上最经典的报错搜索量常年排在第一opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错不是我夸张几乎每个用 npm 安装的 Windows 用户都会遇到。原因特别简单npm 的全局安装目录没有加到系统 PATH 里。解决办法分三步走先找到 npm 全局目录npm prefix -g我机器上输出的是C:\Users\你的用户名\AppData\Roaming\npm这个目录里应该能看到opencode.cmd文件。把这个目录加到系统环境变量 PATH。Win 键搜索“编辑账户的环境变量”在“系统变量”里找到 Path新增一行C:\Users\你的用户名\AppData\Roaming\npm。打开新的终端窗口验证一下opencode --version如果加了 PATH 还是不行检查一下是不是用了公司电脑、有组策略锁住了环境变量或者干脆把 Node 卸载了重装 LTS 版本再用 nvm 管理 Node 版本避免权限问题。我个人在 Windows 上更推荐用官方安装包而不是 npm省去一堆环境变量的破事。2.3 安装完成后先别急着干活做一次体检装好之后我建议先跑两个命令opencode --version opencode --help--help输出的内容不多但主要子命令都在里面opencode直接启动交互式终端opencode run可以非交互式跑一次性任务适合脚本调用opencode auth用来登录或者管理凭证opencode agent可以创建独立会话。首次启动时opencode 会让你选择模型商和填入 API Key。这里有个细节如果你在配置文件里已经写好了 provider启动时它会自动读取不会反复问你。配置文件的路径和写法我放到下一节详细讲。3. 配置与模型接入把模型装进你的终端3.1 配置文件到底在哪怎么改opencode 的配置路径不同系统不一样macOS / Linux~/.config/opencode/opencode.jsonWindows%USERPROFILE%\.config\opencode\opencode.json我的建议是不要急着改全局配置。每个项目下可以放一个.opencode.json项目的配置优先级更高适合按仓库自定义模型和提示词。比如某个仓库要求必须用某个模型跑测试就在项目根目录写一个 .opencode.json团队其他人 clone 下来也能读到非常方便。一个最基础的配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { options: { apiKey: sk-ant-..., model: claude-sonnet-4-20250514 } }, openai: { options: { apiKey: sk-proj-..., model: gpt-4.1 } } } }如果你担心 key 泄露就不要直接把 key 写进 JSON改成引用环境变量{ provider: { openai: { options: { apiKey: {env:OPENAI_API_KEY} } } } }这样 key 只存在于 shell 的环境变量里配置文件即使提交到 git 也不怕。3.2 免费模型怎么选别被“免费”俩字带偏很多人搜“opencode 免费模型”其实是希望不花钱先体验一遍。我实测下来有两条路比较靠谱。一条是接 Ollama 跑本地模型。比如qwen2.5-coder:7b、llama3.1:8b本地推理完全免费但速度取决于你机器配置7B 模型在 16G 内存的 Mac 上还能用在 8G 的 Windows 老机器上就明显卡了。本地模型适合做代码补全、简单重构复杂的跨文件改动基本别指望。另一条是用各家云服务商的免费额度。Google Gemini 的 API 目前对个人开发者非常大方免费额度够日常玩OpenAI 新账号有时会送一些初始额度还有些模型网关平台注册即送使用金。具体到 opencode 里就是在 config.json 里配一个支援对应模型的 provider然后把 apiKey 填成你注册到的 key。这里我要泼一盆冷水“免费模型”不等于“能用得爽”。很多免费接口有每分钟请求次数限制还经常高延迟。在 opencode 里跑长任务比如让它批量修 lint 错误一小时内就能把免费额度烧光。我的建议是免费模型只用来熟悉工具和做简单任务真正常态化使用还是得准备一个付费的强模型。3.3 go 套餐与订阅模型选择我的建议热词里出现频率很高的“opencode go 订阅模型选择”我理解指的是现在市面上一些模型网关/聚合服务提供的“go 套餐”——一个账号、一个 Key然后可以在套餐范围内切换多家模型按量计费。这类服务的好处是显而易见的你不需要为 Anthropic 和 OpenAI 分别充值、分别管理 Key在 opencode 里也只需把 provider 指向网关的 OpenAI 兼容接口就行。配置大概是{ provider: { custom: { npm: ai-sdk/openai-compatible, name: go-gateway, options: { baseURL: https://api.example.com/v1, apiKey: {env:GO_API_KEY} }, models: { claude-sonnet: { name: Claude Sonnet (Gateway) }, gpt-4o: { name: GPT-4o (Gateway) } } } } }选择 go 套餐时我不只看单价还会看三件事上下文窗口是否和原版一致。有些网关会把 64k 上下文偷偷缩水成 32k长文件处理时非常容易出问题。是否有超额熔断。没有熔断的网关一旦你代码里出现死循环调用费用可能瞬间爆表。好在 opencode 自己可以限制最大请求数。模型同步是否及时。很多网关更新模型版本很慢原版都已经发布一个月了它还挂着旧版本回答质量自然差一截。至于热词里提到的“opencode go 需要配合 cc switch 等工具”这类配置切换工具主要就是帮你维护多套网关/多套 Key 的配置避免手动改 JSON 改到直接改坏。用过ccswitch 这类配置切换工具的朋友应该知道它本质上是一个集中管理配置、快速切换方案的工具。我自己的态度是如果你只用一个网关完全没必要加这一层复杂度网关一多用它确实能省心但必须注意账号与 Key 的合规性不要把多个账号的凭证混在同一台公共机器上。提示无论用哪家网关建议都在服务商后台开启“消费上限”和“单 Key 限额”这是我认为最值得养成的习惯。3.4 “this model is not available in your country” 怎么处理搜索词里有一条很典型的报错this model is not available in your country。第一次遇到的人很容易慌以为是 opencode 的问题其实这只是模型服务商侧的账号限制或区域限制。例如某些模型明确只面向特定区域开放当你的账号归属区域、IP 区域或服务商配置不符合条件时接口会直接返回这个错误。我处理这类问题的原则很简单也强烈建议你这么做先确认账号本身的区域设置是不是选错了很多平台在注册时可以选择区域但后期不允许修改。确认 API Key 对应的模型名称拼写是否正确有些报错会被网关包装成“not available”实际只是因为模型 ID 不匹配。如果确实是区域限制不要动歪脑筋去规避。正确做法是换一个对当前区域开放的模型或者改用其他提供商的同类型模型再或者在 go 套餐里找替代模型。也可以直接联系服务商客服问清楚该模型对你的账号是否开放以及是否需要单独申请权限。记住任何通过不合理方式绕过区域限制的做法既违反服务条款也可能导致账号被封。为了用一个模型冒这个风险完全不值。4. 核心玩法Skills、Memory、LSP 与自动化测试4.1 Skills 才是 opencode 的灵魂如果说 opencode 比其他终端 Agent 高出一截的地方我首推 Skills。你可以把它理解为“预置的最佳实践包”当 Agent 判断任务匹配某个 skill 的描述时就会加载这个 skill 的提示词、步骤和工具按固定流程执行而不是每次都自由发挥。比如我写了一个“前端 Bug 复现”的 skill内容大致是当用户报告前端问题时按以下流程处理 1. 先读取 package.json 确认构建工具和框架。 2. 运行 tests 或启动 dev server。 3. 使用 Playwright 打开相关页面尝试复现。 4. 输出步骤、实际表现和期望表现的对比。在 opencode 里skills 其实就是一个放在~/.config/opencode/skills或项目.opencode/skills目录下的目录里面有一个SKILL.md文件描述触发条件和行为。这种机制比较适合团队标准化A 写了 skillB 直接复用不用把经验反复口头交代。社区里现在比较火的还包括oh-my-claudecode这类配置集它本质是把 Claude Code 时代的一些技巧迁移到 opencode 上比如更细粒度的提示词模板、git 提交规范、命名建议等。我装过之后最大的感受是别全盘照搬。每个人工作流不一样逐个 skill 看一遍留几个适合的比一股脑全塞进去更有效。4.2 Memory让 Agent 记住你的项目搜索词里出现opencode memory说明很多人跟我一样遇到的核心痛点是Agent 每次会话都是“失忆”的上轮说好的架构约定下轮就忘了。opencode 的 Memory 机制可以理解成两类。第一类是项目级长期记忆。在项目根目录放一个AGENTS.md里面写清楚项目结构、常用命令、代码风格。opencode 每次启动时会自动读取这个文件相当于一睁眼就看到了“项目使用手册”。比如我有个 Java Spring 项目AGENTS.md 里写- 模块结构api / service / dao 三层。 - 新增接口必须在 controller 包下写 OpenAPI 注解。 - 数据库变更必须写 changelog 文件不允许手动改表。这样 Agent 生成的代码就不会跑偏。第二类是用户级偏好记忆。opencode 的全局配置里可以放instructions字段写你希望它始终遵守的规则比如“所有错误信息要同时给出中文和英文”或者“提交信息必须遵循 conventional commits”。这比每次对话开头都要重复一遍要求舒服太多了。我实际测试下来Memory 对“接手开发项目”这个场景帮助最大。新进入一个老项目让 opencode 先读 AGENTS.md 和 README再让它汇总 TODO、标出明显坏味道最后让它跑一遍测试。半小时的时间能顶我以前大半天熟悉代码的时间。4.3 让 Agent 真正“会读代码”LSP 接入很多人在搜索“opencode 如何使用 LSP”其实是因为发现 Agent 在理解代码符号时经常出错——变量重命名它总是漏掉引用跳转定义也会找错地方。这时候接入 Language Server ProtocolLSP就是正解。LSP 本来是编辑器用来提供智能提示的协议opencode 把 LSP 能力搬到了终端 Agent 里在修改代码前Agent 可以通过语言服务器拿到准确的符号定义、引用和诊断信息而不是靠纯文本猜。配置 LSP 并不复杂。opencode 内置了对常见语言服务器的支持比如 TypeScript 的typescript-language-server、Python 的pyright、Java 的jdtls。以 Python 项目为例你只需要保证本地装了 pyrightnpm install -g pyright然后在 opencode 的配置里启用 LSP 服务即可{ lsp: { python: { server: [pyright-langserver, --stdio], extensions: [.py] } } }启用后你在对话里让 Agent 重构某个函数它会先通过 LSP 识别该函数的所有调用点再给出改动方案准确率比我早期纯靠正则和猜测的方式高出一大截。用一句话总结LSP 是 opencode 从“会聊天的编辑器”变成“懂代码的同事”的关键一步。4.4 用 Playwright 测试前端 Bug别只会截图搜索词里有opencode playwright和opencode playwright 怎么测试前端 bug这绝对是前端开发者最感兴趣的功能。opencode 对 Playwright 的支持就是让 Agent 在对话中直接启动浏览器、访问页面、点击按钮、提交表单、截图记录。你不再需要自己手动复现 bug 路径只需要把 bug 描述清楚Agent 自己跑一遍复现流程。我踩过几次坑之后总结出几个比较高效的做法把复现步骤写进 skill。让每次 bug 排查都从固定 URL、固定账号开始避免 Agent 自己创造路径。给它明确的断言目标。比如“点击登录按钮后如果提示用户名不存在请截图如果跳转成功再执行下一步”。没有明确目标Agent 容易在页面上乱逛白白消耗 token。让它输出操作轨迹。不只看最终截图还要让它记录点击了哪个按钮、填了什么值。前端 bug 往往在某一个交互细节里操作轨迹比结论更有用。一个典型的命令是这样的使用 Playwright 打开 http://localhost:5173/login 输入邮箱 testexample.com 和密码 123456 点击登录 如果出现错误提示截图并读取提示文本如果成功跳转截图首页 最后把整个操作轨迹写进 /tmp/bug-report.mdopencode 会按步骤执行并返回每一步的结果。有了这套流程很多“在我电脑上没问题”的 bug终于可以在一个可复现的环境里暴露出来了。4.5 接手开发项目和 Maven 配置实战关于“opencode 接手开发项目”和“opencode mvn 配置”不少人单独搜过其实这俩是同一个场景——把 Agent 拉进一个老项目让它边理解边干活。以 Java Maven 项目为例我常用的配置是先确保 Agent 能用正确的方式执行 Maven 命令。首先确认本机JAVA_HOME和mvn都在 PATH 里java -version mvn -version然后我一般会先让 Agent 跑一次编译把存量错误暴露出来运行 mvn -q compile把编译错误列表汇总分类为 1. 缺少依赖 2. 语法错误 3. 类型不匹配 4. 其他这一步非常关键因为后续 Agent 改代码时如果编译错误拖着一大堆它很容易在错误的上下文里越改越乱。先把问题缩减到最小集合再逐类解决效率最高。Maven 项目还有一个常见的坑Agent 只会读 pom.xml但并不知道“哪个模块是入口”。所以我会在 AGENTS.md 里写清楚模块依赖关系和启动入口再让它干活。实战案例我上个季度接手的一个老项目600 多个 Java 文件没有文档README 是五年前的。我的操作顺序是opencode run 请扫描整个项目结构找出模块间依赖关系输出一份简短的架构说明。让 Agent 读取pom.xml标注哪些依赖已经过时、哪些版本号冲突。mvn -DskipTests package构建一次把失败信息全部抛给 Agent。逐条让它修复编译错误、单元测试失败。一个下午的时间项目基本可以跑起来了。换作以前光理清模块关系就得花一天。注意Agent 批量修改 Maven 配置时一定要让它改完就执行mvn validate检查。我曾经让 Agent 升级一个依赖版本结果版本号写错了Agent 还自信满满地说“已修复”。所以任何涉及构建配置的修改都必须跑命令验证别轻信“改完了”三个字。5. 编辑器插件与桌面版把 opencode 嵌进工作流5.1 VSCode 插件终端 Agent 和编辑器的缝合点装 opencode 的 VSCode 插件后左侧会多出一个面板可以直接在编辑器里发起对话、查看 diff、接收代码改动。底层调用的还是同一个 opencode 配置——你在配置文件里写的模型和 key在插件里完全复用不用二次配置。但这里我想重点提醒一句插件默认可能会让 Agent 直接修改你在编辑器中打开的文件。我建议在代码审查环节不要偷懒让它把所有改动都生成 diff你逐段看再决定是否接受。尤其是被 Agent “顺手改掉”的无关代码一定要在 diff 阶段拦下来。VSCode 插件适合的场景是你不想在终端和编辑器之间来回切或者你需要一边看文档一边看 diff。日常的重度操作比如批量替换、跨文件重构我依然更推荐切回终端用命令行版本——终端里 Agent 能看到更多上下文出错率反而更低。5.2 JetBrains IDEA 插件Java/Kotlin 项目的正确姿势JetBrains 家族里IDEA 插件对 Java 和 Kotlin 项目的支持会更好一些毕竟它能够借助 IDEA 的导入和索引信息对 Maven 项目、Gradle 项目的结构理解得更准。安装方式很简单Settings Plugins搜索 “opencode”安装后重启。重启完打开右侧工具窗口它会让你选择当前项目的语言模型服务——这里跟终端版一样直接复用全局配置即可。IDEA 插件里给我印象最深的是“把报错直接丢给 Agent”的路径。IDEA 的 Problems 面板会显示红波浪线点一下就复制了具体编译错误然后在 opencode 面板里自动带上文件路径和错误信息让 Agent 直接给修复方案。省了把错误复制来复制去的过程。不过说实话IDEA 插件目前的功能完整度还比不上 VSCode 插件偶尔会出现索引不同步、改动不刷新的情况。如果你的主力语言是 Java用它做辅助没问题如果你指望它在 IDEA 里完成所有复杂重构估计还得等几个版本。5.3 桌面版给不爱敲命令的人一个入口热词里还有opencode desktop和opencode桌面版。桌面版我装过一段时间它的核心就是把终端界面换成独立窗口左侧是会话列表右边是对话和工具输出视觉上更像一个聊天软件。桌面版最大的优点是降低门槛不用记命令、不用看终端配色方案下载安装包、登录、选模型就能用。适合刚接触 AI 编程工具的朋友也适合项目经理、产品经理这类要“看效果但不想碰终端”的人。但它现在还不是我的主力。原因有两点一是桌面版的日志输出不如终端版详实出问题的时候很难定位二是快捷键和脚本集成不如终端版灵活比如我要把 opencode 接进 shell 脚本做自动 commit桌面版就帮不上忙。我的建议是桌面版用来演示和入门正式干活还是用终端版 编辑器插件组合。6. 常见问题速查与避坑心得6.1 高频报错对照表我把这段时间在网上看到过的高频报错整理成了一张表都是我或者朋友实际遇到的问题你可以直接对照着排查报错现象常见原因解决思路无法将“opencode”项识别为 cmdletnpm 全局目录不在 PATH 里把npm prefix -g的目录加进系统 PATHerror: unexpected server error服务端返回异常可能是网络抖动或模型商故障看 opencode 启动日志确认是哪个 provider 报错再等一会重试this model is not available in your country账号区域 / 服务区域限制选择合规的替代模型或联系服务商确认开放范围配置文件改了没生效改错了路径项目级配置和全局配置混淆项目根目录放.opencode.json确认当前工作目录免费模型突然不可用限流或额度用完降低请求频率换备用模型或升级套餐执行 Maven/Shell 命令提示找不到命令Agent 环境变量不全在配置里显式指定 JAVA_HOME、PATH中文路径或中文内容乱码Windows 终端编码问题终端里执行chcp 65001切换到 UTF-86.2 “Unexpected server error” 到底怎么查有些报错一眼就能看出原因但unexpected server error属于最让人头大的一类因为它太笼统了。我的排查逻辑是确认 opencode 版本是不是最新的有些服务端接口更新后老版本客户端容易触发兼容性报错。执行opencode upgrade或重新安装。查看详细日志。opencode 会把日志写到~/.local/share/opencode/log或%USERPROFILE%\.local\share\opencode\log下找错误信息里有没有timeout、403、429这些关键词。如果是timeout大概率是网络到模型服务端的链路不稳或者模型商本身在过载。这种时候别反复重试先休息两分钟或者直接换一个模型。如果是429说明触发了限流。检查是不是并发请求太多把 Agent 的单次对话任务拆小一点。如果错误信息里什么有效内容都没有可以把日志尾部截下来去 GitHub Issues 搜一下相同关键字通常能找到解决方案。这种报错十有八九不是 opencode 本身的问题而是模型服务商不稳定。我的备用方案是配置里写两个 provider一个 primary 一个 fallback遇到持续性故障就切过去不耽误活儿。6.3 配置不生效、JSON 改错后的恢复有搜索词提到“opencode linux 修改 json”八成是改了配置之后发现没生效然后想找正确的修改姿势。这里有个容易被忽略的点opencode 读取配置文件是根据当前工作目录去定位的。如果你在/home/user/projectA目录下启动它优先读/home/user/projectA/.opencode.json如果项目里没有配置文件它才去找~/.config/opencode/opencode.json。很多人在根目录改了半天全局配置结果跑到项目目录下启动发现根本不读就是这个原因。JSON 配置写错了启动时会直接报 JSON 解析错误。解决办法是先在系统里安装一个 jq 工具做语法校验jq . ~/.config/opencode/opencode.json如果返回的不是 JSON 结构而是一段报错说明你的配置文件有语法问题。这时候把高手写的完整配置备份一份放到旁边改错了随时对照。我个人习惯是用 VSCode 打开配置文件配合 JSON Schema 校验可以实时提示字段错误比用记事本硬写稳得多。6.4 免费模型下线或失效时的切换思路搜索词里有“opencode hy3-free 下线了吗”说明大家都在关心手里正在用的免费模型还能撑多久。这类免费模型下线的场景我见得太多了每次都是厂商调整政策、突然移出列表用户一脸懵。应对思路只有一个不要把免费模型当成唯一依赖。我提前做了三件事另一个 provider 里常备一个本地 Ollama 模型比如qwen2.5-coder:7b。免费模型挂了至少还能靠本地模型做轻量任务。把关键的工作流写进 skill这样换模型时不用重新教 Agent“你要怎么做”它自动会按同一套流程跑。定期检查 opencode 的模型列表看看哪些新增了免费额度。很多平台对新手有“首月免费 xx 额度”这种东西错过真的很可惜。如果你发现某个模型真的下线了最急的不是抱怨而是先检查旧会话里有没有缓存下来的“模型配置片段”改几个字段就能切到替代模型其次才是去社区问替代方案。把切换成本降到最低才是长期稳定使用的王道。我自己的使用习惯是每天早上开工前先看一眼 opencode 的配置有没有报错再跑一次轻量任务“热热身”。这个习惯帮我躲过了好几次“今天模型没法用”的尴尬时刻。工具这东西省心比炫技重要稳定比花哨重要。最后再分享一个小技巧opencode 的会话里可以同时开多个任务遇到一个任务卡住别急着终止开个新会话继续干别的等它自己恢复。这个“多开”思路比反复重试效率高得多。