最近我把自己的终端 AI 编码工作流从 Cursor 迁到了 OpenCode顺带折腾了 OpenSpec、Superpowers、Oh-My-OpenCode 这套组合前后花了两三个晚上才把整个链路跑顺。今天把完整的配置过程和踩过的坑整理出来给同样想自建一套命令行 AI 工作流的人做个参考。这套工具链的核心定位非常清晰OpenCode 负责干活OpenSpec 负责给活儿立规矩Superpowers 提供干活的标准招式Oh-My-OpenCode 把前面几个揉在一起统一管理。思路理顺之后配置过程其实比想象中顺畅。1. 三件套的定位与核心价值1.1 OpenCode一个把需求落进代码库的终端 Agent很多刚接触 OpenCode 的人会把它当成一个跑在终端里的 ChatGPT这种理解不准确。它不只是聊天窗口而是一个能真正读代码、改代码、执行命令、跑测试的编程 Agent。和 Cursor、Copilot 这类图形化工具相比OpenCode 最大的特点是把控制权完全交还给你它会主动请求执行权限每个命令都清清楚楚列出来你确认之后它才动手。对于习惯 Git 工作流、长期在 Vim/Neovim 和终端里工作的开发者来说这种“手不离键盘”的体验非常舒服。OpenCode 的核心能力包括三块上下文感知、多文件编辑、工具调用。它会自动扫描项目里的文件结构把关键内容作为上下文提交给模型也能一次性修改多个文件不需要你手动定位还可以调用 shell 命令、读取日志、运行测试形成一个完整的“感知-决策-行动”闭环。对于什么项目适合它我实际测试下来的结论是中大型代码库、需要跨文件重构、有明确测试流程的项目最合适因为 AI 需要主动探索代码才能给出靠谱结果而 OpenCode 在终端环境里做这件事比 IDE 插件更自然。1.2 OpenSpec规范优先的开发约束层OpenCode 再强本质上还是依赖模型的涌现能力而大模型的通病是有时会“自由发挥”得过火。你让它实现一个登录功能它可能会顺手改了数据库表结构让它修一个 bug它可能把无关代码也重构了。OpenSpec 就是用来解决这个问题的它的核心思路是“先立规矩再写代码”。OpenSpec 是一个规范驱动开发的工具链它的做法是先把需求拆解成可验证的结构化描述也就是 spec 文件然后让 AI 严格按照 spec 去实现而不是让它根据一句模糊的自然语言瞎猜。你可以把它理解成装修前先画设计图纸、定施工方案的流程图纸没定好之前工人是不会直接开工的。OpenSpec 提供了一组命令来维护这些 spec初始化工作区、添加新需求、生成任务清单、做计划评审等。所有 spec 都是 Markdown 文件存在项目里的 specs 目录中天然支持 Git 版本管理代码评审时可以清晰地看到“需求定义”和“实际实现”之间的差异。1.3 Superpowers 与 Oh-My-OpenCode技能库和指挥台如果把 OpenCode 比作一个刚毕业的工程师Superpowers 就是这位工程师的系统化“培训教材”。Superpowers 是一个 skills 集合内置了一套经过验证的工程实践技能比如代码评审、测试驱动开发、调试、重构、文档生成等。它的价值在于把行业里的最佳实践固化成 AI 可以调用的流程。举个例子直接让 AI “写测试”它可能写得比较随意但调用 TDD 这个 skill 之后它会严格按照“先写失败的测试 → 实现代码 → 重构”的节奏推进每一步都有明确检查清单。Oh-My-OpenCode 的角色则更像一个指挥台它把 OpenCode、OpenSpec、Superpowers 以及各种自定义规则、模型配置、快捷键统一封装起来。名字灵感明显来自 oh-my-zsh做的事也类似给你一个开箱即用的配置文件集帮你组织好所有零散的配置项。如果你自己手动管理很容易出现“配置文件散落在多个目录、规则互相冲突、不知道哪个配置生效了”的混乱局面Oh-My-OpenCode 通过一套清晰的目录结构和预设配置文件解决这个问题。三件套各司其职之后整条链路才真正具备工业级的稳定性。2. 安装与基础环境准备2.1 把 OpenCode 装好并确认版本可用OpenCode 的安装方式很灵活我推荐优先使用 npm 或 Homebrew。如果机器上已经有 Node.js 环境执行npm install -g opencode-ai就能完成全局安装macOS 用户也可以brew install opencode。安装完成后运行opencode --version确认版本号。这里特别提醒一下OpenCode 迭代非常快很多命令和配置项在不同版本之间会有差异我这次实操使用的是 v2 系版本如果你是从旧版本升级上来的务必留意配置格式的变化。安装完后第一次运行opencode会要求你选择模型提供方并配置 API Key。常见的配置方式有两种一种是使用官方托管的模型网关直接登录授权即可另一种是接入自己的 API Key比如配置 Anthropic 的 Claude、OpenAI 的 GPT 或本地部署的模型。我个人更推荐把模型提供方和 API Key 放在环境变量里管理而不是写进配置文件避免在不同的项目间复制配置时把密钥泄露出去。配置好之后在终端里执行opencode run 你的需求如果能看到模型流式输出了内容说明环境已经跑通。2.2 摸清配置目录和常用命令OpenCode 的配置体系分两层全局层和项目层。全局配置文件在~/.config/opencode/目录下核心文件是opencode.json主要存放模型提供方、默认 Agent、常用参数等信息。项目层则是在项目根目录维护一个opencode.json用于覆盖全局配置。这里的优先级规则要特别记清楚项目配置会覆盖全局配置命令行参数会覆盖文件配置。这一点和 Git 的三层配置逻辑很像理解之后就不会出现“改了配置怎么没生效”的疑惑。常用命令方面opencode直接进入交互式终端opencode run以单次任务模式运行适合脚本化调用opencode auth管理凭证opencode config查看当前配置opencode skills管理技能包。如果要构建复杂工作流建议重点关注opencode run的非交互模式它可以结合 CI/CD 使用甚至可以把 AI 的修改通过 Git 分支隔离体验非常接近一个“智能开发机器人”。我在实际操作中会先用opencode run --help把所有参数看一遍因为很多隐藏的好功能都藏在参数里比如--agent指定不同 Agent、--out输出结构化结果等。2.3 安装顺序和版本兼容性验证这节要讲一个容易踩的坑OpenSpec、Superpowers、Oh-My-OpenCode 的安装是有顺序讲究的。我一开始图省事同时装了三个结果 OpenSpec 规则没有被 OpenCode 识别Superpowers 的 skills 也没有出现在列表里。排查到最后才发现是版本兼容性问题OpenCode v2 对 skills 的目录结构要求发生了变化而 Oh-My-OpenCode 默认生成的是旧格式配置。推荐顺序是这样的先安装并跑通 OpenCode再安装 OpenSpec然后引入 Superpowers最后接入 Oh-My-OpenCode 做统一管理。装完每一个组件都立刻验证一次确认没问题再进行下一步。验证方法也很简单OpenSpec 装完跑一次openspec initSuperpowers 引入后运行opencode skills list查看是否有对应技能Oh-My-OpenCode 接入后看它是否生成了预期的目录结构。宁可多花三分钟做检查也不要等所有配置叠在一起再回头查那种排查成本会高很多。3. OpenSpec 配置实操3.1 初始化一个规范工作区OpenSpec 的安装方式比较灵活可以直接下载二进制也可以通过包管理器安装。安装完成后先进入一个已有的 Git 仓库根目录执行openspec init。这个命令会做三件事创建specs/目录、生成specs/openspec.json配置文件、生成一个 README 说明文件。specs/目录下会预建requirements/、tasks/、decisions/三个子目录分别对应需求描述、任务拆分和架构决策记录。在动手写第一条 spec 之前我建议先花五分钟理解这三个目录的分工。requirements/存放功能需求描述“要什么”tasks/存放执行计划描述“怎么做”decisions/存放技术选型与约束记录“为什么”。这种结构有点类似产品需求文档 技术设计文档的合体。OpenSpec 的核心概念是一条需求对应一个requirements/功能名/README.md文件文件里有明确的功能描述、用户故事、验收条件然后通过openspec add生成对应的tasks/任务列表让 AI 照着任务一步步实现。如果你对目录结构有强迫症也可以手动创建这些文件但强烈不建议因为openspec init除了建目录还会生成一份 schema 定义用来校验 spec 文件是否符合标准。手动创建容易漏掉字段后面 OpenCode 读取时可能解析失败。我第一次就是手动建文件漏掉了status字段白白排查了半小时。3.2 用一条真实需求演示规范的完整生命周期我拿自己最近做的一个小功能来演示给任务管理 API 增加“创建任务”的接口。第一步执行openspec add create-task这个命令会在specs/requirements/create-task/README.md生成一个模板文件内容基本长这样# Create Task ## 需求描述 提供一个创建任务的 API 接口调用方传入标题和描述系统创建任务后返回任务对象。 ## 用户故事 - 作为用户我可以通过 API 创建任务 - 作为用户我需要得到新创建任务的 ID 和状态 ## 验收条件 - [ ] POST /tasks 返回 201 状态码 - [ ] 请求体包含 title 字段必填字符串 - [ ] 请求体包含 description 字段选填字符串 - [ ] 响应体包含 id、title、description、status 字段 - [ ] 创建成功后任务状态为 pending这个模板并不是摆设每一段都有实际作用。需求描述让 AI 理解背景用户故事明确使用场景验收条件则是后续验证的硬指标。关键点在于验收条件一定要写成可验证的断言尽量用“返回 201 状态码”“字段名为 id”这种具体描述而不是“响应正常”“处理成功”这种模糊表述。模糊的验收条件会被 AI 直接跳过因为它不知道怎么证明自己做完了。生成 spec 之后执行openspec plan可以基于需求生成任务计划。这个命令会读取requirements/create-task/README.md拆解出每一步实现任务写入specs/tasks/下对应的文件。从我的实际体验来看plan生成的任务粒度是可控的默认会把“创建路由 → 校验请求 → 实现服务 → 写测试”拆成独立步骤。当然你也可以自己手动编辑任务文件调整顺序或合并步骤。我把任务文件检查一遍确认没有遗漏后就可以进入 OpenCode 环节了。接下来在项目根目录执行opencode run 按照 specs/requirements/create-task/README.md 实现需求并完成 tasks 目录下的所有任务完成后运行测试OpenCode 读取规范文件之后会自动把需求上下文和任务清单一起载入然后像一位真正看见图纸的工程师那样开始编写代码。它会自己创建路由文件、编写业务逻辑、执行测试如果测试失败还会反复调试。我在标准配置下跑完这个流程代码质量和手写基本没有差别关键是人省心很多—你只需要最后审查一次 diff而不是从零开始指挥每一步。3.3 把 OpenSpec 和 OpenCode 的规则文件串起来OpenSpec 能发挥作用的前提是 OpenCode 确实在每次对话前读取了规范文件。如果你只是把需求写进 specs 目录然后让 AI 自由发挥那 OpenSpec 就变成了一个花瓶。这里的关键配置是在 OpenCode 的规则目录下把 OpenSpec 的工作流说明挂载进去。以 OpenCode v2 为例它支持在项目根目录维护一个AGENTS.md文件作为所有 Agent 的全局前置规则。我在AGENTS.md里加了一段固定指令## 规范驱动开发 - 在修改代码前先检查 specs/requirements/ 目录下是否有对应的需求文档。 - 如果存在需求文档严格按文档中的验收条件实现。 - 任务期间需要更新 specs/tasks/ 下的任务状态标记完成或阻塞。 - 遇到需求文档未覆盖的情况先暂停实现向用户补充说明。这段规则的效果立竿见影。没有这段指令之前OpenCode 即使看到了 spec 文件也可能自作聪明地省略某些字段加了之后它会开始主动把实现进度和 spec 里的验收条件一一对应做到最后还会回来逐条勾选验收条件。我自己的感受是OpenSpec AGENTS.md 的组合解决了大模型最让人头疼的“跑题”问题相当于给 AI 戴上了紧箍咒。4. Superpowers 与 Oh-My-OpenCode 接入4.1 引入 Superpowers 技能集并查看可用技能Superpowers 的引入方式并不复杂。以当前主流做法为例你可以从 GitHub 仓库仓库拉取项目然后把它注册到 OpenCode 的 skills 目录里也可以在 OpenCode 的插件体系里直接搜索安装。安装之后运行opencode skills list会看到一组已经注册的技能常见的有这些code-review按行业标准做代码评审能检查可读性、安全性、边界条件test-driven-development强制按 TDD 流程推进先写失败测试再实现通过debugging系统化排查问题从复现到定位再到修复有完整套路refactoring在保持行为不变的前提下改进代码结构documentation根据代码和 spec 生成维护文档你可能觉得这些能力模型本身就有为什么还需要专门装技能包这里要讲明白普通提示词让 AI 做代码评审它可能只会泛泛提几条意见但调用code-review这个 skill 之后它会严格按照评审清单执行先看架构边界再看错误处理然后逐条输出“问题位置、风险级别、修改建议”。这就是“知道该做什么”和“有标准化流程去做”的差别。Superpowers 的价值正是把后者封装备好让每个工程环节都有可复现的流程。4.2 用 Oh-My-OpenCode 集中管理整套配置Oh-My-OpenCode 建议在 OpenCode 和 OpenSpec 都跑通之后再安装因为它会把前面这些配置统一收编。以我使用的版本为例安装后运行omo init它会让你选择初始化模板包括“最小配置”“完整开发配置”等选项。选择完整配置后Oh-My-OpenCode 会在~/.config/opencode/下生成一套结构清晰的目录大概长这样~/.config/opencode/ ├── opencode.json ├── agents/ │ ├── senior-engineer.md │ └── code-reviewer.md ├── skills/ │ ├── code-review/ │ └── tdd/ └── rules/ ├── openspec.md └── project-standards.md这套目录结构最大的好处是把原来凌乱的配置做了分类固化agents 目录放角色定义skills 目录放从 Superpowers 导入的技能rules 目录放和 OpenSpec 联动的规则文件。我之前是把所有东西都堆在opencode.json里导致想改一个 Agent 行为要翻很久。Oh-My-OpenCode 接管之后每个关注点都有了固定位置查找和修改效率提升非常明显。接入 Oh-My-OpenCode 之后并不需要每次手动编写繁琐的 JSON 配置它的命令行工具会提供交互式操作来管理配置。比如想给某个模型设置特定的 temperature直接执行omo config set model.temperature 0.2就行。不过也要提醒一句omo命令在生成配置文件时有时会覆盖你已有的自定义设置所以我建议在运行之前先把旧的opencode.json备份一份。我因为这个吃了亏旧配置里的自定义 Agent 全被冲掉了只好重新加回来。4.3 一条走通全流程的联合工作流示例三件套配齐之后完整的工作流应该是这样的先用 OpenSpec 定义需求然后由 OpenCode 执行实现Superpowers 注入工程方法论Oh-My-OpenCode 保证配置一致。我用一个“修复登录超时漏洞”的例子说明。第一步执行openspec add fix-login-timeout在 spec 里写清楚缺陷现象和修复验收条件。第二步在 OpenCode 交互模式中输入修复请求同时指定调用 Superpowers 的debugging技能指令大致是“使用 debugging 技能定位登录超时问题并按 specs/requirements/fix-login-timeout/README.md 中的验收条件修复”。OpenCode 收到指令后会先运行测试或查看日志复现问题然后按照调试技能的检查单逐项排查最终给出修复方案。整个过程中Oh-My-OpenCode 提供的统一配置确保 OpenSpec 规则和 Superpowers 技能都能被正确加载不会因为配置文件冲突导致技能失效。你只需要在最后查看 diff确认修复符合验收条件然后提交代码。5. 问题排查与独家避坑5.1 模型限流与额度报错怎么破在实际使用中我经常遇到类似这样的报错error from provider (console): opencodes free tier can only be used from wi...。如果你是第一次看到肯定会有点懵但这个报错本质上就两类原因一类是网络出口与提供商限制一类是套餐和账户状态问题。对于免费套餐官方通常会限制使用者的来源 IP 区域如果你的网络处于限制范围内就会触发这个提示。不要想着怎么绕过限制合规的做法是检查一下你的账户是否完成实名认证、套餐是否在有效期内、是否使用了官方认可的调用入口或者直接切换到自带 API Key 的自有模型。我自己的做法是不再依赖免费套餐而是通过环境变量显式配置自己的模型 API Key。具体来说在~/.bashrc或~/.zshrc里设置对应的变量然后在opencode.json里把 provider 的类型指向自定义模型服务和模型名称。配置文件里写上验证方式{ provider: { type: custom, name: my-model, apiKeyEnvVar: MY_API_KEY, model: claude-sonnet } }这样配置的好处是模型调用链路完全由自己掌控不会再被各种套餐入口策略干扰。另一个常见问题是免费套餐的每分钟请求数限制报错信息里经常出现rate limit exceeded。我的解决思路是降低并发请求把 OpenCode 的并发数参数从默认值调低同时在任务之间加一点延迟虽然整体速度慢了些但稳定性提升非常明显。5.2 技能不生效先从注册链路查起很多人在配置完 Superpowers 之后发现 OpenCode 根本调用不到里面的技能第一反应往往是重装依赖其实大概率是注册链路的问题。需要按顺序排查三个环节技能是否已经成功下载、是否正确注册到 OpenCode 的 skills 目录、调用时是否用了正确的技能名称。第一步检查技能包的文件完整性。Superpowers 是以目录形式组织技能的每个技能目录下面应该有一个SKILL.md用来描述技能的使用场景和步骤。第二步确认 OpenCode 能扫描到这个目录。OpenCode 的 skills 目录可以在配置文件中指定也可以通过opencode skills add命令添加。我遇到的最常见的问题是Superpowers 被安装到了用户目录但 OpenCode 默认扫描的是项目目录两边的路径对不上导致技能列表一片空白。解决方法是在项目配置里显式声明 skills 路径或者把技能目录也复制一份到项目下。第三步检查语法规则里是否有明确的技能触发词。Superpowers 的每个技能都有对应的触发词如果你在 prompt 里用的是“帮我看下代码”而技能触发词是“执行 code-review”那么 AI 是不会主动调用这个技能的。正确的做法是在指令里指定技能名称或者配置自动触发规则。5.3 配置冲突与版本兼容的坑Oh-My-OpenCode 的引入虽然让管理变方便了但也带来一个新的问题配置优先级和加载顺序。因为 OpenCode 的配置来源很多命令行参数、项目配置、全局配置、Oh-My-OpenCode 的模板配置如果相互之间出现冲突AI 可能会读出旧配置、错误配置甚至直接跳过某条规则。我建议定期执行opencode config查看最终生效的配置总览。有一次我发现 AGENTS.md 里的规则没生效检查后才知道是opencode.json里有一个ignore: [AGENTS.md]配置挡在那里。还有一次是 OpenSpec 的 schema 版本和 OpenCode 内置的解析器版本不匹配导致生成的 spec 文件校验失败。OpenSpec 本身也迭代得很快如果你用的版本太旧生成的 spec 结构可能和最新的 OpenCode skills 工具不兼容。应对办法很简单粗暴所有核心组件都保持在同一时间窗口更新的版本尽量避免一个最新版搭配一个半年没更新的旧版组合跑偏的概率会大大降低。5.4 布局整条工作流的三条心得体会这里分享几个实操下来最有帮助的经验。第一永远把 spec 文件纳入 Git 管理。OpenSpec 生成的specs/目录不是临时产物它是项目的一部分代码评审时 reviewers 可以很直观地对照“需求 → 任务 → 实现”的闭环。最好再配置一个 commit hook在提交前校验 spec 文件防止格式破坏。第二不要一次性把所有技能都接进 OpenCode先给你的主要工作流配上两三个必要的技能比如 TDD 和 code-review用熟了再扩展。全部加载不仅会消耗大量上下文 token还会让 Agent 在选择技能时犹豫不决反而降低效率。第三把 Oh-My-OpenCode 的配置文件和自己的项目模板一起纳入公司内部脚手架新同事入职后用一条命令就能拉起完整环境团队协作时 AI 的行为规范也会更统一不会出现每个人调出来的 AI 风格天差地别的情况。6. 最后再分享一个小技巧踩过几次坑之后我养成了一个习惯每次调整完配置先跑一个最小的冒烟任务验证链路比如让 AI 读一下 spec 文件并输出三条验收条件。这样做的目的是确认规则加载和技能注册都正常再投入真正的开发任务。这套组合用到现在我最满意的不是某一个工具的单一能力而是整个流程带来的确定性需求被严格定义实现有方法指导配置由统一框架管理AI 的每次改动都有迹可循。对于想从零搭建自己 AI 编码工作流的朋友我的建议是从 OpenCode 开始跑通一条最简单的小需求再逐步引入 OpenSpec 和 Superpowers最后让 Oh-My-OpenCode 接管全局配置。千万不要一上来就把所有组件全部装齐先让最小闭环稳定跑起来你才能真正理解这套工具链的设计精髓。