最近好几个读者都在问 opencode说在 GitHub 趋势上看到它又被各种帖子刷屏。其实我前几个月就已经在终端里用它跑真实项目了从修一个简单 bug 到接手新需求基本每天都在用。opencode 不是一个聊天窗口而是一个跑在终端里的 AI 编程代理agent你给它一个任务它能自己读代码、改代码、执行命令、跑测试甚至打开浏览器帮你复现前端问题。和 Claude Code、Codex、Pi 这类工具是同一赛道但 opencode 最大的特点是模型自由OpenAI、Anthropic、Google、本地模型、各种网关都能接而且配置是纯文件的好审计、好迁移。这篇文章我打算从安装踩坑讲起把配置、插件、Skills、LSP、Playwright 测试这些高频场景都过一遍最后列一份我长期积攒的报错排查清单。适合谁看如果你已经在用 Cursor 但想试试终端 agent或者被 Claude Code 的账号门槛卡住又或者手里有一堆 API key 想统一管理opencode 都值得一试。内容会写得比较细你完全可以照着一步步操作。1. opencode 是什么把“改代码”变成“安排任务”的终端 agent1.1 和 Claude Code / Codex / Pi 的定位差异很多人第一次看到 opencode 会问这不就是又一个 Claude Code 吗事实上这类工具解决的是同一个问题——让 AI 不再只是“问答窗口”而是能真正接管一部分开发流程。但它们在模型绑定、开放程度和交互方式上有明显区别。我用过一段时间之后对这四类工具的定位做过一个粗颗粒度的对比工具模型绑定主要交互适合场景opencode开源多模型聚合终端 TUI 文件配置想自由切换模型、追求可定制、需要把流程沉淀成 SkillsClaude Code深度绑定 Anthropic终端对话Claude 重度和忠实用户Codex深度绑定 OpenAI终端 / IDE 内OpenAI 重度用户Pi轻量 agent 工具终端更轻的单次任务场景opencode 对我来说最大的价值是“不锁死”。我今天的项目可能用 Sonnet 类模型写复杂逻辑明天跑一个小脚本就用便宜快速的轻量模型opencode 只要改配置就能切换不需要重新适应一套交互。这点在真实开发里太重要了因为模型的强弱并不总是决定产出质量成本和响应速度同样影响体验。1.2 本地优先你的配置和会话都是可读文件opencode 的另一个设计思路是“本地优先”。配置文件默认放在~/.config/opencode/opencode.json会话记录、日志都存在本地目录里而不是全部锁在某个云平台上。这意味着三件很实际的事第一配置可以放进版本管理。我通常会把.opencode/下的团队配置提交到仓库里新同事克隆下来就能用同一套模型和规则省去口头同步。第二行为可审计。agent 到底改了哪些文件、执行了什么命令翻开日志一目了然。对于团队协作这比一个“黑盒聊天窗口”靠谱得多。第三迁移成本低。换电脑只要同步配置文件和 key不需要重新“训练”一个工具。如果你之前只用过 IDE 内置的 AI 编程插件第一次用 opencode 可能会不太习惯因为它没有漂亮的图形界面只有终端里的 TUI。但适应之后你会发现终端里的 agent 反而更专注它能直接操作 shell天然适合跑测试、查日志、批量改文件这些“脏活”。2. 安装 opencode从一行命令到 Windows 报错自救2.1 三种安装方式和我的选择opencode 的安装方式主要有三种你按自己环境挑一个就行。npm 方式也是我用得最多的npm install -g opencode-aicurl 脚本方式适合不想依赖 Node 环境的机器curl -fsSL https://opencode.ai/install | bashGo 方式适合本来就有 Go 工具链的人go install github.com/sst/opencodelatest提示curl 脚本和 go install 本质都是拉一个可执行文件到本地npm 方式因为有全局 node_modules 的概念在 Windows 上最容易出现 PATH 问题所以我下面的排错重点说 npm。我自己的习惯是Windows 上用 npmLinux 服务器上用 curl 脚本macOS 上也是 curl 为主。原因很简单npm 版本更新方便一条npm update -g opencode-ai就完事而服务器上我通常不愿意为一个小工具装完整 Node 环境。2.2 Windows 上“cmdlet 无法识别 opencode”的根因和解决搜索热词里出现频率最高的问题是这句报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。用大白话解释这个报错不是说 opencode 没装上而是说你装好的可执行文件放在了一个 Windows 当前不会去找的目录里。npm 全局安装时会把可执行文件放到 npm 的全局 bin 目录通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在 PATH 环境变量里你在任意路径下敲opencodePowerShell 自然找不到。解决步骤很简单先看 npm 全局目录在哪打开 PowerShell 执行npm prefix -g把输出目录加入用户 PATH。假设输出是C:\Users\你的用户名\AppData\Roaming\npm执行[Environment]::SetEnvironmentVariable(Path, [Environment]::GetEnvironmentVariable(Path, User) ;C:\Users\你的用户名\AppData\Roaming\npm, User)关掉当前终端重开一个新的 PowerShell再执行opencode --version如果能看到版本号说明安装成功。这里我再补几个容易忽略的细节。第一改完 PATH 之后一定要重开终端不是刷新一下就行的PowerShell 的环境变量是在启动时加载的。第二如果你用的是 Windows 下的 WSL那 PATH 规则完全不同上面这套只适用于原生 Windows 终端。第三如果你看到的是EACCES权限报错那多半是 npm 全局目录权限不够这时候用管理员身份打开 PowerShell 执行安装或者干脆把 npm 全局目录改到用户目录下尽量不要直接去改系统目录权限。如果上面改动 PATH 太麻烦还有一个临时方案直接用npx opencode启动。npx 会临时找到 npm 全局目录里的包来执行不过每次都要带npx前缀体验一般只适合应急验证。2.3 安装完先做这三件事装好之后不要急着丢任务给它先花两分钟做三件基础检查。第一确认版本和基本信息opencode --version opencode --help第二配置 API key。opencode 支持很多模型供应商你可以用环境变量的方式设置也可以登录官方服务export ANTHROPIC_API_KEY你的key # 或者 opencode auth login第三跑一个最小对话确认链路通opencode 你好帮我看看当前目录下有哪些文件如果这三个环节都正常说明基础环境已经没问题了后面就可以进入模型配置的正题。3. 模型配置opencode 的灵魂是“模型自由”3.1 配置文件长什么样opencode 的配置文件是一个 JSON 文件路径一般在~/.config/opencode/opencode.jsonLinux 和 macOS 都在这个位置Windows 则是C:\Users\你的用户名\.config\opencode\opencode.json。你用opencode --config也能看到实际加载路径。一个最小可用的配置大概是这样的{ $schema: https://opencode.ai/config.json, model: sonnet, provider: { anthropic: { api_key: env:ANTHROPIC_API_KEY }, openai: { api_key: env:OPENAI_API_KEY } } }model字段控制默认模型provider字段配置各家供应商的 key 和可选的请求地址。没有api_key就用环境变量里的这是最推荐的做法因为 key 不会以明文到处散落。注意具体字段名和可用取值会随版本迭代变化写完配置后用opencode doctor或者对着配置文件的 schema 提示检查一遍最稳妥。这里我特别想说一下“配置即代码”的体验。我见过很多人用图形界面的工具点来点去把模型设置好了过一个月换电脑早就忘了当初选了哪个模型。opencode 的 JSON 配置打开就能看懂还能复制给同事这种确定性在团队里非常难得。3.2 不同场景怎么选模型opencode 支持多家模型但这把“自由”其实也是把双刃剑选项太多反而不知道用哪个。我按实际场景给你一套比较稳的选型思路。场景推荐模型类型理由日常开发主力各家旗舰模型如 Sonnet 级别代码生成质量高多步推理能力强快速问答 / 小脚本轻量模型如 Flash / Haiku 级别便宜且响应快体感不拖沓本地离线本地运行的 Coder 类模型数据不出机器适合敏感项目前端 bug 复现主力模型 Playwright 工具agent 需要操作浏览器的能力我的默认配置是日常用“sonnet”级别的模型跑主任务一旦任务较小比如“给这个函数补个注释”我会在对话里临时指定轻量模型省钱也省时间。opencode 支持在对话中直接切换模型这点比很多 IDE 插件都灵活。如果你买了 opencode go 这类官方订阅服务选择套餐里的模型时我的建议是不要只盯着最强的那个。套餐通常包含多个档位的模型关键是看“主力生成模型 轻量模型”的组合是否覆盖你的使用场景。只选最贵的用得少等于浪费只选最便宜的复杂点的需求又跑不动。3.3 配合 ccswitch 统一管理网关地址热词里有一条是“opencode go 需要配合 cc switch 等工具”这里展开说一下。opencode go 这类托管订阅的本质是你付一份订阅费获得统一的多模型调用额度服务商会给你一个请求入口和密钥。在配置层面你把入口地址和密钥填进 provider 即可和自建网关没有本质区别。ccswitch 这类工具解决的是“太多 key 和入口不好管理”的问题。它本质上是一个本地配置管理工具把各家服务商的地址、密钥集中存起来需要时一键切换省得每次改 JSON 文件。配合 opencode 使用时你在 ccswitch 里选好目标服务商把生成的入口地址和 key 复制到 opencode.json 里就行了。提示ccswitch 这类工具只是帮你管理 API 配置不改变 opencode 本身的工作方式。用它之前先确认手里的订阅套餐支持哪些模型、入口地址是否稳定别把希望全放在一个随时可能调整的服务上。3.4 遇到 “this model is not available in your country” 怎么办这个报错严格来说不是 opencode 的问题而是模型服务商根据你的访问来源区域做了限制。处理思路有三个维度。第一换模型。如果你在配置里填的是某个冷门模型或者特定区域的变体可以先用opencode models查看当前可用列表换成服务商明确支持你所在区域的模型。第二换服务商。不同服务商的支持范围不一样很多模型在官方渠道和第三方渠道的可达性也不同你可以选择支持你所在地区的官方 API 服务。第三检查是否用了不常见渠道。如果你是从非官方渠道“共享”来的入口服务端随时可能变更限制这不仅仅是地区报错的问题还可能涉及数据安全不建议作为生产依赖。这里我要特别强调一句遇到地区限制时不要去找不明不白的第三方通道。一是稳定性没有保障今天能用明天就断二是你的代码和对话会经过别人的服务风险不可控。正确的做法是选择在你所在区域合法可用的服务商或者切换到不受影响的模型。4. 把 opencode 用成生产力工具插件、Skills、LSP 与浏览器自动化4.1 VS Code 和 JetBrains 插件安装注意opencode 虽然核心是终端工具但很多人希望能在 IDE 里直接用所以官方和社区都有对应的插件。VS Code 扩展和 JetBrains IDEA 插件我都试过本质上是把终端里的 opencode 面板嵌进 IDE你依然要先把命令行版的 opencode 装好。插件安装有两个容易踩的坑。第一IDE 里的 PATH 和终端不一定一致。尤其是 macOS 上通过 Finder 启动的 IDE不会加载 shell 配置导致插件找不到 opencode 命令。解决办法是在插件设置里显式指定 opencode 可执行文件的完整路径。第二用 WSL 开发时IDE 跑在 Windowsopencode 装在 WSL 里两边互相看不见。这种情况下最简单的方式是在 WSL 的终端里直接用 opencode而不是强行用 IDE 插件。插件的好处是能一边看代码一边和 agent 对话上下文更直观缺点是 IDE 的资源占用本来就高再跑 agent 对老机器有压力。所以我个人是轻量任务用终端重活才开 IDE 插件。4.2 Skills让 opencode 学会你的团队规范Skills 是 opencode 里我非常喜欢的一个功能它和 Claude 系的 Agent Skills 格式类似本质上是给 agent 提供一份“操作手册”告诉它在特定任务下应该按什么流程走。一个 skill 就是一个目录加一个SKILL.md文件。比如我想让 opencode 按照团队规范做代码评审可以这样组织.opencode/skills/code-review/SKILL.mdSKILL.md 内容可以写# Code Review 当用户要求“review 代码”或“看看这个 PR”时执行以下步骤 1. 先读取当前分支相对主分支的变更文件列表。 2. 逐个文件检查命名是否清晰、错误处理是否完整、是否存在明显的性能问题。 3. 按“严重问题 / 建议 / 风格”三类输出评审结论。 4. 不修改代码只输出带文件路径和行号的评审意见。定义好之后在对话里让 opencode 执行 code review它就会按这个流程走不会再漫无目的地乱看。团队可以把这套 skills 目录提交到仓库大家共用一套规范agent 的输出质量会明显更稳定。社区里已经有类似 oh-my-claudecode 的配置管理器开始支持 opencode专门帮人统一管理 skills、模型和快捷键如果你不想手动建目录可以去看看这类工具是否适配你的版本。4.3 LSP让 agent 有“看得懂项目”的能力LSPLanguage Server Protocol是很多编辑器都在用的协议本质上是让工具通过语言服务器获取代码的语义信息比如跳转定义、查找引用、报错诊断。opencode 也支持接入 LSP这样 agent 在改代码时能像 IDE 一样感知项目结构而不是只看字符串。以 TypeScript 项目为例如果你在配置里启用了对应的 LSP{ lsp: { typescript: { command: [typescript-language-server, --stdio] } } }然后让 opencode 修改一个函数它就能先通过 LSP 找到这个函数的引用位置评估改动的影响范围再动手改。这一点在重构场景里特别关键没有 LSP 的 agent 常常改一处漏一处有了语义感知之后它的“判断力”会上一个台阶。注意LSP 服务要提前装好对应的语言服务器比如 TypeScript 的typescript-language-server、Python 的pyright-langserver。opencode 只是扮演客户端角色语言服务器本身得靠你在项目环境里装好。4.4 用 Playwright 让 opencode 自己复现前端 bug这是我觉得 opencode 最惊艳的使用场景之一。以前测前端 bug要么手动点开页面一步步复现要么写一堆测试脚本现在可以直接把 bug 描述丢给 opencode让它用 Playwright 打开浏览器去复现。举个例子。产品反馈说“下单页面的提交按钮点了没反应”传统排查要自己打开浏览器、打开控制台、点一下按钮看报错。用 opencode 的话我会这样下指令Use the browser tool to open http://localhost:3000/checkout, click the submit button, and check for any console errors or network failures. Then suggest a fix.opencode 会调用 Playwright 的工具打开页面、执行点击、查看控制台日志和网络请求再把结果汇报给你。如果页面有报错它甚至可以直接定位到对应的前端代码。我实测下来的感受是这种“让 agent 自己复现”的方式特别适合那种“偶尔出现”的前端问题因为它能自动化地反复操作把不确定性变成可重复的复现步骤。需要注意的一点是Playwright 工具当前是否可用、支持哪些动作取决于你安装的 opencode 版本和项目里是否预装了 Playwright。首次使用前先确认playwright命令在项目里能跑通。4.5 接手一个陌生项目时怎么用 opencode 提效很多人接手遗留项目的第一反应是“头大”。代码多、文档少、历史包袱重。opencode 在这种场景下适合当一个“快速上手指南”。我会先让它做三件事读 README 和启动文档梳理项目结构和模块依赖列出所有 TODO、FIXME 和明显报错。这样不用自己一行行翻代码就能对项目建立起初步地图。然后再让它帮我找某个功能的实现位置。比如Find where the order status is updated after payment callback, and explain the flow.agent 会沿着关键字段和调用链去搜索给出的解释通常比纯 grep 更接近“业务理解”。接手项目的第二天我往往已经能回答很多历史问题效率比纯手动翻代码高不少。当然agent 的理解不一定 100% 正确关键结论还是要自己核对但“从零开始”到“有点眉目”的过程被明显缩短了。5. 常年会踩的坑报错与修复速查5.1 error: unexpected server error. check server logs这个报错在热词里出现得很多而且通常是在 Windows 终端里敲opencode后直接弹出来。看到这个错误时我的第一反应不是怀疑 opencode 本身而是怀疑它连不上下游的模型服务。排查顺序一般是这样的。先看是否设置了 API key环境变量名和配置里的 provider 是否对得上。再看你填的请求地址是否正确如果你配了自建网关或订阅服务baseURL少了一个斜杠、多了个空格都可能出问题。最后看服务商本身是否稳定有些免费模型服务高峰期经常返回 5xx换个时段再试就行。调试时可以用一个更详细的方式启动opencode --log-level debug日志会打印请求细节能直接看出是鉴权失败、地址不通还是模型不存在。这里我特别提醒一下官方服务出问题的概率很低大部分“unexpected server error”都出在自定义配置或者免费模型服务上。5.2 免费的 hy3-free 类模型下线了怎么办社区里经常有人分享一些免费模型名字后面往往带个-free或者日期标记。这类模型本质上是一些免费频道提供的实验性资源最大的问题就是生命周期不可控可能你今天还在用明天就收到“模型不存在”的报错。热词里的 hy3-free 就是这个情况。如果你遇到类似问题处理思路很清楚先看配置里 model 字段是否还指向那个已下线的模型换个还在维护的模型如果是为了省钱才用免费模型我建议把免费模型用于低价值任务核心开发流程还是配一个稳定的商用 API。我的经验是不要把“能跑通”当成“应该用”。免费模型偶尔用来跑个小测试没问题但你在它上面沉淀的 prompt 和流程一旦模型下线就得全部重调这个隐性成本其实很高。5.3 版本升级与配置兼容opencode 2.0 这类迭代中要注意什么opencode 迭代速度很快社区里已经有关于 2.0 的讨论还有 desktop 方向的消息。版本升级最容易出现的问题是旧配置失效比如某个 provider 字段被改名、默认模型取值变了、命令参数不兼容。我的建议是升级前先备份配置文件然后看官方 changelog。不要一看到新版本就立刻升尤其是你手头正跑着重要项目时等一两天看看社区反馈再升也不迟。升级后先用opencode --version和最小对话确认链路正常再用到真实项目上。另外如果你在用第三方配置管理工具管理 skills升级后也要确认工具的兼容性否则可能出现“命令还在skill 加载不出来”的情况。5.4 报错速查表报错现象可能原因解决方向无法将 opencode 识别为 cmdletnpm 全局目录不在 PATH把 npm prefix 目录加入用户 PATH重开终端unexpected server errorAPI key 错误、地址不通、服务端故障检查 key 和 baseURL开 debug 日志this model is not available in your country模型服务商做了区域限制换模型或换支持你所在区域的服务商model not found / unknown model配置里写错了模型名或模型已下线用opencode models查看可用列表插件找不到 opencode 命令IDE 的 PATH 不包含 CLI 目录在插件设置里指定 opencode 的绝对路径Playwright 工具无响应项目里没装 Playwright或版本不匹配先确保playwright命令可运行这张表是我在社区群里帮人排查时积累下来的基本覆盖了常见问题的第一现场。遇到新问题建议先打开 debug 日志看原始信息再往模型、网络、配置三个方向去拆大多数问题都逃不出这三类。6. 个人工作流建议说实话工具再强也只是工具真正有价值的是你对项目的理解。opencode 让我省掉了大量“找文件、读代码、跑测试”的机械劳动但我每次让它动手前还是会先把需求和边界说清楚。说得越具体它交付的结果越接近我想要的这比换一个更贵的模型有用得多。最后再分享一个小技巧把高频动作沉淀成 Skill。我现在的配置里固定有三个自定义 skill分别是代码评审、补单测、迁移脚本生成每次遇到对应场景直接一句话触发出来的结果比“自由发挥”稳定太多。建议你也从自己的重复劳动里找出两三个最痛的点先固化成一个 skill你会发现 opencode 越用越顺手。希望这份实战笔记能帮你把它真正跑起来少走我当初踩过的弯路。 opencode：终端里的多模型AI编程代理实战指南
最近好几个读者都在问 opencode说在 GitHub 趋势上看到它又被各种帖子刷屏。其实我前几个月就已经在终端里用它跑真实项目了从修一个简单 bug 到接手新需求基本每天都在用。opencode 不是一个聊天窗口而是一个跑在终端里的 AI 编程代理agent你给它一个任务它能自己读代码、改代码、执行命令、跑测试甚至打开浏览器帮你复现前端问题。和 Claude Code、Codex、Pi 这类工具是同一赛道但 opencode 最大的特点是模型自由OpenAI、Anthropic、Google、本地模型、各种网关都能接而且配置是纯文件的好审计、好迁移。这篇文章我打算从安装踩坑讲起把配置、插件、Skills、LSP、Playwright 测试这些高频场景都过一遍最后列一份我长期积攒的报错排查清单。适合谁看如果你已经在用 Cursor 但想试试终端 agent或者被 Claude Code 的账号门槛卡住又或者手里有一堆 API key 想统一管理opencode 都值得一试。内容会写得比较细你完全可以照着一步步操作。1. opencode 是什么把“改代码”变成“安排任务”的终端 agent1.1 和 Claude Code / Codex / Pi 的定位差异很多人第一次看到 opencode 会问这不就是又一个 Claude Code 吗事实上这类工具解决的是同一个问题——让 AI 不再只是“问答窗口”而是能真正接管一部分开发流程。但它们在模型绑定、开放程度和交互方式上有明显区别。我用过一段时间之后对这四类工具的定位做过一个粗颗粒度的对比工具模型绑定主要交互适合场景opencode开源多模型聚合终端 TUI 文件配置想自由切换模型、追求可定制、需要把流程沉淀成 SkillsClaude Code深度绑定 Anthropic终端对话Claude 重度和忠实用户Codex深度绑定 OpenAI终端 / IDE 内OpenAI 重度用户Pi轻量 agent 工具终端更轻的单次任务场景opencode 对我来说最大的价值是“不锁死”。我今天的项目可能用 Sonnet 类模型写复杂逻辑明天跑一个小脚本就用便宜快速的轻量模型opencode 只要改配置就能切换不需要重新适应一套交互。这点在真实开发里太重要了因为模型的强弱并不总是决定产出质量成本和响应速度同样影响体验。1.2 本地优先你的配置和会话都是可读文件opencode 的另一个设计思路是“本地优先”。配置文件默认放在~/.config/opencode/opencode.json会话记录、日志都存在本地目录里而不是全部锁在某个云平台上。这意味着三件很实际的事第一配置可以放进版本管理。我通常会把.opencode/下的团队配置提交到仓库里新同事克隆下来就能用同一套模型和规则省去口头同步。第二行为可审计。agent 到底改了哪些文件、执行了什么命令翻开日志一目了然。对于团队协作这比一个“黑盒聊天窗口”靠谱得多。第三迁移成本低。换电脑只要同步配置文件和 key不需要重新“训练”一个工具。如果你之前只用过 IDE 内置的 AI 编程插件第一次用 opencode 可能会不太习惯因为它没有漂亮的图形界面只有终端里的 TUI。但适应之后你会发现终端里的 agent 反而更专注它能直接操作 shell天然适合跑测试、查日志、批量改文件这些“脏活”。2. 安装 opencode从一行命令到 Windows 报错自救2.1 三种安装方式和我的选择opencode 的安装方式主要有三种你按自己环境挑一个就行。npm 方式也是我用得最多的npm install -g opencode-aicurl 脚本方式适合不想依赖 Node 环境的机器curl -fsSL https://opencode.ai/install | bashGo 方式适合本来就有 Go 工具链的人go install github.com/sst/opencodelatest提示curl 脚本和 go install 本质都是拉一个可执行文件到本地npm 方式因为有全局 node_modules 的概念在 Windows 上最容易出现 PATH 问题所以我下面的排错重点说 npm。我自己的习惯是Windows 上用 npmLinux 服务器上用 curl 脚本macOS 上也是 curl 为主。原因很简单npm 版本更新方便一条npm update -g opencode-ai就完事而服务器上我通常不愿意为一个小工具装完整 Node 环境。2.2 Windows 上“cmdlet 无法识别 opencode”的根因和解决搜索热词里出现频率最高的问题是这句报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。用大白话解释这个报错不是说 opencode 没装上而是说你装好的可执行文件放在了一个 Windows 当前不会去找的目录里。npm 全局安装时会把可执行文件放到 npm 的全局 bin 目录通常是C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在 PATH 环境变量里你在任意路径下敲opencodePowerShell 自然找不到。解决步骤很简单先看 npm 全局目录在哪打开 PowerShell 执行npm prefix -g把输出目录加入用户 PATH。假设输出是C:\Users\你的用户名\AppData\Roaming\npm执行[Environment]::SetEnvironmentVariable(Path, [Environment]::GetEnvironmentVariable(Path, User) ;C:\Users\你的用户名\AppData\Roaming\npm, User)关掉当前终端重开一个新的 PowerShell再执行opencode --version如果能看到版本号说明安装成功。这里我再补几个容易忽略的细节。第一改完 PATH 之后一定要重开终端不是刷新一下就行的PowerShell 的环境变量是在启动时加载的。第二如果你用的是 Windows 下的 WSL那 PATH 规则完全不同上面这套只适用于原生 Windows 终端。第三如果你看到的是EACCES权限报错那多半是 npm 全局目录权限不够这时候用管理员身份打开 PowerShell 执行安装或者干脆把 npm 全局目录改到用户目录下尽量不要直接去改系统目录权限。如果上面改动 PATH 太麻烦还有一个临时方案直接用npx opencode启动。npx 会临时找到 npm 全局目录里的包来执行不过每次都要带npx前缀体验一般只适合应急验证。2.3 安装完先做这三件事装好之后不要急着丢任务给它先花两分钟做三件基础检查。第一确认版本和基本信息opencode --version opencode --help第二配置 API key。opencode 支持很多模型供应商你可以用环境变量的方式设置也可以登录官方服务export ANTHROPIC_API_KEY你的key # 或者 opencode auth login第三跑一个最小对话确认链路通opencode 你好帮我看看当前目录下有哪些文件如果这三个环节都正常说明基础环境已经没问题了后面就可以进入模型配置的正题。3. 模型配置opencode 的灵魂是“模型自由”3.1 配置文件长什么样opencode 的配置文件是一个 JSON 文件路径一般在~/.config/opencode/opencode.jsonLinux 和 macOS 都在这个位置Windows 则是C:\Users\你的用户名\.config\opencode\opencode.json。你用opencode --config也能看到实际加载路径。一个最小可用的配置大概是这样的{ $schema: https://opencode.ai/config.json, model: sonnet, provider: { anthropic: { api_key: env:ANTHROPIC_API_KEY }, openai: { api_key: env:OPENAI_API_KEY } } }model字段控制默认模型provider字段配置各家供应商的 key 和可选的请求地址。没有api_key就用环境变量里的这是最推荐的做法因为 key 不会以明文到处散落。注意具体字段名和可用取值会随版本迭代变化写完配置后用opencode doctor或者对着配置文件的 schema 提示检查一遍最稳妥。这里我特别想说一下“配置即代码”的体验。我见过很多人用图形界面的工具点来点去把模型设置好了过一个月换电脑早就忘了当初选了哪个模型。opencode 的 JSON 配置打开就能看懂还能复制给同事这种确定性在团队里非常难得。3.2 不同场景怎么选模型opencode 支持多家模型但这把“自由”其实也是把双刃剑选项太多反而不知道用哪个。我按实际场景给你一套比较稳的选型思路。场景推荐模型类型理由日常开发主力各家旗舰模型如 Sonnet 级别代码生成质量高多步推理能力强快速问答 / 小脚本轻量模型如 Flash / Haiku 级别便宜且响应快体感不拖沓本地离线本地运行的 Coder 类模型数据不出机器适合敏感项目前端 bug 复现主力模型 Playwright 工具agent 需要操作浏览器的能力我的默认配置是日常用“sonnet”级别的模型跑主任务一旦任务较小比如“给这个函数补个注释”我会在对话里临时指定轻量模型省钱也省时间。opencode 支持在对话中直接切换模型这点比很多 IDE 插件都灵活。如果你买了 opencode go 这类官方订阅服务选择套餐里的模型时我的建议是不要只盯着最强的那个。套餐通常包含多个档位的模型关键是看“主力生成模型 轻量模型”的组合是否覆盖你的使用场景。只选最贵的用得少等于浪费只选最便宜的复杂点的需求又跑不动。3.3 配合 ccswitch 统一管理网关地址热词里有一条是“opencode go 需要配合 cc switch 等工具”这里展开说一下。opencode go 这类托管订阅的本质是你付一份订阅费获得统一的多模型调用额度服务商会给你一个请求入口和密钥。在配置层面你把入口地址和密钥填进 provider 即可和自建网关没有本质区别。ccswitch 这类工具解决的是“太多 key 和入口不好管理”的问题。它本质上是一个本地配置管理工具把各家服务商的地址、密钥集中存起来需要时一键切换省得每次改 JSON 文件。配合 opencode 使用时你在 ccswitch 里选好目标服务商把生成的入口地址和 key 复制到 opencode.json 里就行了。提示ccswitch 这类工具只是帮你管理 API 配置不改变 opencode 本身的工作方式。用它之前先确认手里的订阅套餐支持哪些模型、入口地址是否稳定别把希望全放在一个随时可能调整的服务上。3.4 遇到 “this model is not available in your country” 怎么办这个报错严格来说不是 opencode 的问题而是模型服务商根据你的访问来源区域做了限制。处理思路有三个维度。第一换模型。如果你在配置里填的是某个冷门模型或者特定区域的变体可以先用opencode models查看当前可用列表换成服务商明确支持你所在区域的模型。第二换服务商。不同服务商的支持范围不一样很多模型在官方渠道和第三方渠道的可达性也不同你可以选择支持你所在地区的官方 API 服务。第三检查是否用了不常见渠道。如果你是从非官方渠道“共享”来的入口服务端随时可能变更限制这不仅仅是地区报错的问题还可能涉及数据安全不建议作为生产依赖。这里我要特别强调一句遇到地区限制时不要去找不明不白的第三方通道。一是稳定性没有保障今天能用明天就断二是你的代码和对话会经过别人的服务风险不可控。正确的做法是选择在你所在区域合法可用的服务商或者切换到不受影响的模型。4. 把 opencode 用成生产力工具插件、Skills、LSP 与浏览器自动化4.1 VS Code 和 JetBrains 插件安装注意opencode 虽然核心是终端工具但很多人希望能在 IDE 里直接用所以官方和社区都有对应的插件。VS Code 扩展和 JetBrains IDEA 插件我都试过本质上是把终端里的 opencode 面板嵌进 IDE你依然要先把命令行版的 opencode 装好。插件安装有两个容易踩的坑。第一IDE 里的 PATH 和终端不一定一致。尤其是 macOS 上通过 Finder 启动的 IDE不会加载 shell 配置导致插件找不到 opencode 命令。解决办法是在插件设置里显式指定 opencode 可执行文件的完整路径。第二用 WSL 开发时IDE 跑在 Windowsopencode 装在 WSL 里两边互相看不见。这种情况下最简单的方式是在 WSL 的终端里直接用 opencode而不是强行用 IDE 插件。插件的好处是能一边看代码一边和 agent 对话上下文更直观缺点是 IDE 的资源占用本来就高再跑 agent 对老机器有压力。所以我个人是轻量任务用终端重活才开 IDE 插件。4.2 Skills让 opencode 学会你的团队规范Skills 是 opencode 里我非常喜欢的一个功能它和 Claude 系的 Agent Skills 格式类似本质上是给 agent 提供一份“操作手册”告诉它在特定任务下应该按什么流程走。一个 skill 就是一个目录加一个SKILL.md文件。比如我想让 opencode 按照团队规范做代码评审可以这样组织.opencode/skills/code-review/SKILL.mdSKILL.md 内容可以写# Code Review 当用户要求“review 代码”或“看看这个 PR”时执行以下步骤 1. 先读取当前分支相对主分支的变更文件列表。 2. 逐个文件检查命名是否清晰、错误处理是否完整、是否存在明显的性能问题。 3. 按“严重问题 / 建议 / 风格”三类输出评审结论。 4. 不修改代码只输出带文件路径和行号的评审意见。定义好之后在对话里让 opencode 执行 code review它就会按这个流程走不会再漫无目的地乱看。团队可以把这套 skills 目录提交到仓库大家共用一套规范agent 的输出质量会明显更稳定。社区里已经有类似 oh-my-claudecode 的配置管理器开始支持 opencode专门帮人统一管理 skills、模型和快捷键如果你不想手动建目录可以去看看这类工具是否适配你的版本。4.3 LSP让 agent 有“看得懂项目”的能力LSPLanguage Server Protocol是很多编辑器都在用的协议本质上是让工具通过语言服务器获取代码的语义信息比如跳转定义、查找引用、报错诊断。opencode 也支持接入 LSP这样 agent 在改代码时能像 IDE 一样感知项目结构而不是只看字符串。以 TypeScript 项目为例如果你在配置里启用了对应的 LSP{ lsp: { typescript: { command: [typescript-language-server, --stdio] } } }然后让 opencode 修改一个函数它就能先通过 LSP 找到这个函数的引用位置评估改动的影响范围再动手改。这一点在重构场景里特别关键没有 LSP 的 agent 常常改一处漏一处有了语义感知之后它的“判断力”会上一个台阶。注意LSP 服务要提前装好对应的语言服务器比如 TypeScript 的typescript-language-server、Python 的pyright-langserver。opencode 只是扮演客户端角色语言服务器本身得靠你在项目环境里装好。4.4 用 Playwright 让 opencode 自己复现前端 bug这是我觉得 opencode 最惊艳的使用场景之一。以前测前端 bug要么手动点开页面一步步复现要么写一堆测试脚本现在可以直接把 bug 描述丢给 opencode让它用 Playwright 打开浏览器去复现。举个例子。产品反馈说“下单页面的提交按钮点了没反应”传统排查要自己打开浏览器、打开控制台、点一下按钮看报错。用 opencode 的话我会这样下指令Use the browser tool to open http://localhost:3000/checkout, click the submit button, and check for any console errors or network failures. Then suggest a fix.opencode 会调用 Playwright 的工具打开页面、执行点击、查看控制台日志和网络请求再把结果汇报给你。如果页面有报错它甚至可以直接定位到对应的前端代码。我实测下来的感受是这种“让 agent 自己复现”的方式特别适合那种“偶尔出现”的前端问题因为它能自动化地反复操作把不确定性变成可重复的复现步骤。需要注意的一点是Playwright 工具当前是否可用、支持哪些动作取决于你安装的 opencode 版本和项目里是否预装了 Playwright。首次使用前先确认playwright命令在项目里能跑通。4.5 接手一个陌生项目时怎么用 opencode 提效很多人接手遗留项目的第一反应是“头大”。代码多、文档少、历史包袱重。opencode 在这种场景下适合当一个“快速上手指南”。我会先让它做三件事读 README 和启动文档梳理项目结构和模块依赖列出所有 TODO、FIXME 和明显报错。这样不用自己一行行翻代码就能对项目建立起初步地图。然后再让它帮我找某个功能的实现位置。比如Find where the order status is updated after payment callback, and explain the flow.agent 会沿着关键字段和调用链去搜索给出的解释通常比纯 grep 更接近“业务理解”。接手项目的第二天我往往已经能回答很多历史问题效率比纯手动翻代码高不少。当然agent 的理解不一定 100% 正确关键结论还是要自己核对但“从零开始”到“有点眉目”的过程被明显缩短了。5. 常年会踩的坑报错与修复速查5.1 error: unexpected server error. check server logs这个报错在热词里出现得很多而且通常是在 Windows 终端里敲opencode后直接弹出来。看到这个错误时我的第一反应不是怀疑 opencode 本身而是怀疑它连不上下游的模型服务。排查顺序一般是这样的。先看是否设置了 API key环境变量名和配置里的 provider 是否对得上。再看你填的请求地址是否正确如果你配了自建网关或订阅服务baseURL少了一个斜杠、多了个空格都可能出问题。最后看服务商本身是否稳定有些免费模型服务高峰期经常返回 5xx换个时段再试就行。调试时可以用一个更详细的方式启动opencode --log-level debug日志会打印请求细节能直接看出是鉴权失败、地址不通还是模型不存在。这里我特别提醒一下官方服务出问题的概率很低大部分“unexpected server error”都出在自定义配置或者免费模型服务上。5.2 免费的 hy3-free 类模型下线了怎么办社区里经常有人分享一些免费模型名字后面往往带个-free或者日期标记。这类模型本质上是一些免费频道提供的实验性资源最大的问题就是生命周期不可控可能你今天还在用明天就收到“模型不存在”的报错。热词里的 hy3-free 就是这个情况。如果你遇到类似问题处理思路很清楚先看配置里 model 字段是否还指向那个已下线的模型换个还在维护的模型如果是为了省钱才用免费模型我建议把免费模型用于低价值任务核心开发流程还是配一个稳定的商用 API。我的经验是不要把“能跑通”当成“应该用”。免费模型偶尔用来跑个小测试没问题但你在它上面沉淀的 prompt 和流程一旦模型下线就得全部重调这个隐性成本其实很高。5.3 版本升级与配置兼容opencode 2.0 这类迭代中要注意什么opencode 迭代速度很快社区里已经有关于 2.0 的讨论还有 desktop 方向的消息。版本升级最容易出现的问题是旧配置失效比如某个 provider 字段被改名、默认模型取值变了、命令参数不兼容。我的建议是升级前先备份配置文件然后看官方 changelog。不要一看到新版本就立刻升尤其是你手头正跑着重要项目时等一两天看看社区反馈再升也不迟。升级后先用opencode --version和最小对话确认链路正常再用到真实项目上。另外如果你在用第三方配置管理工具管理 skills升级后也要确认工具的兼容性否则可能出现“命令还在skill 加载不出来”的情况。5.4 报错速查表报错现象可能原因解决方向无法将 opencode 识别为 cmdletnpm 全局目录不在 PATH把 npm prefix 目录加入用户 PATH重开终端unexpected server errorAPI key 错误、地址不通、服务端故障检查 key 和 baseURL开 debug 日志this model is not available in your country模型服务商做了区域限制换模型或换支持你所在区域的服务商model not found / unknown model配置里写错了模型名或模型已下线用opencode models查看可用列表插件找不到 opencode 命令IDE 的 PATH 不包含 CLI 目录在插件设置里指定 opencode 的绝对路径Playwright 工具无响应项目里没装 Playwright或版本不匹配先确保playwright命令可运行这张表是我在社区群里帮人排查时积累下来的基本覆盖了常见问题的第一现场。遇到新问题建议先打开 debug 日志看原始信息再往模型、网络、配置三个方向去拆大多数问题都逃不出这三类。6. 个人工作流建议说实话工具再强也只是工具真正有价值的是你对项目的理解。opencode 让我省掉了大量“找文件、读代码、跑测试”的机械劳动但我每次让它动手前还是会先把需求和边界说清楚。说得越具体它交付的结果越接近我想要的这比换一个更贵的模型有用得多。最后再分享一个小技巧把高频动作沉淀成 Skill。我现在的配置里固定有三个自定义 skill分别是代码评审、补单测、迁移脚本生成每次遇到对应场景直接一句话触发出来的结果比“自由发挥”稳定太多。建议你也从自己的重复劳动里找出两三个最痛的点先固化成一个 skill你会发现 opencode 越用越顺手。希望这份实战笔记能帮你把它真正跑起来少走我当初踩过的弯路。