先把话说在前头过去大半年我电脑里同时装着 Claude Code、Codex CLI、Cursor 和 Gemini CLI每个都有各自的长处也每个都有各自的脾气。直到某个周五下午我在一个遗留 Go 项目里被 Claude Code 的授权问题卡了二十分钟顺手点开同事丢过来的 opencode 仓库才发现原来终端 AI 编程助手还有另一种打开方式。opencode 是一个用 Go 写的开源终端 AI 编码工具主打的是一句话能说清楚把 Claude Code 和 Codex 能做的事用一套更开放、更快、更可定制的方案重新实现一遍。它不是某个大厂的封闭产品而是开源社区里持续迭代的项目支持多模型接入、自带模型网关、TUI 交互、非交互批处理还能通过 skills、memory、MCP 协议扩展能力。如果你正在纠结到底该用哪个终端 Agent或者已经用腻了 Claude Code 想换个更灵活的开源方案又或者想给团队统一一套可配置、可审计的 AI 编码工具这篇就按我实际折腾的路径从安装、配置、日常使用到踩坑完整过一遍。1. opencode 是什么终端 AI 编程助手圈里杀出来的开源黑马1.1 我为什么会注意到 opencode2025 年这一年终端 AI 编码工具基本形成了三足鼎立的态势Anthropic 的 Claude Code 占着先发优势OpenAI 的 Codex CLI 背靠 Codex 模型Google 的 Gemini CLI 则靠免费额度拉了一波用户。这三者有个共同特点——都和自家模型深度绑定换个模型供应商就得折腾半天。opencode 进入我视野是因为一个很实际的需求团队里有人用 Claude Code有人用 Codex还有人不想折腾模型 Key只想要一个开箱即用的工具。当时我看了一圈发现 opencode 的定位正好卡在这个空档上它本身不生产模型而是做一个通用的终端 Agent 运行时你可以给它配 Anthropic、OpenAI、Gemini、本地 Ollama甚至各种兼容 OpenAI 协议的第三方服务。用下来之后我把它当成开源版的 Claude Code来用并不是说它完全复刻了 Claude Code 的所有功能而是它把终端 Agent 的骨架做得很完整多模型切换、权限审批、会话管理、Skills 扩展、MCP 支持、IDE 联动这些东西在开源项目里做到了开箱即用的水平。1.2 核心特性拆解拿我实际使用中感知最强的几个能力来说TUI 交互界面不是简单的命令行问答而是带会话列表、消息流、模型选择器的终端界面长时间挂在一个项目里也不会乱。多模型接入可以在一次会话内切换不同模型比如先用便宜模型做初稿再用强模型做重构审查。自带模型网关opencode 官方有一个模型网关层部分模型可以免 Key 使用这对刚上手的新人非常友好。Skills 机制把某个领域的做事方法封装成目录和脚本Agent 遇到对应场景时会自动加载。这个思路和 Anthropic 的 Agent Skills 同源社区里已经有大量现成 skills 可以抄。Memory 记忆跨会话保留项目约定、用户偏好不用每次重新交代一遍。MCP 协议支持能接外部工具我在实际项目里接了 Playwright 来做前端 Bug 复现后面有专门一节讲这个。IDE 插件与桌面版VS Code、JetBrains 都有官方插件桌面版适合不用终端的同学但我的主力还是 TUI。这套组合拳下来opencode 解决的其实是终端 Agent 的碎片化问题团队里不需要再为不同模型买不同工具一个 opencode 实例可以统一调度。2. 安装与首次启动从零跑通第一个会话2.1 三种安装方式的对比opencode 的安装方式有好几种我全部试过直接说结论日常使用用 npm 或官方脚本想要最新代码用 Go 直接编译。安装方式命令适用场景npm 全局安装npm install -g opencode-ai最推荐升级方便Node 18 即可官方脚本curl -fsSL https://opencode.ai/install | bash不想装 Node 依赖时用Go 安装go install github.com/sst/opencodelatest想自己维护源码或体验未发布版本我主力是 npm 方式因为opencode upgrade一条命令就能升版本。Go 方式适合那些本来就装了 Go 环境的开发者但要注意它拉取的是默认分支的最新提交有时候会崩我建议求稳的人避开。2.2 Windows 下的 PATH 坑如果你在 Windows 上用 npm 安装大概率会碰到热搜里那条经典报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这基本不是 opencode 的问题而是 npm 全局 bin 目录没有加入 PATH。npm 全局安装的包会被放到类似C:\Users\你的用户名\AppData\Roaming\npm的目录下这个目录不在 PATH 里就会这样。解决办法有两种。第一种是临时用全路径调用C:\Users\你的用户名\AppData\Roaming\npm\opencode.exe第二种是一劳永逸地把 npm 全局目录加进 PATH打开 PowerShell执行npm config get prefix拿到 npm 全局目录。按下Win R输入sysdm.cpl进入环境变量设置。在用户变量的Path里新增上一步拿到的路径。重新打开终端执行opencode --version验证。这里要提醒一句改完 PATH 之后一定要新开一个终端窗口别在旧窗口里反复试旧窗口的环境变量不会自动刷新。我第一次就是没重开终端白折腾了十分钟。2.3 首次启动与模型认证安装完成之后在任意目录执行opencode会进入一条交互式的引导流程让你选模型供应商。opencode 的模型来源分成两类opencode 官方网关提供的模型不需要你自己配 API Key选一个模型就能直接开始对话。适合快速体验。你自带的模型供应商需要手动配置 API Key通常通过环境变量注入例如export ANTHROPIC_API_KEYsk-ant-xxxx export OPENAI_API_KEYsk-xxxx export GEMINI_API_KEYxxxx配置文件存放在~/.config/opencode/config.jsonWindows 下是%USERPROFILE%\.config\opencode\config.json我一般会把常用的供应商配置写进去避免每次开新项目都重新设置。有一点要注意官方网关虽然方便但它本质是官方提供的代理服务稳定性取决于官方后端。团队项目或生产环境用之前先确认一下网关的可用性不能默认它永远在线。我的做法是配置里同时放官方网关和自备 Key 两套一旦网关超时就切换自备 Key。3. TUI 界面与命令体系日常高频操作速成3.1 界面布局opencode 默认启动后的 TUI 大约是这样一个布局左侧是会话列表每个项目一个会话组历史记录都在。中间是对话消息流Agent 的思考过程和代码 diff 都会展示在这里。底部是输入框输入斜杠命令或直接问问题。顶部或底部会有当前模型标识按Tab可以快速切换模型。刚上手的人最容易困惑的一点是它到底什么时候在等我输入什么时候在跑任务。opencode 的交互是流式的你发一条指令Agent 持续输出期间你可以随时按Esc打断也可以让它继续。这个大模型交互体验比传统输入-回车-等结果的方式顺畅很多。3.2 常用斜杠命令我每天用得最多的是这几个/models弹出模型选择器在会话中直接换模型。/new清空当前会话上下文开一个新会话。/compact把当前长会话压缩成摘要解决上下文超长后的幻觉问题。/agents查看和管理子 Agent比如同时开一个前端排查Agent 和一个后端审查Agent。/share生成一个分享链接把当前会话导出发给同事。/help查看所有命令尤其是版本更新之后命令列表经常变。还有一个很实用的参数启动时用opencode --model 模型名可以直接指定模型跳过 TUI 里的手动切换。写脚本、做自动化调用时这个参数非常重要。3.3 非交互模式 opencode runTUI 适合人坐在电脑前盯着但很多时候我想把它塞进脚本或 CI 里这时候就要用opencode runopencode run 把 src/utils/date.ts 里的日期格式化函数重写补上单元测试加--model指定模型加--agent进入全自动模式Agent 会在关键操作上自动确认不需要你手动批准。但我不建议一上来就用--agent因为权限放开之后它可能会执行你没想到的命令。我的习惯是先让它出方案再手动批准执行。非交互模式还有个很实用的搭配就是配合 Git 做代码审查git diff | opencode run 审查这段 diff指出潜在问题并给出修改建议这个用法已经成为我日常提 MR 之前的固定动作比自己肉眼 review 快很多。4. 模型接入与成本控制免费模型、自带网关与 ccswitch4.1 opencode 的模型加载机制opencode 不绑定某个特定模型它的模型配置是分层的。第一层是内置的模型列表第二层是用户配置文件第三层是环境变量。实际生效的优先级是环境变量和配置文件里显式指定的设置用户配置会覆盖内置列表。我建议把常用模型写进配置而不是每次都靠环境变量。下面这个例子是把 Anthropic 和 OpenAI 都配好{ $schema: https://opencode.ai/config.json, provider: { anthropic: { apiKey: sk-ant-xxxx, model: claude-sonnet-4-20250514 }, openai: { apiKey: sk-xxxx, model: gpt-4.1 } } }配置完成之后在 TUI 里按Tab就能在已配置的模型之间切换。这个会话内切换非常实用我经常先用小模型快速扫一遍代码发现问题后切大模型深入分析能省不少 token 费用。4.2 免费模型与网关的选择对刚接触 opencode 的人来说最大的吸引力之一就是它有免费模型可用。通过官方网关内置的一些开源模型可以直接调用不用申请 Key。这个对体验工具来说非常友好我安利同事入坑时都是让他先跑免费模型跑通流程再考虑自己的 Key。但说句实际的免费模型在复杂项目里的表现和 Claude Sonnet、GPT-4.1 这类商业模型还是有差距尤其在做跨文件重构、理解老项目逻辑时差距很明显。我自己的定位是免费模型用来做格式化、写简单脚本、解释报错信息生产级的代码生成和重构还是交给强模型。社区里也经常看到各种免费通道、第三方中转服务的讨论这些通道确实方便但稳定性和数据安全都没有保障我一般不把它作为日常主力更不会写进公司项目。如果团队要用还是走正规 API 或者官方网关。4.3 ccswitch 的作用与具体用法很多国内开发者会遇到一个痛点环境变量里同时有多个 Key或者想在不同模型服务之间快速切换手动改配置很痛苦。社区里比较常见的做法是配一个叫 ccswitch 的小工具来管理切换逻辑。ccswitch 做的事情本质上是读写 opencode以及其他终端 Agent的配置文件把 provider 的 baseURL、apiKey 这些字段一键替换成你要的目标服务。比如今天用官方 Anthropic明天想切到其他兼容服务不需要手动编辑 JSON执行一条 ccswitch 命令就能切过去。配合 opencode 使用的基本流程是在 ccswitch 里配置好多个服务商每个服务商包含名称、baseURL、apiKey、默认模型。切换时执行类似ccswitch use 服务商名的命令。重启 opencode此时 TUI 里加载的已经是新配置。个人体会是如果你只是自己一个人用环境变量加 config.json 手动维护完全够ccswitch 是锦上添花但如果你要给团队维护一份统一配置ccswitch 这类工具能把切换模型服务商从十分钟的手工活变成一条命令。4.4 成本估算与套餐选择opencode 本身是开源免费的花钱的地方全在模型 API 上。不同模型的价格差异巨大我按自己的使用强度做了一个粗略对比使用场景推荐模型单次会话预估成本说明日常问答、代码解释免费模型或轻量模型0 或极低适合新手体验中等规模功能开发Claude Sonnet / GPT-4.1几毛到几块钱主力场景性价比最高大型重构、复杂架构分析Claude Opus / 类顶级模型几块到几十块需要长上下文token 消耗大批量脚本、CI 自动化轻量模型可忽略控制上下文避免无意义消耗这里有个成本控制的技巧opencode 的上下文窗口是有限且按 token 计费的长时间挂着一个大会话不清理每次请求都会把历史全部重发费用会指数级上涨。我养成的习惯是任务结束就/new或者用/compact压缩会话别让一个会话无限膨胀。5. 项目级配置skills、memory 与 AGENTS.md 的配合5.1 .opencode 目录与 AGENTS.mdopencode 虽然在终端里跑但它的核心能力其实是理解项目。理解项目靠什么靠项目根目录下的.opencode目录和三份核心配置AGENTS.md、skills、memory。先说AGENTS.md这个名字和 GitHub 的 AGENTS.md 规范一脉相承。你在这个文件里描述项目的架构、编码规范、目录结构、常用命令opencode 启动时会自动读取并把它作为全局背景知识注入到每次会话中。举个例子我曾经接手一个老项目第一件事就是在AGENTS.md里写# AGENTS.md ## 项目概述 - 后端Spring Boot 3.xJava 17 - 前端Vue 3 TypeScript - 构建Maven模块化多模块工程 ## 编码约定 - 代码风格遵循 Google Java Style - Service 层必须写单元测试 - 不要手动修改 generated 目录下的文件 ## 常用命令 - 启动后端mvn spring-boot:run - 前端调试npm run dev - 构建产物mvn clean package加了这个文件之后Agent 回答问题的准确率明显提升因为它不会再猜你的项目用什么技术栈了。给 opencode 交代项目背景比换一个更强的模型管用得多。5.2 Agent Skills让 Agent 学会做事方法Skills 是 opencode 里我认为最有想象力的一块。简单说一个 skill 就是一个带SKILL.md的目录里面附带一些脚本或说明描述当你遇到某类场景时应该按什么流程做。目录结构大概是这样.opencode/ skills/ read-backend-log/ SKILL.md parse-command.shSKILL.md内部会有个 YAML 头声明这个 skill 的名称、描述和适用场景下面是具体的执行说明。比如我写过一个排查后端日志的 skill描述是当用户报告接口报错时先检查 application.log 中对应时间窗口的 ERROR 日志再定位到调用链。opencode 读取 skills 的时候会把description语义化地注入到上下文中当用户请求匹配到某个 skill 的描述Agent 就会优先按这个 skill 的流程去执行。这样做的价值是把经验沉淀成项目的可复用资产新同事加入或者 Agent 换了一个只要 skills 还在做事方式就不会跑偏。5.3 Memory跨会话记住项目约定Memory 是另一个让我觉得 opencode 适合长期使用的理由。默认情况下AI 是没有记忆的每次新会话都从零开始。opencode 的 memory 机制则是把一些关键约定在会话之间保留下来。比如我在某个前端项目里第一次告诉它组件命名统一用 PascalCase样式用 Tailwind 而不是 CSS Modules它会把这条规则写进项目的 memory。下一次开新会话再让它写组件它会自动遵守这个约定不用我再重复交代。memory 和AGENTS.md的区别在于AGENTS.md更像人写的项目说明书是静态的、结构化的memory 更像 Agent 的工作笔记是动态积累的。我建议两者配合使用入职新项目时用AGENTS.md把基础背景一次性写清楚后续使用过程中把逐步发现的潜规则交给 Agent 沉淀进 memory。6. 从终端到桌面VS Code 插件、JetBrains 插件与桌面版6.1 VS Code 插件TUI 虽好但有些场景我还是想留在编辑器里操作比如看代码、改文件、对照 diff。opencode 的 VS Code 插件解决的就是终端和编辑器割裂的问题。安装插件之后它会自动连接当前项目对应的 opencode 会话左侧面板会出现对话区选中代码后可以直接让 Agent 解释或修改。最顺手的功能是内联 diffAgent 改完代码你能直接在编辑器里看到红色和绿色的改动一键接受或丢弃比在终端里看着代码块想象要直观得多。插件本质上是opencode serve启动的本地服务的客户端所以它读到的项目上下文和 TUI 是一致的。也就是说你可以在 TUI 里跑一个长任务同时在编辑器里用插件做另一个轻量对话两边不冲突。6.2 JetBrains 插件JetBrains 系IDEA、PyCharm、GoLand 等也有官方插件安装入口在 Settings - Plugins搜索 opencode 就能找到。功能上和 VS Code 插件基本对齐对话面板、代码上下文联动、diff 应用。我的主力 IDE 是 IDEA实际体验中 JetBrains 插件的一个优势是能和 IDE 自带的运行、调试、测试功能联动。Agent 给出修改建议后你可以直接在 IDE 里跑测试验证不用切回终端敲命令。opencode 的 Maven 配置、测试命令如果能写进AGENTS.md插件侧也能感知体验会顺很多。6.3 桌面版与工作流配合opencode 2.0 之后推出了桌面版opencode desktop本质是把 TUI 装进了一个原生窗口另外加了一些图形化的会话管理能力。对不习惯终端的人来说桌面版的接受门槛更低因为它有明确的按钮和菜单不用记斜杠命令。但我个人的主力还是 TUI原因很简单TUI 更轻启动快而且能嵌入我已经习惯的终端工作流。桌面板更适合给团队里那些不愿意碰终端的同事用方便把 opencode 推广到更多人。我目前的工作流是这样分工的大任务、跨文件重构开 TUI挂一个长会话让 Agent 慢慢跑期间我可以去做别的事。小改动、代码解释用 IDE 插件选中代码直接对话不脱离编辑环境。给同事演示、新手体验用桌面版门槛最低。7. 实战让 opencode 用 Playwright 定位前端 Bug7.1 场景与准备说了这么多配置和原理来一个真实到可以照着抄的实战。前阵子同事报了一个前端 Bug登录页输入正确的账号密码点击登录按钮没有任何反应控制台也没有报错。这种点击无反应的 Bug 最烦人因为连报错都没有纯看代码很难定位。传统做法是手动打开浏览器、开 DevTools、打断点、逐步排查耗时少则半小时多则一下午。opencode 接上 Playwright 之后这个排查过程可以被大幅压缩。Playwright 是一个浏览器自动化测试框架而 opencode 通过 MCP 协议调用它等于让 Agent 获得了打开浏览器、点击页面、读取控制台、查看网络请求的能力。7.2 配置 Playwright 工具首先在项目里安装 Playwright MCP 服务npm install -D playwright/mcp然后在 opencode 配置里注册这个 MCP 工具。opencode 的 MCP 配置放在 config.json 的mcp字段下{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest], enabled: true } } }配置好之后重启 opencode在对话里问一句你现在能用 Playwright 吗如果 Agent 回答能调用浏览器工具说明配置成功。注意一个小坑Playwright MCP 需要本地能启动浏览器Linux 服务器上跑之前要先安装浏览器依赖。我踩过一次Agent 报Browser closed unexpectedly查了半天发现是系统缺 Chrome 的运行库执行 Playwright 官方提供的npx playwright install-deps才解决。7.3 完整排查链路配置完成之后我在 opencode 里发了这样一条指令登录页的登录按钮点击无反应。用 Playwright 打开本地开发服务器复现这个 Bug找出原因。不要只猜要实际操作验证。opencode 的响应过程大致是启动 Playwright打开配置的开发地址。填入测试账号密码点击登录按钮。读取浏览器控制台日志和网络面板发现点击按钮时发送了一个/api/login请求这个请求返回了 500。Agent 结合代码仓库定位到后端接口发现是参数校验规则把前端传的字段名映射错了。给出修复建议修改前端请求体字段名或者修改后端接收参数注解。整个过程大约几分钟比我手动排查快了一个量级。最关键的是Agent 不是读代码猜原因而是真的把浏览器开起来做了验证结论可靠得多。我的经验是给 Agent 的指令要强调实际操作验证不要只猜否则它倾向于直接凭代码推断。像用 Playwright 打开页面读取控制台抓网络请求这些具体动作写进 prompt 里能明显提升排查准确性。8. 常见问题排查与同类工具横向选择8.1 高频报错与解决思路用 opencode 这几个月我遇到过几个高频报错列在这里供参考。报错信息常见原因解决思路error: unexpected server error. Check server logs.网关不可用、模型名错误、Key 失效先看opencode --debug日志确认请求到底发给谁再检查配置里的模型名是否在官方列表里最后确认 Key 是否还有余额opencode : 无法将“opencode”项识别为 cmdlet...npm 全局目录未加入 PATH看 2.2 节把 npm 全局目录加进 PATH 并重开终端model not found配置文件里的模型 ID 写错执行opencode models查看当前可用的模型列表严格按列表里的 ID 填写Error: EACCES: permission deniedLinux/macOS 下安装脚本没有权限不要用 sudo 强装优先改用用户目录安装或 npm 前缀重定向这里重点说第一个报错因为它出现得最随机也最容易让人慌。unexpected server error不代表工具坏了而是 Agent 调用的模型服务端返回了异常。我通常按这个顺序排查执行opencode --debug启动看请求实际打到了哪个服务商。如果打到官方网关检查网关公告网关偶尔会因负载高而暂时不可用。如果打到自己配置的 API检查 Key 是否有效、余额是否充足。确认模型名没有被拼错尤其是带日期的模型版本号写错一个字符就是 not found。8.2 与 Codex、Claude Code、Pi 的横向对比很多人在选型时会问opencode、Codex、Claude Code、Pi 到底哪个好用。我四个都用过给一个大白话版的对比工具开源多模型接入上手门槛核心优势主要短板opencode是强中灵活、可定制、无生态锁定需要自己花时间配置Claude Code否弱主打自家模型低与 Claude 模型深度整合开箱即用闭源订阅费用高Codex CLI否弱主打 GPT 系列低OpenAI 生态模型能力强与 OpenAI 绑定Pi是视版本而定中社区活跃迭代快稳定性时有波动我的结论是如果你追求拿到就能用不折腾那 Claude Code 或 Codex 更合适如果你希望能统一管理多个模型、把 AI 编码流程沉淀进项目配置那 opencode 是更长久的选择。至于 Pi它开源且社区热情高但我个人用下来opencode 在项目级配置和企业场景上更成熟。8.3 我的选型建议与使用体会最后分享一点实在的建议。团队选型的时候别只在工具功能层面比要看你有什么模型资源和多少时间维护。如果团队每个成员都有自己的一套模型订阅那 opencode 的价值就不只是多一个工具而是把大家拉到了同一个技术平台上Agent 行为、项目配置、技能沉淀都能共享。如果你只是一个人写代码我建议从免费模型开始体验 opencode跑通流程之后再决定要不要上更贵的模型。别一开始就上一堆高级配置先用起来用顺手了再逐步加 skills、memory、MCP。我在实际使用中的体会是opencode 真正厉害的地方不在于它比 Claude Code 强多少而在于它把终端 AI 编码这件事变成了一个可以自己掌控、可编程、可扩展的体系。对一个长期和代码打交道的人来说这种可控性比某个模型的单点优势更重要。