说实话我第一次注意到 opencode 是在同事的终端录屏里。当时我正为一个跨 20 个模块的老项目发愁改一个接口要同时动前端类型、后端 mock、测试用例全靠手动翻文件。录屏里那哥们就敲了两三行命令opencode 自己打开项目、读了十几个文件、跑了一遍测试然后把改动整理成 PR全程不到十分钟。我当场被种草回去赶紧装了一个。opencode 是一个基于 Go 写的开源终端 AI 编程代理Agent。简单说它就是住在你命令行里的工程师给它一个任务目标它会自己规划步骤、读取代码、执行命令、查看运行结果直到任务完成。它不绑死某一家模型OpenAI 的 GPT 能用Anthropic 的 Claude 能用Google 的 Gemini 能用连你本地 Ollama 起的模型也能用它还通过 skills、MCP 协议接各种外部工具从浏览器测试到数据库查询都能覆盖。适合谁如果你受够了某个商业 Agent 的“全家桶绑定”想在终端里用一套顺手、可配置、支持多模型的 AI 编程工作流或者你就是单纯对“AI 自动改代码”这件事感兴趣opencode 都值得花一个下午认真试试。下面我把自己从安装、配置到实际开发中用得最顺的玩法还有踩过的坑全部整理一遍尽量做到“照着抄就能跑”。1. opencode 到底是什么一个住在终端里的 AI 工程师1.1 从“聊天助手”到“终端 Agent”这一步差在哪很多朋友一开始分不清“命令行里用 AI”和“AI Agent”的区别。你以前可能在终端里跑过类似chatgpt的命令行客户端本质上是把终端当成聊天窗口模型给你回一段文字你复制粘贴去执行。opencode 不是这个思路。它做的是“代理Agent”该做的事理解任务后自己拆解步骤、自己读写文件、自己执行命令、自己看测试输出然后根据结果决定下一步做什么。我用一个生活化的比喻普通 AI 编程助手像是你请了一个“聊天顾问”你说一句它回一句中间所有脏活累活还是你自己干opencode 更像你招了一个“远程实习生”你把需求写成一个 ticket 丢过去它自己看代码库、跑环境、试错、改代码最后把结果汇报给你。区别不在于能不能写代码而在于有没有“动手能力”和“闭环反馈”。这背后的核心技术是 Agent Loop模型先生成一个计划工具读文件、跑命令、搜索执行后把结果再喂回模型模型根据新信息修正下一步。这个循环在 Claude Code、Codex 这类产品里都有opencode 做得比较彻底的地方在于它把循环的每一步都暴露在终端界面上你可以随时看到 agent 正在读哪个文件、执行什么命令、为什么做这个决定。这种“可观测性”对调试特别重要。我实际用下来遇到 agent 走偏的时候一眼就能从日志里发现问题而不是看着一个黑盒干着急。1.2 为什么用 Go 写这件事值得注意opencode 的核心是用 Go 写的这不是一个无关紧要的实现细节。早几年市面上这类终端 Agent 大多基于 Node.js 或 Python好处是生态丰富坏处是依赖一堆运行时。你装一个工具可能要把 node_modules 拉一遍或者被 Python 版本折腾到怀疑人生。opencode 把核心编译成单个二进制文件装上就能跑跨平台体验非常一致。Go 带来的另一个直接好处是启动速度和内存占用。我在一台配置一般的办公笔记本上对比过Claude Code 启动大概要两三秒opencode 几乎是敲完回车就进入界面。长时间开着多个会话内存占用也比 Electron 壳的桌面工具低一个量级。作为一个每天要开几十次终端的开发者这种“轻”是会形成使用习惯的。另外因为核心是 Go它天然适合放到 CI 环境里。我在公司的流水线里加了一个阶段用 opencode 跑一个固定的 review 任务单二进制部署没有任何运行时问题。如果你习惯用 Docker也只需要基于一个瘦镜像把二进制拷进去。注意我这里说的是官方发布版的设计如此具体某个发行平台有没有额外打包逻辑建议以官方仓库的 README 为准。1.3 opencode 与 Claude Code、Codex 的横向对比市面上同类工具不少很多人会纠结“opencode、Codex、Claude Code 到底选哪个”。我这里不做“谁取代谁”的结论只把几个关键维度列成一张表方便你自己判断。对比维度opencodeClaude CodeOpenAI Codex底层语言GoTypeScript/Node闭源服务模型绑定多模型支持 Anthropic / OpenAI / Gemini / Ollama / OpenAI-compatible以 Claude 为主以 GPT 系列为主TUI 交互自带终端界面支持主题、vim 模式终端界面体验好但定制弱偏 CLI 风格Skills 机制支持目录式 skills社区生态活跃有 ANNs 机制但文档门槛高支持有限MCP 支持内置 MCP 客户端配置简单支持支持插件/编辑器集成VSCode 插件、JetBrains 插件、桌面版有 IDE 扩展有 IDE 集成开源程度开源社区可二次开发部分开源闭源如果你重度使用 Claude 的思考链能力Claude Code 有它独特的好处如果你深度绑定 GPT 生态Codex 也不差。但如果你像我一样在不同项目里要用不同模型或者想在本地模型和商业模型之间横跳opencode 的“多模型”设计就非常舒服。它本质上把“模型”从“产品”里剥离了出来你自由选择后端甚至同一个会话里切换到不同的模型。2. 安装与初始化一次跑通不容易这里全是坑2.1 安装方式一览opencode 的安装方式很丰富我列几个主流方案按推荐程度排序。官方脚本安装macOS / Linuxcurl -fsSL https://opencode.ai/install | bashHomebrewmacOSbrew install sst/tap/opencodeGo 安装go install github.com/sst/opencodelatestnpm 安装npm i -g opencode-aiWindows官方提供 PowerShell 脚本或者用scoop install opencode也可以直接下载 GitHub Releases 里的 exe 文件手动放到 PATH。我自己的机器是 macOS用 Homebrew 装最省心。但这里要提醒一句如果你遇到“用 curl 脚本装完却找不到命令”的情况大概率是安装目录没有进到 shell 的 PATH 里。官方脚本默认装到~/.opencode/bin你需要确认类似下面的内容出现在你的~/.zshrc或~/.bashrc里export PATH$HOME/.opencode/bin:$PATH装完之后执行opencode --version能输出版本号基本就成功一半了。我建议顺便跑一下opencode upgrade如果你装的版本支持确保是最新版。opencode 迭代非常激进隔几周就有大版本更新2.0 之后 TUI、MCP 支持变化尤其大。2.2 Windows 报错“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”的完整修复这个报错是 Windows 用户最高频的问题。你敲opencodePowerShell 回你“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”本质原因只有一个系统在 PATH 环境变量里找不到opencode.exe。我帮朋友排查过几次情况基本都是三种。第一种安装过程没真正下载成功。Windows 默认的安全策略有时会拦截下载的 exe尤其是从 GitHub Releases 下载的东西SmartScreen 会弹蓝窗。你需要在弹窗里选择“仍要运行”或者在文件右键属性里勾选“解除锁定”。第二种exe 确实存在但 PATH 没包含对应目录。手动下载 exe 的朋友容易放在C:\Users\你的用户名\Downloads里直接运行那当然只在那个目录下能用。建议把opencode.exe放到C:\Users\你的用户名\.opencode\bin然后把%USERPROFILE%\.opencode\bin加到用户 PATH 环境变量。第三种PATH 加了但当前终端没生效。改完环境变量之后需要新开一个PowerShell 窗口不是用原来的窗口继续敲命令。你可以快速验证一下echo $env:Path看输出里有没有C:\Users\你的用户名\.opencode\bin这一项。没有就说明环境变量没生效手动加一下或者重启终端。还有一个更隐蔽的问题部分用户装了旧版本之后命令被注册成了别的名字比如opencode.exe在某个目录里但目录里另一个同名脚本优先被找到了。检查方法是在 PowerShell 里执行Get-Command opencode它会告诉你实际命中的可执行文件位置。这一步能解决 90% 的“明明装了却跑不了”的玄学问题。2.3 配置模型从云端到本地一锅端安装完之后你还需要告诉 opencode 用哪个模型。官方推荐方式是执行opencode auth login它会引导你登录各家云服务商把 key 存到系统钥匙串里。但更多开发者习惯直接把 API key 放到环境变量这两种方式 opencode 都支持。常用环境变量示例macOS / Linux 写进~/.zshrcWindows 在系统环境变量里配置export ANTHROPIC_API_KEYsk-ant-xxxx # 或者 export OPENAI_API_KEYsk-xxxx # 或者 export GOOGLE_API_KEYAIza-xxxx配好后进入 opencode按快捷键切换 provider 和 model就可以开始对话了。这里我特别想聊一下“免费模型”这个话题。你可能会在网上看到各种“免费 key”“免费端点”我很诚恳地劝一句那些来路不明的第三方接口大多不稳定你今天配好明天可能就 401甚至可能带来隐私风险。我自己的选择是两个安全路径一是本地模型完全免费、数据不出机器二是各家云厂商官方提供的免费额度比如 Gemini 就有免费额度配合 opencode 用足够了。本地模型配置也不复杂。以 Ollama 为例你先在本地启动一个模型比如ollama run qwen2.5-coder:14b。然后在项目根目录创建一个opencode.json{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama (local), options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:14b: { name: Qwen2.5 Coder 14B } } } } }云服务商的配置也类似把 provider 换成anthropic、openai、google等等。实际上 opencode 对 OpenAI-compatible 接口支持得很宽任何遵守该协议的本地推理服务包括 LM Studio、vLLM 等都可以用同一种方式接入字段基本是baseURL加模型名。配置完在 opencode 里选模型时你就能看到本地模型出现在列表里。2.4 编辑器插件与桌面版很多朋友习惯在 VSCode / JetBrains 里干活opencode 也提供了对应插件。插件本质上是把终端的 Agent 体验嵌进 IDE 侧边栏或面板你可以一边看代码一边和 agent 对话agent 的改动会直接以文件变更形式展示。VSCode 市场里搜“opencode”JetBrains 插件市场里搜“opencode”装好之后打开侧边栏登录一下就能用。但我自己的体验是插件适合“和 agent 共同改代码”用起来有点像结对编程而纯 terminal 的 TUI 适合“把任务丢给 agent 去跑”。比如我在做前端 bug 排查时会直接在 VSCode 里用 agent 读代码但如果是批量重构或者跨仓库操作我更喜欢回到终端。这里没有对错看个人习惯。另外 opencode 还有桌面版Desktop做得比较轻本质上是把 TUI 包了一层原生窗口加上了一些配置可视化。对于不喜欢命令行界面的朋友桌面版是一个很好的入口。不过桌面版目前仍然算快速迭代阶段偶尔会有些小 bug如果你追求稳定先踏实用 CLI 或 IDE 插件就好。3. 进阶玩法Skills、Memory、MCP 与真实场景3.1 Agent Skills把你的高频操作沉淀成斜杠命令skills 是 opencode 生态里我最喜欢的功能。一句话解释它允许你把一段操作流程写成 markdown 文档 脚本目录然后像斜杠命令一样在对话里触发。举个例子你团队有一套代码规范每次 review 都要检查某些点与其每次手动提醒 agent不如写一个 skill 让它自己执行。skill 的目录约定很简单全局的放~/.config/opencode/skills项目级的放.opencode/skills每个 skill 是一个子目录里面至少有一个SKILL.md。结构类似skills/ code-review/ SKILL.md review.py frontend-debug/ SKILL.mdSKILL.md就是一个带 frontmatter 的 markdown声明名称、描述然后正文里写具体步骤。比如一个“前端代码 Review”的 skill--- name: code-review description: 对当前分支的前端改动做一次 code review检查状态管理、副作用、内存泄漏等常见问题。 --- 1. 使用 git diff 找到当前分支的改动文件。 2. 重点检查状态更新是否有不可变性问题。 3. 检查 useEffect 依赖项是否存在遗漏。 4. 输出一份简洁的审查报告按严重程度排序。opencode 识别到用户输入“帮我 code review”时就会自动加载这个 skill按步骤执行。你还可以把脚本放进去让 agent 在合适的时候调用比如用一个review.py做静态检查。这不是“插件系统”那种重量级抽象而是更接近“给 agent 一本操作手册”简单直接。社区里有个很出名的 skill 集合叫 superpowers是 obra 发起的项目里面包含了 100 多个设计良好的 skill覆盖代码审计、TDD、需求拆解等场景。安装方式是在全局 skills 目录把仓库 clone 下来或者按它的文档用包管理器装。我试过把 TDD 相关的 skill 装到团队项目里agent 产出的测试覆盖率明显上升。这个方案的核心收益是团队知识可以被结构化地注入到 AI 工作流里而不是靠每次对话临时描述。3.2 Memory 实战让 Agent 记住项目约定热词里很多人关心 opencode memory。我理解的需求是怎么让 agent 在不同会话之间记住项目的技术栈、目录结构、编码风格甚至团队的 Git 约定。opencode 本身会维护每个会话的上下文但会话结束之后下一次 agent 默认不会记得上一个会话聊了什么。想要跨会话记忆我一般用两种方式组合。第一种是项目级约定文件。我习惯在项目根目录放一个.opencode.md里面写明技术栈、常用命令、构建方式、代码风格。opencode 每次启动时会自动加载这类文件作为上下文的一部分。这个文件就像团队的 README但专门写给 AI 看内容越具体agent 越不容易瞎猜。举个例子# 项目背书 - 前端React 18 TypeScript Vite - 后端Go Gin - 测试命令pnpm test --run - 不要修改 src/api 下的自动生成文件 - 新增接口时同步更新 swagger 文档第二种是 skill 式的记忆。把“项目契约”写成 skill名字可以叫 project-context这样你在新会话里敲/project-contextagent 就会读取并复习这些约定。这种方法比全局文件更可控因为你可以在任务开始时主动唤起记忆。网上提到的 opencode memory 也可能是指模型自身的长上下文能力。opencode 在 2.0 之后对长上下文的处理改善了很多但我不建议把整个代码库都塞给 agent。我的经验是给 agent 的上下文越精炼输出质量越高。与其让它海量阅读不如把核心约定写清楚然后在任务描述里告诉它“先看哪些文件”。3.3 MCP 配置与“mvn 配置”的谐音误会MCPModel Context Protocol是 Agent 接入外部能力的标准协议你可以理解为 AI 世界的 USB 接口模型本身不会做某件事但接上一个 MCP 服务器后它就能调用对应的工具。opencode 内置了 MCP 客户端配置方式是在opencode.json里加一个mcp字段。很多 Java 开发者搜索“opencode mvn 配置”我怀疑是把“MCP”输入法打成了“mvn”。当然也不排除有人确实想在 Maven 项目里用 MCP但核心还是同一个东西接入外部工具。下面是一个接入 Playwright MCP 的配置示例用于让 agent 获得操作浏览器的能力{ mcp: { playwright: { type: stdio, command: npx, args: [playwright/mcplatest], env: {} } } }用这个配置的前提是你本机有 Node.js 环境。配置好后opencode 就拥有了启动浏览器、点击页面、截图、读取 console 日志的能力。这个对前端 bug 排查帮助极大后面专门展开。MCP 的安全性值得多说一句给 agent 接的工具越多它的权限边界越大。我见过有人把数据库的 MCP 接上agent 跑测试时顺手执行了清表操作。所以我的建议是最小权限原则只有任务确实需要才接相应的 MCP 服务器生产环境、数据库这类高危工具除非你有严格的审批流程否则不要让 agent 随意调用。3.4 实战用 opencode Playwright 抓前端 bug这里分享一个我最近实际遇到的场景。有一个页面用户点击“提交订单”按钮后偶尔没反应但概率很低无法稳定复现。我让 opencode 开启浏览器会话在本地起了前端项目然后用自然语言描述任务“访问 http://localhost:5173/login登录后跳转到订单页点击提交按钮三次如果页面没有跳转截图并抓取 console 的所有报错。”opencode 通过 Playwright MCP 驱动真实浏览器在测试过程中它会自己看截图、读取 console 的报错信息然后根据反馈修改操作策略。最后它发现是某个接口返回了 500但前端 catch 到了却没给出任何提示所以看起来像是“点了没反应”。它把我的代码里一段吞异常的catch {}标出来并直接给出了修复建议。整个过程大概五分钟比我手动复现再打断点快很多。操作过程的体验类似这样启动 opencode输入任务agent 会先启动浏览器然后一步步操作每一步都会在终端里输出它正在做什么你可以中途插话也可以让它继续。不过要注意Playwright 驱动浏览器时默认是带界面的在无桌面环境的 Linux 服务器上需要 headless 模式配置方式通常是给 MCP 服务器传参数比如在 args 里加上--headless。另一种场景是“让 opencode 写 Playwright 测试脚本”。它会根据页面 DOM 自动生成 E2E 测试用例然后执行并把失败截图给你看。这个流程特别适合页面要重构、需要快速补回归测试的情况。我建议第一次用之前先确认前端服务地址、测试账号这类信息避免 agent 在登录环节反复试错浪费时间。4. 常见问题、排查思路与我的使用建议4.1 高频报错速查表下面整理的是我实际遇到或者帮别人解决过的高频报错按“错误信息—原因—解决办法”列成表格方便直接查。报错现象根本原因解决办法无法将 opencode 项识别为 cmdlet…PATH 没配置或没生效确认 exe 位置把目录加入用户 PATH新开终端验证opencode: error: unexpected server error. check server logs后端模型服务异常或 key 过期/接口限流打开日志opencode --verbose检查 API key、网络、模型服务状态401 unauthorized / invalid api keykey 配置错误或已失效重新opencode auth login或检查环境变量是否被覆盖模型回答很慢或卡住不动本地模型算力不足或云端限流换更小的模型或检查并发会话数量上下文超限 / context length exceeded单个会话里塞了太多内容新开会话把任务切小用.opencode.md收拢必要上下文插件登录失败IDE 版本或插件缓存问题更新 IDE 到新版本禁用再启用插件清理缓存“unexpected server error” 这个报错信息比较迷惑我第一次遇到还以为是 opencode 本身崩了后来用--verbose打开日志才发现是模型服务端返回了一个 5xx。如果你用的是本地 Ollama优先检查 Ollama 进程是否存活如果是云端模型先看 key 有没有余额、请求有没有被限流。定位问题的思路永远是先确认是 opencode 本身的问题还是上游模型服务的问题不要盲目重装。4.2 不是我泼冷水什么场景别用 opencode分享完优点我也想说一些边界。不是所有开发场景都适合用 opencode。如果你的任务对代码风格极其敏感比如大型遗留系统里有一堆“潜规则”没有文档agent 很容易产出“看起来对但风格完全不像”的代码。这时候更适合的做法是把规则写进.opencode.md或者 skill让 agent 先理解再动手。另外涉及生产环境数据库、密钥管理、线上热修复这类高风险操作我不建议直接丢给 agent 自动执行。opencode 的联网能力再强也只是一个“实习生”它不理解你公司的业务红线。我给团队的规范是agent 可以自由改代码、跑测试但涉及生产环境的任何操作都必须由人手动执行。还有一个心态上的建议不要把 opencode 当成“一次就能把整个项目重构成完美代码”的神器。它更擅长拆解小任务、执行确定性操作、快速给方案。我见过有人让它一口气重构一个 10 年老项目agent 跑了几十步后上下文乱了产出一堆半成品。正确的姿势是拆成多个可验证的阶段每阶段验收一次。记住一个原则越是确定性高的任务agent 越值得信任越是需要高层架构判断的越需要人主导。4.3 一个真实项目的接入记录最后用一个真实案例来收拢全文。我最近在一个内部管理系统项目前端 React后端 Go里正式接入了 opencode。团队之前没有统一的代码规范函数命名、组件拆分、接口错误处理风格参差不齐。我做三件事首先写了一个团队级的.opencode.md把技术栈、测试命令、文件目录约定、接口风格都写进去然后在项目.opencode/skills里加了两个 skill一个叫component-review一个叫api-handler分别管前端组件规范和 Go 接口错误处理最后在 CI 里加了一个可选阶段开发提 MR 时可以用 opencode 自动生成一份 code review 建议。实际跑了两个星期最大的变化不是“AI 帮我写了多少代码”而是“AI 让团队的隐性知识显性化了”。以前新同事总问我“这个项目的代码规范是什么”现在可以直接说“看.opencode.md或者跑一下/component-review”。opencode 在这里更像一个载体把团队的工程质量标准落到了 AI 工作流里。就我个人而言用 opencode 这段时间最大的体会是它并不是要取代程序员写代码而是把“打字”这件事的边际成本降到了很低。以前我要花一个小时去查一个 API 怎么调现在可以直接让 agent 去项目里搜用法、写示例、跑通再给我看。效率提升是实打实的但前提是你要愿意花一个下午去配置好模型、写好约定、给它足够清晰的上下文。你用得越认真它回馈的越多。 opencode：开源终端AI编程代理，安装配置与实战指南
说实话我第一次注意到 opencode 是在同事的终端录屏里。当时我正为一个跨 20 个模块的老项目发愁改一个接口要同时动前端类型、后端 mock、测试用例全靠手动翻文件。录屏里那哥们就敲了两三行命令opencode 自己打开项目、读了十几个文件、跑了一遍测试然后把改动整理成 PR全程不到十分钟。我当场被种草回去赶紧装了一个。opencode 是一个基于 Go 写的开源终端 AI 编程代理Agent。简单说它就是住在你命令行里的工程师给它一个任务目标它会自己规划步骤、读取代码、执行命令、查看运行结果直到任务完成。它不绑死某一家模型OpenAI 的 GPT 能用Anthropic 的 Claude 能用Google 的 Gemini 能用连你本地 Ollama 起的模型也能用它还通过 skills、MCP 协议接各种外部工具从浏览器测试到数据库查询都能覆盖。适合谁如果你受够了某个商业 Agent 的“全家桶绑定”想在终端里用一套顺手、可配置、支持多模型的 AI 编程工作流或者你就是单纯对“AI 自动改代码”这件事感兴趣opencode 都值得花一个下午认真试试。下面我把自己从安装、配置到实际开发中用得最顺的玩法还有踩过的坑全部整理一遍尽量做到“照着抄就能跑”。1. opencode 到底是什么一个住在终端里的 AI 工程师1.1 从“聊天助手”到“终端 Agent”这一步差在哪很多朋友一开始分不清“命令行里用 AI”和“AI Agent”的区别。你以前可能在终端里跑过类似chatgpt的命令行客户端本质上是把终端当成聊天窗口模型给你回一段文字你复制粘贴去执行。opencode 不是这个思路。它做的是“代理Agent”该做的事理解任务后自己拆解步骤、自己读写文件、自己执行命令、自己看测试输出然后根据结果决定下一步做什么。我用一个生活化的比喻普通 AI 编程助手像是你请了一个“聊天顾问”你说一句它回一句中间所有脏活累活还是你自己干opencode 更像你招了一个“远程实习生”你把需求写成一个 ticket 丢过去它自己看代码库、跑环境、试错、改代码最后把结果汇报给你。区别不在于能不能写代码而在于有没有“动手能力”和“闭环反馈”。这背后的核心技术是 Agent Loop模型先生成一个计划工具读文件、跑命令、搜索执行后把结果再喂回模型模型根据新信息修正下一步。这个循环在 Claude Code、Codex 这类产品里都有opencode 做得比较彻底的地方在于它把循环的每一步都暴露在终端界面上你可以随时看到 agent 正在读哪个文件、执行什么命令、为什么做这个决定。这种“可观测性”对调试特别重要。我实际用下来遇到 agent 走偏的时候一眼就能从日志里发现问题而不是看着一个黑盒干着急。1.2 为什么用 Go 写这件事值得注意opencode 的核心是用 Go 写的这不是一个无关紧要的实现细节。早几年市面上这类终端 Agent 大多基于 Node.js 或 Python好处是生态丰富坏处是依赖一堆运行时。你装一个工具可能要把 node_modules 拉一遍或者被 Python 版本折腾到怀疑人生。opencode 把核心编译成单个二进制文件装上就能跑跨平台体验非常一致。Go 带来的另一个直接好处是启动速度和内存占用。我在一台配置一般的办公笔记本上对比过Claude Code 启动大概要两三秒opencode 几乎是敲完回车就进入界面。长时间开着多个会话内存占用也比 Electron 壳的桌面工具低一个量级。作为一个每天要开几十次终端的开发者这种“轻”是会形成使用习惯的。另外因为核心是 Go它天然适合放到 CI 环境里。我在公司的流水线里加了一个阶段用 opencode 跑一个固定的 review 任务单二进制部署没有任何运行时问题。如果你习惯用 Docker也只需要基于一个瘦镜像把二进制拷进去。注意我这里说的是官方发布版的设计如此具体某个发行平台有没有额外打包逻辑建议以官方仓库的 README 为准。1.3 opencode 与 Claude Code、Codex 的横向对比市面上同类工具不少很多人会纠结“opencode、Codex、Claude Code 到底选哪个”。我这里不做“谁取代谁”的结论只把几个关键维度列成一张表方便你自己判断。对比维度opencodeClaude CodeOpenAI Codex底层语言GoTypeScript/Node闭源服务模型绑定多模型支持 Anthropic / OpenAI / Gemini / Ollama / OpenAI-compatible以 Claude 为主以 GPT 系列为主TUI 交互自带终端界面支持主题、vim 模式终端界面体验好但定制弱偏 CLI 风格Skills 机制支持目录式 skills社区生态活跃有 ANNs 机制但文档门槛高支持有限MCP 支持内置 MCP 客户端配置简单支持支持插件/编辑器集成VSCode 插件、JetBrains 插件、桌面版有 IDE 扩展有 IDE 集成开源程度开源社区可二次开发部分开源闭源如果你重度使用 Claude 的思考链能力Claude Code 有它独特的好处如果你深度绑定 GPT 生态Codex 也不差。但如果你像我一样在不同项目里要用不同模型或者想在本地模型和商业模型之间横跳opencode 的“多模型”设计就非常舒服。它本质上把“模型”从“产品”里剥离了出来你自由选择后端甚至同一个会话里切换到不同的模型。2. 安装与初始化一次跑通不容易这里全是坑2.1 安装方式一览opencode 的安装方式很丰富我列几个主流方案按推荐程度排序。官方脚本安装macOS / Linuxcurl -fsSL https://opencode.ai/install | bashHomebrewmacOSbrew install sst/tap/opencodeGo 安装go install github.com/sst/opencodelatestnpm 安装npm i -g opencode-aiWindows官方提供 PowerShell 脚本或者用scoop install opencode也可以直接下载 GitHub Releases 里的 exe 文件手动放到 PATH。我自己的机器是 macOS用 Homebrew 装最省心。但这里要提醒一句如果你遇到“用 curl 脚本装完却找不到命令”的情况大概率是安装目录没有进到 shell 的 PATH 里。官方脚本默认装到~/.opencode/bin你需要确认类似下面的内容出现在你的~/.zshrc或~/.bashrc里export PATH$HOME/.opencode/bin:$PATH装完之后执行opencode --version能输出版本号基本就成功一半了。我建议顺便跑一下opencode upgrade如果你装的版本支持确保是最新版。opencode 迭代非常激进隔几周就有大版本更新2.0 之后 TUI、MCP 支持变化尤其大。2.2 Windows 报错“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”的完整修复这个报错是 Windows 用户最高频的问题。你敲opencodePowerShell 回你“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”本质原因只有一个系统在 PATH 环境变量里找不到opencode.exe。我帮朋友排查过几次情况基本都是三种。第一种安装过程没真正下载成功。Windows 默认的安全策略有时会拦截下载的 exe尤其是从 GitHub Releases 下载的东西SmartScreen 会弹蓝窗。你需要在弹窗里选择“仍要运行”或者在文件右键属性里勾选“解除锁定”。第二种exe 确实存在但 PATH 没包含对应目录。手动下载 exe 的朋友容易放在C:\Users\你的用户名\Downloads里直接运行那当然只在那个目录下能用。建议把opencode.exe放到C:\Users\你的用户名\.opencode\bin然后把%USERPROFILE%\.opencode\bin加到用户 PATH 环境变量。第三种PATH 加了但当前终端没生效。改完环境变量之后需要新开一个PowerShell 窗口不是用原来的窗口继续敲命令。你可以快速验证一下echo $env:Path看输出里有没有C:\Users\你的用户名\.opencode\bin这一项。没有就说明环境变量没生效手动加一下或者重启终端。还有一个更隐蔽的问题部分用户装了旧版本之后命令被注册成了别的名字比如opencode.exe在某个目录里但目录里另一个同名脚本优先被找到了。检查方法是在 PowerShell 里执行Get-Command opencode它会告诉你实际命中的可执行文件位置。这一步能解决 90% 的“明明装了却跑不了”的玄学问题。2.3 配置模型从云端到本地一锅端安装完之后你还需要告诉 opencode 用哪个模型。官方推荐方式是执行opencode auth login它会引导你登录各家云服务商把 key 存到系统钥匙串里。但更多开发者习惯直接把 API key 放到环境变量这两种方式 opencode 都支持。常用环境变量示例macOS / Linux 写进~/.zshrcWindows 在系统环境变量里配置export ANTHROPIC_API_KEYsk-ant-xxxx # 或者 export OPENAI_API_KEYsk-xxxx # 或者 export GOOGLE_API_KEYAIza-xxxx配好后进入 opencode按快捷键切换 provider 和 model就可以开始对话了。这里我特别想聊一下“免费模型”这个话题。你可能会在网上看到各种“免费 key”“免费端点”我很诚恳地劝一句那些来路不明的第三方接口大多不稳定你今天配好明天可能就 401甚至可能带来隐私风险。我自己的选择是两个安全路径一是本地模型完全免费、数据不出机器二是各家云厂商官方提供的免费额度比如 Gemini 就有免费额度配合 opencode 用足够了。本地模型配置也不复杂。以 Ollama 为例你先在本地启动一个模型比如ollama run qwen2.5-coder:14b。然后在项目根目录创建一个opencode.json{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama (local), options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:14b: { name: Qwen2.5 Coder 14B } } } } }云服务商的配置也类似把 provider 换成anthropic、openai、google等等。实际上 opencode 对 OpenAI-compatible 接口支持得很宽任何遵守该协议的本地推理服务包括 LM Studio、vLLM 等都可以用同一种方式接入字段基本是baseURL加模型名。配置完在 opencode 里选模型时你就能看到本地模型出现在列表里。2.4 编辑器插件与桌面版很多朋友习惯在 VSCode / JetBrains 里干活opencode 也提供了对应插件。插件本质上是把终端的 Agent 体验嵌进 IDE 侧边栏或面板你可以一边看代码一边和 agent 对话agent 的改动会直接以文件变更形式展示。VSCode 市场里搜“opencode”JetBrains 插件市场里搜“opencode”装好之后打开侧边栏登录一下就能用。但我自己的体验是插件适合“和 agent 共同改代码”用起来有点像结对编程而纯 terminal 的 TUI 适合“把任务丢给 agent 去跑”。比如我在做前端 bug 排查时会直接在 VSCode 里用 agent 读代码但如果是批量重构或者跨仓库操作我更喜欢回到终端。这里没有对错看个人习惯。另外 opencode 还有桌面版Desktop做得比较轻本质上是把 TUI 包了一层原生窗口加上了一些配置可视化。对于不喜欢命令行界面的朋友桌面版是一个很好的入口。不过桌面版目前仍然算快速迭代阶段偶尔会有些小 bug如果你追求稳定先踏实用 CLI 或 IDE 插件就好。3. 进阶玩法Skills、Memory、MCP 与真实场景3.1 Agent Skills把你的高频操作沉淀成斜杠命令skills 是 opencode 生态里我最喜欢的功能。一句话解释它允许你把一段操作流程写成 markdown 文档 脚本目录然后像斜杠命令一样在对话里触发。举个例子你团队有一套代码规范每次 review 都要检查某些点与其每次手动提醒 agent不如写一个 skill 让它自己执行。skill 的目录约定很简单全局的放~/.config/opencode/skills项目级的放.opencode/skills每个 skill 是一个子目录里面至少有一个SKILL.md。结构类似skills/ code-review/ SKILL.md review.py frontend-debug/ SKILL.mdSKILL.md就是一个带 frontmatter 的 markdown声明名称、描述然后正文里写具体步骤。比如一个“前端代码 Review”的 skill--- name: code-review description: 对当前分支的前端改动做一次 code review检查状态管理、副作用、内存泄漏等常见问题。 --- 1. 使用 git diff 找到当前分支的改动文件。 2. 重点检查状态更新是否有不可变性问题。 3. 检查 useEffect 依赖项是否存在遗漏。 4. 输出一份简洁的审查报告按严重程度排序。opencode 识别到用户输入“帮我 code review”时就会自动加载这个 skill按步骤执行。你还可以把脚本放进去让 agent 在合适的时候调用比如用一个review.py做静态检查。这不是“插件系统”那种重量级抽象而是更接近“给 agent 一本操作手册”简单直接。社区里有个很出名的 skill 集合叫 superpowers是 obra 发起的项目里面包含了 100 多个设计良好的 skill覆盖代码审计、TDD、需求拆解等场景。安装方式是在全局 skills 目录把仓库 clone 下来或者按它的文档用包管理器装。我试过把 TDD 相关的 skill 装到团队项目里agent 产出的测试覆盖率明显上升。这个方案的核心收益是团队知识可以被结构化地注入到 AI 工作流里而不是靠每次对话临时描述。3.2 Memory 实战让 Agent 记住项目约定热词里很多人关心 opencode memory。我理解的需求是怎么让 agent 在不同会话之间记住项目的技术栈、目录结构、编码风格甚至团队的 Git 约定。opencode 本身会维护每个会话的上下文但会话结束之后下一次 agent 默认不会记得上一个会话聊了什么。想要跨会话记忆我一般用两种方式组合。第一种是项目级约定文件。我习惯在项目根目录放一个.opencode.md里面写明技术栈、常用命令、构建方式、代码风格。opencode 每次启动时会自动加载这类文件作为上下文的一部分。这个文件就像团队的 README但专门写给 AI 看内容越具体agent 越不容易瞎猜。举个例子# 项目背书 - 前端React 18 TypeScript Vite - 后端Go Gin - 测试命令pnpm test --run - 不要修改 src/api 下的自动生成文件 - 新增接口时同步更新 swagger 文档第二种是 skill 式的记忆。把“项目契约”写成 skill名字可以叫 project-context这样你在新会话里敲/project-contextagent 就会读取并复习这些约定。这种方法比全局文件更可控因为你可以在任务开始时主动唤起记忆。网上提到的 opencode memory 也可能是指模型自身的长上下文能力。opencode 在 2.0 之后对长上下文的处理改善了很多但我不建议把整个代码库都塞给 agent。我的经验是给 agent 的上下文越精炼输出质量越高。与其让它海量阅读不如把核心约定写清楚然后在任务描述里告诉它“先看哪些文件”。3.3 MCP 配置与“mvn 配置”的谐音误会MCPModel Context Protocol是 Agent 接入外部能力的标准协议你可以理解为 AI 世界的 USB 接口模型本身不会做某件事但接上一个 MCP 服务器后它就能调用对应的工具。opencode 内置了 MCP 客户端配置方式是在opencode.json里加一个mcp字段。很多 Java 开发者搜索“opencode mvn 配置”我怀疑是把“MCP”输入法打成了“mvn”。当然也不排除有人确实想在 Maven 项目里用 MCP但核心还是同一个东西接入外部工具。下面是一个接入 Playwright MCP 的配置示例用于让 agent 获得操作浏览器的能力{ mcp: { playwright: { type: stdio, command: npx, args: [playwright/mcplatest], env: {} } } }用这个配置的前提是你本机有 Node.js 环境。配置好后opencode 就拥有了启动浏览器、点击页面、截图、读取 console 日志的能力。这个对前端 bug 排查帮助极大后面专门展开。MCP 的安全性值得多说一句给 agent 接的工具越多它的权限边界越大。我见过有人把数据库的 MCP 接上agent 跑测试时顺手执行了清表操作。所以我的建议是最小权限原则只有任务确实需要才接相应的 MCP 服务器生产环境、数据库这类高危工具除非你有严格的审批流程否则不要让 agent 随意调用。3.4 实战用 opencode Playwright 抓前端 bug这里分享一个我最近实际遇到的场景。有一个页面用户点击“提交订单”按钮后偶尔没反应但概率很低无法稳定复现。我让 opencode 开启浏览器会话在本地起了前端项目然后用自然语言描述任务“访问 http://localhost:5173/login登录后跳转到订单页点击提交按钮三次如果页面没有跳转截图并抓取 console 的所有报错。”opencode 通过 Playwright MCP 驱动真实浏览器在测试过程中它会自己看截图、读取 console 的报错信息然后根据反馈修改操作策略。最后它发现是某个接口返回了 500但前端 catch 到了却没给出任何提示所以看起来像是“点了没反应”。它把我的代码里一段吞异常的catch {}标出来并直接给出了修复建议。整个过程大概五分钟比我手动复现再打断点快很多。操作过程的体验类似这样启动 opencode输入任务agent 会先启动浏览器然后一步步操作每一步都会在终端里输出它正在做什么你可以中途插话也可以让它继续。不过要注意Playwright 驱动浏览器时默认是带界面的在无桌面环境的 Linux 服务器上需要 headless 模式配置方式通常是给 MCP 服务器传参数比如在 args 里加上--headless。另一种场景是“让 opencode 写 Playwright 测试脚本”。它会根据页面 DOM 自动生成 E2E 测试用例然后执行并把失败截图给你看。这个流程特别适合页面要重构、需要快速补回归测试的情况。我建议第一次用之前先确认前端服务地址、测试账号这类信息避免 agent 在登录环节反复试错浪费时间。4. 常见问题、排查思路与我的使用建议4.1 高频报错速查表下面整理的是我实际遇到或者帮别人解决过的高频报错按“错误信息—原因—解决办法”列成表格方便直接查。报错现象根本原因解决办法无法将 opencode 项识别为 cmdlet…PATH 没配置或没生效确认 exe 位置把目录加入用户 PATH新开终端验证opencode: error: unexpected server error. check server logs后端模型服务异常或 key 过期/接口限流打开日志opencode --verbose检查 API key、网络、模型服务状态401 unauthorized / invalid api keykey 配置错误或已失效重新opencode auth login或检查环境变量是否被覆盖模型回答很慢或卡住不动本地模型算力不足或云端限流换更小的模型或检查并发会话数量上下文超限 / context length exceeded单个会话里塞了太多内容新开会话把任务切小用.opencode.md收拢必要上下文插件登录失败IDE 版本或插件缓存问题更新 IDE 到新版本禁用再启用插件清理缓存“unexpected server error” 这个报错信息比较迷惑我第一次遇到还以为是 opencode 本身崩了后来用--verbose打开日志才发现是模型服务端返回了一个 5xx。如果你用的是本地 Ollama优先检查 Ollama 进程是否存活如果是云端模型先看 key 有没有余额、请求有没有被限流。定位问题的思路永远是先确认是 opencode 本身的问题还是上游模型服务的问题不要盲目重装。4.2 不是我泼冷水什么场景别用 opencode分享完优点我也想说一些边界。不是所有开发场景都适合用 opencode。如果你的任务对代码风格极其敏感比如大型遗留系统里有一堆“潜规则”没有文档agent 很容易产出“看起来对但风格完全不像”的代码。这时候更适合的做法是把规则写进.opencode.md或者 skill让 agent 先理解再动手。另外涉及生产环境数据库、密钥管理、线上热修复这类高风险操作我不建议直接丢给 agent 自动执行。opencode 的联网能力再强也只是一个“实习生”它不理解你公司的业务红线。我给团队的规范是agent 可以自由改代码、跑测试但涉及生产环境的任何操作都必须由人手动执行。还有一个心态上的建议不要把 opencode 当成“一次就能把整个项目重构成完美代码”的神器。它更擅长拆解小任务、执行确定性操作、快速给方案。我见过有人让它一口气重构一个 10 年老项目agent 跑了几十步后上下文乱了产出一堆半成品。正确的姿势是拆成多个可验证的阶段每阶段验收一次。记住一个原则越是确定性高的任务agent 越值得信任越是需要高层架构判断的越需要人主导。4.3 一个真实项目的接入记录最后用一个真实案例来收拢全文。我最近在一个内部管理系统项目前端 React后端 Go里正式接入了 opencode。团队之前没有统一的代码规范函数命名、组件拆分、接口错误处理风格参差不齐。我做三件事首先写了一个团队级的.opencode.md把技术栈、测试命令、文件目录约定、接口风格都写进去然后在项目.opencode/skills里加了两个 skill一个叫component-review一个叫api-handler分别管前端组件规范和 Go 接口错误处理最后在 CI 里加了一个可选阶段开发提 MR 时可以用 opencode 自动生成一份 code review 建议。实际跑了两个星期最大的变化不是“AI 帮我写了多少代码”而是“AI 让团队的隐性知识显性化了”。以前新同事总问我“这个项目的代码规范是什么”现在可以直接说“看.opencode.md或者跑一下/component-review”。opencode 在这里更像一个载体把团队的工程质量标准落到了 AI 工作流里。就我个人而言用 opencode 这段时间最大的体会是它并不是要取代程序员写代码而是把“打字”这件事的边际成本降到了很低。以前我要花一个小时去查一个 API 怎么调现在可以直接让 agent 去项目里搜用法、写示例、跑通再给我看。效率提升是实打实的但前提是你要愿意花一个下午去配置好模型、写好约定、给它足够清晰的上下文。你用得越认真它回馈的越多。