如果你最近在逛技术社区，大概率刷到过 opencode 这个名字。它是一款开源的终端 AI 编码代理，简单说就是让你在命令行里像和同事聊天一样，把“写代码、改 bug、跑测试”这些活交给 AI 去执行。和 Claude Code 这类绑定单一模型的工具不同，opencode 最大的卖点是模型自由——你可以把 Anthropic、OpenAI、Google、本地 Ollama，甚至各种兼容 OpenAI 协议的网关都接进来，想用哪个用哪个。
这篇文章不是官方文档的翻译，而是我从下载安装开始，到配置模型、折腾 Skills、接 LSP、用 Playwright 调前端，再到被各种报错教育之后整理的实战笔记。不管你是刚听说 opencode 想试试的新手，还是已经装好但卡在配置上的老用户，顺着文章走一遍基本都能解决。
1. opencode 到底是什么：从定位到工作原理
1.1 一个不绑死模型的开源编码代理
先说一个背景。Claude Code 把“终端里跑 AI 编码代理”这个形态带火之后，很多人确实觉得好用，但也被两件事卡住：一是模型只能选 Claude，二是工具本身闭源，出了问题只能等官方修。opencode 的出现正好补上了这两个缺口。它由 SST 团队维护，代码完全开源，核心思路是把“对话式编码体验”重新做一遍，但把模型层做成可插拔的。
这也解释了为什么搜索框里会同时出现“opencode codex claude code”和“opencode codex pi 哪个 agent 好用”这种对比。我个人的观点是，工具本身已经进入同质化阶段，决定体验的反而是你接什么模型、怎么配置上下文、以及团队的工程习惯。opencode 的价值在于，它把选择权还给了用户，而不是替你做决定。
1.2 客户端 / 服务端架构和 TUI 界面
opencode 在架构上有一个比较鲜明的特点：客户端和服务端是分离的。你在终端里看到的那个界面是 TUI 客户端，但它背后跑着一个本地服务，负责跟模型 API 通信、维护会话、管理工具调用。这个设计带来的直接好处是，官方可以在这个服务端之上继续做桌面版、VSCode 插件、JetBrains 插件，而不是给每个客户端各写一套逻辑。
日常用的时候，你只需要记住两种模式：Agent 模式和 Plan 模式。Agent 模式会真正动手改文件、执行命令，适合你确定任务方向、让它全权干活；Plan 模式只读代码、分析方案，会给你一份改动计划，适合做需求评审或者面对不熟悉的代码库。用 Tab 键可以快速切换，这算是我用的最多的快捷键之一。
2. 安装与首次配置：把 opencode 跑起来
2.1 不同系统的安装方式
opencode 的安装方式很常规，官方提供了 npm、Homebrew 和 curl 脚本三种途径。我建议优先用 npm 全局安装，因为后续升级最方便：
npm install -g opencode-aimacOS 用户也可以用 Homebrew：brew install sst/tap/opencode。Linux 和无包管理器环境可以用官方脚本curl -fsSL https://opencode.ai/install | bash，脚本会把二进制放到~/.opencode/bin下，同时提示你把它加入 PATH。Windows 上除了 npm 方式之外，也可以直接用 winget 搜一下，有些版本是带独立安装包的。无论哪种方式，装完先执行opencode --version，能输出版本号就说明这一步过了。
如果你打算长期用，我建议把 opencode 的配置目录固定下来。它在 Linux 和 macOS 上是~/.config/opencode/，Windows 上大致在用户目录的 AppData 相关路径下。后面要配模型、写 Skills、调 LSP，基本都是往这个目录里放东西，提前知道位置能少走很多弯路。
2.2 模型接入：opencode.json 配置详解
安装只是第一步，真正决定你体验的是模型接入。opencode 默认能从环境变量里读取 Anthropic、OpenAI 等厂商的 API Key：比如ANTHROPIC_API_KEY、OPENAI_API_KEY。如果你用的是官方 API，什么都不配，export 一下环境变量再启动opencode就能跑。
但只要你开始用第三方网关、团队内部的模型代理，或者想同时管理多个模型，就应该创建一个opencode.json配置文件。它的探查顺序是项目根目录优先，然后才是用户目录~/.config/opencode/。我一般把全局配置放用户目录，项目特定配置放项目根目录，两边能合并。一个典型的配置文件长这样：
{ "$schema": "https://opencode.ai/config.json", "provider": { "my-gateway": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://gateway.example.com/v1", "apiKey": "sk-your-key" }, "models": { "gpt-4o": { "name": "GPT-4o" }, "claude-sonnet-4": { "name": "Claude Sonnet 4" } } } } }provider 是个很灵活的抽象，每个 provider 可以有不同的模型列表，甚至不同的 access 方式。这里npm字段指定 AI SDK 的 provider 包，@ai-sdk/openai-compatible意味着只要目标服务是 OpenAI 兼容协议就能接。如果你用的是 Anthropic 官方模型，provider 可以省略，直接用官方默认那套。配置完在 opencode 里输入/models就能实时切换模型，不需要重启。
需要注意，provider 的字段在不同版本里可能有细微差别，拿不准的时候看$schema链接对应的 JSON Schema 定义，IDE 里通常会有自动补全和校验。另外，如果你在 Linux 服务器上改配置，记得改完验证一下 JSON 格式，少一个逗号或者多一个花括号，opencode 启动时会直接报配置解析错误，而且错误提示不一定很友好。
2.3 解决 "opencode 无法识别为 cmdlet" 的经典问题
Windows 用户大概率会撞上这条报错：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名。第一次见别慌，这跟 opencode 本身没关系，是 npm 全局包的安装目录没进 PATH。你需要在 PowerShell 里跑一下npm config get prefix，拿到 npm 全局目录，然后把%APPDATA%\npm或者对应的prefix目录加到系统环境变量 Path 里，改完重开一个终端。
注意：改完 PATH 之后一定要重开终端窗口，PowerShell 里执行
$env:Path = ...只会影响当前进程，不会让 opencode 永久生效。
如果加了 PATH 还是不行，多半是 npm 安装时有权限问题，全局目录被写到了奇怪的位置。我建议检查一下你有没有同时装 nvm 或者 fnm 之类的 Node 版本管理器，因为每次切换 Node 版本，全局包目录也会跟着变。要是实在不想折腾 PATH，可以直接找到 opencode 的可执行文件路径，手动调用，比如C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd。
3. 核心玩法拆解：Skills、Memory、LSP 与浏览器调试
3.1 Skills：给 opencode 装“专属技能”
我第一次听说 Skills 这个概念的时候，第一反应是“这不就是插件吗”。用下来发现它比传统插件轻很多：一个 Skill 本质上就是一个带 Frontmatter 的 Markdown 文件，写在~/.config/opencode/skills或项目.opencode/skills目录下。文件里用name和description描述这个技能是干嘛的，正文就是详细的指令或者工作流。
举个实际例子。我给团队写了一个生成 commit message 的 Skill，内容大致是让 opencode 在用户要求“帮我写提交信息”时，先git diff --stat看改动范围，再git diff看具体内容，最后按 Conventional Commits 规范生成三条候选。这样做的价值不是说 AI 不会写 commit message，而是通过 Skill 把操作步骤固化下来，保证每次都按团队的规范来。团队里的新人只要会用 opencode，就不需要背那些规范细节。
另外要提醒一下，Skills 的生效靠的是 LLM 对 description 的语义匹配。所以 description 一定要写清楚触发场景，别写得太抽象，比如“处理 git 提交”就比“帮助开发者更好工作”有效得多。如果模型怎么也不触发某个 Skill，先检查你的 description 是不是太模糊，再看一下文件路径是不是放对了。我见过很多次技能不生效，最后都是因为文件放到了项目目录但没进 git，换台机器加载不到。
社区里也有不少现成的 Skills 集合包，比如 superpowers、oh-my-claudecode 这类项目，把常用的代码审查、重构、测试生成等技能打包好了，照着说明安装到 skills 目录就能用。我建议新手先装一个社区包感受一下，再用自己的高频场景去改造，比自己从零写十几个技能快得多。
3.2 Memory：让 opencode 记住项目上下文
用过一段时间 opencode 的人，最后基本都会碰到同一个烦恼：每次开新会话，它就把上次聊的上下文全忘了，哪怕你只是让它改同一个模块。opencode 用 Memory 机制来解决这个问题。简单说，Memory 是跨会话持久化的信息块，你可以告诉它“这个项目的测试命令是 pnpm test”，之后每个新会话它都会自动带上这条信息。
Memory 的写入方式很直接，在对话里正常提要求，如果这条信息值得长期记住，就直接说“记住：本项目的构建命令是 pnpm build”，opencode 会把它存到记忆库里，后续新会话都会自动带上。你也可以在项目根目录维护一个AGENTS.md或类似的说明文件，在开头写清楚项目结构、命令、约定，效果和 Memory 类似，而且更容易被团队协作共享。我的建议是：把团队的硬性约定写进项目文件，把个人偏好写进 Memory，两者配合使用。
这里有个细节要留意：Memory 不是无限的，太多记忆反而会稀释真正重要的上下文。我基本每周会清理一次，把已经过时的、不再相关的记忆删掉。opencode 提供内存管理命令，你可以在会话里要求它列出当前记忆，然后逐条删。
3.3 LSP 集成：让编码代理真正理解代码
热词里有“如何使用 lsp”，这确实是 opencode 一个值得单独讲的能力。LSP 就是语言服务器协议，IDE 里那些跳转定义、查找引用、实时诊断，都是靠它实现的。opencode 把 LSP 接进来之后，AI 在改代码之前，能先拿到准确的符号信息和错误列表，而不是靠猜。这样改起代码来，准确率高了不少。
opencode 配置文件的lsp段可以声明项目要用到的语言服务器，以常见的 TypeScript 项目为例：
{ "lsp": { "typescript": { "server": "node_modules/.bin/typescript-language-server" } } }配置好之后，opencode 会在分析代码时主动询问 LSP 服务器，比如跳转到一个函数的定义，或者读取某个文件里的诊断错误。我个人感受是，LSP 对大型代码库的提升最明显。项目越大，模型纯靠读取文件拼出来的“代码地图”越不靠谱，而 LSP 给的是编译级别的精确信息。如果你的项目是 Java、Python、Go 之类的，建议把对应的语言服务器也配上，具体包名可以到对应语言社区查一下。
3.4 Playwright 调试前端：让 Agent 自己开浏览器验证
另一个很有冲击力的场景是热词里的“opencode playwright 怎么测试前端 bug”。opencode 内置了浏览器自动化工具，底层是 Playwright。它可以让 AI 自己打开浏览器，访问本地开发服务器，点击按钮、填表单、截图，甚至读取 console 报错，然后用这些信息来定位 bug。很多人第一次看到这个能力时，都会有一种“这活还能这么干”的感觉。
实际操作时，你只需要在对话里描述 bug 现象，比如“首页搜索框输入关键词后无响应，帮我查一下”，opencode 会自己决定启动浏览器、执行操作步骤、抓取页面信息。它会把每一步操作都展示在终端里，你能看到它点了哪里、输入了什么、页面返回了什么。这个过程很适合验证“改了前端代码但不确定是否修好”的情况，让 Agent 自己跑一遍复现路径，比自己手动点快得多。
提示：让 Agent 跑浏览器自动化之前，最好先把本地开发服务器启动好，明确告诉它访问地址，可以省掉它自己猜端口、试错的时间。
不过要注意，浏览器自动化依赖项目的开发环境能正常启动。如果你的前端项目启动需要复杂的 mock 数据或者特殊代理，最好先手动把开发服务器跑起来，再让 opencode 去连。它虽然能执行命令，但一次会话里既要跑服务、又要开浏览器、又要改代码，上下文一长，出错的概率会明显上升。
4. 实战场景：从新项目到接手旧项目
4.1 用 opencode 从零搭建一个小项目
聊完单个功能，我们把它们串起来看一个从零开始的项目流程。假设我现在要搭一个 Express + TypeScript 的 API 服务。我会先建一个空目录，进入目录后启动 opencode，然后给出这样的任务描述：“初始化一个 Node.js + TypeScript + Express 项目，提供 /health 接口，包含测试和 README。”接下来 opencode 会自动执行npm init、安装依赖、创建目录结构、写代码。
这个过程中你不需要每一步都盯着，但要保留最后的 review 权利。我的习惯是让它每完成一个大步骤就停一下，比如装完依赖、写完骨架、写完测试，分别停下来让我看一眼。这可以通过对话约定来实现，比如第一句话里加上“每完成一个阶段就停下来等我确认”。真要让它一口气从头干到尾也不是不行，只是后面 review 的成本会高很多，尤其项目规模一大，你根本不知道它改了哪些文件。
4.2 接手陌生代码库的正确姿势
热词里有“opencode 接手开发项目”，这个场景我觉得是 opencode 目前最有实用价值的地方。面对一个完全不熟悉的大型代码库，第一步不是急着改代码，而是先让 opencode 做代码勘察。开一个 Plan 模式的新会话，让它先读 README、看目录结构、梳理核心模块和调用链，然后输出一份项目地图。
等它把项目脉络讲清楚了，再切换成 Agent 模式去处理具体任务。这里我有一个强烈建议：接手项目时不要在同一次会话里又分析又动手。Plan 阶段产生的探索性上下文对后续修改帮助有限，反而容易让模型混淆“哪些是分析结论、哪些是实际改动”。分两个会话做，一个负责搞懂项目，一个负责改代码，实测下来效果稳定很多。另外，接手项目后第一时间把项目特有的命令和约定写成AGENTS.md，比如启动命令、测试命令、代码风格、目录约定。这个文件听起来简单，但对后续所有会话的帮助是最大的，我甚至认为一个项目只要有完善的AGENTS.md，opencode 的初始理解能力就能直接上一个台阶。
4.3 与编辑器深度联动：VSCode / JetBrains 插件与桌面版
很多人用 opencode 用久了，会希望别老在终端和编辑器之间来回切。好在官方和社区在这方面做了不少东西。VSCode 插件和 JetBrains IDEA 插件现在都能在编辑器里内嵌 opencode 面板，你可以一边看代码一边跟 AI 对话，选中代码片段直接发给它，它改完的文件在编辑器里实时显示 diff，体验确实比终端舒服。
桌面版则是把 opencode 的 TUI 包成了一个独立的桌面应用，适合那些不想开终端、或者希望把 opencode 放在第二个显示器上单独跑的人。我个人的工作流是：日常小改动直接用 VSCode 插件，跑长任务时开一个独立的终端窗口，桌面版用的频率反而不高。但如果你主力 IDE 是 IDEA，那 JetBrains 插件值得优先试，在插件市场搜索 opencode 就能找到，安装方式和普通插件一样。这里的核心思路不是让你把所有客户端都装一遍，而是根据工作流选一个顺手的主入口。
4.4 接入 opencode go 订阅服务和 ccswitch
聊到模型接入，热词里反复出现的 opencode go 值得单独解释一下。它是 opencode 官方推出的统一模型网关服务，按订阅制付费，订阅之后可以在同一个入口下使用多种模型，比如 Claude、GPT、Gemini 系列。对我来说它最大的价值不是省钱，而是省心——不用分别去管几个厂商的 API Key 和账单，也不用在多个配置之间切来切去。
ccswitch 则是另一个方向的工具，它擅长的是快速切换不同 API 网关的配置。如果你有多套模型调用地址，或者经常要在“公司网关”和“个人订阅”之间切换，可以用 ccswitch 管理这些配置，然后让 opencode 读取它生成的配置。很多人会把 opencode go 和 ccswitch 配合起来用：opencode go 负责解决“多模型统一入口”的问题，ccswitch 负责解决“多套网关快速切换”的问题。两者关注的场景不一样，但确实可以叠加使用。
如果你用的是 opencode go 这类订阅网关，配置方式会简单很多，通常只需要把网关给你的一组 API Key 和 baseURL 填进 provider 就行。模型选择方面，我建议按任务类型来决定：常规开发用中杯模型，复杂重构再上旗舰模型，这样订阅的 token 配额能用得比较久。
5. 常见报错与排查手册
5.1 unexpected server error 的排查思路
热词里有这么一条：opencode error: unexpected server error. check server logs。我几乎可以确定，这条报错的九成原因是“模型请求没有成功返回”。注意，它说的是 server error，不是权限错误，也不是网络错误，所以第一件事应该是看日志。opencode 的日志文件一般存放在系统临时目录或用户配置目录下，具体路径在报错信息里会给出，照着打开最后几十行，通常能看到真正的错误原因。
看到日志之后，剩下的排查思路就清晰了。如果日志里是 401 或 403，说明 API Key 有问题；如果是 429，说明超限了，换个时间段或者上付费档；如果是 model not found，说明你配置的模型名在当前 provider 里不存在，检查一下模型名是不是填成了别名或者版本号写错。还有一种容易忽略的情况：你自己配的网关服务端挂了，但 opencode 本身是好的。所以遇到这类报错，先别急着怪工具，按日志逐层查。
5.2 this model is not available in your country 怎么处理
这条报错在热词里也出现了，字面意思是“当前模型在你所在地区不可用”。遇到它时，最关键的是先搞清楚是谁在限制。如果限制来自模型厂商官方 API，那任何工具都绕不过去，唯一的办法就是换一个在你当地合规可用的模型或者服务商。如果限制来自某个第三方聚合服务，那可以看看该服务是否提供了其他区域入口，或者联系服务商开通权限。
提示：遇到地区限制类报错，优先检查是不是第三方聚合服务的入口限制，这类情况通常可以通过更换官方入口或换一个本地可用的模型来解决，不必在工具层面做额外配置。
这里要强调一下，不要试图通过绕过服务条款的方式访问模型。一方面模型厂商对异常访问的检测越来越严格，账号风险很高；另一方面，编码代理这类工具一旦被限制，损失的是整个工作流。我自己的建议是：优先使用本地模型或者在你所在区域正常提供服务的大厂 API，速度、稳定性和合规性都有保障。工具是帮我们提效的，不是用来冒险的。
5.3 模型选择建议与费用控制
给模型选型一个比较务实的参考。平时小改动、补注释、写测试，可以用便宜的小模型；涉及架构设计、重构、复杂 bug 排查，再用能力强的旗舰模型。opencode 的/models切换成本几乎为零，所以完全可以在同一个会话里按需切换。我在团队里给的建议是：日常默认用性价比高的模型，遇到难题明确告诉 opencode“这个问题很复杂，请用最强模型处理”，再手动切过去。
如果你完全不想花钱，本地 Ollama 是可以接的，能力和云端旗舰模型有差距，但处理注释、小改动、简单脚本这类任务是够用的。如果你走的是官方 API 按 token 计费，要特别注意上下文长度。像 LSP 诊断、Playwright 截图文本这类信息，消耗 token 的速度是惊人的。控制费用的一个有效手段是及时清理会话历史，opencode 支持开新会话，不要一个会话连续用两三天。另外，如果只是偶尔用一下，订阅 opencode go 类型的统一网关可能比分别开几个官方 API 更划算，这个可以自己按使用量估算一下。
5.4 性能与体验优化
最后聊几个让 opencode 用起来更顺手的小技巧。首先是模型切换别只依赖默认，要把常用模型在配置里都列好，并取一个自己一眼就能认出的名字，方便/models时快速选择。其次，如果项目很大，尽量用 LSP 而不是让 AI 自己去读所有源码，能省大量 token。第三，善用 Plan 模式，很多需求先让模型输出方案，比自己直接让它改然后反复返工要快得多。
关于目录权限，也要提前想好。opencode 能执行命令、改文件，默认是以你的用户权限运行的。如果你在一个跨团队的机器上使用，建议给它单独的工作目录，别把整个用户目录暴露给它。另外，遇到奇怪行为时，重启服务端是最快的恢复手段，opencode 退出再启动通常能解决大部分状态错乱的问题。
说了这么多，其实 opencode 最大的特点就是“不锁死”。模型可以换、配置可以到处放、Skills 可以根据团队习惯定制，甚至连客户端都有好几种选择。我个人的体会是，工具本身没有魔法，魔法来自你把项目约定、上下文管理、模型选型这堆基本功做好。先从一个最小配置开始跑通，然后按项目实际情况一点一点加 Skills、Memory、LSP，这类终端编码代理才会真正从一个“玩具”变成你日常开发里的得力干将。
最后再分享一个小技巧：如果你想在团队里推广 opencode，别急着让所有人都配全套。找一两个对命令行熟悉的同事，先用默认配置跑起来，让他们各自写一个小 Skill 解决自己最常做的一件事。当团队里出现第一个“用 opencode 帮我做 X”的实例之后，后面的事情就顺理成章了。工具好不好用，最终还是要回到“解决实际问题”这四个字上。
