这几年终端 AI Agent 的迭代速度真的比很多人想象中还要夸张。我从 Claude Code 用起中途换过 Codex CLI最后长期留在 opencode 上。倒不是因为它名字好记而是它把“终端 Agent”这个概念做得足够开放不锁死某一家模型能接几乎所有主流模型又提供了 Skills、LSP、Playwright 这类真正能提升代码工作流质量的扩展点。这篇文章就把我实际折腾下来的一些经验和踩坑细节整理出来给正在考虑入坑或者已经遇到问题的朋友一个参考。1. opencode 不是一个“套壳 CLI”它是一个可以自己喂模型的终端 Agent1.1 我为什么会从 Claude Code 和 Codex 换到 opencode先说结论opencode 本质上是一个跑在终端里的开源 AI 编程代理。你把它丢进一个项目目录它自己会看项目结构、读代码、改文件、执行命令甚至能自己打开浏览器去复现前端 bug。国内社区很多人喜欢拿它和 Claude Code、Codex CLI 放一起比其实它们都是同一类东西但定位差得挺远。Claude Code 强归强问题是它和 Anthropic 的模型绑定得太死。你想在里面换 GPT、换 DeepSeek、换本地模型基本要绕很多路。Codex CLI 反过来OpenAI 生态内很顺出了 OpenAI 的服务范围也显得封闭。opencode 最打动我的地方是provider 可插拔配置文件里指定用哪家模型它就接哪家甚至连 Ollama 本地模型都能直接当后端用。对于一家同时要接不同价位居多模型的公司来说这个自由度太重要了。1.2 它真正解决的三类问题我用了几个月总结下来 opencode 主要解决三类问题多模型切换问题前端开发想用 Claude 写复杂逻辑日常小改动想用便宜模型省成本本地环境又希望数据不出内网。opencode 把这三条路都通了一份配置切换即可。终端工作流补全问题它不只给你聊天而是真的在 shell 里执行命令。装依赖、跑测试、看 git diffAgent 能自己干你在旁边看着。可扩展性问题Skills 机制、LSP 接入、Playwright 浏览器自动化这三样东西让 opencode 从一个对话助手变成一个真正有手有脚的 Agent。尤其是 LSP后面的章节我会专门讲。1.3 和 Claude Code、Codex、Pi 的横向对比这里我给一张对比表基于我当时使用时的公开版本整理。这类工具迭代非常快具体能力请以各项目 README 和 install 后的--help为准。工具是否开源模型绑定核心扩展点适合什么场景Claude Code否以 Anthropic 模型为主Skills、SubagentAnthropic 重度用户Codex CLI部分开源以 OpenAI 模型为主与 GitHub 深度联动OpenAI / GitHub 生态用户opencode是不绑定厂商Skills、LSP、Playwright、IDE 插件想自由选择模型、深度定制工作流的人Pi是不绑定厂商轻量、社区插件喜欢极简终端体验的人建议别过度迷信哪个最好用先想清楚一个问题你手里能用哪些模型接入资源以及你愿不愿意为开源项目补文档。opencode 的优势在自由度也就是模型自由 扩展自由。2. 第一次跑通 opencode安装、认证、配置文件2.1 三种安装方式以及 Windows 上最容易翻车的 PATH 坑opencode 的安装方式不算复杂主流有三种官方一键脚本curl -fsSL https://opencode.ai/install | bash通过 npm 全局安装npm i -g opencode-ai从 GitHub Releases 页面下载对应平台的二进制包解压。我刚上手的时候在 Windows 上用 PowerShell 执行完安装脚本紧接着敲opencode直接弹出来那条著名报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这不是安装失败而是安装路径没进 PATH或者当前终端会话没有刷新环境变量。常见解决路径是去确认安装目录脚本默认装在用户目录下的.opencode/bin或类似位置然后把它加进 PATH。以 Windows 为例setx PATH $env:PATH;$env:USERPROFILE\.opencode\bin然后重新开一个终端窗口再执行opencode --version验证。用 npm 装的话确认 npm 全局 bin 目录在 PATH 里即可。提示改完 PATH 之后不重开终端回去直接敲命令大概率还是老报错。这个“重开窗口”的动作很多人会漏掉先检查它。Linux / macOS 上没有 PATH 问题的同学也别急着跳过。Linux 下手动改配置的需求反而更多我放到 2.3 节讲。2.2 认证与模型凭据auth login 与直接填 key 两种姿势安装完成之后第一次运行opencode会进入配置流程其中最关键的一步是认证auth。opencode 的服务端抽象做得比较统一认证方式大概分两类交互式登录执行opencode auth login按提示选择你的模型服务商然后走 OAuth 或粘贴 API Key。它会帮你把凭据写到本机配置目录session 复用时自动加载。手写凭据直接编辑配置文件把OPENAI_API_KEY、ANTHROPIC_API_KEY这类环境变量或者 provider 配置写进去。适合服务器、CI 环境这种没法交互登录的场景。我的建议是初次使用先用auth login跑通成功之后再去看它写出来的配置内容顺便理解它到底把 key 存在哪。这比一上来就手改 JSON 省很多事。2.3 Linux 下手动改 JSON 配置文件路径与关键字段搜索热词里有一条 opencode linux修改json说明不少人在 Linux 上折腾过配置文件。Linux / macOS 下 opencode 的全局配置默认在~/.config/opencode/opencode.json项目级配置可以放在项目目录下的.opencode文件夹里实现“不同项目不同模型”的效果。默认会对齐全局配置项目级配置会覆盖全局配置的同名字段这个优先级逻辑对团队协作非常有用。配置的大致结构类似这样{ provider: { openai: { models: { gpt-4o: { name: gpt-4o } } } }, model: gpt-4o, theme: opencode }真实版本里字段会比这段更丰富具体 schema 以opencode config --help和你本地安装版本为准。关键是理解一点JSON 配置不能写注释不能有尾逗号。我见过很多次用户改完配置直接报解析错误一查都是逗号问题。改完可以用jq . opencode.json验证一下再启动程序。注意这属于 JSON 标准对严格性的要求与 opencode 无关。所有面向 JSON 的静态配置都有这个惯例。3. 模型选择、GO 订阅和“你所在国家不提供此模型”的处理思路3.1 opencode GO 是什么套餐怎么选搜索热词里频繁出现的 opencode go指的是 opencode 官方提供的一个统一订阅服务。你可以把它理解成一个模型访问的统一入口用一个 GO 的 Key就能在 opencode 里切换到多款主流模型不需要分别去各家平台开账号、充额度。选择 GO 套餐时我建议按三个维度来评估模型覆盖你先看套餐里是否包含自己日常依赖的顶配模型以及是否有便宜的轻量模型可以跑批量任务。用量计费方式有的套餐偏向包月无限有的按 token 计量。团队协作场景优先选能开多个 Seat 的避免几个人挤一个账号。与现有工具链的兼容性如果你已经在用 CC Switch 这类切换工具可以看 GO 是否支持把 Key 同时配进去让 Claude Code 也能共用同一份额度。社区里有人这么玩具体支持程度以官方文档和 CC Switch 配置页面为准。我的建议是个人尝鲜先按月订别一次性买年付。因为 Agent 类工具的模型选择策略变化很快今天觉得划算的套餐下个月可能因为模型价格调整又不划算了。3.2 免费模型加本地模型低成本跑通日常任务如果你预算有限opencode 也给了两条很实用的路免费额度模型比如部分厂商提供的限时免费层或者社区常见的 DeepSeek、Gemini Flash 等低价高性价比模型写进 provider 配置就能用。适合做代码补全、简单重构、解释代码这类任务。本地模型通过 Ollama 跑 qwen2.5-coder 这类开源模型。先把模型拉下来ollama pull qwen2.5-coder:14b然后在 opencode 配置里把 provider 指向 Ollama 的本地地址就能让 Agent 在完全离线的情况下读代码、写代码。数据不出本机对隐私敏感的项目是真香。不过要说实话本地模型日常写业务代码够用但做跨文件的大范围重构、接住复杂上下文的时候能力上限和云端顶配模型还是有差距。我的做法是本地模型负责简单任务复杂任务切回云端模型这就是 opencode 多 provider 的好处。3.3 “this model is not available in your country” 的正规处理方式很多人在 opencode 里遇到this model is not available in your country.这条报错。先说明一点这个报错来自上游模型提供方不是 opencode 本身的错误。它通常意味着该模型在你当前所在地区没有被官方开放或者提供方法针对该地区做了限制。正确的处理方式是回到“合法可用”的范围内查看你使用的模型提供方在其官方渠道确认该模型支持的地区列表直接切换到支持你所在地区的模型。换一家你能够正常使用其服务的模型提供方配置进 opencode。对隐私或合规要求高的场景使用本地模型绕开外部接口的区域问题。检查你自己的账号设置包括账户地区、计费地址等信息是否与当前所处地区一致避免误判。千万不要去试那些打擦边球的手段一是违反服务条款二是不稳定。与其想方设法访问一个不开放的模型不如换一个同等能力的替代模型。opencode 的多 provider 设计本来就是为了避免这种单一依赖。4. VS Code 与 JetBrains 插件IDE 里用 opencode 的正确打开方式4.1 VS Code 插件把终端窗口搬进编辑器如果你和我一样主力是 VS Code直接在扩展市场搜 opencode 就能找到官方插件。装完之后编辑器和 CLI 是同一套认证体系你在终端里配置好的 provider、key、模型都会在插件里生效。插件提供的核心能力是让 Agent 直接在编辑器里配合你操作你可以给它圈定一段代码让它做解释或重构它给出的 diff 会直接以可预览的形式出现在编辑器里你觉得没问题再接受。这个体验和纯终端相比省掉了“复制代码进终端再粘回来”的中间步骤。这里有一个小细节容易忽略装完插件之后如果终端里已经跑着 opencode 的会话插件大概率会尝试连接本机正在运行的服务。如果你开了多个终端窗口注意关掉不必要的会话避免多个会话同时占用同一个配置目录导致互相干扰。4.2 JetBrains 插件右键发送选中代码JetBrains 全家桶用户IDEA、PyCharm、GoLand在插件市场同样能找到 opencode 插件。插件安装后最实用的交互入口是编辑器右键菜单选中一段代码右键发送给 opencodeAgent 会结合上下文给建议。这个“右键发送选中代码”的设计本质上是在解决一个问题Agent 拿到的上下文质量。你不给它选中区域它只能按自己的策略去猜你要改哪段给了之后它的回答案中率明显高很多。我用 IDEA 插件处理 Java 项目时的体感尤其明显因为 Java 这种强类型语言的改动经常涉及大量跨类引用选中入口方法的代码片段再问比整库扫一遍靠谱得多。JetBrains 上还有一个方便之处是可以在插件面板里直接看到 Agent 的命令执行日志。它跑了什么命令、改了哪些文件、执行结果如何都能按时间顺序回顾排查问题的时候很有用。4.3 我日常的“终端 IDE”双会话工作流很多人问我有了 IDE 插件是不是终端里的 opencode 就可以不学了我的答案是两个都要用但分工不同。我把它们拆成两条线终端 opencode负责整库级任务。比如接一个新需求需要跨目录分析哪里改、哪里加Agent 自己逛代码、自己跑测试我在旁边观察就行。IDE 插件负责文件级、选区级任务。改某个方法、修某个报错、生成某个类的样板代码直接在编辑器里完成既能看到代码高亮也能随时看 diff。两个入口共用的是同一份认证、同一套配置所以我不会在两边重复维护配置。把 IDE 插件当作终端 Agent 的“编辑器前端”这个心智模型一旦建立日常使用就很顺畅了。如果你不喜欢开两个界面opencode 也有桌面端形态可以参考本质都是同一个 Agent 内核的不同外壳。5. Skills、LSP、Playwright三个扩展点把 Agent 变成“会写会查会测”的全能选手5.1 Skills给 Agent 装“操作手册”Skills 是 opencode 非常值得投入时间去理解的功能。你可以把它理解为给 Agent 预先写好的“操作手册”。当你告诉它“按团队规范做 code review”或者“帮我写符合常规格式的 commit message”时它会去加载对应的 Skill 文件按照里面的规则和步骤执行。Skill 就是带特定格式的 Markdown 文件放在约定的目录下。社区里常见的目录规则是全局的~/.config/opencode/skills以及项目里的.opencode/skills。每个 Skill 文件夹里放一个SKILL.md开头写清楚这个 Skill 的用途、适用场景后面是具体指令和示例。现在搜索热词里有 opencode oh-my-claudecode这指的是把社区里为 Claude Code 开发的那套 skills 包迁移给 opencode 用。实操上不建议直接搬因为两家对 Skill 元信息的解析字段不完全一样。正确做法是把.md里的指令正文拿过来按 opencode 的格式重写一遍文件头。我自己迁移过几个常用的 code review skill过程十分钟以内收益却很直接Agent 的产出风格会立刻规矩很多。5.2 LSP让 Agent 不再靠猜而是真正看懂代码LSP 全称是 Language Server Protocol语言服务器协议。它本来是编辑器用来做语法提示、跳转定义、查找引用的底层技术opencode 把它接进了 Agent 的上下文让 Agent 在分析代码时不靠纯文本匹配而是靠语言服务器提供的语义信息。接上 LSP 之后Agent 能做的事情会有一个质的提升。比如准确找到某个符号的定义位置而不是用字符串搜索碰运气。拿到引用某个函数的所有地方从而评估一次改动的影响面。读取诊断信息直接知道哪一行有类型错误。常见语言服务器的接入方式是在配置里指定命令和文件后缀。以 TypeScript 为例{ lsp: { typescript: { command: [typescript-language-server, --stdio], extensions: [.ts, .tsx] } } }前提是这些语言服务器本身已经装好并且在 PATH 里。执行opencode --help或查看文档通常能找到列出当前 LSP 状态的调试命令用来确认到底有没有接上。我的实战体会是LSP 是否生效直接决定了 Agent 做大型重构时的靠谱程度。没接 LSP 时它改一个接口名经常留下几处旧引用没改接上之后它会主动发现所有引用点逐个处理。这个差异在 TypeScript、Go、Java 这类强类型项目里特别明显。如果你只在 JavaScript 小项目里用 opencode没有 LSP 也能跑但一旦项目变大建议优先补上 LSP 配置。5.3 Playwright让它自己开浏览器复现并定位前端 bugopencode 对 Playwright 的集成是它区别于很多终端 Agent 的一大亮点。说白了你可以在对话里要求 Agent “在浏览器里把这个问题复现出来”它会启动一个真实浏览器打开你的页面模拟点击、输入然后通过控制台日志、网络请求和截图来分析问题。要启用这个能力前提是项目里先把 Playwright 装好npm i -D playwright npx playwright install chromium然后启动你的前端项目告诉 opencode“访问 http://localhost:5173 点击登录按钮把控制台报错和页面截图拿给我分析一下为什么登录失败。”这里我分享一个真实场景。有一次我接了个工单问题描述是“列表页筛选后表格是空的控制台有报错”但是手动复现了半天没头绪。我直接让 opencode 用 Playwright 打开页面、按工单步骤操作它很快就把报错定位到了接口返回的字段名不匹配甚至自己提出可以用临时脚本打印一下接口响应结构。最后我把修复推到分支上它再跑一遍 Playwright 确认问题消失。整个流程从复现到验证省掉了我大量手工操作。提示让 Agent 跑浏览器测试时最好让它在临时目录或者 dev 环境里跑别直接对着生产环境做写操作。Agent 再聪明也顶不住它以为自己在测试环境但脚本里写的是生产地址。6. 高频报错实录从命令行不识别到接口报错的完整排查链路6.1 “无法将 opencode 项识别为 cmdlet”PATH 问题的三步定位这条报错在 Windows 上最为常见报错原文是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确保路径正确然后再试一次。排查链路我总结成三步确认二进制是否真的装上。在终端执行Get-Command opencode如果返回空再回到安装目录找找可执行文件是否存在。找不到就说明安装没成功重装一遍。确认 PATH 是否包含安装目录。执行echo $env:PATH看里面有没有 opencode 的安装路径。没有就加加完之后重开终端。确认是不是当前会话没刷新。改完 PATH 后必须重开终端窗口不能指望当前会话自动加载。如果以上都查完还是不行就用where.exe opencode看看系统到底找到了哪个路径。有可能你机器上装了多个版本命令被别的位置的同名文件抢先了。这类问题耐心顺着路径查基本十分钟之内能解决。6.2 “unexpected server error. Check server logs”逐层往下查有搜索热词提到opencode error: unexpected server error. check server lo这是典型的通用服务端报错。它背后的原因可能很多但排查顺序应该从外到内先分清楚是哪一层报错是连接模型 API 时报的还是 opencode 自己的本地服务崩了最简单的方法是临时切换到另一个已经验证可用的模型看还会不会报。如果换了模型就好了问题出在原来的模型端点。看日志opencode 通常会在本地用户目录下写日志文件具体路径以opencode --help给出的信息为准。把日志里的关键错误信息搜一下能定位到是认证失败、超时还是返回格式异常。直接用 curl 测上游接口如果你用的是某个 API 提供方可以用你配好的 key 直接调一次上游 API看返回是不是正常。这个步骤能帮你区分是“opencode 的 bug”还是“上游服务问题”。这个报错最怕的就是不死心重试。很多情况下上游模型服务在高峰期会有毛刺隔几分钟再试就好了但如果连续多次报错就要认真查 key、查额度、查模型名是否写错。6.3 配置不生效与 model 列表不对JSON 和缓存的两个常见原因还有两类很常见的“软故障”不报错但行为不对一类是配置不生效。你改了模型或改了 provider但 opencode 好像还是用旧配置。这种情况多半是配置读取时机的问题很多配置只在启动会话时加载一次改完配置之后要把当前会话退出重进而不是在对话里继续发消息。另外项目级配置优先级高于全局配置如果你在项目里建过.opencode配置它可能覆盖了全局配置导致你以为 “我明明改了全局配置怎么没生效”。另一类是 model 列表不对。你看到可选的模型列表和预期的不一样通常是当前 provider 的模型列表没有同步或者在配置里写的模型名跟 API 提供方实际支持的名称对不上。解决方案是先去官方文档确认准确的模型 ID再更新配置。模型名这东西一点都不能差差一个横杠、一个点都会报错。7. 最后分享一个我在团队里落地 opencode 的实际经验我们团队把 opencode 推广开之后最实际的收益不是“改代码速度快了多少”而是新同学接手项目时Agent 作为“驻场老员工”一直在旁边待命。新需求来了让 opencode 先梳理相关代码路径、列改动方案新人再做 review 和实现上手的门槛明显降低。如果你准备在一个团队里推 opencode我建议先立三条规矩统一模型配置项目级配置里固定默认模型避免每个人用不同模型导致产出风格差异过大。统一 Skills 目录把团队约定、编码规范做成 Skill 文件放进项目仓库谁来用都是同一套“操作手册”。统一审阅流程Agent 的改动一律走 MR review不允许直接推到主干。说到底opencode 是个工具工具的边界由使用它的人决定。多花一点时间把配置、Skills、LSP 这些基础工作做扎实后面省下来的时间远超前期投入。如果你刚入门建议就从“装好它在真实项目里跑一轮小改动”开始遇到问题再回来翻上面这些排查链路。