第一次运行 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.json（MCP 服务器配置）、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里新增一个 provider，baseURL 指过去。 - 把网关支持的模型名逐个填进 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 安装 superpowers""opencode 接入 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 或 Chromium，opencode 会调用 Playwright 驱动它们。如果你的项目在代码里放了一些调试开关，建议在跑 Playwright 之前告诉 AI 先阅读一下项目启动命令，避免它用错误的端口启动。这个细节我在前几次使用时踩过，后来习惯了先给 AI 一条npm run dev -- --port 5173这样的明确命令，成功率就高多了。
5.3 LSP：让 AI 知道你代码里的"引用"去了哪里
热词里有"opencode 如何使用 lsp"，这其实是被很多人忽略的隐形能力。opencode 内置了 LSP（Language Server Protocol）支持，它可以让 AI 拿到 IDE 级别的代码信息，包括"这个函数在哪定义""这个变量在哪里被引用""当前文件有没有编译错误"。
实际使用中，我让 opencode 重构一个函数时，它不只是靠阅读上下文猜引用关系，而是通过 LSP 拿到准确的引用列表，改动时能一并更新所有调用点。在 TypeScript 项目和 Java 项目里，这个能力特别管用。配置 LSP 时，你需要在opencode.json的 languages 字段里指定对应语言的 LSP 命令，例如 TypeScript 用typescript-language-server，Java 用jdtls。配好后，AI 的分析结果明显更"懂代码"。
这里要说句公道话：LSP 的配置对新手来说有一点门槛，因为需要装额外的 language server 并在配置文件里声明。但这是值得投入的，一旦配好，opencode 对代码的理解能力会上一个台阶，尤其在大型代码库里的表现会远超"纯文本阅读"的模式。
5.4 让记忆发挥作用：长期项目维护的秘密
最后说下 memory 的实际用法。在~/.config/opencode/memory/目录下，可以直接存放.md文件，内容就是你想让 AI 长期记住的约定。比如你在一家对公司项目有严格代码规范的团队，可以把规范写成一个 markdown，AI 每次开新会话都会读它。
我自己的一个习惯是，每季度更新一次 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 识别为 cmdlet | npm 全局目录不在 PATH | 把 npm prefix 目录加进 PATH |
| This 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 整个过程，再决定要不要让它成为你的主力工具。反正配置文件就在用户目录下，折腾坏了删掉重来，成本几乎为零。
