2025 年年中我在 GitHub Trending 上刷到sst/opencode那会儿第一反应是“又一个 AI 命令行工具能火三个月就算赢”。真正把它装进终端、扔到三个不同项目里连续用了两周之后我改主意了opencode 是现阶段少数几个真正做到“模型无关”的终端编程 Agent一条命令能进交互式 TUI也能在脚本里跑非交互任务配上 skills、memory、MCP 和 Playwright 之后它基本就是一个住在你项目里的实习生。这篇文章把我从安装、配置到实战排错的完整过程写下来覆盖大家高频搜的那些问题opencode 是哪家公司的、opencode 安装教程、Windows 下 cmdlet 不识别、this model is not available in your country、opencode vscode 插件、opencode playwright 测前端 bug 等等。无论你是刚听说想试一把的新手还是已经在用 Claude Code 或 Codex 想横向对比的开发者应该都能从里面找到自己需要的那一段。1. 先搞清楚opencode 到底是什么以及它和 Claude Code、Codex 的本质区别1.1 它不是“套壳”而是一个模型无关的 Agent 运行时很多 AI 编程工具是反向设计先选定了模型再包一层壳因此你一旦用上就被某个模型的生态绑死了。opencode 的设计是反过来的——它先做了一个“Agent 运行时”把对话管理、工具调用、文件读写、终端命令执行、LSP 代码智能、浏览器自动化这些能力全部内建然后把模型设计成可插拔的部件。这句话翻译成人话就是你今天可以用 Claude明天可以切 GPT后天换 Gemini甚至可以接一个本地跑在 Ollama 上的开源模型。你的操作习惯、会话体系、技能配置、权限策略全都不变变的只是“谁来思考”而已。体现在配置上就是opencode.json里写清楚provider和model一行配置就完成换脑。这个架构带来的实际收益很直接你不再因为“某个模型的额度用完了”“某个模型被限流”而卡住整个工作流。模型只是发动机车还是那辆车。我在实际项目中比较依赖这个特性——团队有时候会因为账务原因临时切换模型opencode 这种切换几乎零成本。1.2 “opencode 是哪家公司的”——这个项目被问得最多的问题opencode 最初来自 Anomaly 工作室就是做 Drizzle ORM 那一批人所在的圈子。后来项目进入大众视野在 SST 团队的主导下继续快速迭代。SST 是搞 serverless 框架的那个技术团队工程能力相当扎实。仓库在 GitHub 的sst/opencode开源协议是 MIT核心维护者是 Kujtim HoxhaGitHub 上的 kujtimiihoxhaSST 的 Dax 等人也深度参与。严格讲它没有“母公司”这个概念更像一个由成熟工程团队供养的开源项目。这个背景对普通用户有个现实意义它不会像某些个人作品一样突然断更Issues 和 PR 的处理速度也一直在线。我关注它的几个月里版本迭代非常快2.0 之后更是加入了 agents、skills、memory 等一批重量级能力。1.3 横向对比Claude Code、Codex CLI、Cursor、opencode 怎么选先给一张我整理过的对比表方便直接抄维度opencodeClaude CodeCodex CLICursor开源是MIT否是Apache-2.0否模型锁定无支持多 Provider主推 Claude 生态主推 OpenAI 系内置多模型交互形态TUI / 单次命令 / 桌面端TUI / REPLTUI图形 IDESkills / 插件支持 skills、MCP支持插件、MCP支持 MCP插件市场浏览器工具内置 Playwright 集成部分支持部分支持部分支持工具费用免费模型自负免费模型按订阅或 API 计费免费IDE 订阅我的个人结论如果团队已经深度绑定 Anthropic 生态Claude Code 仍然是默认选择因为它的系统提示词和自家模型的协同是最优的如果你想要“一套操作习惯、随时换模型”或者主力模型是 Gemini、开源模型那 opencode 是更合理的底座Codex CLI 则适合 OpenAI 重度用户。2. 安装与首次运行三种装法以及最容易翻车的三个坑2.1 三种安装方式npm、官方脚本、Go 源码opencode 本身是用 Go 写的所以安装方式很灵活根据自己的环境挑一种就行。第一种npm 全局安装最通用Windows 和 macOS 都适用npm install -g opencode-ai装完跑一下opencode --version能输出版本号就说明 OK。第二种官方脚本Linux/macOS 上最省事curl -fsSL https://opencode.ai/install | bash脚本会下载对应平台的二进制放到可执行路径下。第三种Go 源码安装适合本来就有 Go 环境的开发者go install github.com/sst/opencodelatest我个人推荐优先走 npm 或官方脚本因为升级方便。opencode 迭代很快几乎每周都有新版本用opencode upgrade可以自更新。桌面版和编辑器插件属于另一个安装路径放到第八节单独说。2.2 Windows 上“无法将 opencode 项识别为 cmdlet”的完整排查这个报错是 Windows 用户遇到最多的问题完整排查链路其实很固定第一步确认到底装没装上。打开终端执行npm ls -g --depth0看输出里有没有opencode-ai。如果压根没有说明安装过程出了问题把 npm 的报错信息翻出来大部分情况是权限问题或网络问题。如果有但运行opencode仍然提示 cmdlet 不识别那就是 PATH 的问题。第二步确认 npm 全局 bin 目录是否在 PATH 里。执行npm config get prefix会输出一个路径Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm。把这个目录加进用户环境变量的 PATH然后重开一个终端窗口。第三步重开终端还不行就手动验证一下 PowerShell 能否解析到这个命令Get-Command opencode -ErrorAction SilentlyContinue如果返回空说明 PATH 里还是没有如果返回了路径只是当前 shell 的缓存问题。实在不行就直接用全路径执行%APPDATA%\npm\opencode.cmd先跑起来再说。还有一个很常见的玄学问题用管理员权限装的和当前用户装的 npm 全局包路径不一致导致环境变量串了。建议清理之后统一用同一个账号安装能省很多事。2.3 首次认证与模型选择auth login 和免费模型的正路装好之后第一步是配置模型访问。最简单的方式是执行opencode auth login它会打开浏览器让你选择要使用的模型服务商并完成授权。也支持直接把 API key 写到环境变量里opencode 会自动识别常见厂商的 key 命名。首次进入 TUI 后输入/models可以列出当前可用的模型并切换。很多人搜“opencode 免费模型”这里我说句实在话opencode 本身没有免费的模型午餐模型能力都是各家厂商收费的但它确实有几条合法省钱的路子。一是本地开源模型。通过 Ollama 跑 Qwen2.5-Coder、DeepSeek 这类模型然后在 opencode 里配置一个自定义 provider指向http://localhost:11434/v1baseURL 和模型名填对就能用。二是 OpenRouter 这类聚合平台上标注:free的免费额度模型。三是各家云厂商新用户赠送的额度。不管选哪条路我都建议别去填那些来路不明的“免费 key”评测不稳定只是小事key 泄露带来的安全风险才真要命。3. 从单次问答到项目级 Agent三种工作模式各有什么用3.1 交互式 TUI日常开发的主战场直接在终端输入opencode就进入交互界面。界面分成三个区域左侧是会话历史列表中间是消息流底部是输入框。用过 Claude Code 的人上手没有障碍。常用操作Tab补全CtrlK打开命令菜单CtrlC中断当前响应输入/model切换模型/new新建会话/share分享当前会话/undo把最后一次操作回滚。不同版本快捷键可能有细微差别以/help输出的实际内容为准。TUI 模式适合需要来回确认的复杂任务。opencode 的交互设计有一点我很喜欢它把 Agent 要执行的动作读文件、改文件、跑命令都摊开给你看你可以选择逐条允许还是全部拒绝而不是一次性给 Agent 全部权限心理负担小很多。3.2 run 模式适合脚本化、CI 和批量任务非交互模式适合不需要人盯着的任务opencode run 给 src/utils.ts 补上单元测试这条命令会在后台完成整个 Agent 循环跑完直接退出。也支持延续之前的会话继续跑opencode run --continue 继续上一轮没改完的部分我常用这个模式做两类事情一是早上到公司先挂一个opencode run让它处理 Ticket 里描述很清晰的 bug然后我边看邮件边等结果二是把一些重复性的代码迁移工作写成脚本批量触发比如把某个老目录下的 CommonJS 文件批量改成 ESM 风格。run 模式跑完之后的输出建议先看一眼改动文件清单再决定是否合并不要把 Agent 的输出直接当最终结果。3.3 接手一个陌生项目的正确姿势很多人拿到一个不熟悉的老项目第一句话就是“帮我加个功能”结果 Agent 一顿操作改得面目全非因为它在根本不理解项目结构的情况下就动手了。我现在的流程是先让它“读书”再动手第一步先让它读项目的元信息文件。没有 README 就先读package.json、go.mod、pyproject.toml弄清楚技术栈、构建方式、依赖管理工具。第二步让它用 LSP 做代码侦查。opencode 会自动启动对应语言的 LSP server能让 Agent 做定义跳转、查找引用、理解类型系统而不是傻乎乎地把整个仓库塞进提示词里。第三步动手之前明确边界。我会在会话里直接说“先不要动 vendor 目录”“不要改测试快照”“只读分析等我确认再改”把 expected behavior 说清楚再放它动手。第四步改完一定要自己 review diff。opencode 会列出改了哪些文件我会逐个文件过一遍再让它补测试、跑测试。把它当实习生带而不是当神供着产出质量会稳定很多。4. opencode.json把配置从“能跑”调到“好用”4.1 配置文件的查找顺序与一份最小可用配置opencode 的配置遵循“项目优先”原则项目根目录的opencode.json优先级最高其次是用户目录下的全局配置Linux/macOS 在~/.config/opencode/opencode.jsonWindows 在%USERPROFILE%\.config\opencode\opencode.json。项目配置适合放团队共享的内容全局配置放个人偏好。一份最小可用的自定义 provider 配置长这样{ $schema: https://opencode.ai/config.json, provider: { my-openrouter: { npm: ai-sdk/openai-compatible, name: OpenRouter, options: { baseURL: https://openrouter.ai/api/v1, apiKey: {env:OPENROUTER_API_KEY} }, models: { anthropic/claude-sonnet-4: {}, meta-llama/llama-3.3-70b-instruct:free: {} } } }, model: anthropic/claude-sonnet-4 }{env:OPENROUTER_API_KEY}的写法是从环境变量读 key这样配置文件可以安全提交到仓库不会泄露密钥。$schema字段指向官方 JSON Schema编辑器里写配置时有补全和校验。需要提醒的是opencode 版本迭代很快配置字段时有调整以当前版本执行opencode config输出的实际结构为准网上的教程包括这篇都可能落后于版本。4.2 多 Provider 与模型兜底策略团队场景里多 Provider 配置很有价值。你可以把主模型配成 Sonnet兜底模型配成 Gemini 或者本地 Ollama 的某个模型。当主模型出现 429 限流或者服务不可用的时候Agent 会自动走兜底逻辑不至于整个工作流断掉。配套还有模型列表管理。在交互界面输入/models可以实时预览和选择可用模型切换后当前会话立刻生效。我习惯在项目配置里只留两个模型一个强推理模型负责复杂重构一个快速便宜的模型负责跑测试、补注释这类琐碎任务。团队协作时具体做法是把opencode.json提交到仓库API key 全部走环境变量新成员 clone 下来之后只要配置好环境变量就能直接用同一套配置。省掉的 onboarding 时间非常可观。4.3 权限声明与 rules给 Agent 立规矩权限声明是 opencode 里最容易被忽视但最重要的配置。它决定了 Agent 能够执行哪些操作。{ permission: { allow: [ git add, git commit, git diff, npm test ], deny: [ rm -rf, git push --force ] } }deny列表里写的是绝对不允许执行的命令即使你手动确认也不行。我会默认把git push --force、rm -rf、直接删分支这类高危操作都加进去。allow列表里放的是日常高频且风险低的命令避免每跑一条测试都弹一次确认。rules 则是给 Agent 的行为准则相当于团队 wiki 里的开发规范写进配置后每个会话都会带上{ rules: [ 所有注释和提交信息使用中文, 提交信息遵循 conventional commits 格式, 不要修改 generated 目录下的文件, 修改公共 API 前必须先说明影响范围 ] }这些规则看起来简单实际效果很好尤其是“改动共享模块前先说明影响范围”这一条能明显减少 Agent 贸然改动公共函数导致其他模块炸掉的情况。5. Skills、Memory、MCP、LSP让 Agent 记住并会使用你的项目5.1 Skills把团队知识沉淀成可调用的技能opencode 从 2.0 开始支持 skills概念类似于 Claude Code 的 agent skills把一段带结构的知识封装成一个“技能”Agent 在合适的场景会自动调用。技能文件是 Markdown放在项目的.opencode/skills目录或者用户全局的~/.config/opencode/skills目录。我团队里最先落地的技能是“生成提交信息”。文件内容大概是这样的结构--- name: commit-msg description: 根据 git diff 生成符合 conventional commits 规范的提交信息 --- 先运行 git diff --cached 查看暂存区改动分析改动属于 feat、fix、refactor、chore 中的哪一类确定影响范围scope然后输出一条不超过 70 字的提交信息格式为 type(scope): subject。这个技能文件本身不需要特别复杂关键是 description 要写得足够清晰这样 Agent 才能判断什么时候该调用它。实际用下来团队里新人提交信息不规范的毛病基本消失了。社区里现在有不少现成的 skills 仓库有些人把 Claude Code 生态里比较流行的 Superpowers 技能库移植到 opencode 使用。移植时注意两点路径要放到 opencode 的 skills 目录frontmatter 的字段要按 opencode 的约定调整直接贴原版经常不生效。5.2 Memory跨会话的项目记忆opencode memory子命令是给 Agent 做长期记忆用的opencode memory add 这个项目使用 pnpm workspace新增包时记得同步更新 root 的 lockfile opencode memory list添加的记忆在后续相关会话中会自动加载进上下文Agent 就不会每次都是“第一次见面”的状态。记忆分全局和项目级项目级的更推荐多存因为它绑定的是当前项目的关键约束。但要注意memory 本质上是上下文提示不是数据库存太多、太细节、会过期的东西反而会污染上下文影响模型判断。我的原则是只存“长期稳定且影响改代码方式”的信息比如“不要动某个目录的生成代码”“测试必须用 vitest 而不是 jest”。5.3 MCP 与 LSP外部工具链和本地代码智能MCPModel Context Protocol是 Agent 连接外部工具的标准化协议。opencode 支持通过opencode mcp add这类命令把外部 MCP server 挂进来比如 GitHub、数据库客户端、Jira 等。挂上之后Agent 就能在会话里直接查 Issue、看 PR、查数据库表结构不再需要你把信息复制粘贴给它。LSP 是 opencode 实现代码智能的关键机制。它会为 TypeScript、Go、Python 等语言自动启动对应的 language server让 Agent 具备跳转定义、查找引用、获取类型信息的能力这比把所有源码塞进上下文要省 token而且理解更准确。关于“opencode 如何使用 LSP”这个问题九成场景你什么都不用做只需要确保系统里装了对应语言的 LSP 程序比如typescript-language-server、gopls、pyright。特殊项目需要指定 root 目录或附加环境变量时在opencode.json的lsp字段里单独配一下就行。6. 让 Agent 自己验证前端改动Playwright 的实战接入6.1 为什么要让 Agent 跑浏览器AI 编程 Agent 有个通病改前端的时候特别容易“自信地错误”。它改完一个交互逻辑告诉你“搞定了”实际上可能是组件根本没渲染出来或者按钮事件压根没绑上。普通代码 review 是看不出这种问题的必须有人跑浏览器点一遍。但每次都让开发者手动验证Agent 的价值就少了一半。我的做法是让 Agent 自己写 Playwright 脚本自己验证。改完前端代码之后它必须启动 dev server写一个浏览器自动化脚本打开页面、执行用户操作、断言结果脚本不跑通就算没完成。这个闭环建立之后前端 bug 的漏网率肉眼可见地下降。6.2 从配置到一次完整的实测流程接入分三步。第一步在项目里装 Playwrightnpm i -D playwright/test npx playwright install chromium第二步把浏览器工具接入 opencode。官方文档里有 browser 相关工具的介绍社区里也常用 Playwright MCP server 的方式接入。两种方式选一种配置完成后在 TUI 里用/mcp确认工具已经加载。第三步给 Agent 下明确指令。我常用的 prompt 模板是这样的启动 dev server 后写一个 Playwright 脚本打开 http://localhost:5173点击登录按钮填写测试账号提交后断言页面跳转到 /dashboard并且右上角显示用户名。脚本通过后把脚本保存到 tests/scripts/login.spec.ts。实测下来我最直观的感受是Agent 会自己写脚本、跑脚本、看报错、再修脚本这个循环非常值得观察。一开始它的选择器写得比较脆弱但经过两三轮迭代后稳定多了。整体成功率大概六到七成失败的场景大多出在环境问题而不是 Agent 逻辑问题。6.3 边界与教训Playwright 适合验证 UI 逻辑链路但不适合做视觉回归像素级样式问题它看不出来也不适合登录态特别复杂的系统比如公司内网需要 SSO 登录的场景Agent 过不了认证就没办法继续。这类系统我改让 Agent 写 API 层的集成测试绕开浏览器登录这个瓶颈。还有资源问题Playwright 跑起来要启动浏览器很吃内存。别同时让多个 Agent 任务一起跑浏览器测试开发机直接卡死。我一般是串行跑或者把这类任务丢到 CI 环境里执行。7. 高频报错排查笔记这些问题 90% 的人都会遇到7.1 Windows 下 cmdlet 识别失败这个上文已经很详细地讲过了简单回顾先npm ls -g --depth0确认有没有装上再用npm config get prefix查 npm 全局 bin 目录确认它在 PATH 里。这一步解决了至少七成的“opencode 无法识别”问题。7.2 “this model is not available in your country” 的正确处理这个报错是模型服务商或聚合平台基于地区策略返回的跟你电脑配置无关也不是 opencode 的问题。看到这个提示正确的处理思路是不要硬刚一是换一个你所在地区可正常访问的其他模型聚合平台通常同时上架了很多模型换个供应源就绕开了地区限制。二是换服务商选择在本地有正式服务的厂商。三是最彻底的在本地跑开源模型比如通过 Ollama 部署 Qwen 系列、DeepSeek 系列模型就在你机器上不依赖任何地区策略。这里我多说一句看到有人建议用奇怪的手段绕过地区限制我是不推荐的。一方面不安全另一方面也不符合各家服务的使用条款。本地开源模型其实已经能覆盖大部分日常编码场景了没必要为了某个特定模型去冒风险。7.3 “unexpected server error. Check server logs.”opencode 的架构是每次运行都会起一个本地 server会话和工具调用都通过它。报这个错十有八九是这么几个原因。首先是模型 API 返回异常比如空响应、5xx 错误。最快的定位方式就是换一个模型试试如果换了就正常说明是原模型服务方的问题。其次是 provider 配置错误。最常见的是 baseURL 写错、apiKey 没注入成功。检查一下配置里的{env:XXX}是否真的有对应的环境变量以及 baseURL 是不是拼写错误。第三是本地 server 端口被占用。之前异常退出旧进程还没释放端口新进程起不来。结束掉残留进程再跑就行。最后是配置文件解析失败。JSON 少个逗号、多了一个字段都会导致 server 启动异常。日志在 Linux/macOS 的~/.local/share/opencode/log目录下Windows 在%USERPROFILE%\.local\share\opencode\log直接看最新日志文件定位。7.4 升级之后配置不生效之类的杂项opencode 2.0 的配置 schema 相对旧版有调整升级后旧配置不生效是正常现象。用opencode config看一眼当前版本实际读取到的配置内容对照新格式改一遍就恢复了。TUI 渲染乱码通常不是 opencode 的问题而是终端环境问题。Linux 上先确认LANG环境变量是 UTF-8macOS 上检查终端软件有没有开启 Unicode 渲染。模型输出质量突然变差先看是不是命中免费模型的限流。免费模型看着省了钱但并发和上下文受限一旦触发限流 Agent 就会“变笨”。8. 从终端到桌面VSCode、JetBrains 插件与桌面版的联动8.1 VSCode 插件边看 diff 边对话扩展市场里搜 opencode找到发布者对应的官方扩展装上。插件主要有两个使用方式一个是在侧边栏打开 opencode 面板把对话界面嵌入编辑器另一个是在集成终端里直接跑opencode用 TUI 模式。我实际用下来觉得插件最大的价值不是省那一个切换窗口的动作而是上下文传递你在编辑器里打开的当前文件、选中的代码段可以直接发送给 Agent不用复制粘贴。Agent 改完文件编辑器里的 diff 实时更新改动想退回也方便。8.2 JetBrains 插件IDEA 系项目的适配IDEA、PyCharm、GoLand 等 JetBrains 系的插件逻辑类似安装后在底部 tool window 打开 opencode。Java/Kotlin/Go 项目的开发者用这个方案比较舒服因为 JetBrains 自家对代码索引的展示更好Agent 改完代码之后 IDE 的 inspection 能马上标出问题形成“Agent 改、IDE 查错”的双重校验。8.3 桌面版与官方托管服务opencode desktop 把 TUI 包成了原生桌面窗口适合不习惯命令行或者想要独立窗口的用户。它本质上还是同一个 opencode配置和技能都是共用的。另外官方还提供 opencode GO一种托管订阅服务帮你把模型访问聚合起来用户不需要自己一个个配 API key按订阅档位选模型即可。适合公司统一付费或者不想折腾模型配置的个人用户。选择的时候注意它和自配 key 的区别GO 的计价和账单都走官方托管服务自由度不如自己配 provider但省心程度高很多。我个人目前还是自配 key 为主因为项目里要用到特定的本地模型和自定义 baseURL。9. 折腾两个月之后几点实在的体会最后分享几个我实际折腾下来的个人感受不算建议只当参考。第一个体会是opencode 的原生客户端速度真的快。Go 编译的单二进制TUI 响应几乎没有延迟比我之前用过的某些 Electron 壳子工具流畅一个量级。这种体感差异在天天用的工具上会被放大用惯了再回去敲那些卡顿的工具会很难受。第二个体会是新手期把权限收紧不要一上来就全自动。先让它跑 run 模式观察它每一步在干什么看它怎么理解你的指令再逐步放开权限。我见过不少同事第一次用这类工具就给了完全信任结果 Agent 把一堆不该动的文件改了个遍回头骂工具不行。其实工具本身可以很稳关键是使用姿势。第三个体会是opencode 的迭代太快了任何教程包括这篇都只能代表某个时间点的状态。你读到这篇文章时可能界面、命令、配置格式又有了变化。遇到对不上的地方优先看官方文档和 changelog别照着旧教程硬抠。opencode 在我看来最有价值的不是某一个功能而是它把“模型无关的 Agent 运行时”这件事做扎实了。在 AI 编程工具一天一个样的今天能把底座做稳、把生态接口打开的工具才是值得长期投入时间去学的那个。