1. 先搞清楚 openspec init 到底会生成什么
OpenSpec 是一套把「需求提案 → 设计规格 → 开发任务」串成流水线的规格管理工具，它本身不写业务代码，而是负责把团队协作里最容易散架的文档资产收拢到一个统一目录里。openspec init是它的初始化命令，跑完之后会在项目根目录生成一个.openspec/文件夹，把配置、提案、设计、任务、模板、归档、缓存这七类资产分门别类放好，不会往根目录乱丢杂文件。适合谁用？适合已经在用 claude code cli 做日常编码、又想让需求到任务这条链路可追溯的开发者，尤其是团队里多人协作、需要统一规格格式的场景。
但这里有个前提：claude code cli 要能正常调用模型，你得先解决 API 通道的问题。我试过直接填各家原生 Key，切换模型时改配置改到烦，后来换成 TaoToken 统一 Key 接入，claude code cli 的settings.json和 OpenSpec 依赖的config.toml都指向同一个通道，初始化流程才顺下来。这篇就按「接入 → init → 核对产出」的顺序拆，重点放在 init 之后那份完整目录清单和关键文件内容上，你可以照着逐项核对。
需要先说明一点：openspec init只创建基础目录、基础模板和 config 文件，task/design/proposal的具体 md 文件不会预先生成，得调用/opsx:propose这类命令才按需创建。所以如果你 init 完发现 proposals 目录是空的，那是正常的，不是出错。
2. TaoToken 前置：统一 Key 与 API 通道准备
TaoToken 在这里扮演的是统一 API 通道的角色，claude code cli 和 OpenSpec 的模型调用都走它，省去多套 Key 来回换的麻烦。你需要先拿到一个可用的 Key，再把它写进 claude code cli 的配置里。
第一步，打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录，进入控制台。第二步，在控制台里找到 API Keys 管理页，新建一个 Key，复制出来先存好，后面配置要用。第三步，确认你要用的模型通道，TaoToken 的 API 入口是 https://taotoken.net/api，这个地址不加任何 UTM 参数，配置里直接写它。
如果你还没决定用哪个模型，可以先去模型对话页面试一下调用效果，确认通道通了再往 claude code cli 里配。对于长期编码和 Agent 场景，Coding Plan 会更合适，额度模型和按量调用不太一样，你可以按自己的使用强度选。
注意：Key 只显示一次，复制后妥善保存。配置里不要把它提交到 Git 仓库，建议用环境变量或本地私有配置文件承载。
拿到 Key 之后，claude code cli 侧的接入就两步：写settings.json，再确认config.toml里的模型通道指向 TaoToken。下面给可直接复制的骨架。
3. 可复制配置：settings.json 与 config.toml 骨架
claude code cli 的配置分两块，一块是它自己的settings.json，一块是 OpenSpec 侧读取的config.toml。两者都指向 TaoToken 的 API 地址，Key 用同一个。
先看settings.json，放在 claude code cli 的配置目录下（不同系统路径不同，按你本地实际位置放）：
{ "apiProvider": "custom", "apiBaseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-20250514", "maxTokens": 8192, "temperature": 0.2, "timeout": 120000 }几个参数说明一下。apiBaseUrl固定写 TaoToken 的 API 入口，不要带斜杠结尾。apiKey换成你控制台里复制的那串。model按你实际开通的通道填，上面只是个示例值。temperature编码场景建议压低，0.2 左右比较稳。timeout给足，长任务别中途断。
再看config.toml，这是 OpenSpec 初始化后会读取的模型通道配置，放在.openspec/根目录或项目约定的配置位置：
[model] provider = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" default_model = "claude-sonnet-4-20250514" [openspec] spec_schema = "spec.schema.json" task_executor = "superpowers" auto_archive = true [superpowers] bridge_enabled = true sync_mode = "bidirectional" conflict_strategy = "manual"[model]段是通道配置，和settings.json保持一致。[openspec]段里task_executor指向 superpowers，这是任务执行器的对接开关。[superpowers]段是桥接配置，bridge_enabled = true时才会生成后面提到的superpowers-bridge.yml和hooks/目录。如果你不打算用 Superpowers，把这段去掉或设成 false，init 后就不会出现这两个产物。
配置写完先别急着 init，用一条最小请求验证通道是否通。
4. 验证请求与 openspec init 成功结果
先验证 TaoToken 通道。用 curl 发一条最小对话请求：
curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的TaoTokenKey" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'返回里带content字段且没有鉴权错误，说明通道通了。如果返回 401，检查 Key 有没有多余空格；返回 404，检查base_url是不是写成了带路径的地址。
通道确认后，在项目根目录执行初始化：
openspec init执行完你会看到终端输出创建了哪些目录和文件。init 成功后，.openspec/下的目录树大致是这样：
项目根目录 └── .openspec/ ├── openspec.config.yml ├── .gitignore ├── readme.md ├── proposals/ │ └── index.yml ├── designs/ │ └── spec.schema.json ├── tasks/ │ └── task-index.yml ├── templates/ │ ├── proposal-template.md │ ├── design-template.md │ └── task-template.md ├── archive/ ├── cache/ ├── superpowers-bridge.yml （联调 Superpowers 才出现） └── hooks/ （联调 Superpowers 才出现） ├── pre-brainstorm.hook.md ├── pre-write-plan.hook.md └── post-execute.hook.md逐项核对一下。顶层三个文件：openspec.config.yml是全局配置，管插件开关、代码规范、任务执行器、文件包含排除规则、团队标签、输出格式和 Git 集成；.gitignore是 OpenSpec 专属忽略，把缓存、临时草稿、本地私有提案、测试快照挡在版本控制外；readme.md写的是项目规范说明、流水线操作命令和团队协作说明。
proposals/是需求提案入口，/opsx:propose会在这里生成proposal-{uuid}.md，内容包含需求描述、输入输出、业务约束、依赖功能、疑问点和待确认清单。index.yml是提案总索引，记录所有提案 ID、状态（draft/approved/archived）和关联设计文档。
designs/是设计规格目录，/opsx:analyze或/superpowers:brainstorm同步后生成design-{proposal-id}.md，里面有技术方案、架构图说明、接口定义、数据库表结构、异常处理、第三方依赖、风险评估和多方案对比记录。spec.schema.json是当前项目的统一规格 JSON Schema，用来校验所有 design 和 task 文件格式，保证团队规范一致。复杂项目还会自动生成可选的architecture.md，写模块分层、依赖关系和目录结构约束。
tasks/对接 superpowers 的 write-plan，/superpowers:write-plan或/opsx:write-plan产出可执行编码任务。单条任务是task-{design-id}-{seq}.md，包含修改文件清单、代码变更范围、测试用例和完成校验标准。task-index.yml是任务总表，关联提案加设计、完成状态、执行人和关联提交记录。
templates/自带三套模板，proposal-template.md、design-template.md、task-template.md，可以自定义扩展。archive/是归档目录，/opsx:archive执行后把已上线完成的 proposal、design、task 按版本或迭代分文件夹移进来，保留完整需求链路方便回溯。cache/是运行缓存，自动生成，里面有code-scan-cache.json、sync-temp.md、lint-snapshot.json，全部是临时文件，删掉不影响项目规格。
联调 Superpowers 后追加两个产物：superpowers-bridge.yml是双向同步配置，管自动读取 brainstorm 输出、同步 plan 任务和冲突处理策略；hooks/下三个钩子文件，pre-brainstorm.hook.md在脑暴前自动加载项目规范，pre-write-plan.hook.md在生成计划前校验设计完整性，post-execute.hook.md在编码完成自动归档规格。
5. 本篇常见错排查
第一个高频问题：init 完 proposals 目录是空的，以为失败了。这不是错，init 只建基础目录和模板，具体 md 文件要调/opsx:propose才生成。核对时看目录和模板在不在就行。
第二个：superpowers-bridge.yml和hooks/没出现。检查config.toml里[superpowers]段的bridge_enabled是不是 true，或者你根本没装 superpowers 桥接。不搭配 Superpowers 时这两个产物本来就不生成，属于预期行为。
第三个：claude code cli 调用报鉴权失败。多半是settings.json和config.toml里的 Key 不一致，或者 Key 前后带了空格。两处都指向同一个 TaoToken Key，改完重启 cli 再试。
第四个：spec.schema.json校验 design 或 task 文件报格式错。这是 Schema 在起作用，说明你手写的 md 结构不符合团队统一规范。对照templates/里的模板改，别自己另起格式。
第五个：cache 目录文件越积越多想清理。直接删，code-scan-cache.json、sync-temp.md、lint-snapshot.json都是临时产物，下次运行会重新生成，不影响任何规格数据。
第六个：archive 归档后找不到历史需求。归档是按版本或迭代分文件夹的，进对应版本目录找，完整链路都在，不会丢。
6. 接入与排障后的下一步
通道和配置都跑通之后，日常操作就围绕几条命令转：/opsx:propose建提案，/opsx:analyze或/superpowers:brainstorm出设计，/superpowers:write-plan或/opsx:write-plan拆任务，/opsx:archive归档。每条命令产出的文件都落在对应目录里，核对产出是否完整，就按第 4 节那份目录树逐项对。
如果你在接入 claude code cli 或核对 init 产物时卡住，先去 API Keys 页面确认 Key 状态，再对照接入文档检查settings.json和config.toml的字段。想先验证模型通道是否正常，用模型对话页面发一条测试请求最快。长期做编码和 Agent 任务的话，Coding Plan 的额度模型更适合持续调用，不用每次按量结算。配置骨架和目录清单都在上面了，照着填、照着核对，init 这一步基本不会再有意外。
