最近大半年我把 Claude Code、Codex CLI、opencode 这几个终端 AI 编程 Agent 都跑了一遍最后日常干活用得最多的反而是 opencode。原因很简单开源、能接免费模型、够灵活改配置不用等官方更新。opencode 本质上是一个跑在终端里的 AI 编码助手和 Claude Code 类似你在终端里启动它它能看到你的项目文件能读取和修改代码能执行命令、跑测试然后以对话的形式和你协作。不同的是opencode 不绑定某一家模型你可以在里面接 Anthropic、OpenAI、Google、DeepSeek甚至接智谱的免费模型。这篇文章不是官方文档是我自己折腾 opencode 的实操记录。从安装、配置、模型接入到 skills、memory、用 Playwright 测前端 bug再到 VSCode / JetBrains 插件和桌面版踩过的坑、能直接抄作业的命令和配置都会写出来。适合在 Claude Code、Codex、Cursor 之间犹豫的人也适合想找个免费模型在终端里写代码的朋友。1. 为什么是 opencode定位、出身与选型思路1.1 opencode 是哪家公司的版本脉络怎么走很多人第一次听到 opencode 都会问一句“这是哪家公司的”。它是 Anomaly Innovations 做的开源项目核心团队也就是搞 SST 的那批人SST 是 Serverless 领域一个很有名的开源框架。所以 opencode 身上一直带着很浓的“给开发者做工具”的基因社区活跃度也高Issues 和 PR 响应都很快。opencode 的版本脉络也要说清楚。早期版本是 TypeScript 写的安装方式是npm install -g opencode-ai用起来还算顺但终端 Agent 这种工具对启动速度和内存占用很敏感Node 那一套跑起来确实有点重。到了 2.0核心用 Go 重写这就是大家说的 opencode go。重写之后启动速度快了很多内存占用也下来了配置统一到 opencode.json而且模型接入方式更灵活。现在新装的话默认就是 Go 版。1.2 和 Claude Code、Codex CLI 比opencode 赢在哪我说几个我实测下来的差异点。第一是模型无关。Claude Code 默认就是 ClaudeCodex CLI 默认是 OpenAI虽然也能改但 opencode 从一开始就把“任意模型”做成了核心体验。你在配置文件里写 provider 就行同一个 agent今天用 Claude 处理复杂重构明天切到免费模型做批量小改动这在 opencode 里非常自然。第二是成本和自由度。Claude Code 要付费订阅或者用 API KeyCodex 要 ChatGPT 的额度opencode 本身开源免费模型你自己定。社区里有很多人用智谱 z.ai 的免费模型就是大家常说的 hy3-free 那一类跑下来做日常小活完全够用。对个人开发者来说省下的订阅费真不是小数目尤其是几个工具都要订阅的时候那开销叠起来挺肉疼的。第三是配置和扩展能力。opencode 的配置就是一个 JSON 文件provider、模型、工具开关、系统提示词都能在里面定义。还支持 skills可以把团队规范、常用操作打包成技能agent 在需要的时候自动加载。这个机制很像 Claude Code 的 skills但 opencode 是开放的你甚至可以把社区里的技能库搬过来用。1.3 也有不适合的场景不过我不建议你把它神化。opencode 解决的是“代码任务”不是“IDE 全家桶”。如果你要的是多点几下鼠标就有完整补全那种体验那 Cursor 或者 IDE 内置的 AI 插件更合适。opencode 的交互方式还是偏终端你要会一点命令行要习惯直接在终端里打字和看 diff。另外如果是超大单体仓库终端 Agent 读文件很容易被上下文窗口卡住这时候还是要靠人工规划把任务拆小或者用它的 plan 模式先做方案再动手。换句话说opencode 更适合已经把 Git 和命令行当日常工具的开发者而不是想完全脱离终端的用户。2. 安装与初始配置从零到能跑通2.1 三种安装方式你选哪种现在 opencode 的安装方式主要有三种curl 脚本安装curl -fsSL https://opencode.ai/install | bashHomebrewbrew install sst/tap/opencodenpm 安装npm install -g opencode-ai我自己的建议是macOS 和 Linux 用户直接用 curl 脚本最省事如果电脑上已经有了 Homebrew用 brew 也没问题好处是升级方便brew upgrade opencode一句命令搞定。Windows 用户我遇到过不少问题后面单独说但前提都是先把命令装到 PATH 能认到的地方。装完跑一句opencode --version能输出版本号就是成功了。如果提示找不到命令多半是 PATH 问题往下看。2.2 Windows 下最常见的坑opencode 无法识别为 cmdlet很多 Windows 用户在 PowerShell 里运行 opencode会碰到一大串红字opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确保路径正确然后再试一次。这个报错本质很简单opencode 不在 PATH 里。但 Windows 上引发的原因五花八门。如果是用 npm 装的先跑npm prefix -g看一下全局 bin 目录在哪然后把那个目录加进系统 PATH。如果是用 curl 脚本装的opencode 通常装在%USERPROFILE%\.opencode\bin这一类的路径下同样需要手动加到 PATH。建议加完之后新开一个终端窗口再试因为 PATH 环境变量的改动对已经打开的窗口不生效。我第一次就栽在这上面加了 PATH 以为立刻能用结果旧窗口怎么敲都报错。如果你是用 nvm 管理 Node 版本还要注意切换 Node 版本后npm 全局包的命令经常直接消失。这不是 opencode 的问题是所有 npm CLI 工具的通病。要么固定 Node 版本要么用 curl 脚本装的独立二进制避开 npm 这条路。2.3 配置文件结构opencode.json 和认证opencode 的配置集中在~/.config/opencode/opencode.jsonWindows 下是%USERPROFILE%\.config\opencode\opencode.json。这个文件的核心结构大概是{ model: anthropic/claude-sonnet-4, provider: { anthropic: { options: { apiKey: sk-ant-... } }, zai: { npm: ai-sdk/zai, name: Z.ai, options: { baseURL: https://api.z.ai/api/paas/v4 }, models: { glm-4.5-flash: {} } } } }model字段决定默认用哪个模型格式通常是provider/model-id。provider字段定义你都要用哪些模型服务商。如果你更习惯走登录授权也可以先跑opencode auth login它会引导你在浏览器里完成认证把凭证写入配置。我第一次配的时候没看文档直接在对话里问 opencode 怎么改默认模型它倒是给了很准确的路径建议。后来我习惯把所有 API Key 都放进环境变量配置文件里写${env.ANTHROPIC_API_KEY}这种引用这样 opencode.json 本身不会泄漏密钥提交到 dotfiles 仓库里也安全。注意opencode.json 里如果直接写明文 API Key务必别把这个文件推到公共仓库。我在 GitHub 上就看到过不少搜索 opencode 配置然后误提交 key 的案例几美元甚至几十美元的费用就这样凭空没了。2.4 用 ccswitch 做多账号配置切换社区里很多人配合使用的还有一个工具叫 ccswitch。它本来是给 Claude Code 切换 API Key / 账号配置用的因为很多人的 Anthropic Key 是共享的、有额度的、要轮换的手动改配置太麻烦。后来 ccswitch 也支持了 opencode可以在切换账号时同步更新 opencode 的配置。我的用法是在 ccswitch 里配好几档配置比如“个人订阅”“团队共享额度”“免费模型”三套每个场景切换一下就换好对应的 provider 和 API Keyopencode 下次启动自动生效。这样做的收益在模型价格波动的时候特别明显——免费模型倒下了切换一下继续干活不用手忙脚乱改 JSON。我自己实测下来ccswitch 这个工具最省心的点就是它可以统一管理多个工具的认证信息不会出现 Claude Code 换了 key、opencode 忘了换的尴尬局面。3. 模型接入与免费模型实操3.1 官方模型接入Anthropic / OpenAI / Google 等opencode 对主流模型厂商的支持都挺成熟。Anthropic 系可以直接用 provider 名anthropicOpenAI 用openaiGoogle Gemini 用googleDeepSeek 用deepseek。如果你用的是 OpenRouter 这类聚合平台也有对应的 provider只要填 API Key 就能用。填 API Key 的位置就是上节说的provider.name.options.apiKey。我的实践是{ provider: { anthropic: { options: { apiKey: ${env.ANTHROPIC_API_KEY} } } } }然后把真实 Key 放到 shell 的 profile 里导出。这样配置干净换机器也方便只需要重新设置环境变量就行。有朋友问 opencode 能不能处理 Maven 项目答案太能了。终端 Agent 的强项就是跑命令你把mvn test的执行结果贴给它它自己就会去读 pom.xml 找依赖问题。改依赖版本、加插件这类活它做起来比 IDE 插件还直接。我和团队里的 Java 同学一起用的时候最常见的操作就是让 opencode 看一遍pom.xml再决定怎么修构建报错省了来回切窗口的力气。3.2 免费模型怎么接hy3-free 与 z.ai 免费额度这是我觉得 opencode 最值得写的一节。opencode 社区里很流行“免费模型”方案大家常说的 hy3-free本质上是智谱 z.ai 开放的免费模型接口主要是 GLM-4.5-Flash 这个档位的模型也有一些限时免费的 GLM 新版本。你不需要去第三方平台直接在 z.ai 官网注册拿一个免费 API Key然后在 opencode 里加 zai provider 就行。配置参考{ provider: { zai: { npm: ai-sdk/zai, name: Z.ai (Zhipu), options: { baseURL: https://api.z.ai/api/paas/v4 }, models: { glm-4.5-flash: { name: GLM-4.5-Flash (free) } } } }, model: zai/glm-4.5-flash }填好之后在 opencode 里打开模型列表就能看到这个模型选中即可。实测下来GLM-4.5-Flash 做代码解释、写脚本、改小 bug 是够用的复杂重构还是不如 Claude 系但胜在免费适合批量跑一些重复性任务。比如让 agent 给项目里所有组件补测试用例这类任务量大、对智力要求不算极高用免费模型跑就很香。3.3 模型切换与按任务选模型opencode 支持在会话里随时切换模型最方便的就是打开模型列表用方向键换也可以直接在输入框里用 引用指定模型。我个人的习惯是日常小改动、整理代码、写注释免费模型架构设计、复杂 bug、多文件重构Claude 或 GPT 的高档模型前端 UI 调整、浏览器调试哪个模型都行但建议用能看到浏览器工具输出的模型这种“按任务贵贱分配模型”的思路一个月下来能省不少 API 费用。同样的活如果全用高档模型跑费用差距大概是 5 到 10 倍。尤其是现在 AI 编码的调用量一旦上去单价差一点点月账单差距就很吓人了。4. 进阶玩法Skills、记忆与浏览器调试4.1 Skills把团队规范变成 agent 的肌肉记忆opencode skills 的核心思想很简单你把一段操作说明写成一个 markdown 文件放到项目的.opencode/skills/skill-name/SKILL.md位置agent 在相关场景下会自动读取并执行这些说明。这就像给 agent 装了一本“团队操作手册”它不需要每次重新解释规范。举个例子我们团队要求所有 commit message 必须遵循特定格式我以前每次都得在 prompt 里写一大段。后来我建了一个 skill--- name: commit-message description: 生成符合团队规范的 git commit message --- 生成 commit message 时必须遵循以下格式 - 第一行是 type(scope): subject - body 里必须写清楚修改原因和影响范围 - 不得使用 WIP 之类的临时描述下次在 opencode 里输入“帮我提交这次改动”它就会自动加载这个 skill按规范生成 message。除了官方 skills 机制社区里流行的 Superpowers 技能库也是同样的思路你把技能文件放进去就能用opencode 完全支持这套加载方式。还有个叫 oh-my-claudecode 的项目原本是给 Claude Code 做增强配置的社区里也有很多人把它那套配置思路迁移到 opencode 上本质上都是在用 skills 机制做工程化沉淀。4.2 Memory让 opencode 记住你的偏好opencode 的 memory 功能简单说就是 agent 会把对话里你认为重要的偏好和约束记录下来后续会话自动使用。很多 opencode 老用户会把常用的开发约定写进全局配置或项目级的 AGENTS.md 文件里opencode 在启动时会主动读取这些文件作为上下文。比如我在 AGENTS.md 里写了“前端项目优先使用 pnpm不新增 yarn 和 npm lock 文件”后面每次让 opencode 安装依赖它都会自动用 pnpm。这个机制比每次在 prompt 里重复强调靠谱得多算是给 agent 建立的“长期记忆”。实际操作中我把 AGENTS.md 放在项目根目录里面又分了几类代码风格、目录结构、本地启动命令、部署注意事项。这样 opencode 每次进入项目都能快速了解上下文不用我把项目背景从头讲一遍。4.3 用 Playwright 让 agent 自己测前端 bugopencode 内置了浏览器工具底层走的是 Playwright。很多人不知道这个功能有多实用——你可以直接让 agent 自己打开本地开发服务器去页面上复现你描述的 bug。比如有次我遇到“点击搜索按钮结果列表没刷新”的问题我给 opencode 下的指令是“用 Playwright 打开 http://localhost:5173 点击搜索按钮把页面上出现的 console 错误和 network 请求状态截图给我再定位到相关组件代码。”opencode 会自己调用浏览器工具打开页面、操作元素、截图、抓 console 日志然后把结果连同代码定位一起反馈。这个“能动手测”的能力让 agent 不再只是一个“凭空猜代码”的聊天对象而是真的能验证自己改得对不对。我也试过让它先写一个页面复现脚本再根据脚本输出定位问题效果也很好。注意浏览器工具需要你的项目能在本地启动且启动后端口要稳定。我先习惯把开发服务器固定到指定端口再交给 opencode避免它每次猜地址猜错了还得重新来反而耽误时间。5. IDE 集成与桌面版从终端回到编辑器5.1 VSCode opencode 插件虽然 opencode 是终端工具但它也出了 VSCode 插件安装后在编辑器左侧会出现 opencode 面板可以像终端里一样发起会话、看 diff、接受修改。这个插件的价值在于你不用在编辑器和终端之间来回切换改代码的上下文可以直接在面板里看。我实际用下来的体验是VSCode 插件适合“边看代码边讨论”的场景比如看一个陌生项目的实现时打开 opencode 面板问问题但真正大范围改代码我还是更喜欢回到终端 TUI因为 TUI 的 diff 交互更顺手能快速对比每个文件的改动空格和回车就能搞定接受或放弃效率高很多。5.2 JetBrains IDEA 插件JetBrains 系的插件也有在 IDEA / PyCharm 等产品的插件市场里搜 opencode 就能找到。安装之后用法和 VSCode 版类似。说实话IDE 插件目前更多是“把 opencode 嵌进编辑器”的程度功能完整度不如终端但对于重度使用 IDEA 的 Java / Kotlin 开发者来说能在编辑器里直接跑终端 agent 已经很方便了。配合 Maven 项目让 opencode 帮你生成 pom 配置、跑 mvn 命令的时候这种集成体验确实比来回切窗口强。5.3 opencode desktop 桌面版现状opencode desktop 还在早期阶段目前用得不多。它是基于桌面外壳封装的图形界面版本适合完全不想碰终端的人。我个人的看法是如果你已经能熟练使用终端版桌面版目前对你的增量不大但如果你要在团队里推广 opencode 给不熟悉命令行的同事桌面版确实降低了上手门槛。可以关注官方发布的进度现阶段用它做日常任务没问题但别指望它替代完整的 IDE 工作流。6. 常见问题与排查技巧实录6.1 命令无法识别cmdlet 问题速查前面 2.2 提过这里给个速查表现象可能原因解决思路PowerShell 不识别 opencodePATH 没配好找到安装目录加入 PATH重开终端npm 全局包装了但命令消失Node 版本切换用npm prefix -g确认 bin 目录或用 curl 装独立二进制命令能识别但版本旧升级没生效跑升级命令或重新执行安装脚本如果你在C:\Windows\System32这个默认目录下直接敲 opencode最好先cd到自己的项目目录再执行 opencode。虽然这不是报错的根本原因但在 Windows 的默认路径下很多用户会因为权限问题或 PATH 未生效而误判。6.2 error: unexpected server error. check server logs这个报错我在 Windows 上遇到过一次在 Linux 上也有朋友遇到过。报错本身很笼统但排查路径是固定的第一确认网络能访问你配置的模型 API 地址。如果模型服务商本身挂了或者限流就会出现这种通用错误。第二确认 API Key 是否还有效很多服务商对免费套餐的 key 是限时的。第三看 opencode 的日志老版本有调试输出新版在各平台的日志目录里错误原因通常会写在日志里比猜快得多。我踩过最蠢的一个坑是配置文件里把 baseURL 多加了一个/v4结果请求路径变成.../v4/v4/chat/completions服务器直接返回错误opencode 就报 unexpected server error。把 baseURL 改成指向根 API 地址后立刻恢复正常。这种配置类问题99% 先检查 baseURL 和 API Key基本能解决。6.3 免费模型服务下线了怎么办hy3-free 这类免费服务有生命周期可能会下线或者改变政策。遇到这种问题不要慌我的处理流程是先去 z.ai 官方看 GLM 免费模型的当前策略如果还有免费档就直接调整配置换模型名如果官方免费档也没了那就退一步把非核心任务切到更便宜的付费模型或者用本地 ollama 跑小模型处理纯格式类工作。opencode 的架构就是好处模型只是配置里的一个 provider随时可以换项目代码不受影响。6.4 opencode、Codex、Claude Code、Pi 怎么选最后说说 agent 选型。我自己的经验是Claude Code综合能力最强生态最成熟但闭源、费用高适合对效果要求高、预算充足的团队。OpenAI Codex和 GitHub 生态结合紧如果你是重度 GitHub Copilot 用户可以试试但同样偏闭源。opencode开源、自由、便宜适合想掌控配置、喜欢换模型、有定制需求的人。Pi 这类轻量 agent各有特色但社区生态还在早期目前更适合尝鲜。如果是新手我的建议是先不用纠结。在 opencode 里把免费模型接上跑一个星期真实项目你对“终端 agent 到底能干什么”有感觉之后再决定要不要上更强的付费模型。我自己用 opencode 这段时间最大的体会是“模型不是最重要的工作流才是”。真正让我留下的是它把“问、改、跑、验”这几个动作在一个终端里串起来了而且换模型、加技能、调配置都是自己说了算。最后再分享一个小技巧往项目根目录放一份 AGENTS.md把你们团队的代码风格、目录结构、常用命令写清楚opencode 每次进来都会读比任何 prompt 模板都管用。这个习惯一旦养成了你回不去。