1. OpenCode到底是什么1.1 一个终端里的AI副驾驶如果你平时已经在用 Claude Code 或者 Codex 这类终端AI编程工具最近应该频繁刷到 opencode 这个名字。简单说opencode 就是另一个跑在终端里的 AI 编程代理但它和同类工具走了不太一样的技术路线底层用 Go 编写安装完就是一个单文件二进制启动速度非常快没有 Node.js 运行时的拖累也没有复杂的 Python 环境依赖。我第一次接触 opencode 是在一个开源项目里看到它作为默认的 AI 辅助工具被写进贡献指南当时第一反应是又冒出来一个轮子。但真正用起来之后发现它和 Claude Code 的体验差异很微妙同样是坐在终端里帮你看代码、改代码、跑测试opencode 在会话管理、多模型切换、配置文件的可读性上做得更工程化一些。尤其对需要经常切换不同模型来对比效果的人来说这套机制非常顺手。它能做的事情包括读取整个代码仓库结构、根据自然语言需求搜索和理解相关文件、自动修改代码、运行测试或构建命令并读取输出、基于运行结果继续修正甚至可以把一段操作固化成可复用的 skill下次一句话就能触发。适用人群也很明确——已经在用 AI 编程助手、但对当前工具链有不满的开发人员以及那些想把AI 结对编程真正落地到日常开发流程里的团队。1.2 为什么我从Claude Code切换到OpenCode先说结论不是 Claude Code 不好而是 opencode 有几个点恰好踩中我的刚需。第一是模型不绑定。Claude Code 默认绑定 Anthropic 的模型虽然也能通过环境变量折腾其他 provider但用起来总有一种这不是官方路径的别扭感。opencode 从设计上就把模型提供商做成可插拔的默认支持一大堆平台而且支持通过ai-sdk/openai-compatible这类适配器轻松接入任何兼容 OpenAI 接口的模型。这意味着同一个工具里我可以上午用 Claude 跑代码审查下午换一个开源模型跑成本敏感的任务配置文件改一下就行。第二是会话数据完全本地化。opencode 的会话记录、消息缓存放的是纯文本和 JSON存在本地数据目录里。我可以用 grep 直接搜历史会话里的关键内容也可以把某个会话导出分享给同事。这种透明感对习惯掌控数据的人来说很重要。第三是社区迭代速度。它的 GitHub 仓库更新非常频繁MCP 支持、Agent 模式、Skills 机制这些特性都是最近几个月快速推进的而且每个版本都有比较清晰的 changelog。对一个工具爱好者来说能看到一个项目在快速进化本身就是加分项。2. 安装和第一份配置2.1 安装方式怎么选opencode 的官方安装方式大致有三条路径选哪条取决于你的操作系统和习惯。# 方式一官方安装脚本macOS / Linux curl -fsSL https://opencode.ai/install | bash # 方式二HomebrewmacOS brew install sst/tap/opencode # 方式三npm 全局安装跨平台 npm install -g opencode-ai我个人在 macOS 上用的是 Homebrew升级方便在 Linux 服务器上用的是官方脚本Windows 机器上建议直接用 npm 方式因为安装脚本对 PowerShell 的适配没有 npm 那么完善。不管你用哪种方式装完先跑一下opencode --version能正常输出版本号就说明装好了。这里有个细节值得注意opencode 是 Go 写的单二进制安装完之后不会像 npm 包那样带一大堆node_modules所以占用空间极小升级也基本是覆盖替换一个文件。对于需要在多台机器上快速部署的团队来说直接分发二进制文件是可行的甚至可以在 CI 镜像里提前装好省去每次构建都拉依赖的时间。2.2 配置模型提供商装完之后最核心的一件事就是配模型。opencode 的配置采用 JSON 格式项目级配置文件叫opencode.json放在项目根目录全局配置文件放在~/.config/opencode/opencode.json。初次运行时如果还没有配置文件它会让你先选一个模型来源。比较推荐的做法是先直接运行opencode进入交互界面按/models打开模型选择列表里面会列出已经内置的 provider。官方内置了不少平台你可以直接挑选并填写对应的 API Key。如果里面的 provider 列表没有你想要的就需要手动编辑配置文件添加。下面是我在本地配过一个基于 OpenAI 兼容接口的本地模型的示例{ $schema: https://opencode.ai/config.json, model: local/qwen2.5-coder:32b, provider: { local: { npm: ai-sdk/openai-compatible, name: Local OpenAI Compatible, options: { baseURL: http://localhost:11434/v1, apiKey: local }, models: { qwen2.5-coder:32b: { name: Qwen2.5 Coder 32B } } } } }这段配置的含义是注册一个名为local的 provider它走 OpenAI 兼容协议baseURL 指向本地 11434 端口这是 Ollama 默认的 API 端口然后声明该 provider 下有一个模型qwen2.5-coder:32b。配置里的model字段用provider/model-id的格式指定默认模型。2.3 全局配置和项目配置的关系理解 opencode 的配置继承关系对日常使用很重要。它的逻辑并不复杂启动时先读全局配置再读项目配置项目配置会覆盖全局配置的同名字段。所以你可以把通用的 provider 凭据放在全局把项目特定的模型选择和行为规则放在项目里。举个例子我全局配置里注册了四五个 provider但某个项目由于成本考虑只允许使用本地模型加一个便宜的云端模型那我就在该项目根目录的opencode.json里把model字段指过去同时可以禁用其他 provider。这样不管谁进来用这个项目默认都走同一套模型策略不会有人误选到一个非常贵的模型然后月底看账单流泪。另外配置文件中可以设置theme、agent默认模式、instructions额外指令文件等字段。我自己最常用的是instructions它允许指定一个额外的 Markdown 文件内容会被自动附加到每次会话的系统提示里。这个特性和后面的AGENTS.md配合起来效果很好。3. 实操从新项目到功能交付3.1 用AGENTS.md搭建项目记忆凡是接触过 AI 编程工具的人基本都遇到过同一个烦恼AI 每次开新会话都失忆明明上次已经说清楚的技术约束和代码风格下次它又按自己的一套来。opencode 解决这个问题的方式是读取AGENTS.md文件这个文件放在项目根目录每次启动会话时会被自动加载进上下文。所谓项目记忆本质上就是这份文件。写得好不好直接决定 AI 在项目里的表现上限。我的经验是不要写空话要写可执行、可检查的具体约束。一个比较适合当模板的AGENTS.md大致长这样# 项目规范 ## 技术栈 - 后端Node.js 20 TypeScript Fastify - 数据库PostgreSQL 15用 Prisma 做迁移 - 前端React 18 Vite样式用 Tailwind CSS ## 目录约定 - src/modules 下按业务模块划分禁止在模块外写大杂烩工具函数 - 公共类型放 src/types组件公共属性放 src/components/ui ## 编码要求 - 函数必须显式声明返回类型 - 错误处理优先用 Result 模式不要裸抛异常 - 修改数据库结构时必须生成 Prisma migration并附 rollback 方案 ## 测试要求 - 每个新功能必须补单测关键路径补集成测试 - 测试文件放在 src/**/__tests__ 下命名以 .test.ts 结尾 ## 提交规范 - commit message 遵循 conventional commits包含类型和影响范围写完这份文件之后你每次打开 opencode它会自动知道这个项目长什么样、改代码要守什么规矩。实测下来模型犯低级错误的概率明显下降比如之前总喜欢把类型定义随手写在函数文件顶部现在会主动往src/types放。这份文件本身也应该放进版本库让团队成员共享。3.2 Agent模式完整走一遍配置好模型和项目记忆之后我来带你完整走一遍一个典型任务这样你能直观看到 opencode 在实操中的能力边界。进入项目目录执行opencode默认进入 TUI 交互界面。如果你希望这次会话更放权一点可以用/agents切到 agent 模式然后输入这样一个需求我现在需要给用户模块加一个最近浏览记录功能。要求 1. 用户登录后访问过的商品详情页自动记录最多存50条 2. 记录按时间倒序返回翻页接口支持 page 和 pageSize 3. 新增一张表来存数据用 Prisma 迁移 4. 前端在个人中心加一个列表页展示这些记录 5. 所有关键路径补单元测试opencode 收到指令后会做几件事先通过代码搜索工具定位用户模块、商品详情页路由和前端页面结构然后读取相关文件内容生成一个实现方案。通常它会先向你确认方案要不要调整比如表结构设计、索引方案、缓存策略这些关键点。你确认后它开始动手改代码。我实际操作下来值得表扬的是它的执行透明度和失败自愈能力。它会像真人一样一步步操作每改完一个文件就显示出来跑测试如果失败了会读取错误输出并自己尝试修复。比如有一次它改了 Prisma schema 之后忘了执行生成客户端测试直接报找不到 PrismaClient它就自己跑npx prisma generate然后重新测试整个过程不需要我干预。但也别指望它每次都能一步到位。复杂需求最好拆成一个一个小步骤来做每完成一个就让它跑一次相关测试。这和带新人是一个道理任务颗粒度越清晰产出质量越稳定。3.3 Skills把重复工作变成可复用命令如果你用过 Claude Code 的 skills那么 opencode 的 skills 机制会很容易理解。它是把一段相对固定的执行流程固化成可复用的操作之后一句话就能触发。举一个我团队里实际在用的例子。我们的项目提交 PR 之前需要跑 lint、类型检查、单测、构建还要按模板生成 changelog。以前这些步骤是写成一个 shell 脚本手动执行现在通过 skill 封装给 opencode{ skill: { name: pre-pr-check, description: 提交 PR 前执行完整检查流程, steps: [ 运行 npm run lint 检查代码规范如果报错逐条修复并说明原因, 运行 npx tsc --noEmit 检查类型错误有错误就修复, 运行 npm run test 执行单元测试失败的情况下分析失败原因并修复, 运行 npm run build 确认构建通过, 以上步骤全部通过后根据 git diff 自动生成 changelog 片段 ] } }配置好之后在会话里输入帮我跑一遍 pre-pr-check它就会按照步骤列表逐项执行。这个机制最大的价值不是省那几行命令而是让执行标准变得统一。以前同事提 PR 之前各查各的有人漏跑类型检查、有人忘了跑单测现在让 AI 按固定流程执行一遍质量下限被兜住了。我自己的建议是把团队里那些文档里写得很清楚但总是有人不照着做的流程挨个固化成 skill。效果比贴十条群公告都好使。4. IDE联动VS Code和JetBrains4.1 VS Code插件使用虽然 opencode 的终端体验已经很完整了但很多人的日常开发主力还是 IDE于是能不能在编辑器里直接嵌入 opencode就成了必然的诉求。官方推出了 VS Code 插件直接在扩展市场搜 opencode 就能安装。这个插件的核心价值不是把 TUI 搬进编辑器而是打通了编辑器上下文和终端 agent之间的连接。装好插件后你在编辑器里打开的文件、选中的代码片段可以一键发送给 opencode 会话。最实用的是代码选中后右键直接选择 Ask opencode它会把选中内容和当前文件路径、语言类型一起带过去省去手动解释我指的是哪段代码的麻烦。另外插件和终端会话的联动做得也算流畅。你可以在插件面板里启动一个新会话然后在编辑器里边看代码边等它改文件改动会实时出现在文件树里配合编辑器的 diff 视图就能快速审查每一处修改。如果你习惯用 VS Code 内置终端也可以直接在终端里跑 opencode插件会识别到当前工作区并自动关联上下文效果是等价的。我的实际体感是日常轻量级提问这个函数是干嘛的帮我解释这段正则直接在编辑器里选中问就行涉及多文件改动的大任务还是切到终端跑TUI 的操作节奏更适合长会话。4.2 JetBrains系列配置JetBrains 家族的插件同样在官方市场可以找到。安装方式不再赘述重点说几个 JetBrains 生态下的差异化体验。第一是和编辑器弹窗提示的集成。在 IDEA 或 GoLand 里选中代码后可以通过 AltEnter 呼出意图操作菜单里面会出现 opencode 相关的选项。这个入口对快捷键党很友好手指不用离开键盘就能把代码送入会话。第二是外部工具链的路径识别。JetBrains 项目往往配置了复杂的 SDK、Maven 或 Gradle 环境opencode 在执行命令时需要能正确读出 JDK 路径、Maven 仓库等变量。如果你在命令行里跑mvn没问题但 opencode 里报mvn: command not found大概率是 JetBrains 自己管理的 PATH 和系统 shell 不一样。解决方式是在 opencode 配置里把必要命令的绝对路径写进env字段或者直接用 JetBrains 自带的 Terminal 启动 opencode这样继承的就是 IDE 的环境变量。第三是在大项目里的索引体验。JetBrains 项目动辄几十万行代码opencode 首次扫描代码库会花一点时间。建议在配置文件里把不需要关注的目录排除掉比如target、node_modules、dist这样既能加快上下文加载又能减少 AI 被无关注释文件干扰的概率。在实际项目里我甚至见过一种玩法在 IDEA 里写代码写完一个方法就选中它让 opencode 补单元测试AI 生成的测试直接在编辑器里打开跑挂了就让它继续改。这种写代码和测代码分属人和 AI的协作方式效率相当可观。5. 常见问题排查实录5.1 Windows下无法识别opencode修复如果你在 Windows 的 PowerShell 里输入opencode后遇到类似的报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的本质是系统在 PATH 环境变量里找不到 opencode 的可执行文件。按我的排查经验按顺序检查下面三个地方基本都能解决。第一确认安装位置。如果你用的是 npm 全局安装先执行npm config get prefix拿到 npm 全局目录opencode 的入口文件就在这个目录下面。第二检查这个目录是否在用户 PATH 里。Windows 下通常需要把%APPDATA%\npm或 npm prefix 目录加进用户环境变量的 Path 中。第三修改完 PATH 之后一定记得把终端窗口全部关掉重开Windows 的终端不会自动刷新环境变量新开的窗口才会读到最新的 PATH。如果你用的是安装脚本方式那安装脚本在 Windows 上的兼容性本身就不如 macOS 和 Linux遇到这种报错我建议干脆卸载后改用 npm 方式安装。省下的折腾时间足够喝一杯咖啡。5.2 unexpected server error排查还有一种高频报错是运行任何命令都可能出现的error: unexpected server error. check server logs这种错误比较迷惑人因为它把问题指向了服务器日志但对单机使用的人来说第一反应基本都是哪来的服务器。实际上 opencode 本地会启动一个后端服务进程来管理会话和工具调用这个报错的意思是后端服务在处理请求时异常退出或返回了非预期结果。排查思路我总结为三步第一步看日志。opencode 的日志默认存在~/.local/share/opencode/log/目录下找到最新的日志文件用 tail 看最后几十行一般能看到具体的错误堆栈。第二步判断是模型侧问题还是工具调用问题。日志里如果能定位到是某个模型 provider 返回了 4xx/5xx 错误那基本是 API Key 失效、额度不足或者模型名不对。如果堆栈指向文件读写或命令执行那就是本地环境问题。第三步兜底操作退出当前会话删掉数据目录里的缓存子目录注意别删配置重新启动。opencode 的状态管理整体比较干净重启基本能恢复正常。老实说这类报错在快速迭代的 tool 里不算罕见关键是别慌先看日志再动手。日志里的信息量通常比表面报错大得多。5.3 模型切换与ccswitch联动opencode 本身的多模型能力很强但如果你同时使用 Claude Code、Codex 等多个终端工具每个工具各自维护一套模型配置确实很烦。社区里很多人会引入 ccswitch 这类工具来统一管理它本意是为 Claude Code 做的模型切换工具但因为很多配置的存储方式大同小异也能间接服务 opencode。不过我个人对 ccswitch 和 opencode 的联动持谨慎态度。opencode 的 provider 机制和 Claude Code 的配置结构并不完全一致强行共用一套配置文件可能反而会引入兼容性问题。更稳妥的做法是opencode 这边就直接用它的原生配置来管理 provider全局配置文件里写好所有需要的平台会话内用/models随时切换一样很顺滑。这里分享一个我自己的模型切换策略默认的model字段配成一个性能均衡、成本可控的模型处理日常轻量任务遇到复杂重构或者代码审查需求时临时切换到更强的模型跑批量小任务时切到便宜或本地模型。整个切换过程在 TUI 里按两下快捷键就能完成这才是 opencode 多模型设计真正省心的地方。5.4 其他值得注意的坑除了上面两个大问题还有几个小坑提一下。第一个是AGENTS.md文件放错位置。opencode 只会自动读取项目根目录下的AGENTS.md如果你把它放进了docs目录或者改了名字它是不会加载的。我一开始就是把团队规范放在docs/guidelines.md结果发现 AI 根本不认后来把内容软链接到根目录的AGENTS.md才生效。第二个是本地模型上下文窗口限制。用 Ollama 之类跑本地模型时如果项目代码库很大上下文很容易被打满表现就是模型开始胡言乱语或者重复输出。解决办法是让 opencode 的检索尽可能精准或减少无关文件的扫描。用exclude配置把大型生成目录排除掉是最直接的优化手段。第三个是长会话的内存占用。跑了几个小时的会话里积累了海量工具调用记录有时会导致界面操作变卡。这时可以直接开一个新会话如果项目记忆写得好新会话能很快进入状态不需要硬撑着用卡顿的旧会话。6. 工具对比与我的最终配置6.1 opencode/codex/claude code怎么选用了一段时间之后我对这几个主流工具算是有了一点自己的判断。它们做的事情非常接近但各自的性格差异其实很鲜明。对比维度opencodeClaude CodeCodex模型绑定多模型可插拔以 Anthropic 系列为主以 OpenAI 系列为主安装形态Go 单二进制轻量npm 包依赖 Node 环境官方 CLI环境要求明确配置文件JSON结构清晰环境变量加配置文件命令行参数加配置文件会话管理本地 JSON可搜索会话加密存储会话可管理社区生态快速迭代MCP/Skills 支持好生态成熟插件丰富与 GitHub 集成深上手门槛中低低低如果说结论那就是如果你只用一家模型的产品、不太关心配置自由度Claude Code 和 Codex 各自的闭源体验都打磨得不错如果你像我一样需要在多个模型间横向比较、经常切换成本策略或者对本地模型有硬性需求opencode 的灵活度是这几个里面最高的。6.2 我当前的生产配置文章最后把我的配置思路完整分享出来。它不是标准答案但至少是一条被我在真实项目中验证过的路径。我当前的~/.config/opencode/opencode.json核心部分{ $schema: https://opencode.ai/config.json, theme: opencode, model: primary/claude-sonnet-4, agent: build, provider: { primary: { npm: ai-sdk/anthropic, name: Primary Claude, options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4: { name: Claude Sonnet 4 }, claude-opus-4: { name: Claude Opus 4 } } }, local: { npm: ai-sdk/openai-compatible, name: Local Models, options: { baseURL: http://localhost:11434/v1, apiKey: local }, models: { qwen2.5-coder:32b: { name: Qwen Coder 32B } } } }, exclude: [ node_modules, dist, build, target, .git ] }配合项目根目录的AGENTS.md一起使用基本上日常开发里 80% 的重复性工作都能交给它。轻量任务我就用默认的 Sonnet 模型重活切成 Opus纯机械操作或离线环境就用本地模型效率与成本的平衡感拉满。如果你也准备在团队里推广 opencode我的建议是别一开始就追求全自动 AI 改代码而是先从AI 辅助代码审查和固定流程自动化这两个场景切入。等团队习惯了这种协作模式再逐步放开 Agent 的权限去真正接手功能开发。任何工具的价值都要靠合适的落地姿势才能发挥出来opencode 也不例外。
