1. opencode 是什么为什么我把它换成了主力 AI 编码工具先说结论opencode 是一个开源、跑在终端里的 AI 编码代理coding agent。它不是那种“你在 IDE 里装个插件、选中代码点一下生成注释”的辅助工具而是能自己读项目、改文件、跑命令、查报错、然后再改代码的独立 Agent。简单说Claude Code 能做的事它基本都能做而且因为开源你能看到它底层怎么运作也能自己改。我最早是从命令行工具开始接触它的。用过一段时间 Claude Code、Codex 这类产品的人应该都有体会AI 编码代理和传统补全工具完全是两个物种。传统插件是你写一句它补一句Agent 是你交代一个任务它自己规划步骤、动手改代码、跑测试、遇到错误自己修。opencode 就属于后者但它在模型接入上更灵活——不锁定某一家模型OpenAI、Anthropic、Google 的模型都能接甚至能接本地模型。这个特性对我来说是刚需因为我手里有好几个 API key有付费的也有免费的额度能自由切换比被绑死在一家强太多了。它适合谁我觉得三类人受益最大。第一类是重度依赖 AI 编程的开发者手里项目多、技术栈杂需要一个不挑项目的通用 Agent。第二类是想要模型自由的人不想被某一家厂商的订阅套餐绑住想按需接入不同模型的 API。第三类是喜欢折腾、愿意花时间把工具调教到顺手状态的人opencode 的配置项和 skills 机制给了很大的自定义空间。1.1 从 Claude Code 到 opencode我为什么切换我得先承认Claude Code 确实是个好工具尤其在代码理解和多步重构上表现非常惊艳。我用了大概两个月整体体验是流畅的。但有两个问题一直没解决一是它和 Claude 的订阅强绑定免费额度用完就得开会员而且会员和 API 是两条计费线这对于我这种想让团队内部分摊成本的人来说很麻烦二是它不支持本地模型的接入我知道有些场景下数据是不允许出内网的终端工具能跑本地模型是很大的优势。opencode 出现后我做了个对比测试。用同一个项目——一个内部的后台管理系统包含前端 Vue3、后端 Go、还有几个定时任务脚本——分别让两个工具完成“给订单列表增加一个按时间筛选的下拉框并支持导出筛选后的数据”这个需求。Claude Code 完成得不错但 opencode 因为在执行前会先规划一个 checklist并且每一步都明确告诉我它要改哪个文件、为什么改整个过程更可控。最让我意外的是opencode 自己主动发现了后端接口里一个时间参数格式的潜在 bug顺手帮我修了。这个“主动性”让我决定认真试试它。当然切换不是没有成本。Claude Code 的默认行为更“固执”它倾向于自己判断然后直接干opencode 更偏向“先问再干”需要你在 prompt 里把需求描述得更精确。但这个习惯养成了之后我发现反而减少了返工因为它的每一步操作都有据可循出问题了我能定位到具体是哪一步决策错了。1.2 核心架构Agent 模式与传统 AI 插件的本质区别想用好 opencode你得先理解它和传统 AI 插件的架构性差异。传统 IDE 插件比如 Copilot 那种本质是个“补全器聊天框”。它对你项目的理解来自上下文窗口但不会主动去动你的文件系统也不会擅自执行命令。它的工作方式是人写代码、AI 建议主动权在人。而 opencode 这样的 Agent 工具工作模式完全不同。它有一个会话循环agent loop大致是这样的你给它一个任务它先自己读项目的目录结构、关键文件理解现状然后它会分解任务形成一个待办清单接着它调用工具读文件、写文件、执行终端命令、搜索代码等一步步执行每执行一步它都会把结果反馈回模型模型判断是否达到目标没达到就继续达到了就结束。这个架构带来两个直接结果。第一它有能力处理跨文件的复杂改动。比如“把整个项目里所有使用旧 API 的地方迁移到新 API”这种任务对传统插件来说很难因为涉及文件太多、上下文不够但对 Agent 来说它每次只需要打开几个文件处理处理完关闭再打开下一批上下文压力小很多。我用 opencode 做过一次这样的迁移涉及 40 多个文件它整整跑了近 20 分钟中间自己还跑了两次编译来验证最终改动基本可用。第二它可以自我纠错。写代码时模型难免出错传统插件会直接把错误代码留给你opencode 会因为执行命令报错而自动进入修复循环它会读报错信息推断原因再改代码再跑直到通过。当然“跑命令”这件事对 Agent 来说是双刃剑。它有能力执行任何你能在终端执行的操作这意味着你需要给它的权限边界有清晰认知。opencode 默认会在执行危险操作前询问你比如运行rm -rf这类命令但这种安全检查并不能覆盖所有情况所以我在重要分支上都会让它先开个 fixup 分支再动手。这个习惯很重要后面我会详细说。2. 安装与基础配置从零跑通 opencode这一节写给第一次接触 opencode 的人我会把安装、初始化、模型接入和几个关键配置文件讲清楚。安装本身不复杂但很多人会卡在“装完用不了”这一步因为默认模型配置没做对。2.1 安装方式与版本选择CLI、桌面版和脚本安装opencode 的官方推荐安装方式是用一行命令拉取安装脚本。在 macOS 或 Linux 上终端执行curl -fsSL https://opencode.ai/install | bashWindows 用户建议用 WSL2 方式或者直接看官方文档里针对 Windows 的安装说明要是直接用 PowerShell 跑上述命令大概率会遇到执行策略拦截。装完后验证一下版本opencode --version如果你看到的是类似opencode 0.x.x的输出说明装好了。我用的是 0.3 版本左右这个工具迭代速度极快几乎每周都在加新功能所以建议盯一下 GitHub releases 页面看到新版本果断升级。除了 CLI 版本官方还推出了桌面版opencode desktop本质是把终端封装成带界面的应用视觉上更友好一些。我的经验是如果你同时在用 VSCode 插件桌面版其实可有可无但如果你的工作环境是裸终端 tmux桌面版能提供一个更清晰的历史会话界面倒是值得一试。还有一个安装方式容易被人忽略——用 Go 直接安装。如果本机有 Go 环境go install github.com/sst/opencodelatest注意这种方式需要保证$GOPATH/bin已经加入PATH环境变量如果装完后你会遇到“opencode 不是内部或外部命令”这个报错九成就是这个路径没配对。我后来遇到很多用户在群里问这个问题十有八九都是这个原因。2.2 首次启动、认证与核心配置项装完以后先在项目目录下运行一次opencode首次启动它会创建一个会话然后要求你配置模型 Provider。opencode 支持的 Provider 非常多支持 OpenAI 系、Anthropic 系、Google Gemini以及本地模型Ollama 等。配置文件默认放在~/.config/opencode/opencode.json你也可以在项目根目录放一个.opencode.json来覆盖全局配置这样不同项目可以用不同模型非常实用。这是我的一个最小化配置示例我用的模型是某家提供免费额度的模型服务商{ $schema: https://opencode.ai/config.json, provider: { myprovider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_PROVIDER_API_KEY} }, models: { my-model: { name: My Model } } } }, model: myprovider/my-model }这里有几个点需要解释。第一你可以把 API Key 放在环境变量里用{env:变量名}引用而不是把密钥明文写进配置文件。这样即使你把配置文件提交到仓库也不会泄露密钥。第二npm字段指定的是模型提供方 SDK 包。opencode 底层接了一个叫 Vercel AI SDK 的生态所以只要是该 SDK 支持的服务商都能直接用。如果你用的模型没有现成的 SDK 包可以选择ai-sdk/openai-compatible这个通用包只要对方提供了 OpenAI 兼容的接口就能接。配置完成后再运行opencode能看到模型列表选好模型就能开始对话了。这里我建议第一次使用的人先在对话里问它一句“帮我看一下这个项目的结构介绍下用了什么技术栈”用它的话确认一下工具是否能正常读取文件。如果这里能正常工作后面就顺畅了。2.3 接免费模型预算有限时怎么选opencode 社区里讨论很多的一个话题是“免费模型能不能用得很好”这个问题的答案取决于你的场景。如果你只是开个终端让它帮你解释一段代码、翻译报错信息、整理 commit message那免费模型的体验和付费模型差别不大因为任务轻、上下文短模型能力不至于成为瓶颈。但如果你让它做复杂重构、跨文件改代码免费模型和 Claude/GPT 顶级模型的差距就显现出来了主要体现为两步第一是“理解偏差”免费模型在理解复杂业务逻辑时容易跑偏明明你让它改 A 服务的逻辑它可能会去动 B 服务的代码第二是“纠错能力弱”它跑测试报错了分析半天可能找不到真正的根因。我实测下来免费模型更适合做“代码清理”“批量修改模式统一的代码”“生成模板”这类任务复杂任务还是得用强模型。我个人的配置策略是“双模型”一个收费的强模型做主力比如 Claude一个免费模型做辅助和轻量任务。opencode 在会话中可以用/models命令快速切换所以我会在会话前期用免费模型做探索和梳理等要动真格改代码了再用/models切到强模型。这个技巧帮我省了不少 API 费用。3. 核心使用实操从简单问答到完整项目落地工具装好、模型配好这只是起点。我真正想分享的是怎么用它打出效率。这一节我会从最常用的命令讲起然后重点分析它的 skills 机制和一个很有意思的用法——用 Playwright 来测前端 bug。3.1 日常命令与终端工作流opencode 的命令体系设计得比较直觉常用命令我用一张表列出来命令作用使用场景opencode启动新会话默认 TUI 界面日常使用opencode 任务描述非交互模式直接执行任务然后退出脚本化调用、CI 集成opencode -m 模型名指定模型启动会话临时切换模型/models在会话中切换模型轻量/重量任务切换/skills查看和管理已安装的 skills能力扩展/memory查看对话历史记忆长任务延续/diff查看当前会话改动过的所有文件 diff代码审查/undo撤销最近一次文件操作改错了想退回/compact压缩上下文把历史对话总结成摘要长会话后释放 token/quit退出会话结束工作这里重点说-m参数和/compact命令它们看似不起眼实际非常实用。比如我在一个项目里同时用两个模型做对比我会开两个终端窗口# 终端1用 Claude 处理主任务 opencode -m anthropic/claude-sonnet-4-20250514 # 终端2用免费模型做代码审查 opencode -m myprovider/free-model当终端 2 里让模型审查终端 1 里生成的代码时两个会话互不干扰这种并行工作流在开发中非常高效。而/compact命令的重要价值在于当对话历史很长、上下文窗口快满时模型会开始“忘记”早期内容处理会变得不准确。/compact会把之前的对话压缩成一份摘要释放上下文空间。我通常是每工作 20-30 轮对话就主动执行一次这比等到报“context length exceeded”再处理要顺畅得多。3.2 skills 机制给模型装上“业务专用技能包”如果你深入了解过 opencode会发现它有一个非常独特的设计叫 skills技能。这个机制简单说就是你可以给模型预先定义一组能力让它知道某个领域的常规操作套路。每个 skill 实际上是一个 markdown 文件里面写了“当你遇到 XX 场景时你应该按以下步骤操作”。以我实际用过的场景为例。我负责一个用 Vue3 TypeScript 写的前端项目组里规范是组件文件用script setup langts样式用 scss 的use引入而且每个新页面必须在router里注册路由。以前我用 AI 生成新页面时总是需要反复叮嘱“别忘注册路由”模型还是偶尔遗漏。后来我用 skills 解决这个问题。我写了一篇frontend-vueskill--- name: frontend-vue description: 当项目涉及 Vue3 前端开发时使用此技能规范包含组件写法、样式编写和路由注册。 --- ## 组件编写规范 - 使用 script setup langts 语法 - 组件命名使用 PascalCase - 样式使用 scss变量从 /styles/variables.scss 中引入 ## 路由注册 - 新页面文件创建后必须在 src/router/index.ts 中注册对应路由 - 路由 path 使用 kebab-case 命名 - 路由 component 使用懒加载方式 () import(...) ## 提交前检查 - 修改组件后运行 npm run type-check 验证类型 - 确认没有未使用的 import保存到~/.config/opencode/skills/frontend-vue.md或项目的.opencode/skills目录下。之后当我让 opencode 写一个新页面时它会在任务开始前自动读取这个 skill 文件按里面的规范执行。效果立竿见影路由忘记注册的问题彻底消失了。skill 机制的底层逻辑其实很朴素它相当于给模型一份“最佳实践手册”让它在任务开始前先读手册再动手而不是靠训练数据里泛泛的想象力来猜你项目的规范。这比你在 prompt 里反复叮嘱要可靠得多因为 prompt 会随着对话变长而稀释但 skill 会在每次任务开始时都重新加载。我强烈建议每个项目都建一个定制 skill内容不用多3-5 条最重要的规范就够了。有人担心这会增加模型执行成本实际上 skill 只在任务启动时读取token 消耗很小但收益非常大。3.3 opencode skill 的“隐藏玩法”和 memory 机制除了项目规范opencode 还支持一种更高级的玩法把“常用操作流程”写成 skill让模型自动执行。比如我写过一个叫commit-flow的 skill它规定了代码提交前要做的事先跑 lint、再跑单测、检查 Git 状态、然后根据 diff 生成符合 Conventional Commits 规范的 commit message。有了这个 skill我基本不用手动执行那些检查命令了直接跟 opencode 说“帮我提交这次改动”它就会按流程走完。还有memory机制。opencode 会把对话历史持久化存储下一次新会话里你可以通过/memory查看过去的命令、决策和项目关键信息。这有点像给 AI 助手配了一个持久记忆。我实测下来它的实现对长任务接力非常有帮助——比如你昨天和模型讨论了某个架构设计今天重新打开 opencode通过 memory 它还能记住相关上下文。不过要注意隐私边界建议只在个人可控环境中使用这个功能。3.4 使用 Playwright 测试前端 Bug这个场景我特别想展开说一说。很多人不知道opencode 可以集成 Playwright 来做浏览器自动化测试也就是说它不只是改代码还能像人工一样打开浏览器操作页面、点击按钮、输入文字验证前端功能是否正常。这对排查那些“只在交互中出现”的 bug 特别有效。具体操作方法是这样的。先确保你的项目里有 Playwright 环境然后通过 opencode 的 tool 机制装配浏览器能力。官方有一些社区 skill 或插件可以直接使用你也可以手动配置 Playwright 的启动脚本。配置好之后我会这么跟 opencode 说“这个页面的筛选功能有问题。帮我用 Playwright 打开http://localhost:5173/orders登录后点击筛选栏选择状态为‘已完成’然后点击查询看看列表有没有异常把控制台报错信息贴给我。”你会看到 opencode 自动执行一串操作启动浏览器、打开页面、模拟点击、等待网络请求、抓取控制台日志、可能还会截图。它把整个操作过程逐步输出然后结合报错信息推断问题根源。有一次它甚至测试出一个很隐蔽的问题筛选条件中的日期选择器在某浏览器核下无法弹窗这个 bug 我们在 QA 环境里被卡了两天结果它一次就复现了。要注意让 opencode 操作浏览器需要环境支持。如果你是 headless 环境需要确保 Playwright 的浏览器依赖已安装如果你本机有图形界面用 headed 模式会更容易观察错误。另外建议在开发环境如 localhost中进行这类测试不要直接让工具在线上生产环境乱点风险太大了。4. 编辑器插件生态VSCode、IDEA 与桌面版的选型与配合很多人习惯在终端里用 AI 编码代理但不可否认大多数开发者的主战场还是 IDE。opencode 在这块的生态布局也很积极VSCode 和 JetBrains 系的插件都已经有了用起来体验还算稳定但选型我建议结合自己的开发习惯。4.1 VSCode 插件把命令面板变成 AI 入口VSCode 的 opencode 插件目前基本具备原版 CLI 的核心能力安装后侧边栏会多出一个会话面板你可以在右侧跟模型对话它会在当前打开的项目上下文中操作文件。比起单独的终端VSCode 插件的最大优势是“所见即所得”你看着代码修改的过程副作用在文件树里直接体现而且 diff 视图集成得很自然——改动过的文件会标红标绿你可以逐个精读确认。我的实际体验是轻量微信用插件重型任务还是切回终端。原因在于 VSCode 插件对 TUI 里的一些高级交互比如/skills的切换、复杂 diff 的逐块对比支持还不够完整而且当会话非常长、模型要连续改很多文件时终端的输出流更清晰卡顿更少。但如果你平时主用 VSCode 且没有太重的任务需求插件完全够用。另外一个 VSCode 生态里的免费增强方案是和局域网模型服务结合使用。你可以在本地起一个支持 OpenAI 协议的服务VSCode 插件把它当作一个 provider 接入这样代码完全不出机器对安全性要求高的公司环境非常友好。4.2 JetBrains IDEA 插件Java/Kotlin 项目的最佳搭档如果你是 Java 或 Kotlin 开发者IDEA 插件的实用程度甚至比 VSCode 插件更高。JetBrains 系的 IDE 本身对代码结构理解就很强opencode 插件可以和 IDE 的智能索引配合识别工程里的依赖关系、运行配置。这意味着你让它改一个 Spring Boot 接口时它不仅能找到 Controller、Service、Mapper还能理解它们之间的调用链改动后甚至会提示你检查相关的 MyBatis XML 映射。实际测试中我让 IDEA 插件处理一个典型的 CRUD 需求新增一个“用户角色”字段涉及实体类、数据库迁移脚本、DTO、Controller 接口、前端调用代码总共 10 个左右文件。它能比较准确地生成全套代码只是偶尔在数据库字段类型和 Java 类型的映射上有偏差比如把tinyint映射成boolean而不是Integer这些地方需要你人工盯一下。IDEA 插件的配置方式与 CLI 大体一致也是读取opencode.json所以你之前配好的 provider、模型、skills 在 IDE 里直接可用这个体验很顺畅。唯一要注意的是插件版本迭代快偶尔会有和 IDE 新版本不兼容的报错建议关注 opencode 官方 release notes。4.3 桌面版与多端协同桌面版本质上是给那些“不想开终端、又想要活动会话”的用户准备的。它把终端聊天、文件列表、diff 视图整合在一个原生窗口里视觉上比 TUI 清爽很多。我第一次用桌面版时最直观的感受是切换会话非常方便——左侧是一个会话列表点一下就能切到几小时前的工作上下文这一点终端 TUI 只能靠 tmux 模拟体验远不如桌面版。但桌面版也有短板它对自定义 model provider 的配置界面支持还不完善某些配置项还是要手动改 JSON 文件。而且桌面版因为绑定了一个本地服务进程类似opencode serve在资源占用上比纯 TUI 模式要高不少如果你的开发机内存吃紧我建议优先用终端模式。说到底选型不重要关键是让工具贴合你的工作流而不是反过来。5. 踩坑实录与常见问题速查写这部分时我回顾了自己和社区里大量用户提过的共同问题以速查表的形式整理出来。我敢说这节内容你在官方文档里很难一次找全因为都是真实环境里踩过的坑。5.1 环境问题与安装排查报错/问题出现原因解决办法opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称Windows 下 PATH 未配置正确检查安装目录是否在 PATH 中建议通过 npm 或官方安装器安装并重启终端command not found: opencodeLinux/macOS 下安装目录未加入 PATH确认~/.opencode/bin或$GOPATH/bin是否在 PATH 中必要时手动export PATH$PATH:~/.opencode/binERROR: unexpected server error服务端返回异常通常是 5xx 或网络层错误检查模型 API 的状态页看是否有可用额度也可以尝试切换模型或增加超时时间配置升级后配置丢失版本更新导致配置结构变化查看 release notes备份原opencode.json新版本通常有迁移指引安装脚本执行被拦截安全策略拦截脚本执行可以手动下载二进制 release或使用包管理器安装第一行的“无法识别 cmdlet”这个问题我见得最多。很多 Windows 用户安装完选择在当前 PowerShell 窗口直接运行但新装的程序路径不会自动刷新到当前会话的 PATH 中必须重开终端才能生效。如果重开后还不行那就是安装路径本身就不在系统 PATH 中需要手动去系统环境变量里添加。有一个容易被忽略的问题当你使用go install方式安装后会安装到$GOPATH/bin目录但很多人的GOPATH/bin没有加入 PATH。这是 Go 工具链的常见坑不只在 opencode 上出现用 Go 写的小工具多了你就明白了先把PATH配好再聊别的。5.2 模型、API 与服务配置问题报错/问题出现原因解决办法模型对话响应极慢免费模型的服务端负载高或上下文过长尝试切换轻量模型执行/compact压缩上下文对话中模型“忘记”早期内容超出上下文窗口被截断定期使用/compact或拆分成多个会话处理模型生成的代码不符合项目规范没有使用 skills为项目编写技能文件在任务开头明确说明规范baseURL配置后请求 404对方服务接口路径不标准检查 baseURL 是否包含/v1路径或换用 provider 的 SDK 类型API Key 暴露在 git 提交中配置了明文密钥立即撤销旧 Key改用{env:变量名}方式引用某些模型工具调用报错模型对 function calling 支持不完整换用对 function calling 支持更好的模型或调整 tool 配置“对话中模型忘记早期内容”这个问题几乎每个长会话用户都会遇到。我的经验是不要等到明显感觉模型变笨了才做/compact而是要养成习惯。当你意识到一个会话已经持续了 30 轮以上、涉及文件超过 20 个时主动停下来让模型总结一下当前进度把结论记录到 memory然后开新会话继续。这种“接力式”用法比硬撑一个超长会话要稳定得多。还有一个真实的心得模型报错时不一定马上怀疑 opencode 本身很多时候问题出在 API 服务端。我遇到过一整个下午请求全部超时的情况排查到最后发现是模型服务商在做容灾切换跟本地配置一点关系都没有。建议你在遇到不明原因的unexpected server error时先去 API 服务商状态页看一眼别在本地瞎折腾。6. 我的经验总结衡量 opencode 好不好的两个标准最后再说点个人体会。很多人问我opencode 和 Claude Code / Codex 到底选哪个我的回答通常不是直接推荐某一个而是给他们两个判断标准——这也是我自己实践下来最看重的两点。第一看“可解释性”。AI 编码工具的决策过程是不是透明的直接决定了出问题后你能不能快速恢复。opencode 的 TUI 会明确展示每一步要执行什么命令、改哪个文件、为什么改这种透明度让我在复杂的重构中特别安心。遇到改崩了的情况我可以根据它之前每一步的操作逐级排查而不是对着一个黑盒发呆。第二看“可扩展性”。一个编码工具是否愿意开放底层机制让你定制决定了它是玩具还是平台。opencode 的 skills、memory、provider 自定义配置本质上都在做一件事把 AI 编码代理从“通用模型”变成“你的项目的专属工具”。一旦你为项目写好了 skills 文件配置好了多模型切换策略这个工具的效率和纯开箱即用相比完全是两个层级。根据我个人的实际体验opencode 在当前的开源 AI 编码代理里属于“上限很高、下限也不低”的那类。它最明显的优势是配置自由度高、社区活跃、迭代快最大的成本是你需要花点时间学习和调教它而不是装了就能立刻完全发挥出作用。如果你愿意投入两三天的学习成本来配置一遍 skills 和模型策略它带来的效率提升会是长期且稳定的。最终选不选它还是那句话——看你的工作流是否需要可持续定制而不是一次性热度。