如果你最近在关注 AI 编程助手大概率已经听过 opencode 这个名字。作为一个常年泡在终端里的开发者我从 Claude Code 刚火那阵就开始重度使用 agent 写代码后来 Codex 也试过一圈最后在朋友安利下换到了 opencode并且把团队好几个项目都迁了过来。今天这篇不是官方文档的复述而是我把 opencode 从安装、配置到真实项目落地的完整经验整理了一遍包括踩过的坑、写过的配置、以及怎么让它老实干活。内容适合三类人想从 Claude Code / Codex 迁移过来的老用户、刚听说 opencode 准备入坑的新手、以及已经在用但被模型接入、Skills、LSP 这些配置折腾过的进阶玩家。1. OpenCode 到底是个什么来头1.1 一句话说清它的定位OpenCode 是一个开源、跑在终端里的 AI 编程 agent和 Claude Code 属于同一类工具。它跟普通聊天机器人最大的区别在于它能直接操作你的文件系统、执行终端命令、运行测试、读取报错然后自己决定下一步做什么。你给它一个任务它会自己拆解步骤、改代码、跑验证遇到关键操作停下来等你确认。底层用 Go 编写所以单文件分发、启动速度快、内存占用比那些 Electron 套壳应用轻得多。更重要的是它不锁定单一模型厂商。OpenAI、Anthropic、Gemini 这些主流模型都能接也支持各种 OpenAI 兼容接口甚至可以接本地模型。很多人把它当作 Claude Code 的开源替代品但我用下来的感受是它更像是一个“模型中立”的 agent 底座你给它配什么模型它就变成什么风格的助手。1.2 我为什么从 Claude Code 换到它先说结论不是 Claude Code 不好而是 opencode 更适合我的工作方式。第一是开源可控。Claude Code 虽然好用但它是个闭源工具你没法看到它的 prompt 体系、没法深度定制内部逻辑。opencode 整个项目开源配置体系也透明遇到不合理的默认行为可以直接翻源码确认甚至提 issue 让作者改。对于团队落地来说这个“可控感”非常重要。第二是模型自由。Claude Code 基本绑定了 Anthropic 的模型而我在实际项目里经常要切换不同模型简单任务用便宜快速的模型复杂重构才用顶级模型。opencode 的模型切换就是改一个配置或者启动参数的事不用换工具。第三是扩展生态。Skills、LSP、MCP、Playwright 这些能力它都能接。我后面会详细讲这里先提一句它不是一个“死工具”而是一个可以不断往里加能力的框架。1.3 Codex、Claude Code、OpenCode怎么选这个对比我经常被问到直接放一张我自己的选型表维度OpenCodeClaude CodeOpenAI Codex开源是否否模型绑定不绑定多模型可切换主要是 Anthropic 系列主要是 OpenAI 系列安装方式npm / brew / curl / go installnpm / 脚本npm / 脚本IDE 插件VSCode、JetBrains 都有官方插件在推进有 VSCode 插件扩展能力Skills、MCP、LSP、Playwright插件机制、MCPMCP 支持配置难度中等全在 JSON 里低交互式为主低适合场景想自己掌控全部细节的开发者追求开箱即用的体验OpenAI 生态重度用户我的建议很简单如果你只想有个“能用”的 agent三个都行如果你想把它纳入团队的工程规范想接自己的模型网关想用 Skills 沉淀团队经验opencode 是当前最合适的选择。它不完美但它是少数把“可定制”这件事做到位的 agent 工具。2. 安装与环境准备从零跑通 CLI2.1 四种安装方式选哪个opencode 的安装方式很丰富我列一下常见的几种# 方式一npm 全局安装最常用 npm install -g opencode-ai # 方式二macOS 用户用 Homebrew brew install opencode # 方式三官方一键脚本适合 Linux / CI 环境 curl -fsSL https://opencode.ai/install | bash # 方式四Go 用户直接装因为 opencode 本身是 Go 写的 go install github.com/sst/opencodelatest我自己在 Mac 上习惯用 Homebrew升级方便在 Linux 服务器上会用一键脚本在 Windows 上则优先推荐 npm。如果你本身是 Go 开发者方式四最自然装完之后直接就是一个独立二进制连 Node 运行时都省了。装完之后先跑一下版本号确认opencode --version如果能看到版本信息说明安装成功。这里额外提醒一句opencode 迭代速度很快大版本之间配置格式可能有变化。你看到 2.x 的配置写法和几个月前零散教程里的 1.x 写法可能不一样遇到报错先去官方 changelog 查一下是不是版本问题。2.2 Windows 下“无法识别 opencode”怎么破这个报错我见过太多次了网上问的人也特别多opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的本质是opencode 的可执行文件没有被加到系统 PATH 里。npm 全局安装的包它的可执行文件在 npm 的全局 bin 目录。如果你用的是 nvm-windows这个目录通常是C:\Users\你的用户名\AppData\Roaming\nvm\node版本\node_modules\.bin解决办法有两种。第一种是重开终端因为 PATH 的环境变量是在终端启动时加载的安装完 npm 包后必须新开一个终端窗口才能生效。第二种是手动把 npm 全局 bin 目录加到 PATH。你可以先执行下面的命令查看 npm 全局目录npm prefix -g然后把得到的路径加上\node_modules\.bin添加到系统环境变量里。添加完记得重新打开终端验证where.exe opencode能输出路径就说明 OK 了。2.3 升级与版本管理opencode 的升级不同安装方式有不同命令npm 安装npm update -g opencode-aiHomebrew 安装brew upgrade opencode脚本安装重新执行一次安装脚本即可有一点我想特别强调升级前先看一眼当前项目的 opencode 配置备份。因为 agent 工具的特殊性它的配置格式经常随着版本调整升级后最坏的情况是旧配置直接失效。我的习惯是升级前把opencode.json提交到 git升级完如果 CLI 报配置解析错误用git diff看改动再对照官方文档调整。另外opencode 会自动检查更新也可以在配置里关掉这个检查。3. 模型接入与核心配置让 OpenCode 听你的3.1 opencode.json 配置文件拆解opencode 的核心理念是“一切皆配置”。在项目根目录放一个opencode.json它就会按照这份配置工作。下面是我目前在一个真实项目里的精简配置{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { my-gateway: { npm: ai-sdk/openai-compatible, name: My Gateway, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_GATEWAY_API_KEY} }, models: { claude-sonnet-4: { name: Claude Sonnet 4 (via gateway) } } } }, instructions: 这是一个前后端分离项目。前端是 React TypeScript后端是 Go测试命令是 go test ./...。改代码时保持现有风格。, tools: { playwright: true, lsp: true } }逐项解释一下model默认使用的模型 ID。opencode 的模型 ID 格式是厂商/模型名比如anthropic/claude-sonnet-4、openai/gpt-4o、google/gemini-2.0-flash。provider模型服务商的配置。最关键的是options.baseURL和options.apiKey。如果你只是用官方 API其实不用写 provider直接在终端执行opencode auth login登录对应厂商即可。apiKey我强烈建议用{env:变量名}从环境变量读取而不是把密钥明文写在 JSON 里。这个文件通常会被提交到 git一旦泄露密钥等于裸奔。instructions给 agent 的全局指令相当于项目的“工作手册”。它和 AGENTS.md 的作用类似我后面会细说。tools控制哪些工具可以被 agent 调用。playwright是浏览器操控能力lsp是语言服务器能力按需开启。3.2 免费模型怎么接选型原则是什么opencode 最吸引人的一点是它接免费模型非常方便。常见的免费接法有这么几种厂商官方免费额度像 Gemini Flash、DeepSeek 这些模型都提供免费或极低价格的 API只要注册拿到 key在 opencode 里登录即可。本地模型用 Ollama 跑 qwen、llama 这类模型配置一个本地 provider模型请求走http://localhost:11434/v1。社区免费模型网上会有各种“免费模型”入口比如社区里流传的 hy3-free 这类。但说实话这类免费源的稳定性没法保证我见过不少用着用着就下线或者开始限流的。如果你对稳定性有要求别在生产环境依赖它。我的选型原则是日常琐碎任务用便宜或免费的模型结构性改动和重大重构用高质量付费模型。举个例子让 agent 格式化代码、补注释、查一个 API 的用法用轻量模型完全够但如果是“重构这个模块的错误处理逻辑”我会切回 Claude Sonnet 或者 GPT 级别的大模型。opencode 切换模型很方便在对话里输入/models就能调出选择器或者在启动时加参数opencode --model google/gemini-2.0-flash3.3 this model is not available in your country 怎么办这个报错在热词里出现了好几轮说明不少人遇到过This model is not available in your country.翻译过来就是模型服务商根据你的访问来源限制了某些模型的使用地域。这是模型厂商自己的合规策略跟 opencode 本身没关系。我的处理办法按优先级排序换模型同一个厂商通常有很多模型限制的只是其中一部分。比如某个模型不可用试试同厂商的其他模型或者换个厂商的等效模型。换服务商入口如果你是通过某种聚合 API 网关接入的看看网关是否提供了其他区域的接入点有时候只是接入点选择的问题。用本地模型本地模型完全不依赖外部接口自然不存在地区限制问题。用 Ollama 跑一个能力不错的开源模型应付常规任务足够了。不管哪种方案我都建议在配置里多准备几个备用模型遇到限制直接切换而不是卡在一个模型上死磕。3.4 多套配置切换ccswitch 这类工具怎么用当你同时有官方 API、第三方网关、免费模型、本地模型好几套接入方式时手动改opencode.json就会变得很烦。社区里解决这个问题的思路是“配置切换工具”比如很多人提到的 ccswitch。ccswitch 这类工具做的事情很简单它帮你维护多套 provider 和模型配置通过命令一键生成或切换当前的opencode.json。比如你有一份“日常免费模型”配置和一份“深度重构付费模型”配置平时用前者接到复杂需求后敲一条命令切到后者不用手动改 JSON。我自己的做法更朴素在项目里维护几个配置文件例如opencode.free.json、opencode.pro.json需要切换时就复制一份覆盖为opencode.json。如果你要管理多个项目、多套密钥再用 ccswitch 这类工具会舒服很多。工具只是辅助关键是思路把“用什么模型”和“项目配置”解耦切换成本降到最低。4. 高频功能实操Skills、LSP、Playwright、Memory4.1 Skills把团队规范沉淀成 agent 技能Skills 是我最喜欢 opencode 的一点。简单说它是一组预置的指令模板让 agent 在特定场景下按照你的标准流程干活。一个 Skill 就是一个带SKILL.md文件的目录放在~/.config/opencode/skills/或项目.opencode/skills/下。举个例子我们团队写 React 组件有固定要求必须用 TypeScript、必须带测试、样式用 CSS Modules。平时跟 agent 说一遍它不一定记住但做成 Skill 之后它每次都会遵守。SKILL.md 的格式如下--- name: react-ts-component description: Generate a React component with TypeScript and tests --- When asked to create a React component, follow these rules: 1. Use TypeScript, define prop types explicitly. 2. Create a test file using Vitest and Testing Library. 3. Style with CSS Modules, no inline styles. 4. Export the component as a named export.配置好之后你只需要在对话里说“用 react-ts-component 生成一个用户头像组件”它就会自动加载这个 Skill 对应的规则来执行任务。实际使用中我建议团队把代码规范、提交信息格式、目录结构约定这些东西都写成 Skill。这比写文档有用因为文档是给人看的而 Skill 是直接喂给 agent 的“行为准则”。更妙的是Skill 文件本身是纯文本可以作为团队知识库沉淀在 git 仓库里新同事入职之后也能直接复用。4.2 接上 LSP让 agent 真正“懂”你的代码库LSPLanguage Server Protocol是 opencode 的另一个关键能力。没有 LSP 的时候agent 分析代码主要靠正则和文本搜索它能猜到某个变量是干嘛的但没法拿到精确的类型信息、函数定义、报错位置。接上 LSP 之后agent 就相当于有了 IDE 级别的代码理解能力。在opencode.json里可以配置语言服务器。比如 TypeScript 项目{ lsp: { typescript: { command: typescript-language-server, args: [--stdio] } } }Go 项目就换成goplsPython 项目用pyright-langserver。启动 opencode 后它会在后台拉起这些语言服务器然后通过 LSP 获取符号、诊断、类型等信息。你在 prompt 里让 agent“找出这个函数的所有调用点”时它就不只是文本搜索了而是真的通过语言服务器拿到准确的引用列表。想让 LSP 生效前提是本地已经装好了对应的语言服务器命令行工具。比如 TypeScript 的需要npm install -g typescript-language-serverGo 的需要go install golang.org/x/tools/goplslatest。第一次配置完可以用opencode的日志确认 LSP 是否连接成功没连上的话大概率是命令不在 PATH 里。4.3 Playwright 实战让 agent 自己复现前端 bug前端 bug 是最难描述的你辛辛苦苦截图、描述操作步骤agent 可能还是理解不了。opencode 内置了 Playwright 浏览器自动化能力可以让 agent 自己打开页面、点击操作、读取控制台报错然后直接定位到出问题的代码。这招用好了排前端 bug 的效率提升是肉眼可见的。我的标准操作流程是这样的先把前端项目跑起来比如npm run dev确认本地开发服务器地址是http://localhost:5173。启动 opencode让它用 Playwright 打开页面并复现问题。prompt 可以直接这样说用 Playwright 打开 http://localhost:5173 点击页面上的“提交订单”按钮然后查看浏览器控制台有没有红色报错。如果有报错把报错信息和对应源码位置告诉我。agent 会启动浏览器执行点击操作读取控制台信息。如果它定位到某个 React 组件抛了错你可以继续让它读源码、分析原因、给出修复方案。我实际用下来这个流程最适用于“操作路径明确但根因不明”的 bug。比如表单提交失败、按钮点了没反应、某个路由白屏这类问题让 agent 自己点一遍比自己手动打开浏览器反复试高效得多。它的 Playwright 工具还支持截图你可以在 prompt 里要求它截图确认页面状态。配合 LSP它能从报错栈直接跳到源码位置修复准确率很高。有一点要注意Playwright 需要安装浏览器内核第一次运行可能会自动下载浏览器如果网络条件不好这一步会比较慢。另外它跑的是真实浏览器所以你本地的开发服务器必须已经启动否则它打开的是个空页面报“连接不上”也是白搭。4.4 Memory 与 AGENTS.md让项目上下文不丢失用过 agent 的人都有一个痛点每次新开会话它好像把前面的对话全忘了连项目背景都要重新讲。opencode 解决这个问题靠的是 AGENTS.md 文件。AGENTS.md 是给 agent 看的技术文档CLAUDE.md 的类似物。opencode 启动时会自动读取全局的~/.config/opencode/AGENTS.md、项目根目录的AGENTS.md以及子目录下的AGENTS.md把它们作为默认上下文注入。这意味着你完全可以把“这个项目是干什么的、技术栈是什么、测试怎么跑、代码风格是什么”写进 AGENTS.md之后每次启动 opencode 它都自动知道不用重复交代。我的项目 AGENTS.md 一般长这样# Project: 用户中心服务 ## Tech Stack - Backend: Go, Gin, PostgreSQL - Frontend: React TypeScript Vite ## Commands - Run tests: go test ./... npm test - Run dev server: npm run dev ## Conventions - Error handling: always wrap lower-level errors with context. - Database migration files go under /migrations.这个文件建议提交到 git让所有团队成员共享。你甚至可以让 opencode 自己来维护它新接手一个项目时先让它读代码生成一版 AGENTS.md后面再不断完善。它相当于给 agent 装了一个“长期记忆模块”每次会话都从它开始项目上下文再也不丢。5. 在 IDE 里用 OpenCodeVSCode、JetBrains 与桌面版5.1 VSCode 插件终端和编辑器无缝衔接虽然 opencode 本身就是个终端工具但长时间在终端里看代码、改代码还是不够直观。官方 VSCode 插件解决了这个问题。装好插件后VSCode 侧边栏会多一个 OpenCode 面板你可以直接在编辑器里跟 agent 对话它修改的文件会高亮显示差异比终端里黑底白字的体验好很多。插件的核心优势是上下文衔接。在 VSCode 里打开某个文件agent 就知道你当前在看什么选中的代码片段它也能直接读到。你可以先在编辑器里选中一段可疑代码然后让 opencode“看看这段为什么性能差”它不需要你复制粘贴自己就有上下文。打开插件面板的快捷键在官方文档里有我习惯自己绑定一个组合键。插件和 CLI 共用同一套配置和登录状态所以你在终端里配置好的模型、Skills在插件里直接就生效不用二次配置。5.2 JetBrains IDEA 插件与 Java 项目配置如果你主力 IDE 是 IntelliJ IDEA、PyCharm 这类 JetBrains 系产品opencode 也有官方插件。JetBrains 插件的用法跟 VSCode 类似都是在侧边栏启动对话共享项目上下文。这里特别说一下 Java / Maven 项目的使用注意事项。opencode 执行mvn test、mvn package这类命令时依赖的是系统环境里的mvn命令。很多人 JetBrains 里用的是 IDEA 自带的 Maven 或者配置了特定 Maven 路径但 opencode 在终端环境里跑它只认 PATH 里的mvn。所以如果 agent 报“找不到 mvn 命令”而你机器上明明装了 Maven九成是 Maven 没加到系统 PATH或者你只配置了 IDEA 内部的 Maven home path。解决方案很简单把 Maven 的bin目录加到系统 PATH然后在终端里手动跑一下mvn -v确认能识别。另外Java 项目的语言服务器可以用 JDTLS配置好 LSP 之后agent 分析 Java 代码的准确性会明显提升。5.3 桌面版不想碰终端的人有福了除了 CLI 和 IDE 插件opencode 还提供了桌面版客户端。桌面版本质上是把 CLI 的能力包装成了图形界面适合不习惯终端操作、或者想给团队里非技术同事用的人。界面通常包含对话窗口、文件变更预览、终端输出区域底层还是同一套配置和模型体系。我的建议是开发者日常用 CLI 或 IDE 插件足够桌面版可以作为“图形化辅助”装在备用机器上。它的配置文件和 CLI 是共通的所以不用担心在两台机器间上下文不一致。如果你是在带 GUI 的 Linux 桌面环境上使用桌面版也能避免“只会在终端里跑 agent”的尴尬。6. 常见问题与排查技巧实录6.1 高发报错速查表报错信息可能原因解决思路无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称PATH 没配置好或终端没重开重开终端确认 npm 全局 bin 目录在 PATH用where opencode验证Unexpected server error. Check server logsAPI 网关或模型服务端返回异常查看 opencode 日志定位请求详情切换模型检查 baseURL 是否配置正确This model is not available in your country模型服务商有地区限制换可用模型换接入点考虑本地模型context length exceeded上下文超长换更大上下文的模型拆分任务清空会话重来tool execution timeout命令跑太久未结束把任务拆小检查是否有交互式命令阻塞给 agent 更明确的完成条件LSP server failed to start语言服务器命令不在 PATH 或版本不兼容确认对应命令可执行检查版本查看 opencode 日志排查这类问题我的通用办法是开 debug 日志。启动时加--debug参数opencode 会把每次请求、每个工具调用的细节都打到日志里。看到具体请求的出错信息解决问题就有了方向。不要只盯着终端那两三行红色报错日志里往往藏着真正的答案。6.2 我的几条避坑经验第一永远不要把 API Key 写死在配置文件里。用{env:KEY_NAME}引用环境变量并且把.env文件加入.gitignore。我见过不止一次团队仓库把密钥提交上去第二天就收到服务商的泄露告警邮件非常被动。第二给 agent 设定“完成定义”。模糊的任务得到模糊的结果。不要只说“优化这个页面”要说“优化这个列表页的渲染性能目标是首屏时间降低 30%改完后跑一遍 Lighthouse 并贴出前后对比”。agent 需要明确的验收标准否则它会自己定义“完成”那通常跟你的预期差很远。第三高风险操作前先让 git 打底。opencode 支持交互式确认模式大改动前会让你 review。我通常让它先建一个分支每完成一个阶段性改动就提交一次。这样即使它改出问题回滚也就一条命令的事。如果你已经给它用了-y全自动模式那我建议只在低风险任务里用。第四免费模型用之前先确认上下文窗口。很多免费模型的上下文很小你把整个项目文件都塞给它还没开始干活上下文就满了。我的经验是免费模型适合处理单文件、单函数级别的任务涉及跨文件改动时还是切付费大模型更省心。6.3 “接手老项目”的落地流程热词里有人在问 opencode 怎么接手开发项目这块我最近刚实践过一轮流程已经稳定了。团队里有个历史系统文档缺失、维护的人走了我接手的第一个任务就是让 opencode 帮我把项目摸清楚。我的操作步骤是这样的在项目根目录启动 opencode让它先读README.md、package.json、go.mod等关键文件并生成一份简短的架构摘要。让它检查项目的构建命令和测试命令逐个跑一遍把环境问题暴露出来。比如依赖缺失、Node 版本不对、数据库没起这些在第一步就能发现。让它梳理核心业务流程画一个“请求从入口到数据库的路径”文字版说明。注意opencode 不会画图但它能列出关键函数调用链。把以上的产出整理成一个AGENTS.md提交到仓库之后自己和同事都能受益。让它修复第一步发现的构建问题提交一个“让项目可运行”的初始 PR。整个过程下来接手成本从“看代码好几天”压缩到“半天能上手改 bug”。但这背后有个前提agent 的每一步产出都需要人来做 review。它帮你把地图画出来了但地图准不准、有没有遗漏只有人才能判断。接手项目这件事opencode 是极好的“侦察兵”但指挥官还是你自己。在项目里用 opencode 这几个月我最大的体会是工具的价值不在于它有多智能而在于你愿不愿意花时间去约束它、训练它。一份用心维护的 AGENTS.md、一组沉淀团队规范的 Skill、一套清楚明白的模型切换机制这些“配置功夫”才是让 agent 从“玩具”变成“生产力工具”的关键。opencode 给我最大的惊喜也在于此它把所有细节都摊开放在你面前怎么调教它选择权在你自己手里。后续我打算再给团队配一套项目专用的 MCP 服务把内部系统和更多自动化能力也接进去让 agent 不只是改代码还能直接操作整个研发链路。