最近一个月我几乎把日常写代码的主战场搬进了终端主力工具从 Claude Code 换成了 opencode。如果你还没听过这个名字可以把它理解成一个开源的 AI 编程代理coding agent它不是一个单纯的 IDE 插件而是能直接跑在你项目目录里的命令行助理能读代码、改代码、执行命令、跑测试甚至打开浏览器帮你复现前端 bug。很多人第一次接触它是在技术社区看到“opencode 安装”“opencode 使用教程”这些热搜词但真正把它用顺手的并不多。这篇文章我不打算念文档而是把从安装、配置、模型选择到 skills、LSP、Playwright 调试这些我实际走过的路整理出来给大家一份能直接照着走的实战笔记。适合这几类人看经常在终端里写代码的人、被商业 AI 编程工具的价格和限制劝退的人、需要接手陌生项目的人以及想把 AI 编程助手真正接进现有工程的团队。1. 先搞清楚 opencode 是什么以及它和 Claude Code、Codex 的差别1.1 从“聊天机器人”到“能动手改代码的代理”很多人第一次打开 opencode会误以为它又是一个终端版 ChatGPT。但实际上这类工具和普通问答式 AI 最大的区别在于它能直接看到你的项目文件能在你的机器上执行命令能调用语言服务器拿到类型和诊断信息再基于这些信息真正动手改代码。举个例子你让它“把这个接口的鉴权逻辑抽取成独立中间件”它不是给你一段示例代码让你自己去粘而是会先读你的项目结构定位到相关路由和鉴权代码理解现有风格之后直接在你的工程里创建文件、修改引用、运行测试最后把改动结果汇报给你。opencode 是 SST 团队开源的一个项目不是哪家商业公司的主营产品代码、配置和模型接口都是开放的。它默认支持 OpenAI、Anthropic、本地模型等一大堆 provider所以你用它的时候模型选择是自由的不会被某一家厂商绑死。这一点对我来说很重要因为项目里不同任务我会轮换着用不同模型。1.2 与 Claude Code / Codex CLI / Pi 怎么选网上关于“opencode codex claude code”“opencode codex pi 哪个 agent 好用”的讨论很多。我三种都用过一段时间简单说下差异工具开源模型绑定程度特点更适合谁opencode是多 provider自由切换开源、可配置性强、支持 skills 和 LSP喜欢折腾、需要接入多种模型或本地模型的人Claude Code否主要绑定 Anthropic 模型与 Claude 深度结合改代码能力强闭源愿意用 Claude 生态、不太关心配置自由度的人Codex CLI否主要绑定 OpenAI 模型OpenAI 官方出品和 GPT/Codex 模型配合好深度使用 OpenAI 模型的人Pi取决于具体项目多模型社区项目有些轻量场景表现不错想找 opencode 替代品、做对比测试的人我的体感是如果团队里已经有固定的模型供应商选对应的 CLI 最省心如果你希望一个工具能吃下不同模型、能自定义技能、能接 LSP 和浏览器自动化那 opencode 当前是最灵活的那个。下面所有内容都以 opencode 为主线来讲。2. 安装 opencode命令、平台差异和两个高频报错2.1 环境检查和安装命令opencode 本质是一个 Node.js 编写的命令行工具所以安装前你先确认机器上有没有 Node.js。我个人建议至少在 18 以上最好用 20 或 22 的 LTS 版本实测更稳。node -v npm -v安装方式官方给了两条线一条是 curl 安装脚本一条是 npm 全局包。我两种都试过curl 脚本适合 macOS 和 Linuxnpm 方式在 Windows 上也通用# 方式一官方脚本macOS / Linux curl -fsSL https://opencode.ai/install | bash # 方式二npm 全局安装 npm install -g opencode-ai安装完成后命令行执行opencode --version如果能正常输出版本号说明安装成功。如果提示找不到命令大概率就是 PATH 问题我后面会专门讲。安装这一块的重点不是“敲命令”而是想清楚你打算在哪些环境用。我自己是公司电脑装一套、个人电脑装一套顺带在 Linux 服务器上也装了一份用来处理线上日志和配置排查。它们共用一个配置文件体系换机器成本很低。2.2 无法识别 cmdlet 的排查流程很多人在 Windows 上遇到这个经典报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。我第一次在 PowerShell 里遇到这个报错时第一反应是“没装成功”后来才发现安装其实完成了只是命令所在的目录没有加入 PATH或者终端没有重新加载环境变量。解决路径分三步走。第一步先确认可执行文件到底装到哪了。如果用的是 npm 全局安装npm prefix -g这个命令会输出全局 node_modules 的路径可执行文件一般就在对应目录下。比如输出是C:\Users\你的用户名\AppData\Roaming\npm那opencode.cmd就存在这里面。第二步手动把这个目录加到系统环境变量 PATH 里然后重新打开一个终端窗口。第三步如果你是在 VS Code 的集成终端里跑的注意重启 VS Code 或者重新加载窗口否则它读到的还是旧的环境变量。如果你没走 npm 而是用安装脚本Windows 上的脚本一般会装到用户目录的某个 bin 文件夹下同样加 PATH 就行。还有一个小技巧临时急用的时候可以用npx opencode-ai直接跑绕过 PATH 问题但只是应急长期用还是把 PATH 配好。2.3 unexpected server error 的排查思路还有一个很常见的启动报错opencode error: unexpected server error. check server logs第一次看到这个我有点懵因为信息太少完全不知道哪里出了问题。后来翻了源码和日志才搞清楚opencode 启动时会拉起一个本地 server 进程负责处理模型请求、文件读取、插件通信这些事。如果这个 server 起不来或者请求中途挂了CLI 就会抛这个通用错误。排查思路是先看日志直接找 opencode 的日志目录。我这边日志路径在~/.local/share/opencode/log下不同平台可能略有差异也可以通过终端先跑一遍opencode --debug看详细输出。经验上这个报错最常见的原因是配置写坏了比如 opencode.json 里 provider 的字段不合法或者某个 model 名写错其次是网络问题比如模型 API 超时、公网不通偶尔是本地端口冲突。我自己的处理顺序是先打开日志文件看最后几十行如果有“fetch failed”就查网络如果有“invalid json”就去改配置如果日志里是权限错误就检查文件目录权限。大部分问题都能靠这个顺序定位。3. 模型提供商、订阅套餐与配置文件拆解3.1 opencode.json 配置文件到底在配什么安装好之后第一个要面对的就是配置。opencode 的主配置是一个 JSON 文件一般放在项目根目录或者用户配置目录下。网上很多旧教程会让你改 opencode.toml那是老版本的东西现在基本统一成opencode.json了。我第一次接触时恰好看到旧资料照着改了半天后来才发现版本差异。一个基础的配置文件大致长这样{ provider: { default: anthropic, anthropic: { model: claude-sonnet-4-5, apiKeyEnv: ANTHROPIC_API_KEY }, openai: { model: gpt-4o, apiKeyEnv: OPENAI_API_KEY } }, skills: [~/.config/opencode/skills], lsp: { typescript: [typescript-language-server, --stdio], go: [gopls] } }注意openopencode 的字段在不同版本里会有微调你最好以当前版本opencode --help或者官方文档为准我这个是 2.x 时代的常用结构。核心思路是你把用到的模型服务商都注册进来然后指定哪个是默认的。API Key 我强烈建议不要直接写在配置文件里而是通过环境变量引用这样即使配置文件不小心提交到仓库也不会泄露密钥。实际使用中我一般是项目根目录放一份 opencode.json专门给这个项目配置模型和 skills用户目录再放一份全局配置给所有项目兜底。这样团队里其他人拿到项目后不需要额外配置太多东西就能跑起来。3.2 opencode go 订阅/免费模型怎么选这两年很多模型服务商都推出了订阅套餐搜索引擎里“opencode go 订阅模型选择”“opencode go 套餐”热度不低。这里我给你一个选型框架别光看总 token 数量。第一看上下文窗口。你让 opencode 修改一个大型函数的时候它需要把相关文件内容塞进上下文。如果模型上下文只有 32k面对稍微大一点的代码文件就很吃力经常出现“改了前面忘了后面”的情况。我自己的门槛是主力模型至少要 128k 上下文做跨文件重构的时候甚至要 200k 以上。第二看速率限制也就是 RPM 和 TPM。免费模型或低价套餐经常限速很厉害连续问几个问题就开始转圈。这种模型适合简单问答、生成测试用例但让它在一个大模块里反复修改体验会非常折磨。想要稳定干活至少要选一个不那么容易触发限流的套餐。第三看团队共享能力。如果你是个人用无所谓如果是团队一起用最好选支持组织级控制台、能统一看消耗量的套餐不然月底账单对不上特别头疼。顺带说一下“opencode go 需要配合 cc switch 等工具”这个说法。cc switch 这类工具本质是帮你快速切换本地的 API 配置不是 opencode 自己必须依赖的东西。你只需要确认三件事匹配baseURL、API Key、模型名。三者对不上神仙工具也救不了。至于“opencode 免费模型”我的建议是可以用来做草稿、做解释、做小范围改动真正要动核心代码还是用稳定一点的大厂模型或者按量付费模型省下来的时间比省的钱值钱。3.3 “this model is not available in your country”怎么处理这个报错我在换模型服务商时踩过一次This model is not available in your country.第一次看到它时我以为是 opencode 的问题后来排查了一圈才发现是模型服务商那边的地域限制。不同 API 服务商或者同一服务商的不同区域站点支持的模型列表并不完全一样。你配置的模型名在那个地区/域名的服务里根本没有被开放所以服务商直接拒绝请求。解决方式不是去折腾什么“曲线救国”的方案而是老老实实做两件事一是去你用的模型服务商官方文档里查“models by region”或“supported models”列表确认你当前账号所在区域到底支不支持这个模型二是如果你的配置里填了自定义 baseURL确认这个 endpoint 和模型名是匹配的。实在不行就换个支持你所在区域的模型。现实里很多人一看到“not available in your country”就本能地想找歪路子但作为一个做工程的人我劝你优先走正规流程。换地区服务商、换模型、看官方文档这些都是有据可查的方案不会给你带来额外的合规风险。3.4 Linux 下改配置的实操很多后端工程师会在 Linux 服务器上装 opencode用来排查线上问题。Linux 下改 opencode 配置有两点要注意。第一是文件路径。项目配置放项目根目录全局配置一般在~/.config/opencode/opencode.json。如果你不确定当前生效的是哪份可以在项目目录里跑opencode --print-config它会输出合并后的最终配置一眼就能看出当前模型和 provider 是什么。第二是 JSON 格式。opencode.json 是严格 JSON不支持注释。很多人习惯在 JSON 里写注释写完直接启动就报 server error。Linux 下我一般用小技巧先写一个opencode.json.template带注释的模板文件改好之后再手动生成没有注释的 JSON或者用 jq 处理jq .provider.default openai opencode.json temp.json mv temp.json opencode.json注意 jq 这种覆盖写法会丢掉文件格式和原有注释改动前最好先备份。如果只是想临时切换模型其实不用改文件直接在 opencode 交互界面里用/model命令切换就行我后面会讲到。4. 把 opencode 用起来接手项目、Skills 与 LSP4.1 用 opencode 快速接手一个陌生项目“opencode 接手开发项目”这个话题在我看是 opencode 最实用的场景之一。刚进一个新团队或者被分配到一个遗留项目时第一反应通常是恐惧代码几千个文件文档还不全根本不知道从哪里下手。我现在的习惯是在项目根目录直接启动 opencode然后先用几个固定问题让它帮我建立地图“读取 README 和项目文档总结这个项目是干什么的用了什么框架”“列出项目的核心目录结构标出入口文件、路由、数据模型的位置”“查看最近的 git log告诉我最近几次提交改了什么项目当前处于什么阶段”opencode 会自己去翻文件然后把成果整理成结构化摘要。这一步能把“盲人摸象”变成“先看地图”效率提升是肉眼可见的。接下来如果有一个具体报错要修我会把完整堆栈丢给它并明确上下文“这是线上环境的一个报错发生在某个接口调用后帮我定位到对应代码并分析原因。”它能把错误栈映射到具体代码行甚至直接给出修复补丁。这里有个非常重要的实操原则不要让 AI 一次改太多文件。我的经验是AI 在多文件修改时很容易在某个文件里漏掉一处引用导致编译错误或者运行时行为不一致。所以我会要求 opencode“一次只改一个模块改完跑一次测试/编译再继续”这样即使出问题也容易定位。4.2 Skills把团队经验变成可复用的技能包opencode 有一个我非常喜欢的功能skills。你可以把它理解为“AI 的技能包”或者“插件”。团队里很多经验是可以结构化的比如代码规范、数据库操作流程、部署检查清单、新人常见陷阱。这些内容如果每次都在对话里重新描述又啰嗦又不稳定而 skills 可以把它们沉淀成 opencode 能主动加载的固定知识。典型的 skills 目录结构是这样的~/.config/opencode/skills/ └── code-review/ ├── SKILL.md └── review.pySKILL.md 里用 Markdown 描述这个技能什么时候该用、具体怎么做、有哪些禁忌。我写了一个很简单的 code-review 技能大致内容是这样的--- name: code-review description: 当用户要求 code review 或审查代码时使用 --- # Code Review 流程 1. 先读取本次改动涉及的 diff 文件确认改动范围 2. 按顺序检查业务逻辑正确性、边界情况、错误处理、安全风险 3. 对每一条问题标注严重级别blocker / major / minor 4. 汇总输出时先列 blocker 和 major再列 minor 5. 不要直接改代码只输出评审意见配置好 skills 目录后当你在对话里请求 code reviewopencode 就会自动加载这个技能按照你定义的流程执行。这比每次口头叮嘱“你要先看 diff 再给出严重级别”要可靠得多。我个人建议团队可以把几个高频场景固化成技能代码评审、数据库迁移检查、发布前检查、日志排查。一个 SKILL.md 加上一两个辅助脚本就能把老师傅的经验复制给整个团队。4.3 LSP 集成让 AI 不再“瞎猜”编译错误LSP 是 opencode 另一个杀手级特性。不了解的人可能觉得它很抽象其实用一句话解释LSP 让 AI 在改代码的时候能拿到编辑器同级别的类型信息、语法诊断和符号定义而不是对着纯文本瞎猜。比如你用 TypeScript配置了 typescript-language-server 后opencode 在修改某个函数参数时能立刻知道调用方有哪些地方会报类型错误然后主动去修复这些连带的调用点。没有 LSP 的时候它改完代码经常会留下一堆类型错误你还得手动跑tsc去发现有 LSP 之后它会像一个人借助 IDE 写代码一样实时看到红线。配置方式大致就是在 opencode.json 里加 lsp 字段把语言服务器命令填进去{ lsp: { typescript: [typescript-language-server, --stdio], go: [gopls], python: [pyright-langserver, --stdio] } }注意你本机必须先安装对应的语言服务器否则 opencode 只是启动了一个不存在的命令。以 TypeScript 为例你需要先保证typescript-language-server在 PATH 里Go 对应goplsPython 对应pyright-langserver。装完语言服务器后重启 opencode 就能生效。实际体验中LSP 对“重构”类任务帮助最大。有一次我让 opencode 把一个工具函数从utils.ts迁移到lib/format.ts它通过 LSP 找到所有引用点迁移后还把 import 全部更新掉了我跑了一遍编译零报错。这个体验在没配 LSP 之前是想都不敢想的。5. 用 Playwright 让 opencode 自己复现并修复前端 bug5.1 为什么前端 bug 最适合交给浏览器自动化前端 bug 是最难口头描述的“页面上有个按钮有时候点了没反应”“这个弹窗在某些情况下不显示”“表单校验偶尔报错”。这种问题听的人崩溃AI 也容易一头雾水。但 opencode 内置了浏览器自动化能力基于 Playwright可以让 AI 自己打开页面、操作界面、收集控制台报错然后分析复现路径。这个思路本质上不是让 AI 凭空猜而是给它一套“眼睛和手”它能看到页面真实渲染结果能点击、输入、跳转甚至截图给你看。比传统人肉复现 bug 高效得多。我这里说的 Playwright 能力有两种接入方式一种是 opencode 内置的浏览器工具另一种是单独挂一个 Playwright MCP 服务。不同版本的 opencode 对 MCP 工具的支持方式略有调整你在交互界面里输入斜杠命令看有没有playwright或mcp相关的列表就能确认。5.2 一次完整的前端 bug 修复流程我建议你按下面这个流程使用别跳步我在最后一步吃过亏第一步启动 opencode 后明确告诉它当前项目的前端启动命令。比如“项目是 Vite Reactnpm run dev启动在 5173 端口”。它会自己把开发服务器跑起来或者告诉你需要先手动启动。第二步描述 bug 现象要具体。比如“登录页输入正确账号密码后点击登录按钮没有任何反应控制台也没有报错”。然后要求它“用浏览器工具复现这个问题”。第三步它会写一个 Playwright 脚本打开浏览器、访问页面、输入内容、点击按钮、收集 console 日志和网络请求结果。你可以看到它实时操作浏览器的输出也可以让它截图保存到项目目录。第四步根据复现结果它通常能定位到问题根源。比如某个事件绑定写错了选择器或者某个接口请求被拦截。这时候再让它修复它脑子里有“真实发生过的错误信息”不是凭空猜测修得会准很多。第五步修完代码后重新让它跑一遍同样的 Playwright 流程验证 bug 是否真的消失。这一步不能省我上次让 AI 改完后没验证结果它改对了 A 场景却弄坏了 B 场景。5.3 浏览器调试的注意事项用 Playwright 跑前端测试有几个坑要提前说。第一浏览器二进制一定要装。你光装了 npm 包还不够还得执行类似npx playwright install chromium的命令把实际的浏览器下载下来。不装的话AI 一启动浏览器工具就会报错。第二headless 模式和带界面的模式各有用途。我调试时喜欢让它在有界面模式下跑这样我能亲眼看到页面变化如果只是 CI 回归验证可以用无头模式速度快。第三如果项目里有登录鉴权直接让 AI 打开页面往往会跳转到登录页。你可以在描述里把测试账号给它或者让它读取你本地已有的登录态。千万注意别把密码写进公开的配置和 SKILL.md 里。第四前端 bug 不一定都在控制台报错里能看出端倪。有时候页面显示异常是 CSS 样式问题控制台完全没报错。这种时候要让 AI 截图给你看你用人眼判断一下视觉效果再告诉它怎么调整。6. VS Code、JetBrains 插件与桌面端选哪个6.1 插件只是“遥控器”核心还是本地 CLI现在 VS Code 和 JetBrains 里都有 opencode 插件网上搜“vscode opencode 插件”“idea opencode 插件”的教程也很多。我两个都试过结论是插件本质上是一个“遥控器”它把 opencode 的能力搬到了 IDE 面板里实际干活的核心还是你本地的 opencode CLI 和 server 进程。VS Code 插件安装后侧边栏会多出一个 opencode 面板你可以直接选中一段代码右键发送给 opencode 让它解释、优化、补测试。JetBrains 插件的工作方式类似适合 Java、Go、Kotlin 等重度 IDEA 用户。选择建议很简单如果你日常大部分时间在 VS Code/IDEA 里写代码装插件能减少切换终端的频率。但如果你要处理跨文件重构、跑测试、操作浏览器这些复杂任务我还是推荐切回终端用 CLI因为终端下的交互流更完整输出信息也更全。6.2 我的 IDE 使用习惯我自己目前的节奏是“双轨并行”日常小改动比如写个函数、补个注释、写单测直接在 VS Code 的 opencode 面板里完成省得切窗口一旦涉及多文件重构、排查线上问题、跑 Playwright 复现 bug就打开终端用 CLI让 opencode 按计划一步步改。还有一点要提醒IDE 插件和终端 CLI 共用一个配置和会话体系你在插件里配置好了模型终端里也能直接用。但反过来如果你在终端里改了 opencode.json记得重启 IDE 插件或者重新加载窗口否则它可能还拿着旧配置。至于 opencode desktop桌面客户端我也装过它把终端交互变成了一个独立窗口视觉上更像聊天软件适合不太习惯命令行的朋友。但对我来说桌面端多一层进程占内存平时还是用 CLI 最多。7. 常见问题速查表最后把网上热搜里出现频率最高的几个问题整理成速查表方便你遇到问题时直接查。7.1 报错类问题报错现象常见原因解决方式无法将“opencode”项识别为 cmdlet可执行文件目录没加入 PATH或终端未重启npm prefix -g找到目录加入 PATH 后重开终端opencode error: unexpected server error配置文件非法、网络超时、端口冲突打开~/.local/share/opencode/log日志看堆栈按定位处理This model is not available in your country模型在所选区域/端点未开放查服务商官方模型清单换支持区域或换模型Playwright 报错找不到浏览器浏览器二进制未安装执行npx playwright install chromiumLSP 一直转圈不返回语言服务器未安装或不在 PATH确认typescript-language-server、gopls等已安装7.2 使用习惯类问题问题现象我踩过的坑现在的做法AI 改的面目全非一次让 AI 同时改多个模块结果每处都改一半一次只改一个模块改完跑测试再继续长会话后半段回答质量骤降上下文窗口被占满模型“忘了”开头的约定定期用新会话继续每次开头重申关键上下文密钥泄露风险曾经把 key 写进 opencode.json 并提交到仓库全部改用环境变量并在 .gitignore 里排除配置模型明明很强输出却很水默认模型选错或 temperature 过高切换模型、调整配置里的温度参数这里再补充一个公开文档里不太会写的技巧opencode 在交互界面里支持很多斜杠命令比如/model随时切换模型/new开启新会话/export把当前会话导出成文件。遇到上下文太长、模型开始“发昏”的时候直接/new开新局把关键背景重新描述一遍比硬撑到最后一本正经胡说八道要省时间。我自己现在已经养成了习惯长任务绝不从头到尾只开一个会话做到一个里程碑就切新会话让模型保持新鲜上下文。另外如果你有多个服务商的 API Key我强烈建议用环境变量的方式管理而不是放在配置文件里硬编码。在终端里临时设置一次export ANTHROPIC_API_KEYsk-xxx export OPENAI_API_KEYsk-xxx然后启动 opencode它就能自动读到。这样既安全又方便切换不同服务商的套餐。最后聊两句我自己的使用体会。以前用 AI 编程助手我总担心它“乱改”“改错”所以事无巨细都要盯着。用 opencode 这段时间下来我最大的转变是学会了“让 AI 先出方案再动手”。哪怕是一个很小的改动我也先让它列出计划、标明要动的文件和涉及的风险确认没问题后再让它执行。这个习惯帮我挡住了很多次本来会发生的“AI 式破坏”。如果你现在刚开始接触 opencode我的建议是先别急着配一堆花哨的 skills 和 LSP先用最基础的安装 一个可靠的模型跑通一个小任务的完整流程等熟悉了它的交互节奏再去接 LSP、写 SKILL.md、上 Playwright。这个工具能给你带来的上限很高但前提是你得先学会怎么安全地驾驭它。