最近我把自己的终端 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 init，Superpowers 引入后运行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): opencode's 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 接管全局配置。千万不要一上来就把所有组件全部装齐，先让最小闭环稳定跑起来，你才能真正理解这套工具链的设计精髓。
