最近几天我把主力终端AI助手从Claude Code切换到了opencode中间踩了几个典型的坑也发现了一些被低估的地方。如果你正在关注开源AI编程助手想找一个能接多种模型、又有完整插件生态的工具这篇是我用opencode接手实际开发工作的完整记录它是什么、怎么装、模型怎么配、skills怎么用、插件怎么选以及与Codex、Claude Code之间的真实差异。opencode是一个开源的终端AI编程agent能直接在你的项目里读代码、改文件、跑测试、执行命令通过TUI界面和它对话。这篇文章从零开始把安装到上手全流程说清楚适合已经习惯“让AI帮我改代码”、但还没找到趁手工具的开发者也适合想从单一模型助手迁移到多模型工作流的人参考。1. 先搞清楚opencode到底是哪个项目解决什么问题1.1 同名项目不少别一开始就装错opencode这个单词在GitHub上能搜出一堆同名仓库这也是很多人踩的第一个坑。热度最高、也是我今天要聊的是SST团队开源的终端AI编程agent项目地址在sst/opencode官方网站是opencode.ai。它跟早期那个“用网页打开VS Code的open code”完全是两回事别混了。这个项目本质上是一个运行在终端里的AI编码助手核心形态是一个TUI界面。你在项目目录下敲opencode它会启动一个对话窗口读取当前项目的文件结构、Git状态、语言上下文然后你可以直接下指令帮我修这个bug、给这个接口加单元测试、解释这段业务逻辑、把这段代码重构一下。它不只是聊天而是真的能在你的工作区里创建文件、修改文件、执行命令再根据结果继续调整。1.2 它和Claude Code、Codex的关键区别在哪同样是终端里的AI编程agentopencode和Claude Code、OpenAI Codex的定位还是有明显差异我从实际使用角度说几个感受最深的点。第一个是模型开放性。Claude Code基本绑定Anthropic系列模型Codex绑定OpenAI系模型而opencode从设计上就支持多个provider。你可以在同一个界面里切换Anthropic、OpenAI、Google Gemini甚至接本地模型比如Ollama。对开发者来说这意味着你可以根据不同任务选不同模型也可能用本地模型处理一些敏感代码不需要把业务代码上传到外部服务。第二个是配置的工程化程度。opencode有项目级配置文件opencode.json模型、provider、技能路径等都写在配置里可以跟着项目走。团队协作时新人clone仓库后跑一遍opencode就能用同一套配置这比每个人各配各的开销要小得多。第三个是skills技能机制。这个机制最早被Claude Code带火opencode很快跟进并做了自己的实现。简单说skills就是一套markdown指令集你可以把团队代码规范、常用命令、测试流程写成技能文件agent在遇到相关任务时会自动加载这些指令。这个后面我会专门展开讲。第四个是开源可审计。原项目代码完全开放数据流向、权限控制、底层实现都能直接看源码对一些对供应链安全有要求的团队来说这一点是闭源工具没法比的。2. 从安装到跑通第一个任务命令、路径和Windows专属坑2.1 安装前的环境准备opencode本质是Node.js应用最常用的安装方式就是npm全局安装。先确认几样东西Node.js版本建议18以上我用的是20.x没遇到兼容问题Git要装好因为agent在读取diff、提交代码时依赖Git另外终端要能正常走代理或者直连外网因为模型API的调用需要网络。2.2 三种安装方式推荐第一种# 方式一npm全局安装最主流 npm install -g opencode-ai # 方式二macOS下用Homebrew brew install sst/tap/opencode # 方式三官方安装脚本 curl -fsSL https://opencode.ai/install | bash这里提醒一下npm包名是opencode-ai不是opencode。如果直接npm install -g opencode会装到一个完全不相干的老项目上去。这个坑我已经见过好几次了安装前一定看清楚包名。装完验证一下opencode --version如果能正常输出版本号说明安装成功。如果提示找不到命令看下面这节。2.3 Windows下“cmdlet不识别opencode”的真正原因热词里有这么一条“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名”。这是Windows用户最常见的安装问题我帮人排查过好几次原因几乎都是同一个npm全局安装目录没有加到系统PATH里。解决步骤很直接先查npm全局目录在哪npm config get prefix把输出目录加到PATH。比如输出是C:\Users\你的用户名\AppData\Roaming\npm那就打开“系统属性 - 环境变量”在用户变量PATH里追加这个路径。配置完后关掉当前终端重新打开一个新终端再跑opencode --version。如果加完PATH还是不行可能是权限问题。npm全局目录在Program Files下面时经常出现权限不够的情况建议把npm prefix指到用户目录里npm config set prefix $env:APPDATA\npm # 重新安装 npm install -g opencode-ai另外一个常见问题是Windows下偶尔会被安全软件拦截npm脚本执行如果执行时提示权限相关错误检查一下终端是不是以管理员身份跑的以及执行策略是不是正常的。2.4 首次启动与模型登录装好之后在任意项目目录下运行opencode第一次进去会提示你选择模型。以Anthropic官方账号为例流程是opencode auth login回车后会列出支持的provider选择Anthropic然后按提示完成登录。登录成功之后opencode会把凭据保存在本机配置里后续启动不用重复登录。这里多说一句如果你同时有多个provider的key建议都登录一遍因为后面切换模型时就不用再输一遍了。多模型配置的具体玩法我在下一章详细说。2.5 我的第一个真实任务让它修一个bug登录完我随手打开一个Go项目给opencode下了一个指令“看一下main.go里的并发处理竞态检测器报了几个警告定位原因并修复。”opencode先自动翻了main.go和go.mod确认这是Go 1.21项目然后建议跑go build -race复现问题。我同意后它执行了命令看到输出定位到一处map并发读写随后直接创建了修复后的diff把普通map换成了sync.Map我再选择“应用改动”整个流程就结束了。整个过程最让我满意的地方是它不乱来改代码前会先确认执行命令前会说明要做什么遇到权限相关的操作会停下来问。这种“有边界的自主”正是我希望agent具备的。2.6 “unexpected server error”排查思路终端里报error: unexpected server error. check server lo...这是热词里出现频率很高的一条。我的经验是分三步排查第一步确认模型服务端是否正常。如果你用的官方API登录官方控制台看余额和访问状态如果消息大面积报服务端错误通常是对方服务端问题等一会儿再试。第二步确认本地的登录态是否过期。重新执行opencode auth login刷新凭据能解决相当一部分“昨天还能用今天突然报错”的情况。第三步确认配置文件是否改坏。如果你手动改过provider配置、环境变量很可能是配置里的key格式或API地址写错了。比较好的做法是先临时把配置文件改名备份让opencode回到默认状态再试。3. 模型配置是opencode最值钱的部分多provider的玩法3.1 官方支持哪些模型opencode对模型的支持理念是“开放优先”官方文档维护了一份完整的模型列表覆盖了Anthropic的Claude系列、OpenAI的GPT系列、Google的Gemini系列以及一批开源模型。对大多数人来说最关心的可能是能不能顺便用本地模型兜底以及怎么配置一套统一的模型管理。3.2 项目级配置文件opencode.json多模型管理的核心是项目根目录下的opencode.json。我的配置大概长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { openai: { apiKey: {env:OPENAI_API_KEY} }, google: { apiKey: {env:GEMINI_API_KEY} } } }日常开发我主力用Claude Sonnet系列长上下文任务切到OpenAI的模型前端页面走Gemini各有各的优势。你可以把环境变量直接引用到配置文件里这样不会把key提交到代码仓库。这套配置的好处是跟着项目走切换模型不再依赖终端里临时设置的变量git提交时也不需要担心key泄露。我通常会在.gitignore里把opencode.local.json忽略掉把自己的模型偏好留在本地把公共配置提交到仓库。3.3 本地模型接入Ollama本地模型最大的价值是处理敏感代码和不依赖外网。接入方法也很简单先在本地装好Ollama拉一个模型ollama pull qwen2.5-coder:7b然后在opencode.json里加一个本地provider{ provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:7b: { name: Qwen Coder 7B } } } } }然后在对话里通过/models命令切换到ollama/qwen2.5-coder:7b就可以开始本地模型对话了。这里必须说清楚7B量级的本地模型跟云端大模型在代码生成质量上差距是肉眼可见的它更适合做代码解释、简单重构、日志分析这类对智能要求不高的任务不太适合让它独立开发复杂功能。我一般只在处理敏感片段或离线环境时切过去。3.4 关于“免费模型”和模型切换这个话题很多刚接触opencode的人一上来就问“有没有免费模型”。我的建议是分两条线看一是模型服务商官方提供的免费额度这是合法且安全的二是本地模型也是完全自己掌控的至于社区里那些来路不明的“免费中转”渠道我建议直接跳过一是key容易泄露二是稳定性完全没有保障三是代码安全问题。给自己的开发环境配一个正规的API额度本质上是对自己调试效率和代码安全负责。社区里也有一些模型配置切换工具比如ccswitch这类可以把一套API配置复用到不同的终端AI助手上。这类工具的价值在于统一管理而不是帮你找“白嫖渠道”。我个人的态度是工具可以了解但核心思路一定要放在“正规、可审计”这几个字上。4. skills让agent学会你的工作习惯4.1 skills是什么跟提示词有什么区别如果你用过Claude Code的skills那对opencode的skills机制一定不陌生。简单说skills就是把一段高度结构化的markdown指令集放在指定的目录里当agent判断当前任务涉及某个技能时会自动加载这个技能文件的全部内容作为上下文。它跟普通提示词最大的区别在于“自动触发”和“结构封装”。普通提示词需要你每次手动粘贴给agent而skills设置好之后agent会根据你描述的任务自动匹配并加载相应的技能指令不需要你重复解释“按什么流程做、用什么格式输出”。这相当于给agent建立了“肌肉记忆”。4.2 skills的存放位置和格式opencode有两个存放skills的目录全局目录所有项目共用一般放在~/.config/opencode/skills/项目目录跟随仓库走放在.opencode/skills/下每个技能是一个文件夹里面必须有SKILL.md文件结构大概是--- name: code-review description: 对当前变更做一次代码审查重点关注并发问题、资源泄漏和错误处理 --- 执行代码审查时遵循以下步骤 1. 先运行 git diff 获取当前变更 2. 逐文件检查并发安全、资源释放、错误处理 3. 按严重程度输出问题列表严重/一般/建议 4. 每条问题给出对应的修复建议和demo代码 5. 最后汇总变更文件清单和风险点关键是description字段它是agent决定何时触发这个技能的“索引”。所以description写得越具体越好尽量包含你能想到的、用户在对话里会使用的句子。4.3 一个真实可复用的前端bug排查skill热词里有一条“opencode playwright 怎么测试前端bug”这正好是我配置过的场景。前端bug的复现一直是agent能力里比较弱的一环因为agent看不到页面只能靠静态代码分析。但结合Playwright这个问题能被很好地解决。我写了一个专门用来排查前端bug的skill核心思路是让opencode用Playwright写一个自动化脚本先复现问题再定位代码。SKILL.md大致长这样--- name: frontend-bug-repro description: 排查前端页面bug时先使用Playwright脚本复现问题再结合源码定位根因 --- 当用户反馈前端页面出现bug时按以下流程处理 1. 先根据bug描述找到对应路由和组件代码 2. 使用Playwright编写一个能复现该bug的测试脚本 3. 脚本中要包含用户描述的关键操作步骤和期望结果 4. 在本地启动开发服务器运行脚本 5. 根据脚本失败信息判断是渲染问题、网络问题还是交互逻辑问题 6. 定位到具体组件后给出修复方案 7. 修复后再次运行同一脚本确认bug不再复现有了这个skill之后我排查前端bug的效率高了很多。以前是让agent猜问题原因改一版跑一版现在是先复现、再定位、后修复、最后回归一条链路走下来。这也是我觉得skills最值得配置的原因。4.4 团队级skills的沉淀在团队开发场景里把代码规范、上线检查清单、提交信息规范沉淀成skills价值会非常大。新成员加入时不用看一堆文档只要让opencode遵循某个skill它就能按团队约定来执行任务。我给团队配过一个“Go代码审查”技能和一个“标准提交信息”技能效果很好。前者会在每次提交前检查错误处理是否完整、并发访问是否安全后者会强制按conventional commits格式生成提交信息。这东西只要配一次后面省下来的沟通成本是相当可观的。5. 从终端到桌面插件生态和多端协同5.1 VSCode插件把agent塞进编辑器热词里有不少“opencode vscode插件”的搜索。opencode官方提供了VS Code扩展装上之后可以在侧边栏直接使用agent能力不用切到终端窗口。实际体验下来它更适合“边看代码边让agent改东西”的场景你在编辑器里选中一段代码右键发送给opencode让它解释或者重构它把建议diff返回后你可以直接在编辑器里diff视图审阅并接受。同时TUI模式下它就没有离开日常重活还是在终端里做因为TUI的信息密度、长上下文对话体验更好。这个组合算是我目前效率最高的模式。5.2 JetBrains插件与Java/Maven项目配置opencode也有JetBrains插件IDEA里可以直接安装。对于Java项目特别是Maven工程配置上有个容易被忽视的点opencode需要知道项目的构建和测试命令才能很好地完成编译、测试、修复。我把自己项目的构建信息写进了项目说明文件比如AGENTS.mdopencode启动时会读取这类项目级说明文件内容大致是本模块是Java 17 Spring Boot 3项目使用Maven构建。 构建命令mvn clean package -DskipTests 测试命令mvn test 单元测试报告生成mvn surefire-report:report之后opencode在改代码时会自动使用mvn test验证改动而不是傻乎乎地手动猜测。这个习惯对任何语言都适用尤其是Java这类构建链比较重的项目。5.3 桌面版和“superpowers”这类增强包opencode还有桌面版opencode desktop本质上是把TUI过程可视化对不习惯命令行的新手更友好。老手依然会更喜欢纯终端版启动快、内存占用小。另外一个大热话题是给opencode装“superpowers”。所谓superpowers是社区里一个流行的skills增强包里面封装了一整套方法论级的技能比如“头脑风暴”“系统设计”“debug排查”等。装好之后opencode在面对复杂任务时会更体系化而不是直给方案。官方也支持sst/opencode兼容Claude Code风格的skills目录所以不少给Claude Code写的技能包能直接迁移。配置这些增强包的关键是读README搞清它的skills目录结构然后把路径映射到opencode的配置里。整体不算难照着文档走就行。5.4 接手存量开发项目的实际经验“opencode接手开发项目”是热搜词里我觉得最实用的一条。实际场景是你拿到一个从没接触过的代码仓库直接扔给opencode让它改需求很容易翻车。它不了解项目的领域语言、潜在约定甚至不知道构建命令是什么。我的做法是分三步第一步先让opencode只做“理解”不做“改动”。让它把项目结构、数据流、核心模块读一遍输出一份项目总结。这个阶段我发现它读代码的能力比大部分人想象中强能把那些“没有文档的老项目”梳理出清晰的脉络。第二步在对话里追问自己关心的细节某个核心模块的数据模型、越权校验在哪实现、某条链路的日志追踪策略。把项目的“活文档”沉淀在脑图或笔记里。第三步再让它动手改代码。这一步就稳很多因为核心上下文已经建立。改之前务必让opencode先说明改动方案确认风险点后再执行。5.5 周边工具链oh-my-claudecode这类打包方案热词里还有“oh-my-claudecode”。它本来是给Claude Code做终端增强配置的社区项目把一些常用快捷键、skill、命令布置成一套打包方案。因为opencode和Claude Code的skills机制高度相似这类方案的许多配置也能迁移到opencode上省去自己从头配的时间。这类工具用的一个好的姿势是“看它的设计思路而不是照抄它的配置”把别人沉淀好的技能拿过来后根据自己的实际工作流删减修改最终形成自己顺手的一套配置。6. 用了一周后的真实体感它和Codex、Claude Code怎么选6.1 三者能力的横向对比维度opencodeClaude CodeOpenAI Codex模型支持多provider可切Anthropic/OpenAI/Gemini/本地基本绑定Claude系列基本绑定OpenAI系列安装难度npm一条命令官方脚本官方脚本/npm配置文件opencode.json项目级多配置位点社区方案丰富配置项较封闭skills机制原生支持兼容度高原生支持不支持同等机制TUI体验成熟信息密度高稳定好用偏向轻量CLI编辑器插件VSCode JetBrainsVSCode/JetBrains主要依赖网页端开源是否否团队协作配置项目级配置可共享较好但生态割裂一般单看功能opencode在“开放性”和“可定制性”上优势明显。Claude Code的问题解决的闭环更强因为模型和产品是同一家公司设计很多小细节做得很顺手Codex背靠OpenAI的代码能力尤其适合深度依赖OpenAI模型的团队。而opencode相当于“把决定权还给了用户”。6.2 我实际的使用分工我用了一个多星期后形成的分工是这样的日常主力agentopencode配合Claude模型做功能开发、重构、写测试。原因是它让我能在不同模型间切来切去某些场景下用Gemini某些场景切换到本地模型。复杂架构设计、大段代码的语义化重构Claude Code更擅长一些它跟Claude模型配合得比较深。需要快速在网页端验证idea、处理少量代码直接用Codex网页版更快不用配环境。说白了它们不是替代关系而是互补关系。如果你只能选一个我更推荐opencode因为它在模型自由度上留了后手。6.3 值得注意的缺点和隐藏成本opencode也不是没有短板。第一次用它的时候没有完整项目说明文件的项目它也会出现误判偶尔给出“看起来很合理但实际跑不通”的改动。TUI的配色和响应速度虽然比我预期好但跟Claude Code相比还是有一点差距偶尔在超大工程里会出现轻微卡顿。最需要留意的是token消耗。多provider灵活切换是好事但也容易让人忽略不同模型的计费差异极大长会话的上下文积累会拉高单次调用成本。我现在的做法是遇到超长会话及时开新对话把之前的结论整理成项目说明文件再携带到新会话中而不是长期挂在一个上下文里。另外opencode迭代很快从2.0开始几乎每周都有新版本。配置方式、skills路径这类东西在不同版本之间可能有差异遇到行为变化时先去看官方changelog别急着怀疑是自己配错了。6.4 一个关于“memory”的心得热词里还有“opencode memory”。我的理解是opencode的记忆能力更多来自项目说明文件和skills而不是自动的长期记忆。它不会像人一样“记得你上次让它怎么做事”除非这些经验被固化到了配置里。所以我现在的习惯是每做完一个模块顺手把“这个项目里的约定”“容易踩的坑”“常用的命令”追加到项目的AGENTS.md里。下次不管是我自己还是团队其他人再开opencode它都能在一开始就获得这部分上下文少走很多弯路。这种“主动沉淀经验”的工作方式比单纯依赖工具本身的记忆能力要靠谱得多。如果你刚接触opencode我的建议是从小任务开始先让它读代码、梳理逻辑、写测试逐步建立信任再放手让它做复杂重构。第2章里那些Windows的坑、服务端报错的排查链路、skill的配置格式都是我自己踩过之后的沉淀希望能替你省掉几天的弯路。
开源终端AI编程助手opencode实战：安装配置、skills与插件生态全解析
最近几天我把主力终端AI助手从Claude Code切换到了opencode中间踩了几个典型的坑也发现了一些被低估的地方。如果你正在关注开源AI编程助手想找一个能接多种模型、又有完整插件生态的工具这篇是我用opencode接手实际开发工作的完整记录它是什么、怎么装、模型怎么配、skills怎么用、插件怎么选以及与Codex、Claude Code之间的真实差异。opencode是一个开源的终端AI编程agent能直接在你的项目里读代码、改文件、跑测试、执行命令通过TUI界面和它对话。这篇文章从零开始把安装到上手全流程说清楚适合已经习惯“让AI帮我改代码”、但还没找到趁手工具的开发者也适合想从单一模型助手迁移到多模型工作流的人参考。1. 先搞清楚opencode到底是哪个项目解决什么问题1.1 同名项目不少别一开始就装错opencode这个单词在GitHub上能搜出一堆同名仓库这也是很多人踩的第一个坑。热度最高、也是我今天要聊的是SST团队开源的终端AI编程agent项目地址在sst/opencode官方网站是opencode.ai。它跟早期那个“用网页打开VS Code的open code”完全是两回事别混了。这个项目本质上是一个运行在终端里的AI编码助手核心形态是一个TUI界面。你在项目目录下敲opencode它会启动一个对话窗口读取当前项目的文件结构、Git状态、语言上下文然后你可以直接下指令帮我修这个bug、给这个接口加单元测试、解释这段业务逻辑、把这段代码重构一下。它不只是聊天而是真的能在你的工作区里创建文件、修改文件、执行命令再根据结果继续调整。1.2 它和Claude Code、Codex的关键区别在哪同样是终端里的AI编程agentopencode和Claude Code、OpenAI Codex的定位还是有明显差异我从实际使用角度说几个感受最深的点。第一个是模型开放性。Claude Code基本绑定Anthropic系列模型Codex绑定OpenAI系模型而opencode从设计上就支持多个provider。你可以在同一个界面里切换Anthropic、OpenAI、Google Gemini甚至接本地模型比如Ollama。对开发者来说这意味着你可以根据不同任务选不同模型也可能用本地模型处理一些敏感代码不需要把业务代码上传到外部服务。第二个是配置的工程化程度。opencode有项目级配置文件opencode.json模型、provider、技能路径等都写在配置里可以跟着项目走。团队协作时新人clone仓库后跑一遍opencode就能用同一套配置这比每个人各配各的开销要小得多。第三个是skills技能机制。这个机制最早被Claude Code带火opencode很快跟进并做了自己的实现。简单说skills就是一套markdown指令集你可以把团队代码规范、常用命令、测试流程写成技能文件agent在遇到相关任务时会自动加载这些指令。这个后面我会专门展开讲。第四个是开源可审计。原项目代码完全开放数据流向、权限控制、底层实现都能直接看源码对一些对供应链安全有要求的团队来说这一点是闭源工具没法比的。2. 从安装到跑通第一个任务命令、路径和Windows专属坑2.1 安装前的环境准备opencode本质是Node.js应用最常用的安装方式就是npm全局安装。先确认几样东西Node.js版本建议18以上我用的是20.x没遇到兼容问题Git要装好因为agent在读取diff、提交代码时依赖Git另外终端要能正常走代理或者直连外网因为模型API的调用需要网络。2.2 三种安装方式推荐第一种# 方式一npm全局安装最主流 npm install -g opencode-ai # 方式二macOS下用Homebrew brew install sst/tap/opencode # 方式三官方安装脚本 curl -fsSL https://opencode.ai/install | bash这里提醒一下npm包名是opencode-ai不是opencode。如果直接npm install -g opencode会装到一个完全不相干的老项目上去。这个坑我已经见过好几次了安装前一定看清楚包名。装完验证一下opencode --version如果能正常输出版本号说明安装成功。如果提示找不到命令看下面这节。2.3 Windows下“cmdlet不识别opencode”的真正原因热词里有这么一条“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名”。这是Windows用户最常见的安装问题我帮人排查过好几次原因几乎都是同一个npm全局安装目录没有加到系统PATH里。解决步骤很直接先查npm全局目录在哪npm config get prefix把输出目录加到PATH。比如输出是C:\Users\你的用户名\AppData\Roaming\npm那就打开“系统属性 - 环境变量”在用户变量PATH里追加这个路径。配置完后关掉当前终端重新打开一个新终端再跑opencode --version。如果加完PATH还是不行可能是权限问题。npm全局目录在Program Files下面时经常出现权限不够的情况建议把npm prefix指到用户目录里npm config set prefix $env:APPDATA\npm # 重新安装 npm install -g opencode-ai另外一个常见问题是Windows下偶尔会被安全软件拦截npm脚本执行如果执行时提示权限相关错误检查一下终端是不是以管理员身份跑的以及执行策略是不是正常的。2.4 首次启动与模型登录装好之后在任意项目目录下运行opencode第一次进去会提示你选择模型。以Anthropic官方账号为例流程是opencode auth login回车后会列出支持的provider选择Anthropic然后按提示完成登录。登录成功之后opencode会把凭据保存在本机配置里后续启动不用重复登录。这里多说一句如果你同时有多个provider的key建议都登录一遍因为后面切换模型时就不用再输一遍了。多模型配置的具体玩法我在下一章详细说。2.5 我的第一个真实任务让它修一个bug登录完我随手打开一个Go项目给opencode下了一个指令“看一下main.go里的并发处理竞态检测器报了几个警告定位原因并修复。”opencode先自动翻了main.go和go.mod确认这是Go 1.21项目然后建议跑go build -race复现问题。我同意后它执行了命令看到输出定位到一处map并发读写随后直接创建了修复后的diff把普通map换成了sync.Map我再选择“应用改动”整个流程就结束了。整个过程最让我满意的地方是它不乱来改代码前会先确认执行命令前会说明要做什么遇到权限相关的操作会停下来问。这种“有边界的自主”正是我希望agent具备的。2.6 “unexpected server error”排查思路终端里报error: unexpected server error. check server lo...这是热词里出现频率很高的一条。我的经验是分三步排查第一步确认模型服务端是否正常。如果你用的官方API登录官方控制台看余额和访问状态如果消息大面积报服务端错误通常是对方服务端问题等一会儿再试。第二步确认本地的登录态是否过期。重新执行opencode auth login刷新凭据能解决相当一部分“昨天还能用今天突然报错”的情况。第三步确认配置文件是否改坏。如果你手动改过provider配置、环境变量很可能是配置里的key格式或API地址写错了。比较好的做法是先临时把配置文件改名备份让opencode回到默认状态再试。3. 模型配置是opencode最值钱的部分多provider的玩法3.1 官方支持哪些模型opencode对模型的支持理念是“开放优先”官方文档维护了一份完整的模型列表覆盖了Anthropic的Claude系列、OpenAI的GPT系列、Google的Gemini系列以及一批开源模型。对大多数人来说最关心的可能是能不能顺便用本地模型兜底以及怎么配置一套统一的模型管理。3.2 项目级配置文件opencode.json多模型管理的核心是项目根目录下的opencode.json。我的配置大概长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { openai: { apiKey: {env:OPENAI_API_KEY} }, google: { apiKey: {env:GEMINI_API_KEY} } } }日常开发我主力用Claude Sonnet系列长上下文任务切到OpenAI的模型前端页面走Gemini各有各的优势。你可以把环境变量直接引用到配置文件里这样不会把key提交到代码仓库。这套配置的好处是跟着项目走切换模型不再依赖终端里临时设置的变量git提交时也不需要担心key泄露。我通常会在.gitignore里把opencode.local.json忽略掉把自己的模型偏好留在本地把公共配置提交到仓库。3.3 本地模型接入Ollama本地模型最大的价值是处理敏感代码和不依赖外网。接入方法也很简单先在本地装好Ollama拉一个模型ollama pull qwen2.5-coder:7b然后在opencode.json里加一个本地provider{ provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:7b: { name: Qwen Coder 7B } } } } }然后在对话里通过/models命令切换到ollama/qwen2.5-coder:7b就可以开始本地模型对话了。这里必须说清楚7B量级的本地模型跟云端大模型在代码生成质量上差距是肉眼可见的它更适合做代码解释、简单重构、日志分析这类对智能要求不高的任务不太适合让它独立开发复杂功能。我一般只在处理敏感片段或离线环境时切过去。3.4 关于“免费模型”和模型切换这个话题很多刚接触opencode的人一上来就问“有没有免费模型”。我的建议是分两条线看一是模型服务商官方提供的免费额度这是合法且安全的二是本地模型也是完全自己掌控的至于社区里那些来路不明的“免费中转”渠道我建议直接跳过一是key容易泄露二是稳定性完全没有保障三是代码安全问题。给自己的开发环境配一个正规的API额度本质上是对自己调试效率和代码安全负责。社区里也有一些模型配置切换工具比如ccswitch这类可以把一套API配置复用到不同的终端AI助手上。这类工具的价值在于统一管理而不是帮你找“白嫖渠道”。我个人的态度是工具可以了解但核心思路一定要放在“正规、可审计”这几个字上。4. skills让agent学会你的工作习惯4.1 skills是什么跟提示词有什么区别如果你用过Claude Code的skills那对opencode的skills机制一定不陌生。简单说skills就是把一段高度结构化的markdown指令集放在指定的目录里当agent判断当前任务涉及某个技能时会自动加载这个技能文件的全部内容作为上下文。它跟普通提示词最大的区别在于“自动触发”和“结构封装”。普通提示词需要你每次手动粘贴给agent而skills设置好之后agent会根据你描述的任务自动匹配并加载相应的技能指令不需要你重复解释“按什么流程做、用什么格式输出”。这相当于给agent建立了“肌肉记忆”。4.2 skills的存放位置和格式opencode有两个存放skills的目录全局目录所有项目共用一般放在~/.config/opencode/skills/项目目录跟随仓库走放在.opencode/skills/下每个技能是一个文件夹里面必须有SKILL.md文件结构大概是--- name: code-review description: 对当前变更做一次代码审查重点关注并发问题、资源泄漏和错误处理 --- 执行代码审查时遵循以下步骤 1. 先运行 git diff 获取当前变更 2. 逐文件检查并发安全、资源释放、错误处理 3. 按严重程度输出问题列表严重/一般/建议 4. 每条问题给出对应的修复建议和demo代码 5. 最后汇总变更文件清单和风险点关键是description字段它是agent决定何时触发这个技能的“索引”。所以description写得越具体越好尽量包含你能想到的、用户在对话里会使用的句子。4.3 一个真实可复用的前端bug排查skill热词里有一条“opencode playwright 怎么测试前端bug”这正好是我配置过的场景。前端bug的复现一直是agent能力里比较弱的一环因为agent看不到页面只能靠静态代码分析。但结合Playwright这个问题能被很好地解决。我写了一个专门用来排查前端bug的skill核心思路是让opencode用Playwright写一个自动化脚本先复现问题再定位代码。SKILL.md大致长这样--- name: frontend-bug-repro description: 排查前端页面bug时先使用Playwright脚本复现问题再结合源码定位根因 --- 当用户反馈前端页面出现bug时按以下流程处理 1. 先根据bug描述找到对应路由和组件代码 2. 使用Playwright编写一个能复现该bug的测试脚本 3. 脚本中要包含用户描述的关键操作步骤和期望结果 4. 在本地启动开发服务器运行脚本 5. 根据脚本失败信息判断是渲染问题、网络问题还是交互逻辑问题 6. 定位到具体组件后给出修复方案 7. 修复后再次运行同一脚本确认bug不再复现有了这个skill之后我排查前端bug的效率高了很多。以前是让agent猜问题原因改一版跑一版现在是先复现、再定位、后修复、最后回归一条链路走下来。这也是我觉得skills最值得配置的原因。4.4 团队级skills的沉淀在团队开发场景里把代码规范、上线检查清单、提交信息规范沉淀成skills价值会非常大。新成员加入时不用看一堆文档只要让opencode遵循某个skill它就能按团队约定来执行任务。我给团队配过一个“Go代码审查”技能和一个“标准提交信息”技能效果很好。前者会在每次提交前检查错误处理是否完整、并发访问是否安全后者会强制按conventional commits格式生成提交信息。这东西只要配一次后面省下来的沟通成本是相当可观的。5. 从终端到桌面插件生态和多端协同5.1 VSCode插件把agent塞进编辑器热词里有不少“opencode vscode插件”的搜索。opencode官方提供了VS Code扩展装上之后可以在侧边栏直接使用agent能力不用切到终端窗口。实际体验下来它更适合“边看代码边让agent改东西”的场景你在编辑器里选中一段代码右键发送给opencode让它解释或者重构它把建议diff返回后你可以直接在编辑器里diff视图审阅并接受。同时TUI模式下它就没有离开日常重活还是在终端里做因为TUI的信息密度、长上下文对话体验更好。这个组合算是我目前效率最高的模式。5.2 JetBrains插件与Java/Maven项目配置opencode也有JetBrains插件IDEA里可以直接安装。对于Java项目特别是Maven工程配置上有个容易被忽视的点opencode需要知道项目的构建和测试命令才能很好地完成编译、测试、修复。我把自己项目的构建信息写进了项目说明文件比如AGENTS.mdopencode启动时会读取这类项目级说明文件内容大致是本模块是Java 17 Spring Boot 3项目使用Maven构建。 构建命令mvn clean package -DskipTests 测试命令mvn test 单元测试报告生成mvn surefire-report:report之后opencode在改代码时会自动使用mvn test验证改动而不是傻乎乎地手动猜测。这个习惯对任何语言都适用尤其是Java这类构建链比较重的项目。5.3 桌面版和“superpowers”这类增强包opencode还有桌面版opencode desktop本质上是把TUI过程可视化对不习惯命令行的新手更友好。老手依然会更喜欢纯终端版启动快、内存占用小。另外一个大热话题是给opencode装“superpowers”。所谓superpowers是社区里一个流行的skills增强包里面封装了一整套方法论级的技能比如“头脑风暴”“系统设计”“debug排查”等。装好之后opencode在面对复杂任务时会更体系化而不是直给方案。官方也支持sst/opencode兼容Claude Code风格的skills目录所以不少给Claude Code写的技能包能直接迁移。配置这些增强包的关键是读README搞清它的skills目录结构然后把路径映射到opencode的配置里。整体不算难照着文档走就行。5.4 接手存量开发项目的实际经验“opencode接手开发项目”是热搜词里我觉得最实用的一条。实际场景是你拿到一个从没接触过的代码仓库直接扔给opencode让它改需求很容易翻车。它不了解项目的领域语言、潜在约定甚至不知道构建命令是什么。我的做法是分三步第一步先让opencode只做“理解”不做“改动”。让它把项目结构、数据流、核心模块读一遍输出一份项目总结。这个阶段我发现它读代码的能力比大部分人想象中强能把那些“没有文档的老项目”梳理出清晰的脉络。第二步在对话里追问自己关心的细节某个核心模块的数据模型、越权校验在哪实现、某条链路的日志追踪策略。把项目的“活文档”沉淀在脑图或笔记里。第三步再让它动手改代码。这一步就稳很多因为核心上下文已经建立。改之前务必让opencode先说明改动方案确认风险点后再执行。5.5 周边工具链oh-my-claudecode这类打包方案热词里还有“oh-my-claudecode”。它本来是给Claude Code做终端增强配置的社区项目把一些常用快捷键、skill、命令布置成一套打包方案。因为opencode和Claude Code的skills机制高度相似这类方案的许多配置也能迁移到opencode上省去自己从头配的时间。这类工具用的一个好的姿势是“看它的设计思路而不是照抄它的配置”把别人沉淀好的技能拿过来后根据自己的实际工作流删减修改最终形成自己顺手的一套配置。6. 用了一周后的真实体感它和Codex、Claude Code怎么选6.1 三者能力的横向对比维度opencodeClaude CodeOpenAI Codex模型支持多provider可切Anthropic/OpenAI/Gemini/本地基本绑定Claude系列基本绑定OpenAI系列安装难度npm一条命令官方脚本官方脚本/npm配置文件opencode.json项目级多配置位点社区方案丰富配置项较封闭skills机制原生支持兼容度高原生支持不支持同等机制TUI体验成熟信息密度高稳定好用偏向轻量CLI编辑器插件VSCode JetBrainsVSCode/JetBrains主要依赖网页端开源是否否团队协作配置项目级配置可共享较好但生态割裂一般单看功能opencode在“开放性”和“可定制性”上优势明显。Claude Code的问题解决的闭环更强因为模型和产品是同一家公司设计很多小细节做得很顺手Codex背靠OpenAI的代码能力尤其适合深度依赖OpenAI模型的团队。而opencode相当于“把决定权还给了用户”。6.2 我实际的使用分工我用了一个多星期后形成的分工是这样的日常主力agentopencode配合Claude模型做功能开发、重构、写测试。原因是它让我能在不同模型间切来切去某些场景下用Gemini某些场景切换到本地模型。复杂架构设计、大段代码的语义化重构Claude Code更擅长一些它跟Claude模型配合得比较深。需要快速在网页端验证idea、处理少量代码直接用Codex网页版更快不用配环境。说白了它们不是替代关系而是互补关系。如果你只能选一个我更推荐opencode因为它在模型自由度上留了后手。6.3 值得注意的缺点和隐藏成本opencode也不是没有短板。第一次用它的时候没有完整项目说明文件的项目它也会出现误判偶尔给出“看起来很合理但实际跑不通”的改动。TUI的配色和响应速度虽然比我预期好但跟Claude Code相比还是有一点差距偶尔在超大工程里会出现轻微卡顿。最需要留意的是token消耗。多provider灵活切换是好事但也容易让人忽略不同模型的计费差异极大长会话的上下文积累会拉高单次调用成本。我现在的做法是遇到超长会话及时开新对话把之前的结论整理成项目说明文件再携带到新会话中而不是长期挂在一个上下文里。另外opencode迭代很快从2.0开始几乎每周都有新版本。配置方式、skills路径这类东西在不同版本之间可能有差异遇到行为变化时先去看官方changelog别急着怀疑是自己配错了。6.4 一个关于“memory”的心得热词里还有“opencode memory”。我的理解是opencode的记忆能力更多来自项目说明文件和skills而不是自动的长期记忆。它不会像人一样“记得你上次让它怎么做事”除非这些经验被固化到了配置里。所以我现在的习惯是每做完一个模块顺手把“这个项目里的约定”“容易踩的坑”“常用的命令”追加到项目的AGENTS.md里。下次不管是我自己还是团队其他人再开opencode它都能在一开始就获得这部分上下文少走很多弯路。这种“主动沉淀经验”的工作方式比单纯依赖工具本身的记忆能力要靠谱得多。如果你刚接触opencode我的建议是从小任务开始先让它读代码、梳理逻辑、写测试逐步建立信任再放手让它做复杂重构。第2章里那些Windows的坑、服务端报错的排查链路、skill的配置格式都是我自己踩过之后的沉淀希望能替你省掉几天的弯路。