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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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把这段去掉或设成 falseinit 后就不会出现这两个产物。配置写完先别急着 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 这一步基本不会再有意外。