说实话我现在的开发主战场已经不在编辑器里了。不管是改 bug、重构还是接手一个陌生仓库我第一反应都是打开终端进入项目目录然后敲下 opencode。如果你还没用过它可以先把它理解成一个开源版的 Claude Code一个跑在终端里的 AI 编程代理能读你项目里的代码调用终端命令自己改文件跑测试甚至打开浏览器排查前端问题。这篇文章是我自己从第一天安装到现在把这大半年的实操经验、踩过的坑、以及我觉得真正好用的配置方式一次讲清楚。适合第一次接触 opencode 的人也适合已经在用但想把它配置得更顺手的朋友。1. 先搞清楚opencode 到底是什么1.1 一个开源的终端 AI 编程代理opencode 本质上是一个跑在终端里的 AI 编程代理。你用自然语言给它派活它会自己去读代码、找文件、改代码、执行命令、看测试结果然后把改动和结论汇报给你。它不是 IDE 插件不是聊天机器人套壳而是一个有完整工具调用能力的 agent。项目由做 Serverless Stack 的 SST 团队发起代码放在 GitHub 的 sst 组织下面是一个正经的开源项目不是某家公司的闭源产品。所以你可以直接看它的源码也能自己改、自己包、自己部署这一点对很多团队来说很重要——不依赖某个商业服务的黑盒行为。它的界面是 TUI也就是终端里的图形交互界面。启动后你会看到一个带边框的交互面板左边是会话内容右边是文件列表和 diff 预览底部是输入框。第一次用的人可能会觉得密密麻麻但习惯之后比纯命令行反馈高效得多因为你能直接看到模型读了哪些文件、执行了什么命令、改动了哪些代码每一步都可以叫停。1.2 和 Claude Code、Codex 相比差在哪很多人问opencode 和 Claude Code、OpenAI Codex 这类工具到底有什么区别。我平时两个都会用感受是这样的维度opencodeClaude CodeCodex CLI是否开源是否是模型绑定多模型任意厂商以 Anthropic 系为主以 OpenAI 系为主配置灵活度高能自定义 provider中受官方限制中官方支持第三方交互方式TUI 面板终端流式对话终端流式对话生态扩展MCP SkillsSkills MCPMCP 逐步增加最核心的差异在模型解耦上。Claude Code 的默认模型是 ClaudeCodex CLI 的默认模型是 OpenAI 家的而 opencode 可以接 Anthropic、OpenAI、Google Gemini、DeepSeek甚至你本地跑的 Ollama 模型。这就意味着你不会被绑定在单一模型上今天用 Sonnet 写代码明天想试试其他模型改个配置就行。另一个差异是权限和可见性。opencode 在执行命令前会经过你的确认每一步工具调用都会显示在面板里。相比之下有些工具会偷偷跑一堆命令虽然大部分时候没问题但遇到环境莫名的被改掉排查起来很痛苦。opencode 这种前置确认模式至少在初期能让你清楚它在干什么。1.3 什么人适合用它能解决哪些问题我用下来opencode 最能打的是这三类场景第一接手不熟悉的项目。新项目 clone 下来与其自己翻半天 README 和 package.json不如直接让它先把项目结构摸清楚告诉我启动方式、测试命令、核心技术栈它能把上下文梳理得明明白白省掉大量阅读时间。第二批量机械改动。比如整个项目里某个函数签名要换、一组文件要统一改 import 路径手动改容易漏让 agent 按规则批量处理并逐个 diff 给你审查效率和准确率都很高。第三前端 bug 复现。opencode 能通过 Playwright 等 MCP 工具启动真实浏览器打开本地页面、点击按钮、读取 console 报错。这个对排查交互类 bug 特别实用后面我会专门写一节。反过来说如果你只是想要一个对话框来问答不想让它动你的文件那 opencode 可能有点重。它更适合愿意把一部分编码流程交给 agent 执行、并且习惯在终端里工作的人。2. 从安装到跑起来环境准备和踩坑实录2.1 先检查环境Node.js 和 npmopencode 是用 Node.js 写的安装之前先确认机器上有 Node 环境。node -v npm -v建议 Node.js 版本在 20 以上。老版本不是不能跑但一些新的配置语法和 MCP 功能对 Node 版本有要求。如果还没装 Node推荐用 nvm 这类版本管理工具来装不要直接去官网下安装包因为后面你可能需要在多个 Node 版本间切换。我见过不少人在这一步卡住明明node -v能输出版本号但npm -v报错。这种情况一般是 npm 没跟着 Node 一起装好或者 PATH 配置有问题。先解决 npm 再继续否则后面装 opencode 一定失败。另外如果 npm 版本太旧全局安装容易遇到权限或者网络解析问题先升级一下比较省事npm install -g npmlatest2.2 用 npm 完成全局安装opencode 在 npm 上的包名是opencode-ai不是opencode。这个细节很重要因为opencode这个包名被别人的项目占了直接npm install -g opencode装出来的是另一个东西。npm install -g opencode-ai安装完成后验证一下opencode --version能输出版本号就说明装成功了。macOS 用户如果想用 Homebrew 管理官方文档也提供了 tap 的方式但我个人更推荐 npm 全局装因为升级方便跨平台行为一致。后续升级npm update -g opencode-ai如果公司网络对 npm 源有限制记得先配好 npm 镜像源否则会卡在下载阶段。国内常见做法是把 registry 指到镜像地址配置后重新安装即可。2.3 解决 Windows 下无法识别 opencode的经典报错这是 Windows 用户安装后最常遇到的一个问题报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确认路径正确然后再试一次。第一反应不要怀疑安装失败绝大多数原因是 npm 的全局 bin 目录没有加到 PATH 里。排查步骤很简单先看 npm 全局目录在哪npm prefix -g一般会输出类似C:\Users\你的用户名\AppData\Roaming\npm的路径。确认这个路径在你的 PATH 环境变量里。在 PowerShell 里查看echo $env:Path如果发现没有去系统设置里把这个目录加进去。加完之后一定要重新打开终端因为环境变量不会自动刷新到已开的窗口。另外还有一个隐藏雷区PowerShell 的执行策略。即使 PATH 配置好了如果执行策略禁止运行 npm 的脚本文件同样会报这个错。检查一下Get-ExecutionPolicy如果不是RemoteSigned建议执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这会允许运行本机脚本但依然阻止未签名的远程脚本安全性上是可以接受的。注意如果你用npx opencode-ai能跑但直接输入opencode不行那基本就是 PATH 或执行策略问题而不是包没装好。别反复重装先把环境变量理清楚。2.4 VSCode、JetBrains 插件和桌面版怎么选终端里的 TUI 用顺手之后很多人还是会希望在 IDE 里也能和 opencode 交互尤其是看 diff 和改文件的时候IDE 体验确实更好。VSCode 的话直接在扩展市场搜索 opencode装那个支持状态栏显示和面板集成的扩展。装好后你会在左侧看到一个 opencode 面板可以把编辑器里选中的代码直接发给它它改完的 diff 会以编辑器内联的形式呈现比切到终端再切回来舒服不少。JetBrains 系也有类似插件我在 IDEA 里装过一个使用逻辑差不多右侧工具窗打开 opencode 面板选中代码可以发送上下文模型改动会生成 diff你可以在 IDE 里直接 review。如果你主力是 IntelliJ IDEA 或者 WebStorm装插件后基本回不到纯命令行了。至于桌面版目前 opencode 的重心还是在终端官方并没有一个和 Claude Desktop 一模一样的独立桌面应用。社区有一些 Electron 封装和第三方桌面壳但功能参差不齐。我的建议是如果不想用纯终端优先用 IDE 插件体验最完整桌面壳等生态再成熟一点再考虑。3. 模型接入与配置别只会用默认模型3.1 第一次启动登录模型供应商安装完成后在任意目录直接输入opencode它会引导你选择模型供应商并登录。如果你想手动触发登录流程也可以执行opencode auth login这个命令会交互式列出当前支持的厂商包括 Anthropic、OpenAI、Google、DeepSeek、OpenRouter、Ollama 等。选一个后它会走 OAuth 流程或者要你粘贴 API Key。如果你更习惯用环境变量管理密钥opencode 也支持直接读取常见厂商的变量名比如ANTHROPIC_API_KEY、OPENAI_API_KEY。只要环境变量里有值启动时会自动识别不需要再走一遍登录流程。登录完之后可以用这条命令查看当前有哪些模型可用opencode models默认模型的选型我的建议是写代码为主的任务Claude 系列的 Sonnet 模型综合体验最好简单重构、写注释、批量格式化这类轻任务用便宜的小模型就够对隐私敏感的项目直接连本地 Ollama。3.2 用 opencode.json 自定义模型供应商opencode 的配置中心是一个叫opencode.json的文件。它既可以放在项目根目录作为项目级配置也可以放在全局配置目录下作为用户级配置。Linux 和 macOS 下全局配置路径是~/.config/opencode/opencode.jsonWindows 在用户目录下的.config/opencode里。自定义一个供应商的常见写法大致是这样{ $schema: https://opencode.ai/config.json, model: deepseek/deepseek-chat, provider: { deepseek: { npm: ai-sdk/deepseek, name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: {env:DEEPSEEK_API_KEY} }, models: { deepseek/deepseek-chat: { name: DeepSeek Chat } } } } }这里的npm字段告诉 opencode 这个供应商要加载哪个 AI SDK 包options里配置接口地址和密钥models里声明你实际要用的模型 ID。注意我用了{env:DEEPSEEK_API_KEY}这种写法opencode 支持在配置文件里引用环境变量这样 key 就不会被写进仓库避免泄漏。每次改完配置建议重启一下 opencode或者用opencode models验证模型是否被正确加载。如果模型列表里看不到你刚加的模型优先检查models里的 key 格式是否写对。提醒项目级配置文件会被提交到 git如果你是团队协作千万不要把 API Key 直接写在项目配置里。一律走环境变量引用。3.3 配合 CC Switch 等工具快速切换配置很多用过 Claude Code 的朋友应该知道 CC Switch 这个工具它最初是用来在 Anthropic、Gemini、其他兼容服务之间快速切换 Claude Code 配置的。因为 opencode 同样支持从环境变量读取模型网关信息所以你也可以把 CC Switch 那一套切换思路搬过来。我自己的做法是这样的在 opencode.json 里把baseURL和apiKey都写成环境变量引用{ provider: { custom: { npm: ai-sdk/openai-compatible, options: { baseURL: {env:LLM_BASE_URL}, apiKey: {env:LLM_API_KEY} }, models: { custom/my-model: { name: My Model } } } } }这样我只需要在一处统一管理LLM_BASE_URL和LLM_API_KEY切供应商的时候改环境变量就行不用频繁改 opencode.json。不过这里要泼一盆冷水第三方兼容服务的稳定性常年飘忽不定免费类网关更是随时可能下线。很多人问某个免费网关是不是挂了这种问题本质上是不可控的。生产环境最稳妥的方案永远是两条腿走路官方付费 key 一个本地模型一个第三方网关只当作临时体验。3.4 免费模型和本地模型的接入思路如果你暂时不想花钱也有几条路可以走。一是大厂提供的免费额度。Google Gemini 有免费的 API 层日常小任务够用Groq 提供了一些开源模型的免费额度响应速度还很快DeepSeek 虽然不完全免费但价格很低一顿饭钱能用很久。二是本地模型。配合 Ollama你可以把模型跑在自己机器上完全免费、数据不出本机适合对隐私要求高的项目。先拉一个代码向的模型ollama pull qwen2.5-coder:7b然后在 opencode.json 里加一个本地 provider{ provider: { ollama: { npm: ai-sdk/ollama, options: { baseURL: http://localhost:11434/api }, models: { ollama/qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B } } } } }注意本地模型的代码理解能力跟云端大模型有明显差距适合做代码解释、小范围重构、生成单测这类任务让它跨模块做大重构很容易把上下文搞崩。别对它期待过高把它当作一个离线兜底方案就好。4. 实战流程用 opencode 接手一个开发项目4.1 在项目目录启动 opencode 并给出上下文接手一个别人写的项目最忌一上来就让模型帮忙改个 bug。它对你项目一无所知直接给任务大概率答非所问。正确的姿势是先进入项目目录启动 opencodecd ~/workspace/legacy-app opencode第一次对话不要派活先让它建立上下文。我常用的开场 prompt 是这样的这是一个刚从 git 仓库 clone 下来的项目。先不要改任何代码帮我做三件事第一读 README 和 package.json搞清楚技术栈和启动方式第二找一下测试命令并跑一遍现有测试第三输出一份项目结构说明包括主要模块和入口文件。跑完之后让它把关键信息整理成一份 notes 给你。这一步看起来耗时但后面的效率会成倍提升。模型知道了启动命令、测试命令、目录结构再让我改 bug 时它能自己先跑测试复现而不是瞎猜。opencode 在 TUI 里执行命令前会弹出权限确认你可以选 allow 或 deny。第一次用的时候建议全部 deny看它请求哪些命令评估合理后再放行。等你对它建立起信任再放宽权限也不迟。4.2 用 AGENTS.md 建立项目记忆接手一个项目最大的成本是上下文。每一次新会话模型都要重新理解项目。opencode 的解决方案是AGENTS.md它会在每次会话启动时自动读取这个文件把它当作项目的基本盘。全局的 AGENTS.md 放在~/.config/opencode/AGENTS.md适合写你自己的通用规则比如永远不要删除未读的 TODO 注释、修改公共接口前必须先列出调用方。项目级的 AGENTS.md 放在项目根目录适合写这个项目的专属事实。我通常会在 AGENTS.md 里写这些东西# 项目指南 ## 技术栈 - 前端React 18 Vite TypeScript - 后端Node.js Express端口 4000 ## 常用命令 - 安装依赖pnpm install - 开发启动pnpm dev - 测试pnpm test ## 规则 - 修改公共 API 前必须先检查所有调用方 - 不要引入新的 UI 库统一用项目自带的组件库 - 密钥一律放环境变量禁止写进代码有了这份文件每次新对话它都能快速把上下文找回来不用你反复跟它解释这个项目用 React 写的测试跑 pnpm test。这也是 opencode 里最被低估的一个功能强烈建议每个项目都建。4.3 用 opencode run 把任务交给 Agent 执行TUI 适合交互式操作但有些场景你并不想盯着屏幕比如在 CI 里跑批量任务、在服务器上处理日志、或者睡觉前丢一个任务让它慢慢改。这时候就用非交互模式opencode run 修复 src/utils/date.ts 里的日期格式化 bug修复后运行 pnpm test 确认所有测试通过opencode run会把任务一次性交给 agent执行完后退出输出结果直接打印到终端。它也可以配合管道使用比如把一个错误日志文件的内容喂给它让它分析cat error.log | opencode run 分析这份日志指出最可能的三类错误原因非交互模式跑任务前我建议先把两件事准备好一是默认模型要选好二是权限规则提前调好。因为没有 TUI 交互它执行命令时如果遇到需要确认的权限流程会比较绕。我第一次用的时候就踩过这个坑任务跑到一半卡在命令确认上最后只能中断重来。4.4 借助 Playwright 让 Agent 自己复现前端 bug前端 bug 和纯逻辑 bug 不一样很多时候你根本不知道用户是怎么把页面点坏的。opencode 可以通过 MCP 接入 Playwright让模型自己打开浏览器、点按钮、截图、读 console 报错。在 opencode.json 里配置一个 Playwright MCP server{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }配置好之后重启 opencode在对话里给它一个具体的复现任务本地开发服务跑在 http://localhost:5173用 playwright 打开这个页面点击导航栏的登录按钮输入错误密码触发登录失败提示然后把页面截图和 console 报错一起给我。然后你就能看着它自己打开浏览器一步步操作最后把截图展示在对话里。相比你自己打开 DevTools 手动复现这个方法最大的价值是你不用知道 bug 的触发路径只要描述现象它自己去试。不过记得第一次用 Playwright 前先把浏览器内核装上不然会报找不到浏览器npx playwright install chromium如果你的测试环境需要处理登录 cookie、mock 接口也可以在 prompt 里交代清楚它会在脚本里自动处理。这个功能用熟之后前端 bug 的排查效率至少翻倍。5. 进阶玩法Skills、Memory 和 MCP 扩展5.1 给 opencode 安装 Superpowers 技能包Skills 是 opencode 一个很提效的能力。说白了它就是把一整套工作流写进 Markdown 指令文件模型遇到对应任务时会自动加载这套流程而不是凭感觉自由发挥。社区里最有名的 Skills 集合是 obra 做的 Superpowers。它把常见的任务比如写周报、生成文档、做代码审查、整理 PDF 等都拆成了标准化步骤。装好之后你只需要说用 Superpowers 的周报技能帮我生成一份本周总结它就会按里面的步骤来执行输出质量比裸 prompt 稳定得多。安装步骤不复杂。先把仓库克隆到本地git clone https://github.com/obra/superpowers ~/.config/opencode/superpowers然后把它的 skills 目录接到 opencode 能识别的位置。最简单的做法是做一个软链接ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skillsWindows 上如果没有软链接权限直接把superpowers/skills文件夹复制到全局配置目录下的 skills 文件夹也行。装完之后重启 opencode问它一句你现在有哪些 skills 可用它会把加载到的技能列出来。如果看不到多半是目录路径没放对检查一下 opencode 文档里的 skills 目录要求。5.2 Memory 的正确使用姿势opencode 运行时会为项目生成一个.opencode目录里面存了会话记录、消息历史这些运行时数据。但这些是短期记忆关了会话就过期了并不能真正让模型记住项目。真正能当长期记忆用的还是 AGENTS.md。我的习惯是每个大任务结束之后花一分钟把关键信息同步回 AGENTS.md包括这次改动了哪些模块、是否留下技术债、下一步准备做什么。下一次会话它读到这些内容相当于把接力棒直接传给新对话不需要你重新描述。还有一个小细节AGENTS.md 不是越厚越好。模型每次启动都会把这些内容读进上下文文件太大反而会稀释对当前任务有用的信息。我的原则是只写项目事实和决策记录不写大段解释文字。过时的内容要顺手删掉留着只会误导模型。5.3 MCP 扩展把文件、数据库、浏览器都接进来MCP 是开放的工具调用协议你可以理解成给 AI 装外接插件。opencode 支持标准的 MCP server这意味着 GitHub、文件系统、数据库、浏览器、通知服务等都可以接到对话里。除了前面提到的 Playwright我再举一个例子把本地文件系统接口暴露给模型{ mcp: { fs: { type: local, command: [npx, -y, modelcontextprotocol/server-filesystem, /tmp], enabled: true } } }MCP server 分两种本地 server 通过 command 启动远程 server 直接填 URL。你用 opencode 做项目初始化的时候可以把 GitHub MCP 接进来让模型在对话里直接拉 issue 列表、提 PR省掉不少切上下文的时间。但这里有个忠告不要贪多。每个 MCP 工具都会占用模型上下文预算接得越多模型面对的信息越杂反应也会变慢。我的习惯是最多同时开两三个只接当前任务真正用得到的。等任务做完了再关掉不用的 server。6. 常见问题与工具选型速查6.1 安装与启动问题一览表我把自己踩过、以及被身边朋友问过最多的安装启动问题整理成了一张表基本能覆盖九成以上的情况现象可能原因解决办法无法将“opencode”项识别为 cmdletnpm 全局目录不在 PATHnpm prefix -g拿到路径加入 PATH 后重启终端opencode 命令执行无反应Node 版本过低或安装损坏node -v检查升级到 20重装 opencode-ai提示找不到 Node 模块npm 全局环境被清理或变更重新执行npm install -g opencode-aiPowerShell 执行脚本被拦截执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignednpx opencode-ai能用但很慢npx 每次都要临时解析包改用全局安装不要依赖 npx 当日常入口6.2 模型请求报错的核心排查思路启动 opencode 后如果请求模型报错常见提示是opencode: error: unexpected server error. check server logs看到这个先别慌按顺序排查三件事API Key 是否有效、baseURL 是否正确、模型 ID 是否被供应商支持。第一个看 Key。如果用的是某个平台试用的 key很可能过期了如果是公司网关的 key可能是权限范围不够。第二个看 baseURL。opencode 自定义 provider 时最容易写错的就是接口地址有些平台要求末尾带/v1有些则不允许这个直接看平台文档。第三个看模型 ID。不同平台对模型的命名规则不一样填错一个字符就会报错。更详细的日志可以打开 opencode 的日志目录查看实际请求返回的 HTTP 状态码。401 和 403 基本是 Key 或权限问题429 是限流换个模型或者降频试试500 类的报错大概率是供应商服务问题只能等。我个人的习惯是在 opencode.json 里把 apiKey 都改成环境变量引用排查的时候直接看对应环境变量是否设置正确比在配置文件和账户后台之间反复切换快得多。6.3 opencode、Claude Code、Codex 到底选哪个这个话题几乎每个接触终端 Agent 的人都会问。我给不出标准答案但可以把我的选择理由分享出来如果你追求自由度想在不同模型之间随意切换甚至要接本地模型选 opencode。它开源、透明、配置灵活适合长期主义者。如果你团队已经在 Claude 的生态里买了 Claude 的额度并且你也觉得 Claude 系列的代码能力最适合你那直接上 Claude Code。它的闭环体验确实好对官方模型的整合程度最高。如果你主力模型是 OpenAI而且想要一个和官方工具链配合紧密的 CLI那 Codex CLI 值得试。它现在也开放了不少自定义能力但整体上还是没有 opencode 那么百搭。就我自己来说主力工具是 opencode兜底是 Claude Code。遇到 opencode 在某些复杂项目上表现不稳定我会切到 Claude Code 对比一下结果。工具之间的差异并没有网上说的那么玄乎真正影响效率的还是你对项目上下文的组织能力。最后分享一个我自己很受用的习惯每次新建项目我会先花十分钟让 opencode 把项目的 AGENTS.md 建好。技术栈、启动命令、测试命令、编码规范全部写进去。这个文件就是你和 agent 团队的共同工作手册后面每一次对话都在吃这本书的红利。工具会迭代模型会换但这个项目记忆的习惯一旦养成收益是长期的。