如果你最近在逛技术社区大概率刷到过 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 用户也可以用 Homebrewbrew 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.mdopencode 的初始理解能力就能直接上一个台阶。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”的实例之后后面的事情就顺理成章了。工具好不好用最终还是要回到“解决实际问题”这四个字上。