最近被问得最多的一个 AI 编程工具，不是 Claude Code，也不是 Codex，而是 opencode。一开始我以为又是个套壳的终端助手，直到自己把它装进一个多模块的 Go 项目里实际干了两个星期，才理解为什么越来越多人把它写进自己的主力工作流。这篇文章不打算写官方文档的复读版，而是把我从安装、配置、接入编辑器，到用 skills、memory、LSP 和 Playwright 把 Agent 调教成能接手实际开发任务的完整过程，连同踩过的坑一起梳理出来，给正在观望或者刚上手 opencode 的人一个真实的参考。
1. opencode 是什么：一个重新定义“终端里的 AI 结对程序员”的开源项目
1.1 为什么最近大家都在聊 opencode
先说结论：opencode 是一个跑在终端里的 AI 编程 Agent，但它没有把赌注押在某一家的模型上。你可以给它配 Anthropic 的模型，也可以配 OpenAI、DeepSeek、智谱，甚至本地 Ollama 拉起来的开源模型。这个“模型自由”的打法，正好戳中了很多团队的痛点——不是所有人都愿意把代码库的上下文完全交给某一家云厂商，也不是所有人都受得了在 A 工具里用熟悉的模型、换到 B 工具又要重新折腾一遍配置。
它本身是一个开源项目，代码放在 GitHub 上，基于 MIT 协议。这意味着你可以直接读它的源码，看它到底把提示词拼成了什么样，也可以改源码满足自己团队的怪需求。我身边不少同事选择 opencode 的理由很朴素：同样是终端 Agent，Claude Code 虽然好用，但它的账号体系、订阅方式和模型绑定让一部分人觉得不够透明；Codex CLI 很酷，但如果你主力模型并不是 OpenAI 那一系，用起来总隔了一层。opencode 的做法是把“模型接入”做成一个可插拔的配置项，核心体验围绕“让 Agent 安全地读代码、改文件、跑命令”展开，而不是围绕某一家模型展开。
1.2 它和 Claude Code、Codex CLI 的本质差异
我自己三种工具都用过一段时间，列个对比表更直观：
| 维度 | opencode | Claude Code | Codex CLI |
|---|---|---|---|
| 开源程度 | 完全开源，可自行审计和修改 | 闭源，但可免费体验核心能力 | CLI 开源，服务端闭源 |
| 模型绑定 | 多 provider 自由切换 | 默认绑定 Claude 系列模型 | 默认绑定 OpenAI 系列模型 |
| 配置存储 | 本地 JSON 配置，天然适合纳入版本管理 | 配置逻辑偏内部化 | 配置项不少，但主体逻辑同样偏封闭 |
| 扩展能力 | skills、memory、LSP、Playwright 等 | 有 subagent 机制，但插件生态较封闭 | 插件机制相对有限 |
| 适合人群 | 喜欢掌控细节、有多模型需求的人 | Claude 生态忠实用户 | OpenAI 模型重度用户 |
这个表不是想说谁比谁强，而是想说明定位差异。opencode 更像一把瑞士军刀：每个单项功能未必做到行业最顶尖，但它把所有能力都摊开放在你面前，并且允许你用配置文件把它们串起来。Claude Code 开箱即用的体验确实顺滑，但如果你想让 Agent 遵循一套团队的内部规范，或者想让它通过 LSP 拿编译诊断而不是靠猜，opencode 的开放程度会带来明显优势。
1.3 一个真实的 opencode 工作流长什么样
我接手一个遗留项目时，第一次被 opencode 惊艳到。当时项目文档缺失、依赖古老、测试还跑不过，我先在项目根目录写了一个非常简单的AGENTS.md，里面写清楚：这是什么项目、用什么命令构建、测试入口在哪、有哪些不能动的历史包袱。然后在终端执行：
opencode进入 TUI 之后，我直接输入了一句任务描述：
先读一下 AGENTS.md 和 README，梳理这个项目的模块边界， 然后跑一遍测试，把失败用例和根因按优先级列出来，不要急着改代码。它做的事让我意外：先列出读到的关键文件，主动执行了几个只读命令来摸清项目结构，然后把测试失败的原因归类成“依赖版本导致”“资源文件缺失”“真正的逻辑回归”三类，最后生成了一份带文件路径和处理顺序的排查计划。整个过程没有改一个文件，所有操作都在我可见的命令日志里。这种“先理解再动手”的节奏，其实比让 Agent 直接冲上去改代码更适合实际工程场景。
2. 安装和首次运行：从零到让 Agent 在仓库里干活
2.1 三种主流安装方式，怎么选
opencode 的安装入口非常多，官方主推的是一键脚本，但我建议你根据自己所在的环境先想清楚再动手。
- macOS / Linux 用户：用 Homebrew 最省事，一条命令搞定后续升级。
brew install sst/tap/opencode- 任意平台通用：官方安装脚本，适合不想管包管理器的场景。
curl -fsSL https://opencode.ai/install | bash- Node 用户：如果你的机器上已经有 Node.js 环境，用 npm 全局安装也常见。
npm install -g opencode-ai我个人更推荐前两种。npm 方式的问题是全局 bin 目录在不同系统上差异较大，Windows 下尤其容易踩 PATH 的坑，这一点下面会展开说。另外，如果你在公司内网环境下，一键脚本偶尔会被安全策略拦下来，这时候直接去 GitHub Releases 页面下载对应平台的二进制也是可行的，记得把解压出来的目录手动加进 PATH。
2.2 Windows 下“无法将 opencode 识别为 cmdlet”的完整排查
这个问题几乎是 Windows 用户搜索 opencode 时最高频的报错，报错原文是：
opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。第一次看到这个报错，很多人第一反应是“没装上”，但真相往往不是没装上，而是装完之后命令所在目录不在 PowerShell 的 PATH 里。我把排查步骤按顺序写一下，照做基本能解决。
第一步，确认程序到底装到哪里了。如果用的是 npm 全局安装，运行：
npm config get prefix输出通常类似C:\Users\你的用户名\AppData\Roaming\npm。然后看这个目录下有没有opencode.cmd或者opencode可执行文件，有就说明安装成功，只是 PATH 没被正确识别。
第二步，检查当前会话的 PATH：
where.exe opencode如果这条命令有输出，说明当前会话能找到；如果报错找不到，说明 PATH 里缺失。解决办法是把 npm 的全局目录手动加进去。我比较推荐用 PowerShell 的用户级环境变量，避免要管理员权限：
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\你的用户名\AppData\Roaming\npm", "User")改完之后一定要开一个全新的终端窗口验证：
opencode --version第三步，如果 PATH 看起来没错但依然报这个错，那很可能不是 PATH 问题，而是 PowerShell 执行策略禁用了脚本。检查一下：
Get-ExecutionPolicy -List把 CurrentUser 作用域调整为RemoteSigned通常就够了：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这三个步骤基本覆盖了绝大多数“cmdlet 无法识别”的场景。我自己还遇到过一种情况：开了 Windows Terminal 但默认 Shell 是旧版 PowerShell，环境变量改了没刷新，重启 Windows Terminal 就正常了，所以遇到问题先别急着重装。
2.3 第一次启动：TUI、登录和第一个任务
安装成功后，在项目目录里直接执行opencode，会进入一个全屏 TUI。第一次进入时，它会提示你配置模型凭据。opencode 支持两种方式：
- 交互式登录：运行
opencode auth login，按提示选择 provider 并填入 API Key。 - 环境变量：在 shell 配置或系统环境变量里设置
ANTHROPIC_API_KEY、OPENAI_API_KEY这类变量。
我更推荐环境变量方式，因为后续换机器或者进 CI 时，配置可以用同一个模板复制，Key 不会散落到项目代码里。首次启动后，可以在 TUI 里输入一句话测试链路：
打印当前目录的文件树，并告诉我 .gitignore 忽略了哪些内容。如果能看到正确的输出，说明安装、登录、模型调用这一整条链路已经通了。这时再去试“读取文件”“修改文件”这类需要权限的操作，TUI 里每次执行写操作都会先征求你的同意，这个机制可以放心。
3. 模型接入与配置：把 opencode 调成顺手的样子
3.1 配置文件结构与多 provider 接入
opencode 的配置文件默认位于~/.config/opencode/opencode.json，Windows 下是%USERPROFILE%\.config\opencode\opencode.json。如果你熟悉 VS Code 的 settings.json，那对这个文件会非常亲切。一个最简配置长这样：
{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "api_key": "{env:ANTHROPIC_API_KEY}", "model": "claude-3-5-sonnet-latest" } }, "model": "claude-3-5-sonnet-latest" }注意{env:...}这种写法会从环境变量里读取 Key，不要在 JSON 里明文写 Key，否则哪天把配置发到群里就尴尬了。
如果团队内部同时用 OpenAI、DeepSeek 和本地模型，可以一次性把多个 provider 都配好：
{ "provider": { "anthropic": { "api_key": "{env:ANTHROPIC_API_KEY}", "model": "claude-3-5-sonnet-latest" }, "openai": { "api_key": "{env:OPENAI_API_KEY}", "model": "gpt-4o" }, "deepseek": { "api_key": "{env:DEEPSEEK_API_KEY}", "model": "deepseek-chat" }, "ollama": { "model": "qwen2.5-coder:14b" } } }需要哪个模型时，在 TUI 里可以用/models命令切换，改了默认模型之后新开的会话就会走新的 provider。这种“模型路由”能力，让我很少因为单一厂商限流而被卡住：Anthropic 配额紧张时，切到 DeepSeek 或本地模型继续做重构类任务，体验虽然略有差别，但至少不会中断工作。
3.2 模型选型思路与 opencode go 订阅
很多人刚开始用 opencode 都会纠结一个问题：到底用哪个模型最合适。我的经验是分任务类型来决定，而不是只盯着“最强”的模型：
- 需求分析、架构梳理、老代码解读：优先用上下文窗口大、推理稳定的模型，比如 Claude 的 Sonnet 系列或 GPT-4o，这类任务上下文长，小模型容易丢细节。
- 确定性重构、补测试、改注释：可以用便宜或本地模型，比如 DeepSeek、Qwen，速度不差，成本低一大截。
- 复杂调试、多文件联动修改：用最强的模型，哪怕慢一点也不怕，因为这类任务返工成本远高于调用成本。
至于热搜词里反复出现的 opencode go，它是官方推出的订阅服务，可以理解成把模型访问和托管执行环境打包在一起的方案，省去自己管理多个 Provider Key 的麻烦。如果你只是在本地个人项目里用，不一定要订阅；但如果你希望不同项目之间共享一套稳定的模型通道，又不想维护一堆环境变量，可以关注一下官方页面看它当前的套餐内容和模型清单。
这里想提醒一句：社区里流传的“免费模型中转通道”这几年下线得比翻书还快，稳定性完全不可控，我不建议拿这类通道接入到日常开发流程中。免费的代价通常是随时消失或者把你的上下文当训练数据，风险不值得。
3.3 两个高频报错的定位链路：模型不可用与 unexpected server error
这两个报错在搜索词里反复出现，我分别讲一下定位思路。
第一个是this model is not available in your country。这个报错本质上来自云端模型服务的区域开放策略，而不是 opencode 本身的问题。遇到时不要慌，先确认三件事：你的 API 账号所属区域是否在该模型的支持范围内；配置里写的模型 ID 是否真的对应一个对外提供服务的版本；你当前网络下访问到的服务端点是否是官方文档指定的端点。如果确认是区域策略问题，合规的做法是咨询服务商支持、使用该服务商在对应区域合法提供的接入方式，或者干脆换一个当前可用的等价模型。硬要绕过限制，既不稳定也不安全，没必要。
第二个是：
opencode error: unexpected server error. check server logs这个报错看着吓人，实际排查路径比较固定。第一步看是不是 Key 失效或者模型名写错，这是最高发原因。第二步用最简单的 curl 直接调一次 API 验证上游是否正常，例如：
curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-3-5-sonnet-latest","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'如果 curl 返回正常但 opencode 仍报错，再用opencode debug查看详细日志，重点看请求发送的模型名、API 地址、认证头是不是和自己预期一致。大部分“unexpected server error”最后都能定位到配置里的模型名与账号实际权限不匹配。
4. 编辑器集成：VS Code、JetBrains IDEA 和桌面版
4.1 VS Code 插件：面向日常开发的轻量入口
虽然 opencode 的主战场是终端，但日常开发里我大多数时候还是开着 VS Code 的。官方 VS Code 插件相当于给 TUI 套了一层编辑器界面：可以选中一段代码直接让 Agent 解释，也可以让它在右侧面板里展示修改 diff。插件的底层和终端版共享同一份配置，所以你在终端里调好的模型、skills 和 memory，在插件里开箱即用。
VS Code 插件在我这最常用的场景是“选中即解释”：鼠标选中一段让人头疼的旧代码，Ctrl+Shift+P 调出命令面板，选择 OpenCode 的解释功能，再把问题说清楚。这样不用切到终端就能完成问答，上下文自动带上选中内容，省去了反复复制粘贴的痛苦。
不过要注意，插件模式和终端模式的权限逻辑不完全一样。在插件里，Agent 执行写操作时同样会在面板里请求授权，这个动作不要直接点“允许所有”，尤其是当它说要修改多个文件时，先看 diff 列表再决定。插件界面里查看 diff 比终端 TUI 里方便得多，这是插件的一大优势。
4.2 JetBrains IDEA 插件与 Maven 项目配置
在 JetBrains 系 IDE 里使用 opencode，体验跟 VS Code 稍微不一样。IDEA 插件默认会继承当前项目的 SDK 和构建工具配置，所以对 Java 项目来说，只要 IDE 本身能正常跑 Maven，Agent 通常也能正确调用mvn命令。
我在 IDEA 里踩过最深的坑是 Maven 项目里的多模块依赖。Agent 单独编译某个子模块时没问题，但只要涉及跨模块引用，它就容易忘记先去根目录执行mvn install把依赖装进本地仓库。后来我在项目根目录的AGENTS.md里明确写了这条约定：
本项目是多模块 Maven 项目。 修改任何子模块后需要在本模块运行 mvn test 前，先执行: mvn -q -pl <模块> -am install -DskipTests加上这条之后，Agent 在 IDEA 里跑测试的失败率明显下降。另一个值得花时间的是把 IDEA 的 Maven Runner 配置里的 JVM 参数和 opencode 的环境变量对齐，否则可能遇到 Agent 命令行里跑不过、IDE 里却能跑过的奇怪情况，本质是运行时环境不一致。
4.3 桌面版和 CLI 的关系
桌面版是我最近才开始用的。它的定位不是替代 IDE 插件，而是给不习惯终端操作的人一个低门槛入口。桌面版的界面更接近一个独立应用，左侧是任务列表，右侧是对话和文件变更预览，底层依然是同一个 opencode 引擎。如果你身边有同事对终端有心理障碍，但又想体验 Agent 编程，桌面版是很好的过渡工具。
对于已经习惯 TUI 的人来说，桌面版的效率未必更高，但它有一点好处：可以同时挂多个项目的任务窗口，而 TUI 里切换项目需要退出重进。我的建议是日常单项目开发用 TUI 或 IDE 插件，桌面版留着做多项目并行时的辅助窗口。
5. 进阶玩法：skills、memory、LSP 和 Playwright 组合拳
5.1 skills：把团队规范变成 Agent 的行为准则
用过 Claude Code 的人应该对 skills 这个概念不陌生：它是一段结构化的行为指令，让 Agent 在特定任务出现时自动加载对应的工作流程。opencode 也支持类似的技能机制，而且目录组织很直观。
你可以在项目根目录放一个.opencode/skills/目录，也可以在全局配置目录下建skills/目录。每个技能就是一个 Markdown 文件，文件头用 YAML 写元信息，正文写具体步骤。我拿团队里沉淀过的一条前端 bug 排查技能举例：
--- name: frontend-bug-hunt description: 当用户描述一个前端页面 bug 时，按此流程排查 --- 1. 先确认开发服务器是否已启动，未启动则执行 npm run dev。 2. 用 Playwright 打开对应页面 URL。 3. 记录 console 报错和 network 请求状态。 4. 如果问题涉及交互，按用户描述的操作步骤逐步复现。 5. 将报错信息和可能原因一起输出，不要直接改代码。设置好之后，只要在对话里提到“页面有问题”“按钮点了没反应”这类描述，opencode 就会自动加载这个技能并按照其中的步骤展开，而不是面目模糊地边猜边改。
社区里也有很多现成的技能包可以参考，比如 superpowers 这类把常见工程任务沉淀成技能的合集。我的建议是不要直接把别人的整套技能包塞进来，而是抽出与当前项目相关的部分，因为技能文件越多，Agent 每次匹配时的噪音也越大。
5.2 memory：让 Agent 记住你的工程习惯
opencode 的 memory 是我最依赖的功能之一。它解决了 Agent 编程里一个隐蔽痛点：每个新会话都是“失忆”的，哪怕昨天刚交代过的约定，今天新开会话它又忘了。
memory 本质上是一份持久化的文档/目录，opencode 会在会话初始化时读取它，相当于每次对话前你先给它“喂”了一段背景信息。我会把团队和个人的工程约定写在这里，例如：
- 这个项目的 Python 版本是 3.12，依赖统一用 uv 管理。
- 测试命令是
uv run pytest，不是python -m pytest。 - 提交信息遵循 Conventional Commits。
- 禁止在业务代码中直接使用
print调试，统一用 logging。
把这些内容写进 memory 之后，Agent 在遇到相关场景时会自动带上这些约束。我个人的体会是，memory 的价值在于把“重复交代”的隐性成本降到了零。新接手一个项目时，先花十分钟把项目背景写进 memory 或AGENTS.md，后面整个开发过程都会顺畅得多。
5.3 LSP：让 Agent 拿到编译器级别的诊断
默认情况下，Agent 看代码和你看代码差不多，都是“读文本”。但 opencode 支持接入 LSP（Language Server Protocol），让 Agent 调起语言服务器来获取类型信息、编译诊断、跳转定义等能力。这意味着它不再靠肉眼找 bug，而是能拿到编译器实时报告的错误清单。
配置 LSP 需要在opencode.json里声明，例如给 TypeScript 项目接入的类型服务：
{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] } } }这里需要系统已经安装了对应的 language server。以 Python 项目为例，一个可选方案是pyright-langserver；Java 项目对应的是jdtls。配置完成后，当 Agent 需要理解代码结构时，会主动通过 LSP 拉取诊断信息。我自己在改一个 TypeScript 旧项目时，Agent 能准确说出“这里报的错是类型不匹配，不是运行时异常”，就是靠 LSP 拿到的上下文，而不是靠提示词里的运气。
5.4 Playwright：自然语言驱动浏览器排查前端 bug
前端 bug 是 Agent 编程里最头疼的场景，因为很多问题只有打开页面才能复现。opencode 内置了对 Playwright 的支持，这让 Agent 可以真的打开浏览器、点击按钮、读取控制台报错，而不是对着代码空想。
我常用的完整链路是这样：先在项目里确认 Playwright 环境可用（npx playwright能正常跑），然后给 opencode 下一条类似这样的指令：
用 Playwright 打开 localhost:3000，进入用户中心，点击“导出报表”按钮， 把页面出现的 console 错误和网络请求里的 4xx/5xx 状态码整理出来。Agent 会执行类似npx playwright test或者直接调用浏览器工具的流程，把页面交互、报错信息带回来，再结合源码分析根因。这个过程本质上把“人工复现 bug”的时间压缩到了原来的十分之一。要注意的是 Playwright 本身的浏览器依赖要先安装好，否则 Agent 会停在环境问题上报错退场。这个功能对现在频繁迭代的前端项目价值非常大，也是我目前向团队推荐 opencode 时最常演示的场景。
6. 横向对比与选型：opencode、Codex、Claude Code、Pi，到底选谁
6.1 四种终端 Agent 的定位差异
搜索词里频繁出现“opencode codex claude code”“opencode codex pi哪个agent好用”，说明大家在不同 Agent 之间纠结得很真实。我根据自己的使用经验把它们的定位再拆开讲一下。
- Claude Code：如果你主力模型是 Claude，且不想折腾配置，它的开箱体验是最好的。它的问题在于生态相对封闭，想要自定义技能和接入外部工具会受限。
- Codex CLI：适合重度使用 OpenAI 模型的人。CLI 本身开源，但服务端逻辑和模型绑定比较强，自定义空间同样有限。
- opencode：胜在开放和可组合。多模型切换、skills、memory、LSP、Playwright 全都能通过一套配置串起来。代价是如果你想“开箱即用”，需要花点时间做初始配置。
- Pi：据我了解是一款更轻量的终端 Agent，主打简单快速接入。适合偶尔用来处理小任务，但在需要多文件、长上下文、复杂工具调用的工程场景下，生态和扩展能力还不完善。
选型这件事，与其比较谁的模型强，不如看你需要什么样的控制力。如果你希望 Agent 的行为能被团队规范、项目约定、本地工具链精确约束，opencode 是四个里面最合适的。
6.2 我的实测感受与选型建议
我用 opencode 跑了两个不同类型的项目：一个 Python 数据处理服务，一个 TypeScript 前端中后台系统。坦白说，初期体验并不完美，遇到最多的不是能力问题，而是“上下文没对齐”问题：它有时会不知道项目里有构建脚本，或者不知道某个约定。但这些问题大部分靠AGENTS.md和 skills 就能解决，一旦把这些工程上下文喂进去之后，稳定性大幅提升。
相比之下，Claude Code 初期更“聪明”，因为它的默认提示词和模型调校做得很好，但遇到团队特有规范时，它的自定义路径要绕一些。Codex CLI 在 OpenAI 模型下表现很好，但如果团队已经采用混合模型策略，它反而成了单一绑定的限制。
我的选型建议一句话总结：如果你想要的是“最强单个模型体验”，选择你最喜欢模型对应的官方 Agent；如果你想要的是一个可以被团队制度、工程规范、本地工具链改造的 Agent 框架，opencode 是当前最值得投入时间的选项。它不会让你的代码一夜变好，但会让你把好的规范稳定地重复执行下去。
最后分享一点我自己的使用体会。opencode 真正打动我的不是某个炫酷功能，而是它把“人、Agent、代码库”之间的上下文传递做得足够透明。Agent 读到了什么、执行了什么命令、为什么这么改，每一步都能回溯，这在一个多人协作的仓库里意味着安全感和可控性。工具本身只是起点，真正让 Agent 从玩具变成生产力的，是你愿不愿意把团队里的隐性知识沉淀成 skills、memory 和AGENTS.md这样的显式文件。这一步做完，opencode 能替你干的活，远比想象中多。
