这段时间我的终端里几乎全是 opencode 的日志。作为一个长期在 Codex CLI 和 Claude Code 之间反复横跳的人opencode 是唯一让我连续待机两小时不想切走的开源终端 Agent。它不像商业产品那样有漂亮的引导流程第一次装完甚至有点懵但一旦把模型配好、把 Skills 和 MCP 接上你会发现这套东西确实比“每次都重新描述项目背景”的用法靠谱得多。这篇就基于我最近从安装到实战的完整过程把 opencode 的模型配置、Skills、Memory、IDE 插件、Playwright 联调这些事一次性聊透。适合刚接触 opencode 的人也适合已经在用但被各种报错卡住的人。1. 先搞清楚它到底是“哪家”的产品比 Codex、Claude Code 和 pi 差在哪1.1 不是商业公司是开源社区摊上事的那个项目很多人搜“opencode是哪家公司的”因为它看起来太像商业产品了。其实 opencode 的定位很明确它不是某一家公司的闭源服务而是一个开源编程代理项目。最早由 sst.dev 团队发起后来逐步社区化现在源码、核心机制、插件接口都摆在 GitHub 上你可以直接 fork 改造成团队内部工具。这一点和 Codex CLIOpenAI或 Claude CodeAnthropic有本质区别。商业产品往往绑定自家模型 API而 opencode 天生就是“多模型路由”的思路。它不生产模型只负责把终端里的任务拆解、调用模型、执行命令、改文件然后把结果呈现在 TUI 界面里。也就是说你完全可以给它配一个 OpenAI 的 Key也可以配 Anthropic甚至本地跑一个开源模型也行。这解答了热词里另一个高频问题“opencode是哪家的”——谁都不是又谁都能接。它更像是一个标准化终端 Agent 的“发动机”模型提供商只是油。1.2 同类工具横向对比为什么它值得单独占一个章节我同时装过 Codex CLI、Claude Code 和 opencode加上社区里常被提到的 pi另一个终端 Agent简单列一个我的实际感受表工具开源情况模型绑定交互界面插件体系上手难度opencode完全开源多模型可自定义 provider终端 TUI也有桌面端Skills / MCP中Claude Code核心不开源主要绑定 Anthropic终端 CLI插件系统低Codex CLI开源主要绑定 OpenAI终端 CLI较少低pi开源多模型终端 TUI一般中关键差异在于 opencode 的 TUI 不是简单的问答框。它能直接显示文件 diff、命令执行状态、多步骤 Agent 的中间过程你可以在它“准备改文件”之前打断它这种控制感很多工具给不了。对经常要盯着 Agent 每一步动作的人来说这比纯文本输出舒服很多。1.3 适合谁、不适合谁如果你满足下面任意一条opencode 值得试想用一个开源 Agent 接管日常编码任务不想被单个云厂商绑定已经有 API Key想按量付费而不是买固定套餐团队里有统一的编码规范想让 Agent 也遵守规范需要让 Agent 操作浏览器、跑测试、查日志而不只是改文件。不太适合的人也很明确完全不想碰配置文件、希望装完就能像 ChatGPT 一样聊天的人。opencode 的默认配置虽然能跑但要发挥真正威力至少得理解 provider、模型名称、API Key 这些概念。它更适合“愿意折腾十分钟换后续无限便利”的开发者。2. 安装与模型配置从“无法识别命令”到“免费模型跑起来”2.1 三种安装姿势脚本、Go 版、桌面版怎么选热词里反复出现“opencode安装”“opencode go”这其实对应了两种不同的安装路径。官方推荐的安装方式是在终端里执行curl -fsSL https://opencode.ai/install | bash这条命令会把 opencode 装到用户目录然后加入 PATH。如果你在 Windows 上建议在 PowerShell 里执行装完必须重开终端否则大概率出现那个经典报错“opencode : 无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个报错九成以上不是 opencode 本身的问题而是 PATH 没有刷新。你可以用下面几个命令依次排查where.exe opencode $env:PATH -split ; | Select-String opencode opencode --version如果where.exe找不到但安装脚本又提示成功就去检查~/.opencode/bin或%USERPROFILE%\.opencode\bin是否在 PATH 里。还有一个更省事的替代方案社区里有人维护 Go 语言编译的 opencode 二进制源码和安装包在 GitHub 上能找到。这就是“opencode go”这个说法的来源之一——它本质上是用 Go 编译的版本好处是你不需要在机器上装 Node.js 和 npm也不会被 Node 版本兼容问题折腾。另外要提一下“opencode desktop”。官方桌面版是对 TUI 的图形封装界面更接近现代聊天软件命令历史和文件 diff 可视化做得比较好。如果你习惯在终端里做事用 CLI 就够如果团队里有非命令行重度用户桌面版能降低入门门槛。但要注意桌面版和 CLI 共用同一个配置文件目录所以并不冲突。2.2 第一次配置模型免费模型、自带 Key 和 ccswitch配好模型是 opencode 能否真正跑起来的关键。项目根目录下创建opencode.json最常见的配置长这样{ $schema: https://opencode.ai/config.json, provider: { openai: { api_key: sk-xxx, model: gpt-4o }, anthropic: { api_key: sk-ant-xxx, model: claude-sonnet-4-20250514 } } }如果你不想在配置里明文写 Key也可以直接用环境变量OPENAI_API_KEY或ANTHROPIC_API_KEY。opencode 的机制是你配置了哪个 provider它就去调用哪个 provider 的接口并不限制你必须用哪家。所以我自己的习惯是日常用免费模型兜底重活切到付费模型。“开放免费模型”是热词里“opencode免费模型”的来源。很多人在网上分享的免费模型其实是社区代理或第三方中转服务这种我一般不建议直接用——你永远不确定服务商的稳定性也不知道请求数据到底去了哪里。更稳妥的做法是自己带 Key或者用本地模型服务比如 Ollama、LM Studio暴露一个 OpenAI 兼容接口然后在 opencode 里把 provider 指到本地地址。配置大致如下{ provider: { local: { npm: ai-sdk/openai-compatible, base_url: http://localhost:11434/v1, api_key: local, model: qwen2.5-coder } } }这样写的好处是免费、数据不出内网、你完全掌控。缺点也很明显本地模型的能力上限和云端大模型有差距做简单重构、写脚本没问题复杂架构设计还是得靠商用模型。聊到 ccswitch这是热词里反复出现的“ccswitch配置opencode”。ccswitch 是一个配置切换工具最早是用来切 Claude Code 配置的后来扩展支持了 Codex、opencode 等。它解决的问题很真实你同时用多个 Agent 工具每个工具都要配不同的 api_key、base_url、model手工切换特别容易出错。ccswitch 会统一管理这些配置然后通过软链到各工具自己的配置文件里。用它来管 opencode 的好处是当你的模型供应商有多套 Key 时不用每次手改opencode.json直接ccswitch切一下就行。2.3 “unexpected server error”到底怎么查热词里那个c:\windows\system32opencode error: unexpected server error. check server lo...的报错我在配 claude 模型时也遇到过一次。这个报错其实是服务端响应异常不是本地语法错误。常见原因有以下几类模型 API Key 填错或过期服务端返回 401/403但 opencode 把原始错误包装成了“server error”网络出口不稳定请求在发起阶段就失败base_url 填了不存在的地址或者写成了 HTTPS 但服务端只支持 HTTP免费模型服务那边限流返回 429也被包装成了 server error。排查路径我给两套。先看 opencode 的日志启动时加环境变量LOG_LEVELdebug opencode日志会打印每个请求发往哪个 url、状态码是什么。如果日志显示 401直接换 Key。如果显示连接超时换一个网络环境或者直接自建本地模型。这一步能过滤掉八成问题。2.4 VS Code 和 JetBrains 插件并不是“另一个 opencode”热词里“vscode opencode插件”“idea opencode插件”出现频率很高。VS Code 插件和 JetBrains 插件的本质是把 Agent 的对话面板嵌入编辑器底层仍然调用命令行 opencode。也就是说你用插件之前命令行版必须先能跑通。插件的好处是看代码 diff 时不用切终端改完一个文件侧边栏里直接红绿对比跳转定位也更顺手。JetBrains 系装插件时还要注意 mvn 配置问题热词里“opencode mvn配置”就是这个场景。其实那是用户在 IDE 里安装了 opencode 插件后插件默认用终端命令启动但 IDE 的子进程环境里 PATH 缺少 opencode 安装目录导致插件报错。解决方法很简单在 IDE 的系统设置里给 PATH 加上 opencode 的安装路径或者在启动 IDE 前先在终端里执行一次 opencode。这个问题和 IDE 本身无关属于“环境继承”的老毛病。3. 让 Agent 真正干活Skills、MCP 和 Memory 三件套3.1 Skills 是怎么工作的很多人第一次听到“opencode skills”会误以为它类似浏览器插件或者脚本插件。实际上Skills 是给 Agent 提供“结构化操作说明”的文件集合。它可以是一段 carefully 写的提示词也可以带脚本、模板、检查清单。核心作用是把团队规范、重复性工作固化下来让 Agent 在合适的场景自动想起该怎么做。在 opencode 里Skill 本质是一个目录目录里至少有一个SKILL.md文件里面有 frontmatter 和 body。举个例子我想让 Agent 每次改完前端代码都强制跑一遍类型检查--- name: typecheck description: 在修改 TypeScript 文件后自动运行类型检查并修复错误。 --- 执行以下步骤 1. 运行 npm run typecheck。 2. 如果报错逐个文件修复。 3. 修复后再次运行确保通过。把这段内容保存到.opencode/skills/typecheck/SKILL.md然后告诉 Agent “用 typecheck 的方式帮我改这个组件”它就会按这个流程执行。这里的关键是description写得越具体Agent 在自动决策时才越容易把当前任务和 Skill 匹配上。描述里应包含触发条件比如“在修改 TypeScript 文件后”而不是一句话“类型检查”。3.2 社区技能包superpowers 和 oh-my-claudecode热词里“opencode 安装 superpowers”“opencode oh-my-claudecode”其实都是社区 Skills 集合。superpowers 是国外社区比较流行的技能包包含任务规划、代码审查、调试流程等一整套预设 skilloh-my-claudecode 则是把 Claude Code 时代的很多优秀 prompt 和 skill 迁移到 opencode 生态里。安装方法非常简单基本就是 git clone 到 skills 目录。比如git clone https://github.com/xxx/superpowers.git .opencode/skills/superpowers但是直接 clone 有个坑如果仓库里的 skill 是给 Claude Code 用的目录结构可能不完全兼容。你需要确认每个 skill 都有SKILL.md而不是只有.claude/skills下的旧格式。opencode 对 skill 目录的扫描逻辑是递归查找SKILL.md找不到就无视。所以安装社区包之后第一件事不是急着用而是检查目录结构。我更推荐的做法是不要一股脑装全部 skill而是把需要的几个单独复制到自己的.opencode/skills下。团队里留太多不相关的 skill会影响 Agent 匹配准确度。3.3 MCP 接 Playwright前端 Bug 可以让 Agent 自己复现热词里那句“opencode playwright 怎么测试前端bug”特别具体。这正好涉及到 MCPModel Context Protocol的用法。MCP 是一个标准协议允许 Agent 通过外部服务获得额外能力。Playwright MCP 就是让 Agent 能操作浏览器的服务。我在一个 React 项目里遇到过按钮点击无响应的问题手动排查非常费劲。接上 Playwright MCP 后我给 opencode 下达任务opencode run 打开 http://localhost:3000点击左上角的提交按钮观察控制台是否有报错截图后根据报错定位原因配置好之后opencode 会通过 MCP 调动 Playwright一步步打开页面、点击按钮、读取 console 日志然后拿着日志去分析错误根源。这样它不仅能看代码还能“亲眼看到”运行时的现象。你需要在opencode.json里加一个 mcp 配置段{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest] } } }注意这条配置要求你的机器装了 Node.js。启动 opencode 后它会自动拉起 Playwright MCP 服务。第一次运行会让 Agent 自动打开一个 Chromium 实例速度会比平时慢一点属正常。实际操作中我建议明确指定“用 headless 模式”或者给 Agent 一个允许使用的浏览器范围避免它反复弹窗干扰工作。3.4 Memory 不是聊天记忆是文件记忆“opencode memory”这个热词有点误导人。它不是说你关掉终端再打开Agent 还能记得上一段对话而是基于文件的项目记忆。opencode 会把每个项目的关键信息存在配置文件和历史文件里下次启动时重新加载。我理解的 Memory 分成两层一层是AGENTS.md放在项目根目录里面写项目的技术栈、启动命令、代码规范。opencode 每次进入项目时会主动读取相当于给 Agent 一份“项目说明书”。另一层是对话历史的持久化opencode 会在本地目录记录 run 的历史方便你回溯。真正好用的做法是每接手一个新项目先让 opencode 读一遍代码然后自己把技术栈和约定写进AGENTS.md。这样后续所有任务都会自动带上项目上下文不用每次重复描述。比如# AGENTS.md ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Express - 包管理pnpm ## 常用命令 - 开发pnpm dev - 构建pnpm build - 测试pnpm test ## 编码规范 - 组件文件使用 PascalCase - 不允许在业务代码中使用 any这段文件的价值比任何“记忆插件”都稳定因为它能被 Git 跟踪、能被团队 review。团队新成员拉下仓库时Agent 也自动具备同样的上下文这就把个人经验变成了团队资产。4. 实战复盘让 opencode 接手旧项目从一头雾水到改完验证4.1 第一步不是“改代码”而是先让它读项目“opencode接手开发项目”这个热搜词很典型大多数人刚接触 Agent 时上来就让它改功能结果 Agent 连项目结构都没搞清楚输出一堆幻觉代码。我的习惯是先跑一次“项目扫描”opencode run 阅读 README、package.json、src 目录结构以及现有路由配置然后输出一份项目架构说明包括前后端如何组织、接口如何调用、有哪些注意事项这个阶段不要让它写代码只看它读得准不准。如果输出描述和实际项目有偏差多半是上下文窗口不够或者某些目录被忽略了。这时可以在AGENTS.md里写清楚“核心逻辑在 src/modules 下不要在 src/generated 目录里改代码”然后再试一次。这一步的意义是Agent 后续的任务规划、文件定位都会以下面这个“读到的世界”为基础。项目读偏了后面全偏所以值得多花两分钟验证。4.2 现场演示用“读日志 - 改代码 - 让它自己测”的三段式我拿之前的 Playwright 例子继续讲。当 Agent 通过 Playwright 拿到 console 里的报错后我还会让它再做一件事修改完代码后重新跑一遍同样的页面流程确认报错消失。这个“验证闭环”特别重要否则 Agent 可能只是“以为修好了”。我倾向于给 opencode 一个多步骤任务用引号直接包起来会更容易让它理解opencode run 先用 Playwright 打开登录页面输入测试账号登录点击确定后观察网络请求找到 /api/login 返回 500 的原因然后修复代码修复完再重新跑一次登录流程验证成功实测下来它能做到的是打开页面、填表、点击、查看 Network、读后端日志、改修复代码、再自动回滚验证。整个过程我只需要最后看一次 diff。不过需要注意Agent 改到一半如果发现设计思路有问题最好及时在 TUI 里打断重新描述目标不要让它硬着头皮继续。4.3 多 Agent 怎么分工opencode、Codex、Claude Code 和 pi 的经验很多人纠结“opencode codex claude code哪个agent好用”我可以分享我的分工原则如果任务是纯粹的、模型厂商 SDK 非常成熟的场景比如调 OpenAI 的接口Codex CLI 最顺手如果要和团队知识库、私有文档、Terraform 这些强上下文打交道Claude Code 自带的企业级配置更稳如果任务涉及“多模型切换、本地优先、开源可审计”opencode 是首选pi 更像轻量级玩具适合快速跑个脚本不适合重度开发。我现在的常用方式叫“双 Agent 制”用 opencode 做代码结构和重构因为它在仓库里改文件的 diff 展示清楚、方便追踪遇到需要长对话理解业务需求的场景再切回 Claude Code。不是某一个 Agent 绝对碾压另一个而是用不同 Agent 的长板去匹配不同类型任务。4.4 团队规范怎么沉淀直接提交到仓库热词里没有直接提团队规范但“Skills”和“AGENTS.md”本质上就是团队规范的载体。我自己在团队里推 opencode 时做了这么几件事在仓库根目录建.opencode/skills放“新建组件”“代码审查”“后端接口联调”三个核心 skill在AGENTS.md里写清楚分支策略、提交规范、测试命令要求所有 Agent 完成任务后必须输出一份“变更说明”。这样同一团队的人用 opencode 时不需要每个人都自己输入一堆背景Agent 自动加载仓库里的 skill 和 AGENTS.md。而且这些文件跟着代码走新成员入职拉完仓库就自动继承。5. 版本、升级与生态2.0、免费模型下线、配置迁移的避坑建议5.1 opencode 2.0 到底改了什么热词里“opencode 2.0”很有代表性。2.0 是一次比较大的版本迭代核心改动集中在 TUI 响应速度、配置加载逻辑和 Skills 目录扫描方式上。我直观的感受是同样一个任务2.0 版本比旧版快了不少界面切换也更流畅。但升级不是没有代价。旧版本里写在opencode.json里的某些 provider 配置字段在新版本里可能被废弃。比如有些自建模型的 provider 段需要新增ai-sdk/openai-compatible的 npm 依赖字段旧版可能忽略新版就强制校验。所以每次升级前最好先备份配置cp opencode.json opencode.json.bak升级后如果发现 Agent 找不到模型或加载 skill 异常可以先打开日志再逐项排查是配置兼容问题还是缓存问题。缓存问题直接删掉~/.cache/opencode就能解决配置兼容问题就得对着文档改字段名。5.2 免费模型下线后的配置迁移“opencode hy3-free下线了吗”这个热搜词反映了免费模型服务的普遍问题不稳定说停就停。我之前也用过一些社区免费模型后来发现他们陆续限制了并发甚至停服导致项目 CI 里的自动任务中断。从那之后我彻底转向自备 Key 或本地模型。如果你正在用某个免费模型我的建议是不要把 Agent 的核心工作流绑在一个免费模型里。在opencode.json里配置一个“付费模型 免费模型”双通道付费模型做个兜底。免费模型用于简单查询和代码补全付费模型用于复杂任务。这样即使免费模型下线只需要改一行配置就能切到备用模型Process 不会断。另一种更彻底的做法是本地化。最近本地模型能力进步很快配合 opencode 跑日常开发任务完全够用。把本地模型配置好之后你甚至可以完全不依赖任何云端 API这是最可控的状态。5.3 社区包升级导致的“技能失灵”很多人装了 superpowers 或 oh-my-claudecode 后过一阵子突然发现某些 skill 不起作用了。原因通常是两种opencode 升级后SKILL.md frontmatter 要求的字段变了社区包更新时某个 skill 目录被改名导致 Agent 匹配不到旧的触发条件。解决办法是不要直接用 git pull 更新整个 skills 目录而是定期对比上游变更人工合并。更稳的方式是把用到的 skill 复制到团队自己的目录里形成 fork。这样上游更新只作为参考不会突然破坏本地环境。5.4 最终值不值得用我的结论我不会说 opencode 能完全代替 Codex 或 Claude Code但它确实是我目前最愿意长期维护的终端 Agent。原因有三点第一开源性让我能砍掉不需要的功能而不是被迫接受一个黑盒第二多模型支持让我不会被卡在单一供应方第三Skills MCP Memory 的组合让 Agent 真正可以沉淀进团队工作流而不是一个随处可换的聊天框。最后再说一个小技巧如果你第一次运行 opencode 时觉得它“不够聪明”先不要急着换模型检查是不是AGENTS.md没写、Skills 没配、上下文太多噪音。很多时候不是模型弱是 Agent 对项目的“世界观”还没建立起来。把项目背景喂给它的这一步做到位opencode 的效果会立刻提升一个档次。