先说结论我最近把手头的两个业务项目和一个开源小工具全部从 Claude Code 迁到了 opencode。起因不算复杂——我需要一个开源的、配置透明的、能自由换模型的终端 Agent而 opencode 恰好把 TUI终端界面、配置管理、Skills 扩展这些点都做对了。如果你已经在用 Claude Code 或 Codex或者正准备入坑 AI 编程助手这篇就是我在实际项目中跑通 opencode 的完整记录包括安装、配置、编辑器联动和避坑。我尽量按“我当时怎么想的、怎么查的、最后怎么解决”的顺序来写不罗列文档只讲实操。1. 被一个截图逼出来的工具迁移我为什么开始用 opencode1.1 从 Claude Code 迁移的三个直接原因先交代背景我之前是 Claude Code 的重度用户终端里跑 SSH、改代码、提交 PR 基本都靠它。但用了几个月有三件事越来越难受。第一是配额和套餐拆得太碎。大型模型按套餐卖用超了要么排队、要么单独加购团队里几个人共享一个账号更是难受。我需要一个能直接看到 token 消耗、能按项目切换不同模型、甚至能接本地模型的方案。opencode 的做法是模型成本全部走你自己的 Provider Key开源内核免费用多少模型付多少钱账单透明。第二是配置黑盒。Claude Code 的很多行为是内置的我自己想改 system prompt、挂一个内部规范文档、塞一条团队代码风格要求都得绕路。opencode 把配置收敛在opencode.json和 Skills 目录里改了就是改了没有隐藏逻辑。第三是“接手陌生项目”的能力。Claude Code 对老项目尤其是没有完整索引的仓库做全局理解需要额外配置而 opencode 的 agent 模式在扫描目录、读取关键文件、生成待办清单方面的节奏更接近我人工看代码的方式——先看 README、再看 package.json / pom.xml、然后看目录结构、再定位入口。如果你问我“opencode 是哪家公司的”它是 SST 团队Anomaly Innovations推出的开源项目SST 本身是做 Serverless 开发框架的团队所以在打磨开发者工具这块不缺积累。这也是我把核心工具押在它身上的信心来源之一。1.2 opencode 到底改了什么交互范式一个很容易被忽略的点是opencode 的主界面是 TUI但它并不是让你在终端里“聊天”那么简单。它的左侧是会话列表右侧是代码编辑区底部是输入框。你在输入框里让 Agent 改文件它会直接以 diff 形式展示改动你可以逐行接受/拒绝而不是让 AI 把整段代码“吐”到聊天窗口里再手动复制。这种交互有两个直接影响上手成本低了VSCode 那边插件也沿用了同样的 diff 交互从终端切到编辑器没有割裂感。误改面更小Agent 并行改多个文件时我可以只挑某几个文件的改动接收其余驳回这比“全部接受”安全得多。另外opencode 的会话里可以随时切换模型。比如我先用 claude-3.5-sonnet 做大范围重构然后切到便宜的小模型做重复性补注释这种事情不用起两个会话对话内直接切。提示如果你之前只用过网页版 AI 编程助手第一次打开 opencode 的 TUI 可能会觉得“就这”。请务必把文件编辑权交给它让它改一个真实项目试试感受才会出来。2. 安装到跑通跨平台环境准备与 cmdlet 报错的完整排查2.1 官方脚本和 npm 两种安装方式怎么选opencode 的安装方式常见有两种# 方式一官方安装脚本macOS / Linux curl -fsSL https://opencode.ai/install | bash # 方式二npm 全局安装需要 Node.js 18 npm install -g opencode-ai我自己在 macOS 上用的官方脚本装完二进制放在~/.opencode/bin下npm 方式则会把可执行文件链接到全局 node_modules 的 bin 目录里。两种方式本质是一样的最终都是拿到一个opencode可执行文件。这里有个容易被忽略的点选择哪种方式决定了后续升级命令和服务环境变量。官方脚本安装的版本升级通常用同一条脚本重跑npm 装的升级用npm update -g opencode-ai。我建议团队内统一一种方式否则不同机器上版本不一致排查问题时很烦。2.2 Windows 下cmdlet、函数、脚本文件或可运行程序报错的根因我同事第一次在 Windows 上跑opencode --versionPowerShell 直接给了一行红色报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确保路径正确然后再试一次。这个报错翻译成人话就是PowerShell 在当前 PATH 环境变量里找不到opencode。注意这不一定是没装上更常见的是装上了但 PATH 没生效。排查链路按下面这几步走先确认安装产物在哪。如果你用 npm 装的执行npm ls -g opencode-ai能看到版本号就说明包装成功了。找到 npm 全局 bin 目录npm prefix -g比如返回C:\Users\你的用户名\AppData\Roaming\npm那opencode.exe应该就在这个目录下。手动把该目录加进用户 PATH。可以在 PowerShell 执行[Environment]::SetEnvironmentVariable(Path, $env:Path ;C:\Users\你的用户名\AppData\Roaming\npm, User)关掉当前终端重新打开一个 PowerShell再执行opencode --version这里最容易踩的坑是第 4 步。很多人加完 PATH 后在原窗口继续跑发现还是报错就以为安装方式不对其实只是当前会话的环境变量没刷新。如果你是走官方脚本安装那多半是脚本把二进制放到了%USERPROFILE%\.opencode\bin之类的目录同样检查 PATH 是否包含该目录即可。装完后如果想在 IDEA 插件、VSCode 扩展里让 opencode 作为后端也必须确认这个可执行文件在 PATH 里否则编辑器插件会一直提示“找不到 opencode”。2.3 首次运行和几个高频命令安装完成后先做一次登录/密钥配置opencode auth这个命令会列出一批可用的模型服务商选一个粘贴 API Key 即可。我更推荐直接手动写配置文件原因下一节详细说。日常使用中这几个命令我基本每天都会用到# 启动交互式 TUI opencode # 非交互模式直接让 opencode 分析某个文件并输出结果 opencode run 看一下 src/main/java 下哪些类有问题 # 查看当前使用的模型和配置 opencode models # 打开终端 UI 的调试日志排查问题很有用 opencode --print-logs第一次跑opencode run会有一个建立项目索引的过程项目越大越久。不要以为卡死了耐心等。索引完后续会话会明显变快。3. 模型接入与配置从免费模型到 CC Switch 的多 Provider 管理3.1 opencode.json 核心字段Provider、Model、Options 是怎么协作的opencode 的配置中心是一个opencode.json文件默认位置在当前项目的根目录也可以放到全局配置目录。核心结构是这样的{ $schema: ./node_modules/opencode-ai/schema.json, provider: { ollama: { npm: ollama/opencode-provider, name: Ollama Local, models: { qwen2.5-coder:14b: { name: Qwen 2.5 Coder 14B } } }, my-openai-compatible: { npm: opencode-ai/openai-provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { gpt-4o-mini: { name: GPT-4o Mini } } } }, model: ollama/qwen2.5-coder:14b }字段之间的关系是这样的provider是“模型服务商”可以同时配很多个。每个 provider 对应一个安装包npm字段opencode 会通过 npm 自动加载这个 provider 的适配器。models是这个服务商下面可用的模型列表可以给模型起别名。options是一些传输层参数baseURL指向服务商的接口地址apiKey可以是明文也可以写成{env:MY_API_KEY}这种从环境变量读取的方式——我强烈建议用环境变量方式不要把密钥提交进 Git 仓库。最下面的model字段是默认模型格式是“provider名字/模型名”。提示不要凭记忆手写字段。opencode.json 里的$schema字段指向官方 Json Schema你用 VSCode 打开这个文件时会自动获得字段补全和校验提示。配置字段眼花缭乱时让 schema 做你的字典。3.2 免费模型怎么接Ollama 本地模型和免费额度服务商很多人一搜“opencode 免费模型”第一反应是去网上找各种限时免费的模型源。我可以很直接地告诉你这类社区免费源比如之前流传过一阵的 hy3-free非常不稳定随时可能下线我实测遇到过来回超时的情况根本不具备生产可用性。我更推荐两条稳妥路线。第一条路线本地 Ollama。如果你有一台 16GB 以上内存的机器跑 7B~14B 的代码模型完全可行# 安装并拉取一个代码模型 ollama pull qwen2.5-coder:14b然后在 opencode.json 里配上上面的 ollama provider。选这个方案的好处是无网络依赖离线也能跑不产生任何 token 费用适合处理不方便出本机的敏感代码片段。坏处也显而易见小参数模型在复杂任务上的表现距离云端大模型有明显差距我通常只用它做补注释、生成单测模板这类低难度任务。第二条路线用有免费额度的模型服务商。现在不少模型平台对新用户有免费 token 额度你只需要申请一个 API Key然后配进 opencode 的 provider。opencode 对 OpenAI 兼容接口的支持比较完善只要是兼容协议一般都能接。我的建议是把免费额度当成“试用环境”用来熟悉配置和写一些小脚本没问题真正接手大项目时还是用付费的可靠模型。3.3 CC Switch 联动一套配置秒切全家桶用过 Claude Code 的人可能知道 CC SwitchClaude Code Switch这个工具它的作用是管理多套 Claude Code 配置做快速切换。因为 opencode 在配置设计上和 Claude Code 有不少互通思路网上可以看到很多人用 CC Switch 同时管理 Claude Code 和 opencode 的 Provider 配置。我自己的操作方式很简单为 opencode 单独建一份全局配置放在~/.config/opencode/opencode.json不同项目的覆盖配置写在各自项目的opencode.json里比如 A 项目默认用本地 OllamaB 项目默认用付费大模型需要整体切换“某个环境”时用 CC Switch 或手动替换配置目录。“opencode go 需要配合 CC Switch 等工具”这个说法其实指的就是这种配置管理的工作流。虽然 opencode 本身支持opencode.json的分层配置但当你同时用多套 Agent 工具时统一一个入口管理所有密钥和 BaseURL 会省心非常多。我踩过的一个坑是同一个 API Key 同时配在 Claude Code 和 opencode 里结果某平台的超额告警一直响后来才发现是两边各算各的用量。建议同一个服务商的相同用途尽量只在一边配置避免用量翻倍。4. 编辑器集成VSCode 插件、IDEA 插件和桌面版的定位差异4.1 VSCode 插件从 TUI 到图形化 diff 的无缝过渡在 VSCode 扩展市场搜 opencode会看到官方插件。装上之后侧边栏会多一个面板可以直接在编辑器里发起会话。我最常用的场景是这样的在编辑器里选中一段代码右键选择“发给 opencode”然后在面板里输入修改意见。Agent 改完后改动会以 diff 形式展示在编辑器的“时间线”区域我可以逐个文件查看、接受或拒绝。这款插件的核心价值不只是“图个好看”而是能复用 VSCode 本身的代码上下文。选中代码时插件会自动把相关文件路径、光标位置、当前文件的语言类型带着一起发过去Agent 不需要猜你指的是哪一段。这在改一个几千行的大文件时特别好用减少了很多“上下文来回确认”的时间。安装后如果面板提示找不到 opencode回到第 2 节检查可执行文件是否在 PATH 中。VSCode 插件本身不内置 opencode 运行时它只是壳后端还是那个命令。4.2 JetBrains IDEA 插件Java/Maven 项目的接入细节如果你主力 IDE 是 JetBrains IDEA 或全家桶其他成员插件市场里同样能找到 opencode。Java 项目Maven 结构接入时有一个细节要注意opencode 在分析项目时可能会调用系统命令做构建检查或者读取 Maven 配置来判断依赖结构。如果你的mvn不在 PATH 里插件能看代码但经常无法准确判断“这个类依赖哪个 jar”分析精度会下降。所以先用命令行确认一下mvn -v如果报mvn 不是内部或外部命令你需要先配好 Maven 环境变量或者至少在 IDEA 的 Settings - Build Tools - Maven 里指定好 Maven home path。还有 Maven 仓库的镜像如果配的是内网私服确保 opencode 插件运行时的网络环境能够访问到私服否则依依赖分析会一直转圈。IDEA 插件的 diff 交互和 VSCode 版不太一样它把改动展示在运行面板下方的专用区域可以直接“单文件应用”。这个设计更符合 JetBrains 用户的使用习惯毕竟你已经很熟悉“先看预览再逐个应用”的节奏了。4.3 Desktop 桌面版适合谁的普及型入口opencode 桌面版opencode desktop是给不想在终端和编辑器之间频繁切换的人准备的。它是一个独立窗口左侧会话列表右侧对话和文件改动预览整体体验比 TUI 更“图形化”。我个人的看法是桌面版适合几类人——你主要用浏览器和聊天工具处理开发诉求不想改自己的 IDE 习惯你需要同时监控多个项目的 Agent 任务用一个独立窗口做“控制台”你带了几个不太熟悉命令行的同事桌面版能降低他们的使用门槛。但如果你本身就在 VSCode/IDEA 里高强度工作我更推荐用对应的编辑器插件因为插件能直接拿到编辑器里的选中内容和文件上下文桌面版则需要你手动粘贴文件路径或内容效率低一个档次。提示桌面版和插件版可以共存。我自己的习惯是小需求直接在 VSCode 插件里解决批量处理多个仓库或做全量重构时开一个桌面版窗口专门盯着任务队列。5. Skills 与 Memory把 Agent 从实习生带成老员工5.1 Skills 机制为什么是扩展性的核心Skills 是 opencode 的“能力外挂”。默认情况下Agent 只能做代码生成、文件读写、命令行执行这些基础操作。但装上特定 Skills 之后它可以具备更加专业的行为模式。你可以把 Skills 理解为给 Agent 定制的“岗位培训手册”和“工具清单”。Skill 的本质是一个带SKILL.md的目录里面写清楚这个技能的触发条件、执行步骤、使用哪些脚本。opencode 会在对话过程中根据用户的意图去匹配并加载合适的 Skill而不是把所有 skill 全部塞进上下文——这一点很关键避免了上下文爆炸。5.2 安装 superpowers一套开箱即用的高阶能力包你在相关工具社区里常看到的 opencode 安装 superpowers就是一个集成式 Skill 库。激活之后它会为 Agent 补充一系列能力比如更规范地拆解任务、写测试、做代码审查等。安装方式通常是把仓库克隆到 opencode 的 skills 目录然后重启 opencodegit clone https://github.com/作者/superpowers ~/.config/opencode/skills/superpowers装完之后一个比较明显的变化是Agent 在拿到一个复杂需求时会先输出“任务拆解清单”列出自己要读哪些文件、要改哪些代码、要写哪些测试然后再动手。这个过程看起来多了一步但实际上大大降低了“改到一半发现理解错了”的概率。我自己还积累了另一个习惯不只是装别人的 superpowers还会为团队写一个“团队约定”的 Skill。目录结构大致如下~/.config/opencode/skills/my-team-rules/ ├── SKILL.md └── scripts/ └── check-commit-format.mjsSKILL.md的头部是 YAML 格式的元信息比如 name、description、when_to_use。正文写触发条件和处理流程。比如我要求 Agent 在所有提交信息里强制带 JIRA 单号这个规则就写进这个 Skill再配合一个小脚本做二次校验。效果比口头提醒好很多。5.3 Memory 持久化让 Agent 记住项目偏好和历史决策opencode 的 Memory 功能简单说就是让 Agent 跨会话记住一些关键信息。以前用 Claude Code 时每次新开会话都要重新告诉它“我们项目的测试命令是 npm run test:unit不是 npm test”很烦。opencode 的做法是把记忆问题转换为可持久化的文件内容。你可以在项目中维护一个 memory 目录或者通过 opencode 内置的 Memory 管理命令把“项目事实”写进指定文件。之后每次会话开始时Agent 会自动读取这些备忘录。我遇到的实际案例有一个项目用的是 pnpm workspace包管理器版本要求 8 以上。第一次干活时我明确告诉 Agent 用 pnpm 8第二次新开会话它又想用 npm 试。写入 Memory 之后它每次都直接用 pnpm再没犯过。写 Memory 的时机不必很刻意。我在完成一次比较有价值的“项目事实澄清”后会让 Agent 把结论补进记忆文件。这个动作 10 秒钟但能避免未来无数次的重复沟通。5.4 用 Playwright Skill 让 Agent 自己测前端 bug最后重点说一个我特别喜欢的玩法通过 opencode 的 Playwright Skill 让 Agent 直接在浏览器里操作页面复现并验证前端 bug。以前遇到“前端页面点登录没反应”这种问题我的流程是自己打开控制台、定位按钮事件、翻代码找原因一轮下来最少半小时。用 opencode 之后流程变成了在对话里告诉 Agent“打开项目的本地开发服务器localhost:5173点首页的用户菜单确认下拉列表是否展示然后尝试登录账号用测试账号 xxx密码 yyy。”opencode 的 Playwright Skill 会接管一个真实浏览器实例打开页面、执行点击、截图、把控制台日志返回给 Agent。Agent 根据页面表现和日志定位到具体代码文件直接给出修复建议或动手修改。这中间最关键的一点是Playwright 给 Agent 提供了“真实的感知通道”它不再靠猜而是真的能看到页面渲染结果和浏览器报错。前端 bug 很多都是交互时序问题光看代码很难复现给一个真实浏览器让它操作效率完全不一样。注意这个 Skill 需要本机有可用的 Chromium 浏览器第一次跑会自动安装对应内核。在 CI 环境里如果没有图形界面可以用 headless 模式我在本地还是习惯让浏览器弹出窗口便于我同步观察。6. 实战横评与踩坑记录opencode、Claude Code、Codex、pi 的取舍6.1 四款常见 Agent 的选型维度对照表我实际用了 opencode、Claude Code、Codex以及另外一个在社区口碑不错的终端型 Agent通常称呼为 pi之后整理了一张选型对照表维度opencodeClaude CodeCodexpi开源开源闭源部分组件开源社区项目配置透明高JSON 可见中依赖官方黑盒中中模型切换自由度高可接本地/多家低绑定自家大模型中以自家模型为主中上下文管理强Skills 按需加载强但受套餐限制中中编辑器集成VSCode、IDEA、桌面版插件/CLI官方 IDE 集成偏 CLI上手成本中低中低中成本模式只付模型费订阅用量订阅/用量低如果你已经有 Claude Code 的订阅预算其实直接用也没问题尤其是写文档、写方案这种偏向“对话式产出”的场景Claude Code 的上下文理解仍然是一流水平。但如果你要的是“一个自己完全可控的编码基建”opencode 的开源和配置透明是没法替代的。至于 Codex它最大的优势是 GitHub 生态集成度高在 PR review、issue 处理这些场景顺滑。而当你需要“本地化、多模型、私有化部署”时opencode 明显更灵活。6.2 接手陌生项目的实测流程我有一单外包性质的活客户丢给我一个 Spring Boot Vue 的旧系统代码量大、文档稀少。我实际用 opencode 走了一遍“接手流程”第一步新建会话不急着改代码先问请先不要修改任何文件。分析项目结构给我一份说明文档技术栈、模块划分、启动方式、数据库迁移脚本位置。opencode 会扫描目录然后输出结构化的项目地图。这一步有一次它把src/main/resources排查得非常快直接用项目索引找文件比我手动翻了 20 分钟还全。第二步让它确认本地启动方式找到 README 里的启动步骤检查项目的 Maven wrapper 和前端 package.json告诉我本地跑起来最省事的方式。它会顺带发现 README 里和实际依赖不一致的地方这个非常有用——老项目的文档滞后是常态Agent 通过比对代码和文档能挑出这些差异。第三步指派一个小任务验证它是否真正理解了项目在用户模块下加一个接口返回当前登录用户的权限列表参照现有 UserController 的代码风格实现。如果前两步理解到位这一步基本一次过。如果不满意不要急着重新开对话先检查是不是项目索引没建完整或者 Memory 里没有补充关键上下文。6.3 我踩过的几个坑和最后的建议最后集中列几个我用 opencode 过程中真实遇到的问题也算是一种“负向清单”并行改文件过多时改动冲突变多。Agent 一次改 8 个文件时偶尔会出现“改了 A 文件却把 B 文件的引用也顺手改了理由不充分”的情况。后来我习惯在指令里明确“本次只改 A其余文件只读不要动”冲突率明显下降。上下文过长的任务费用蹭蹭涨。让 Agent 分析整个大型项目时它会读入大量文件。opencode 虽然按需加载 Skills但文件本身还是要进上下文的。超过一定量级后建议拆成两步先让 Agent 产出代码索引和任务清单再分文件进入子任务。不同模型的结果风格不稳定。同一个需求用 claude-3.5-sonnet 和用 gpt-4o代码风格差异很大。opencode 允许在会话内切模型但千万别在同一个任务中途任意切换容易把 Agent 搞“分裂”。我通常是先确定任务再选一个模型跑到底。Maven/Node 环境不一致时Agent 会“谎报”构建结果。我遇到过 Agent 说“构建通过”但其实它没在当前项目根目录执行命令。建议在关键构建步骤后要求它回显工作目录和执行命令别只看结果。免费模型的“隐形成本”是自我纠错成本。14B 模型在简单模板生成上没问题但一遇到复杂需求就开始一本正经地生成错误代码你反而要花更多时间去 review。所以我的用法是小模型干小活大模型干大活不要因为“免费”硬上。综合这几轮的测试和使用体验opencode 目前已经是我日常工作的主力。我的最终建议是工具选型没有标准答案如果你看重开源、可控、多模型自由切换opencode 可以直接装来试。但请把预期管理好——它不会因为安装了一个 Agent 就让项目自动变好真正重要的还是你得清楚自己的代码库、业务流程和验收标准。opencode 是一个执行力很强的执行助理但方向仍然由你来定。