第一次运行 opencode 的时候我的反应是又一个终端 AI 编码助手那时候我的终端里已经躺着 Claude Code 和 OpenAI Codex平时基本是哪个顺手用哪个突然多一个opencode第一感觉是没必要。后来强迫自己用了一个月opencode 反而成了我打开项目后的默认工具。原因很简单它的配置足够透明模型路由足够灵活skills 机制比我想象的成熟而且对用 Agent 写代码这件事的处理方式更贴近真实开发流程。这篇文章不打算写成官方文档的搬运而是把我从安装、配置模型、接 skills、用 Playwright 做前端验证这一路踩过的坑和验证过的方法完整过一遍。无论你是刚听说 opencode 的新手还是已经在 Claude Code 里折腾很久的老手应该都能找到点有用的东西。1. 先把 opencode 放进终端安装方式与常见的启动失败原因1.1 安装前先搞清一件事你装的是哪个包opencode 这个项目的包名和命令名不一样命令是opencode但 npm 包名是opencode-ai。这点初次接触的人特别容易搞混因为 npm 上确实存在一个叫opencode的旧包直接执行npm install -g opencode装出来的东西跟官方项目根本不搭边运行起来大概率是你认知之外的某个工具甚至可能直接报错。正确的安装方式很简单npm install -g opencode-ai opencode --version执行完opencode --version能输出版本号说明安装成功。opencode 是 SST 团队维护的开源项目这一点在 GitHub 仓库里能看到底子是 TypeScript 写的运行时依赖 Node.js 18 以上版本。如果你本机 Node 版本偏老装完启动会直接报语法错误尤其是 Windows 上常见。我自己的习惯是用 npm 全局安装因为后续升级直接npm update -g opencode-ai一行命令搞定日常使用频率高的话很省事。如果你是用 Homebrew 的用户也可以试试brew install opencode实测效果一样两条路走一条就行。1.2 Windows 上最典型报错无法将 opencode 项识别为 cmdlet这个报错在Windows 上出现频率极高搜索热词里也单独占了条。第一次遇到的时候说实话有点懵明明 npm 装的时候没有任何报错怎么一执行就说不认识这个命令原因并不复杂npm 全局安装的可执行文件放在 npm 的全局 bin 目录下而 Windows 的 PowerShell 和 CMD 并不会自动把这个目录加进PATH环境变量。换句话说opencode 装好了但你当前 shell 不知道它在哪里。排查和解决分三步走# 第一步查看 npm 全局 bin 目录的真实路径 npm config get prefix假设输出是C:\Users\你的用户名\AppData\Roaming\npm那opencode.exe应该就在这个目录下。# 第二步把该目录加入 PATH按Win S搜索环境变量编辑用户变量里的Path新增上面那个路径重启 PowerShell。# 第三步验证 opencode --version这条报错想排查其实很机械但真到了终端面前很多人会慌因为错误提示里带着 cmdlet、函数、脚本文件或可运行程序 一长串看着像是什么严重故障。实际上就是 PATH 没配好跟 opencode 本身没有任何关系。1.3 首次启动TUI 界面与配置文件骨架安装验证没问题后在一个项目目录里直接执行opencode会进入一个 TUI终端用户界面。左手边是会话历史中间是对话区底部是输入框。这个布局在终端 AI 工具里算比较干净的了没有太多花里胡哨的东西。首次启动会在你的用户目录下生成配置文件。Linux 和 macOS 路径是~/.config/opencode/Windows 是%USERPROFILE%\.config\opencode\。目录下常见的文件包括opencode.json主配置模型、provider、权限全在这里、mcp.jsonMCP 服务器配置、skills/技能目录、memory/记忆目录。有一点需要强调opencode 默认用的模型是 Anthropic 的 Claude 系列。你没有配置任何东西的情况下直接运行它会尝试用环境变量里的ANTHROPIC_API_KEY或者OPENAI_API_KEY去连模型如果没有这些变量就会在界面上提示需要设置 API Key。所以第一次启动看到需要配置模型不要慌这不是 bug是它等你把模型通道配好。2. 读懂 opencode.json模型、网关与多配置切换2.1 一个最小可用的配置长什么样opencode 的配置核心是opencode.json这个文件直接决定了 opencode 连哪家模型、用哪个型号、走什么接口。初次接触的人最容易犯的错是去网上抄一堆复杂配置结果格式化错误或者字段名不对启动直接挂掉。其实最小配置只需要几行{ $schema: https://opencode.ai/config.json, provider: { my-gateway: { npm: ai-sdk/openai-compatible, name: My Gateway, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_GATEWAY_KEY} }, models: { my-model: { name: My Model } } } }, model: my-gateway/my-model }这里面有一点很关键npm: ai-sdk/openai-compatible表示这是一个 OpenAI 兼容接口的 provider。现在绝大多数第三方模型服务都提供 OpenAI 兼容的/v1/chat/completions接口所以这个配置适配度最高。如果你用的是 Anthropic 官方接口npm 字段应该改成ai-sdk/anthropic如果走 OpenAI 官方就是ai-sdk/openai。我当时从官方模型迁移到网关的时候最大的感触是 opencode 的 provider 抽象做得比较干净。它不像很多工具只支持 OpenAI 格式而是通过ai-sdk/*这一系列包来适配不同协议换模型基本就是改配置不用改工具自身。2.2 免费模型与第三方网关一份订阅钱访问多种模型热词里出现的opencode go、go订阅模型选择、go套餐、hy3-free我猜大部分人和我一样第一次看到是懵的。说下我的理解opencode go 这类名字本质上是社区流行的模型网关/订阅服务核心价值是你通过一份订阅费用在 opencode 里访问多家模型。配置上它们大多统一走 OpenAI 兼容协议也就是上面那个ai-sdk/openai-compatible的接入方式。我在折腾opencode 接入 superpower和opencode go的过程中摸索出的配置套路很简单在网关控制台拿到 baseURL 和 apiKey。在opencode.json里新增一个 providerbaseURL 指过去。把网关支持的模型名逐个填进 models 字段。全局 model 字段指定默认模型。比如某个网关同时提供 Claude 和几个开源模型你可以在 models 里列出多个然后在会话中用命令切换不用每次改配置文件。部分网关还支持set model这种运行时切换实际用起来很顺手。关于免费模型热词里有个hy3-free 下线了吗。我个人的观点是免费模型服务天然不稳定下线是很正常的生命周期现象。你想在 opencode 里接免费模型当然可以但要有心理预期不要在生产环境或者重要任务上依赖免费通道。免费模型适合拿来跑通流程、验证配置是否正确真正干活还是得靠付费模型或者稳定网关。还有一个高频报错也跟模型有关this model is not available in your country.这个问题通常发生在直接调用某些区域限制模型的时候。解决思路不是去绕什么限制而是走你所用网关提供的可用区域模型或者干脆换同系列的替代模型。注意opencode 本身不管这个它只是把请求发给模型服务能不能用取决于模型服务商对区域的开放策略。2.3 用 ccswitch 管理多套配置热词里出现opencode go 需要配合 cc switch 等工具这也是我实际用下来觉得很有价值的一个点。ccswitch 原本是给 Claude Code 等工具做配置切换的但 opencode 的配置文件也是标准 JSON所以完全可以纳入 ccswitch 管理。使用步骤大致如下安装 ccswitch。添加一个opencode类型配置组。把不同的 provider 配置官方、网关A、网关B分别存成一套快照。需要切换时在 ccswitch 里点一下它会自动把对应配置写入opencode.json。有了 ccswitch我就不用手动改 JSON 了尤其是同时维护多个项目、每个项目用不同模型的时候这个切换成本省得特别明显。不过要注意一点切换配置本身不影响当前已经打开的会话改完记得重启 opencode 会话再加载。3. 从编辑器到桌面VSCode、IDEA 插件和桌面版的真实体验3.1 VSCode 插件够用但别当主力opencode 在 VSCode 里的插件体验一句话概括适合看代码不适合长时间写代码。安装之后左侧会多出一个面板能直接查看当前项目的会话历史、当前模型、还能在编辑区里用快捷键唤起行内补全。它最大的价值在于选中一段代码右键发送给 opencode它能把上下文带过去不用像 TUI 里那样手动复制粘贴。实际用下来我的感受是 VSCode 插件适合在人机结对模式下用你想让 AI 改一个小函数直接选中、唤起、让它出 diff满意就采纳。但如果要做大规模重构我反而建议切回终端 TUI因为终端里的上下文感知更专注不容易被编辑器里的其他干扰带偏。热词里提到的vscode opencode插件安装方式很简单直接在扩展市场搜 opencode装完后让它指向你本机正在运行的 opencode 即可。它不需要单独的 API Key因为复用的是 opencode 本地的配置和会话这点做得比较聪明。3.2 IDEA 插件与 Java 项目的 mvn 配置JetBrains 用户也不用眼红IDEA 里同样有 opencode 插件。安装后建议配合mvn 配置一起用这个对我来说是刚需因为不少 Java 项目依赖关系复杂Agent 经常搞不清项目里到底引了哪些包、哪个模块是入口。通过在 opencode 里配置一个 maven MCP 服务它就能读取pom.xml和构建信息回答这个项目依赖什么版本这个模块怎么构建这类问题时会靠谱得多。IDEA 插件的界面比 VSCode 版稍显粗糙但核心能力都在。对于 Maven 项目我一般先在mcp.json里配好构建查询服务再让 opencode 接手实测在改动依赖版本、排查模块编译错误的时候能省不少事。要注意的是IDEA 插件调用 opencode 时最好保证本机已经提前启动过 opencode 并且配置正确否则插件里看到的会一直是连接失败。3.3 桌面版 vs CLI什么时候用哪个opencode 桌面版是后来才出的热词里也有不少人搜。我的判断是桌面版更适合把 AI 助手当作独立应用的人它把 TUI 界面搬到了图形窗口里能同时开多个项目视觉上更友好。但它本质上还是套了一个壳底层的配置、模型、skills 机制跟 CLI 完全一样。如果你习惯终端工作流CLI 完全够用而且更快。如果你希望把 AI 会话窗口独立出来方便边写代码边看那桌面版会更合适。我自己是双持状态日常终端为主需要同时盯多个项目会话时用桌面版。两者共享同一套~/.config/opencode配置所以没有任何切换成本。4. Skills 机制与 superpowers别把 opencode 当成普通聊天窗口4.1 Skills 是什么如果你用过 Claude Code应该对 Agent Skills 有点印象。opencode 的 skills 机制思路类似你可以给 AI 预定义一组可复用的行为包每个 skill 包含一段系统提示词、一些示例、可选的脚本文件。当对话中涉及到某个领域时AI 会调用对应 skill按里面定义的流程去思考和行动。为什么要搞这么一层因为裸的模型对话虽然能写代码但缺少方法论。比如你让它修 bug它可能直接给个补丁但不会先去问你复现步骤、也不会帮你梳理根因。而一个设计良好的 debug skill 会强迫它先描述问题、再提假设、再验证最后才动手改。这些流程感对真实工程落地非常重要。4.2 安装 superpowers 技能包热词里的opencode 安装 superpowersopencode 接入 superpower指的是社区非常流行的superpowers技能集合。它里面包含了几十个 skill覆盖头脑风暴、任务规划、代码审查、调试等场景。安装方式很直接git clone https://github.com/obra/superpowers ~/.config/opencode/skills/superpowers克隆完成后重启 opencode在会话里当你描述一个任务时它会自动匹配对应的 skill。以我实际体验来说superpowers 里最有价值的是 planning写代码之前先给计划和 debugging按照系统化流程排查问题这两个 skill它们明显提升了 AI 输出的稳定性——不会一上来就甩代码而是有步骤地推进。另外热词里的oh-my-claudecode其实是在 Claude Code 生态里比较流行的配置增强方案社区现在也有人尝试把它里面对 skills 的定义迁移到 opencode 上来。这类跨工具迁移能走通全靠 opencode 的 skill 格式跟 Claude Code 兼容性做得不错。4.3 手写一个 skill比想象中简单如果你不想直接用现成的技能包自己写一个 skill 也非常简单。目录结构是这样的~/.config/opencode/skills/ └── my-skill/ ├── SKILL.md └── scripts/ └── run.shSKILL.md是核心文件开头用 frontmatter 写元信息正文写触发条件和行为说明--- name: my-skill description: 这个技能会在用户要求 ... 时被调用 --- # My Skill 1. 先做 A确认结果后再做 B 2. 如果遇到 C 情况改用 D 方案 3. 最后输出一份简明摘要我自己写过一个API 客户端代码生成技能每次需要根据 OpenAPI 文档生成客户端时它会自动检查项目里已有代码风格、生成对应语言代码、再补充单测。写完之后最大的体会是skills 把可复制的工程流程固化下来了下次遇到同类型任务AI 的表现会稳定很多不会每次重新发挥。5. 真实任务实战旧项目接手、Playwright 抓前端 bug、LSP 的隐形作用5.1 接手旧开发项目的正确打开姿势热词里opencode 接手开发项目戳中了不少人的痛点。拿到一个陌生项目时最怕的不是代码复杂而是 AI 在没有上下文的情况下瞎改。我的做法是让 opencode 先做代码侦探而不是直接提需求opencode进入 TUI 后输入提示词让 AI 先读项目结构请先浏览整个项目告诉我这个项目是做什么的技术栈是什么入口文件在哪里启动方式是什么核心模块和依赖关系有哪些有没有 README 或文档可以参考opencode 会通过内置工具读取目录结构、package.json、README 等文件很快给出项目概况。接下来再让它给出如何安全地新增一个功能的规划它会基于已读取的代码风格提出建议。这一步做完再正式开始改代码出错率会明显降低。如果你希望长期记忆项目特点可以用 memory 机制。opencode 会把一些关键约定比如本项目使用 pnpm代码风格是 2 空格缩进写入memory/目录下的文件后续会话自动加载。这个功能对持续维护一个项目的人来说价值不亚于 skills。5.2 用 Playwright 驱动浏览器测前端 bug前端 bug 是 Agent 最难搞的一类任务因为纯看代码很难复现问题。opencode 内置了 Playwright 相关的 MCP 工具可以让 AI 真正打开浏览器、点击页面、观察渲染结果和控制台报错。我在一次排查登录按钮点击无反应的问题时直接在会话里问使用 Playwright 打开 http://localhost:5173 点击页面上登录按钮观察控制台有没有报错。opencode 会启动无头浏览器执行点击操作把控制台报错抓回来。第一次看到它在终端里模拟浏览器操作的时候我确实被震撼到了——这已经不是读代码猜 bug了而是真的在跑前端。后续我还让它做过表单校验测试、页面跳转路径检查基本上能覆盖日常前端 bug 排查的 80% 场景。想启用这个能力需要确保本机有 Chrome 或 Chromiumopencode 会调用 Playwright 驱动它们。如果你的项目在代码里放了一些调试开关建议在跑 Playwright 之前告诉 AI 先阅读一下项目启动命令避免它用错误的端口启动。这个细节我在前几次使用时踩过后来习惯了先给 AI 一条npm run dev -- --port 5173这样的明确命令成功率就高多了。5.3 LSP让 AI 知道你代码里的引用去了哪里热词里有opencode 如何使用 lsp这其实是被很多人忽略的隐形能力。opencode 内置了 LSPLanguage Server Protocol支持它可以让 AI 拿到 IDE 级别的代码信息包括这个函数在哪定义这个变量在哪里被引用当前文件有没有编译错误。实际使用中我让 opencode 重构一个函数时它不只是靠阅读上下文猜引用关系而是通过 LSP 拿到准确的引用列表改动时能一并更新所有调用点。在 TypeScript 项目和 Java 项目里这个能力特别管用。配置 LSP 时你需要在opencode.json的 languages 字段里指定对应语言的 LSP 命令例如 TypeScript 用typescript-language-serverJava 用jdtls。配好后AI 的分析结果明显更懂代码。这里要说句公道话LSP 的配置对新手来说有一点门槛因为需要装额外的 language server 并在配置文件里声明。但这是值得投入的一旦配好opencode 对代码的理解能力会上一个台阶尤其在大型代码库里的表现会远超纯文本阅读的模式。5.4 让记忆发挥作用长期项目维护的秘密最后说下 memory 的实际用法。在~/.config/opencode/memory/目录下可以直接存放.md文件内容就是你想让 AI 长期记住的约定。比如你在一家对公司项目有严格代码规范的团队可以把规范写成一个 markdownAI 每次开新会话都会读它。我自己的一个习惯是每季度更新一次 memory 文件把当前项目的主要架构决策、第三方依赖、部署流程写进去。几个月后再打开项目AI 仍然能准确说出这个服务用什么端口这个模块为什么这样设计大大减少了重新解释的成本。6. Agent 之间没有绝对的胜负opencode、Codex、Claude Code、pi 的取舍6.1 四款终端 Agent 的对比热词里opencode codex claude code pi 哪个 agent 好用这种问题很常见但我的回答始终是没有最好的 agent只有最适合你工作方式的 agent。下面这张表是我用了一个月之后的真实感受工具上手成本模型灵活性Skills 能力前端测试能力适合人群opencode中高多 provider 任意接强原生支持强内置 Playwright喜欢自己掌控模型路由和流程的人Claude Code低低主要是 Anthropic 系强Agent Skills中深度使用 Claude 模型的用户Codex低中弱中偏向简单快速完成任务的人pi中中弱中追求极简终端体验的用户从表格能看出来opencode 最大的差异化优势是模型灵活性和 Skills 机制。它不像 Claude Code 那样绑定型号而是让你自由选择任何 OpenAI 兼容的模型。这意味着你可以把同一个工作流在便宜模型 贵模型之间来回切换成本控制灵活得多。6.2 我的主观选择与真实理由我个人现在的主力是 opencode核心原因是它把选择权还给了用户。我想给它接一个便宜的日常模型做通用对话再切到 Claude 做深度重构这些通过 provider 配置就行。而 Claude Code 虽然开箱即用但我在里面想换非 Anthropic 模型明显感觉是被强按在椅子上。pi 我也长期试过它很轻但生态远不如 opencode。热词里有人拿 pi 跟 opencode 比我只能说两者不在一个量级——如果你需要 skills、MCP、Playwright 这些能力直接 opencode 就完了如果你只需要一个终端聊天机器人那 pi 也确实够用。至于 Codex它的优势是简单直接适合不太想折腾配置的人但如果你的需求开始变复杂它的天花板很低扩展性明显赶不上 opencode。7. 高频报错不是玄学排查手册与一次完整追查过程7.1 报错速查表我把自己在 opencode 使用中遇到的高频问题整理成了一张表方便你遇到同类问题直接对号入座报错 / 现象常见原因处理办法无法将 opencode 识别为 cmdletnpm 全局目录不在 PATH把 npm prefix 目录加进 PATHThis model is not available in your country模型服务对当前地区不开放换网关可用模型或换同系列模型Unexpected server error. Check server logs模型网关 5xx / 请求超时检查网关状态切换模型节点看日志opencode 启动后没有响应Node 版本过老 / 配置 JSON 格式错误升级 Node校验 JSON 格式插件面板连接失败本机 opencode 未启动先在终端跑opencode再重试插件模型切换不生效配置缓存 / 未重启会话保存配置后重启 opencode 会话免费模型突然不可用服务方下线或限流增加备用 provider不依赖免费通道这张表里的每一条都是我实际遇到过或者陪朋友排查过的不是从文档里抄的。大多数问题归根结底就三类路径问题、配置问题、模型服务问题。先把这三类分开排查起来思路就清晰很多。7.2 一次 unexpected server error 的完整定位过程热词里出现error: unexpected server error. check server logs我也被这个报错折磨过一段时间。那是某天我切换到一个网关模型opencode 一发起请求就报这个错完全没有更多提示。我当时的排查链路是这样的先确认是只有这个模型报错还是所有模型都报错。我用另一个 provider 里的模型发同样请求结果正常说明问题不在 opencode 本身而在那个网关。直接在终端里手动 curl 一下网关的/v1/chat/completions用同样参数发送请求结果返回了 502。得出结论是网关侧出了问题不是 opencode 的问题。去网关控制台看节点状态发现是某个上游节点过载。切换到另一个节点后opencode 恢复正常。这个案例想说明的是很多报错表面上出现在 opencode 里实际上根因在模型服务方。遇到异常报错第一步应该是绕过 opencode 直接测试 API这一步能把排查范围缩小一大半。不要一开始就怀疑 opencode 本身它在多数情况下只是忠实地把错误转述给你。7.3 让排查更省力的小习惯最后分享几个我自己养成的维护习惯不一定都写在官方文档里善用日志opencode 的日志目录里能看到详细的请求和响应记录报错时去翻一下尾部比在终端里看那两行提示信息有效得多。配置文件备份调整opencode.json之前先复制一份改坏了能秒回滚。我见过太多人改配置改到起不来最后只能删掉重置。模型命名规范在 provider 里给模型起有一定辨识度的名字别用model1、model2这种。会话里切换模型时一目了然不会切错了还不知道。新技能小范围试用加载一个新的 skills 包后先在一个小项目里跑两天不要在核心生产项目上直接上。skills 的提示词可能和你预期不符先观察再放开。这些习惯帮我省掉了非常多重复的坑。说实话opencode 这类工具本身学习成本并不高真正耗时的是你被各种环境问题、服务问题、配置问题反复消耗的时间。把上面的排查思路和预防习惯刻进肌肉记忆之后我用 opencode 干活效率确实提升了一大截。如果你目前还在观望它和 Claude Code、Codex 之间的选择我的建议是别急着卸载哪个装一个 opencode把你手头一个不重要的项目交给他跑一遍感受一下它调动模型、使用 skills、操控 Playwright 整个过程再决定要不要让它成为你的主力工具。反正配置文件就在用户目录下折腾坏了删掉重来成本几乎为零。 opencode实战：从安装配置到模型路由与Skills机制的终端AI编码助手指南
第一次运行 opencode 的时候我的反应是又一个终端 AI 编码助手那时候我的终端里已经躺着 Claude Code 和 OpenAI Codex平时基本是哪个顺手用哪个突然多一个opencode第一感觉是没必要。后来强迫自己用了一个月opencode 反而成了我打开项目后的默认工具。原因很简单它的配置足够透明模型路由足够灵活skills 机制比我想象的成熟而且对用 Agent 写代码这件事的处理方式更贴近真实开发流程。这篇文章不打算写成官方文档的搬运而是把我从安装、配置模型、接 skills、用 Playwright 做前端验证这一路踩过的坑和验证过的方法完整过一遍。无论你是刚听说 opencode 的新手还是已经在 Claude Code 里折腾很久的老手应该都能找到点有用的东西。1. 先把 opencode 放进终端安装方式与常见的启动失败原因1.1 安装前先搞清一件事你装的是哪个包opencode 这个项目的包名和命令名不一样命令是opencode但 npm 包名是opencode-ai。这点初次接触的人特别容易搞混因为 npm 上确实存在一个叫opencode的旧包直接执行npm install -g opencode装出来的东西跟官方项目根本不搭边运行起来大概率是你认知之外的某个工具甚至可能直接报错。正确的安装方式很简单npm install -g opencode-ai opencode --version执行完opencode --version能输出版本号说明安装成功。opencode 是 SST 团队维护的开源项目这一点在 GitHub 仓库里能看到底子是 TypeScript 写的运行时依赖 Node.js 18 以上版本。如果你本机 Node 版本偏老装完启动会直接报语法错误尤其是 Windows 上常见。我自己的习惯是用 npm 全局安装因为后续升级直接npm update -g opencode-ai一行命令搞定日常使用频率高的话很省事。如果你是用 Homebrew 的用户也可以试试brew install opencode实测效果一样两条路走一条就行。1.2 Windows 上最典型报错无法将 opencode 项识别为 cmdlet这个报错在Windows 上出现频率极高搜索热词里也单独占了条。第一次遇到的时候说实话有点懵明明 npm 装的时候没有任何报错怎么一执行就说不认识这个命令原因并不复杂npm 全局安装的可执行文件放在 npm 的全局 bin 目录下而 Windows 的 PowerShell 和 CMD 并不会自动把这个目录加进PATH环境变量。换句话说opencode 装好了但你当前 shell 不知道它在哪里。排查和解决分三步走# 第一步查看 npm 全局 bin 目录的真实路径 npm config get prefix假设输出是C:\Users\你的用户名\AppData\Roaming\npm那opencode.exe应该就在这个目录下。# 第二步把该目录加入 PATH按Win S搜索环境变量编辑用户变量里的Path新增上面那个路径重启 PowerShell。# 第三步验证 opencode --version这条报错想排查其实很机械但真到了终端面前很多人会慌因为错误提示里带着 cmdlet、函数、脚本文件或可运行程序 一长串看着像是什么严重故障。实际上就是 PATH 没配好跟 opencode 本身没有任何关系。1.3 首次启动TUI 界面与配置文件骨架安装验证没问题后在一个项目目录里直接执行opencode会进入一个 TUI终端用户界面。左手边是会话历史中间是对话区底部是输入框。这个布局在终端 AI 工具里算比较干净的了没有太多花里胡哨的东西。首次启动会在你的用户目录下生成配置文件。Linux 和 macOS 路径是~/.config/opencode/Windows 是%USERPROFILE%\.config\opencode\。目录下常见的文件包括opencode.json主配置模型、provider、权限全在这里、mcp.jsonMCP 服务器配置、skills/技能目录、memory/记忆目录。有一点需要强调opencode 默认用的模型是 Anthropic 的 Claude 系列。你没有配置任何东西的情况下直接运行它会尝试用环境变量里的ANTHROPIC_API_KEY或者OPENAI_API_KEY去连模型如果没有这些变量就会在界面上提示需要设置 API Key。所以第一次启动看到需要配置模型不要慌这不是 bug是它等你把模型通道配好。2. 读懂 opencode.json模型、网关与多配置切换2.1 一个最小可用的配置长什么样opencode 的配置核心是opencode.json这个文件直接决定了 opencode 连哪家模型、用哪个型号、走什么接口。初次接触的人最容易犯的错是去网上抄一堆复杂配置结果格式化错误或者字段名不对启动直接挂掉。其实最小配置只需要几行{ $schema: https://opencode.ai/config.json, provider: { my-gateway: { npm: ai-sdk/openai-compatible, name: My Gateway, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_GATEWAY_KEY} }, models: { my-model: { name: My Model } } } }, model: my-gateway/my-model }这里面有一点很关键npm: ai-sdk/openai-compatible表示这是一个 OpenAI 兼容接口的 provider。现在绝大多数第三方模型服务都提供 OpenAI 兼容的/v1/chat/completions接口所以这个配置适配度最高。如果你用的是 Anthropic 官方接口npm 字段应该改成ai-sdk/anthropic如果走 OpenAI 官方就是ai-sdk/openai。我当时从官方模型迁移到网关的时候最大的感触是 opencode 的 provider 抽象做得比较干净。它不像很多工具只支持 OpenAI 格式而是通过ai-sdk/*这一系列包来适配不同协议换模型基本就是改配置不用改工具自身。2.2 免费模型与第三方网关一份订阅钱访问多种模型热词里出现的opencode go、go订阅模型选择、go套餐、hy3-free我猜大部分人和我一样第一次看到是懵的。说下我的理解opencode go 这类名字本质上是社区流行的模型网关/订阅服务核心价值是你通过一份订阅费用在 opencode 里访问多家模型。配置上它们大多统一走 OpenAI 兼容协议也就是上面那个ai-sdk/openai-compatible的接入方式。我在折腾opencode 接入 superpower和opencode go的过程中摸索出的配置套路很简单在网关控制台拿到 baseURL 和 apiKey。在opencode.json里新增一个 providerbaseURL 指过去。把网关支持的模型名逐个填进 models 字段。全局 model 字段指定默认模型。比如某个网关同时提供 Claude 和几个开源模型你可以在 models 里列出多个然后在会话中用命令切换不用每次改配置文件。部分网关还支持set model这种运行时切换实际用起来很顺手。关于免费模型热词里有个hy3-free 下线了吗。我个人的观点是免费模型服务天然不稳定下线是很正常的生命周期现象。你想在 opencode 里接免费模型当然可以但要有心理预期不要在生产环境或者重要任务上依赖免费通道。免费模型适合拿来跑通流程、验证配置是否正确真正干活还是得靠付费模型或者稳定网关。还有一个高频报错也跟模型有关this model is not available in your country.这个问题通常发生在直接调用某些区域限制模型的时候。解决思路不是去绕什么限制而是走你所用网关提供的可用区域模型或者干脆换同系列的替代模型。注意opencode 本身不管这个它只是把请求发给模型服务能不能用取决于模型服务商对区域的开放策略。2.3 用 ccswitch 管理多套配置热词里出现opencode go 需要配合 cc switch 等工具这也是我实际用下来觉得很有价值的一个点。ccswitch 原本是给 Claude Code 等工具做配置切换的但 opencode 的配置文件也是标准 JSON所以完全可以纳入 ccswitch 管理。使用步骤大致如下安装 ccswitch。添加一个opencode类型配置组。把不同的 provider 配置官方、网关A、网关B分别存成一套快照。需要切换时在 ccswitch 里点一下它会自动把对应配置写入opencode.json。有了 ccswitch我就不用手动改 JSON 了尤其是同时维护多个项目、每个项目用不同模型的时候这个切换成本省得特别明显。不过要注意一点切换配置本身不影响当前已经打开的会话改完记得重启 opencode 会话再加载。3. 从编辑器到桌面VSCode、IDEA 插件和桌面版的真实体验3.1 VSCode 插件够用但别当主力opencode 在 VSCode 里的插件体验一句话概括适合看代码不适合长时间写代码。安装之后左侧会多出一个面板能直接查看当前项目的会话历史、当前模型、还能在编辑区里用快捷键唤起行内补全。它最大的价值在于选中一段代码右键发送给 opencode它能把上下文带过去不用像 TUI 里那样手动复制粘贴。实际用下来我的感受是 VSCode 插件适合在人机结对模式下用你想让 AI 改一个小函数直接选中、唤起、让它出 diff满意就采纳。但如果要做大规模重构我反而建议切回终端 TUI因为终端里的上下文感知更专注不容易被编辑器里的其他干扰带偏。热词里提到的vscode opencode插件安装方式很简单直接在扩展市场搜 opencode装完后让它指向你本机正在运行的 opencode 即可。它不需要单独的 API Key因为复用的是 opencode 本地的配置和会话这点做得比较聪明。3.2 IDEA 插件与 Java 项目的 mvn 配置JetBrains 用户也不用眼红IDEA 里同样有 opencode 插件。安装后建议配合mvn 配置一起用这个对我来说是刚需因为不少 Java 项目依赖关系复杂Agent 经常搞不清项目里到底引了哪些包、哪个模块是入口。通过在 opencode 里配置一个 maven MCP 服务它就能读取pom.xml和构建信息回答这个项目依赖什么版本这个模块怎么构建这类问题时会靠谱得多。IDEA 插件的界面比 VSCode 版稍显粗糙但核心能力都在。对于 Maven 项目我一般先在mcp.json里配好构建查询服务再让 opencode 接手实测在改动依赖版本、排查模块编译错误的时候能省不少事。要注意的是IDEA 插件调用 opencode 时最好保证本机已经提前启动过 opencode 并且配置正确否则插件里看到的会一直是连接失败。3.3 桌面版 vs CLI什么时候用哪个opencode 桌面版是后来才出的热词里也有不少人搜。我的判断是桌面版更适合把 AI 助手当作独立应用的人它把 TUI 界面搬到了图形窗口里能同时开多个项目视觉上更友好。但它本质上还是套了一个壳底层的配置、模型、skills 机制跟 CLI 完全一样。如果你习惯终端工作流CLI 完全够用而且更快。如果你希望把 AI 会话窗口独立出来方便边写代码边看那桌面版会更合适。我自己是双持状态日常终端为主需要同时盯多个项目会话时用桌面版。两者共享同一套~/.config/opencode配置所以没有任何切换成本。4. Skills 机制与 superpowers别把 opencode 当成普通聊天窗口4.1 Skills 是什么如果你用过 Claude Code应该对 Agent Skills 有点印象。opencode 的 skills 机制思路类似你可以给 AI 预定义一组可复用的行为包每个 skill 包含一段系统提示词、一些示例、可选的脚本文件。当对话中涉及到某个领域时AI 会调用对应 skill按里面定义的流程去思考和行动。为什么要搞这么一层因为裸的模型对话虽然能写代码但缺少方法论。比如你让它修 bug它可能直接给个补丁但不会先去问你复现步骤、也不会帮你梳理根因。而一个设计良好的 debug skill 会强迫它先描述问题、再提假设、再验证最后才动手改。这些流程感对真实工程落地非常重要。4.2 安装 superpowers 技能包热词里的opencode 安装 superpowersopencode 接入 superpower指的是社区非常流行的superpowers技能集合。它里面包含了几十个 skill覆盖头脑风暴、任务规划、代码审查、调试等场景。安装方式很直接git clone https://github.com/obra/superpowers ~/.config/opencode/skills/superpowers克隆完成后重启 opencode在会话里当你描述一个任务时它会自动匹配对应的 skill。以我实际体验来说superpowers 里最有价值的是 planning写代码之前先给计划和 debugging按照系统化流程排查问题这两个 skill它们明显提升了 AI 输出的稳定性——不会一上来就甩代码而是有步骤地推进。另外热词里的oh-my-claudecode其实是在 Claude Code 生态里比较流行的配置增强方案社区现在也有人尝试把它里面对 skills 的定义迁移到 opencode 上来。这类跨工具迁移能走通全靠 opencode 的 skill 格式跟 Claude Code 兼容性做得不错。4.3 手写一个 skill比想象中简单如果你不想直接用现成的技能包自己写一个 skill 也非常简单。目录结构是这样的~/.config/opencode/skills/ └── my-skill/ ├── SKILL.md └── scripts/ └── run.shSKILL.md是核心文件开头用 frontmatter 写元信息正文写触发条件和行为说明--- name: my-skill description: 这个技能会在用户要求 ... 时被调用 --- # My Skill 1. 先做 A确认结果后再做 B 2. 如果遇到 C 情况改用 D 方案 3. 最后输出一份简明摘要我自己写过一个API 客户端代码生成技能每次需要根据 OpenAPI 文档生成客户端时它会自动检查项目里已有代码风格、生成对应语言代码、再补充单测。写完之后最大的体会是skills 把可复制的工程流程固化下来了下次遇到同类型任务AI 的表现会稳定很多不会每次重新发挥。5. 真实任务实战旧项目接手、Playwright 抓前端 bug、LSP 的隐形作用5.1 接手旧开发项目的正确打开姿势热词里opencode 接手开发项目戳中了不少人的痛点。拿到一个陌生项目时最怕的不是代码复杂而是 AI 在没有上下文的情况下瞎改。我的做法是让 opencode 先做代码侦探而不是直接提需求opencode进入 TUI 后输入提示词让 AI 先读项目结构请先浏览整个项目告诉我这个项目是做什么的技术栈是什么入口文件在哪里启动方式是什么核心模块和依赖关系有哪些有没有 README 或文档可以参考opencode 会通过内置工具读取目录结构、package.json、README 等文件很快给出项目概况。接下来再让它给出如何安全地新增一个功能的规划它会基于已读取的代码风格提出建议。这一步做完再正式开始改代码出错率会明显降低。如果你希望长期记忆项目特点可以用 memory 机制。opencode 会把一些关键约定比如本项目使用 pnpm代码风格是 2 空格缩进写入memory/目录下的文件后续会话自动加载。这个功能对持续维护一个项目的人来说价值不亚于 skills。5.2 用 Playwright 驱动浏览器测前端 bug前端 bug 是 Agent 最难搞的一类任务因为纯看代码很难复现问题。opencode 内置了 Playwright 相关的 MCP 工具可以让 AI 真正打开浏览器、点击页面、观察渲染结果和控制台报错。我在一次排查登录按钮点击无反应的问题时直接在会话里问使用 Playwright 打开 http://localhost:5173 点击页面上登录按钮观察控制台有没有报错。opencode 会启动无头浏览器执行点击操作把控制台报错抓回来。第一次看到它在终端里模拟浏览器操作的时候我确实被震撼到了——这已经不是读代码猜 bug了而是真的在跑前端。后续我还让它做过表单校验测试、页面跳转路径检查基本上能覆盖日常前端 bug 排查的 80% 场景。想启用这个能力需要确保本机有 Chrome 或 Chromiumopencode 会调用 Playwright 驱动它们。如果你的项目在代码里放了一些调试开关建议在跑 Playwright 之前告诉 AI 先阅读一下项目启动命令避免它用错误的端口启动。这个细节我在前几次使用时踩过后来习惯了先给 AI 一条npm run dev -- --port 5173这样的明确命令成功率就高多了。5.3 LSP让 AI 知道你代码里的引用去了哪里热词里有opencode 如何使用 lsp这其实是被很多人忽略的隐形能力。opencode 内置了 LSPLanguage Server Protocol支持它可以让 AI 拿到 IDE 级别的代码信息包括这个函数在哪定义这个变量在哪里被引用当前文件有没有编译错误。实际使用中我让 opencode 重构一个函数时它不只是靠阅读上下文猜引用关系而是通过 LSP 拿到准确的引用列表改动时能一并更新所有调用点。在 TypeScript 项目和 Java 项目里这个能力特别管用。配置 LSP 时你需要在opencode.json的 languages 字段里指定对应语言的 LSP 命令例如 TypeScript 用typescript-language-serverJava 用jdtls。配好后AI 的分析结果明显更懂代码。这里要说句公道话LSP 的配置对新手来说有一点门槛因为需要装额外的 language server 并在配置文件里声明。但这是值得投入的一旦配好opencode 对代码的理解能力会上一个台阶尤其在大型代码库里的表现会远超纯文本阅读的模式。5.4 让记忆发挥作用长期项目维护的秘密最后说下 memory 的实际用法。在~/.config/opencode/memory/目录下可以直接存放.md文件内容就是你想让 AI 长期记住的约定。比如你在一家对公司项目有严格代码规范的团队可以把规范写成一个 markdownAI 每次开新会话都会读它。我自己的一个习惯是每季度更新一次 memory 文件把当前项目的主要架构决策、第三方依赖、部署流程写进去。几个月后再打开项目AI 仍然能准确说出这个服务用什么端口这个模块为什么这样设计大大减少了重新解释的成本。6. Agent 之间没有绝对的胜负opencode、Codex、Claude Code、pi 的取舍6.1 四款终端 Agent 的对比热词里opencode codex claude code pi 哪个 agent 好用这种问题很常见但我的回答始终是没有最好的 agent只有最适合你工作方式的 agent。下面这张表是我用了一个月之后的真实感受工具上手成本模型灵活性Skills 能力前端测试能力适合人群opencode中高多 provider 任意接强原生支持强内置 Playwright喜欢自己掌控模型路由和流程的人Claude Code低低主要是 Anthropic 系强Agent Skills中深度使用 Claude 模型的用户Codex低中弱中偏向简单快速完成任务的人pi中中弱中追求极简终端体验的用户从表格能看出来opencode 最大的差异化优势是模型灵活性和 Skills 机制。它不像 Claude Code 那样绑定型号而是让你自由选择任何 OpenAI 兼容的模型。这意味着你可以把同一个工作流在便宜模型 贵模型之间来回切换成本控制灵活得多。6.2 我的主观选择与真实理由我个人现在的主力是 opencode核心原因是它把选择权还给了用户。我想给它接一个便宜的日常模型做通用对话再切到 Claude 做深度重构这些通过 provider 配置就行。而 Claude Code 虽然开箱即用但我在里面想换非 Anthropic 模型明显感觉是被强按在椅子上。pi 我也长期试过它很轻但生态远不如 opencode。热词里有人拿 pi 跟 opencode 比我只能说两者不在一个量级——如果你需要 skills、MCP、Playwright 这些能力直接 opencode 就完了如果你只需要一个终端聊天机器人那 pi 也确实够用。至于 Codex它的优势是简单直接适合不太想折腾配置的人但如果你的需求开始变复杂它的天花板很低扩展性明显赶不上 opencode。7. 高频报错不是玄学排查手册与一次完整追查过程7.1 报错速查表我把自己在 opencode 使用中遇到的高频问题整理成了一张表方便你遇到同类问题直接对号入座报错 / 现象常见原因处理办法无法将 opencode 识别为 cmdletnpm 全局目录不在 PATH把 npm prefix 目录加进 PATHThis model is not available in your country模型服务对当前地区不开放换网关可用模型或换同系列模型Unexpected server error. Check server logs模型网关 5xx / 请求超时检查网关状态切换模型节点看日志opencode 启动后没有响应Node 版本过老 / 配置 JSON 格式错误升级 Node校验 JSON 格式插件面板连接失败本机 opencode 未启动先在终端跑opencode再重试插件模型切换不生效配置缓存 / 未重启会话保存配置后重启 opencode 会话免费模型突然不可用服务方下线或限流增加备用 provider不依赖免费通道这张表里的每一条都是我实际遇到过或者陪朋友排查过的不是从文档里抄的。大多数问题归根结底就三类路径问题、配置问题、模型服务问题。先把这三类分开排查起来思路就清晰很多。7.2 一次 unexpected server error 的完整定位过程热词里出现error: unexpected server error. check server logs我也被这个报错折磨过一段时间。那是某天我切换到一个网关模型opencode 一发起请求就报这个错完全没有更多提示。我当时的排查链路是这样的先确认是只有这个模型报错还是所有模型都报错。我用另一个 provider 里的模型发同样请求结果正常说明问题不在 opencode 本身而在那个网关。直接在终端里手动 curl 一下网关的/v1/chat/completions用同样参数发送请求结果返回了 502。得出结论是网关侧出了问题不是 opencode 的问题。去网关控制台看节点状态发现是某个上游节点过载。切换到另一个节点后opencode 恢复正常。这个案例想说明的是很多报错表面上出现在 opencode 里实际上根因在模型服务方。遇到异常报错第一步应该是绕过 opencode 直接测试 API这一步能把排查范围缩小一大半。不要一开始就怀疑 opencode 本身它在多数情况下只是忠实地把错误转述给你。7.3 让排查更省力的小习惯最后分享几个我自己养成的维护习惯不一定都写在官方文档里善用日志opencode 的日志目录里能看到详细的请求和响应记录报错时去翻一下尾部比在终端里看那两行提示信息有效得多。配置文件备份调整opencode.json之前先复制一份改坏了能秒回滚。我见过太多人改配置改到起不来最后只能删掉重置。模型命名规范在 provider 里给模型起有一定辨识度的名字别用model1、model2这种。会话里切换模型时一目了然不会切错了还不知道。新技能小范围试用加载一个新的 skills 包后先在一个小项目里跑两天不要在核心生产项目上直接上。skills 的提示词可能和你预期不符先观察再放开。这些习惯帮我省掉了非常多重复的坑。说实话opencode 这类工具本身学习成本并不高真正耗时的是你被各种环境问题、服务问题、配置问题反复消耗的时间。把上面的排查思路和预防习惯刻进肌肉记忆之后我用 opencode 干活效率确实提升了一大截。如果你目前还在观望它和 Claude Code、Codex 之间的选择我的建议是别急着卸载哪个装一个 opencode把你手头一个不重要的项目交给他跑一遍感受一下它调动模型、使用 skills、操控 Playwright 整个过程再决定要不要让它成为你的主力工具。反正配置文件就在用户目录下折腾坏了删掉重来成本几乎为零。