1. OpenSpec 约束 Claude Code先拆 Key 与通道TaoToken 只提供 Key 与通道访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_intro 获取 KeyBase URL 用 https://taotoken.net/api。如果你已经在 Claude Code 的settings.json中配置了ANTHROPIC_BASE_URL却发现 OpenSpec 生成的 spec 仍然被编码智能体绕过或者每次需求变更都会产生大量无关改动那么要先把两个问题拆开OpenSpec 负责把需求、任务、验收标准固化成可审查的文件TaoToken 负责编码工具调用时的 Key 与通道。两者职责一旦混在一起排障会非常痛苦你以为是模型不听话实际是 spec 没被读你以为是 OpenSpec 目录不对实际是 Claude Code 还在走旧的ANTHROPIC_*配置。OpenSpec 的定位是把软件规范做成轻量、可配置、可版本化的文件集合让团队和编码智能体在需求演进中保持同一套上下文。公开信息里它兼容 Claude Code、Cursor 等 39 个工具但这个数字只能说明工具体系覆盖广不代表每个工具都能自动识别同一份 spec。真正落地时工程团队需要明确Claude Code 读什么文件、Cursor 从哪个入口走自定义模型、Codex 为什么不能用ANTHROPIC_*、CC Switch 如何管理供应商三件套、Token 消耗对照表又该怎么记录。下面按可复现步骤展开。2. 准备阶段去 TaoToken 官网拿 Key而不是改 OpenSpec 目录当团队准备把编码智能体调用的 Key 统一到 TaoToken 时第一步不是改 OpenSpec也不是先调模型参数而是先确认通道层可用。可以访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_prepare_key 获取 Key然后在本地用占位符YOUR_API_KEY替换不要把真实 Key 写进示例配置或提交到 Git。建议团队按下面顺序准备在 TaoToken 官网创建或登录账号进入控制台。创建 API Key先用于本地验证不要直接给 CI 或多人共享。确认 Base URL 使用https://taotoken.net/api不要在 Claude Code 配置里随意追加/v1、/anthropic等路径除非对应工具文档明确要求。在本地 shell 中先验证 Key 是否可用再写入编辑器或 CLI 配置。把 OpenSpec 目录纳入 Git把 Key 放入本地环境变量或密钥管理不要混在一起。可以先建立一个只在本机生效的环境文件# 本地验证用不要提交到仓库 export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYYOUR_API_KEY curl -sS $TAOTOKEN_BASE_URL/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head这里的关键不是 curl 返回了什么而是确认三件事Base URL 没有写错、Key 已经替换、网络层能正常到达。如果这一步失败后面 Claude Code、Cursor、Codex 的配置都不用继续调。如果这一步成功再进入 OpenSpec 目录设计和编辑器配置。3. OpenSpec spec 目录最小落地结构OpenSpec 的价值不在于生成一堆文件而在于让编码智能体每次改代码前都有稳定的上下文入口。团队可以先落一个最小目录不追求复杂模板先把需求、任务、变更记录分开。下面是一个可复现的本地目录结构命令由读者在自己的项目根目录执行mkdir -p openspec/specs/auth mkdir -p openspec/changes/active/2025-auth-refresh mkdir -p openspec/archive touch openspec/project.md touch openspec/specs/auth/spec.md touch openspec/specs/auth/tasks.md touch openspec/changes/active/2025-auth-refresh/proposal.md touch openspec/changes/active/2025-auth-refresh/spec-delta.md目录大致如下openspec/ ├── project.md ├── specs/ │ └── auth/ │ ├── spec.md │ └── tasks.md ├── changes/ │ └── active/ │ └── 2025-auth-refresh/ │ ├── proposal.md │ └── spec-delta.md └── archive/project.md放团队级约束例如技术栈、代码风格、禁止改动的目录、测试命令。specs/放已经稳定的能力说明。changes/active/放当前迭代的需求变更。archive/放已经完成并归档的变更记录。这样 Claude Code 在生成或修改代码时可以只读取当前任务相关的 spec而不是每次把整个仓库都塞进上下文。一个spec.md可以这样写--- spec: auth-session status: active owner: platform version: 1 --- # 能力目标 为 Web 端提供登录态创建、刷新和注销能力。 # 非目标 - 不处理第三方 OAuth 登录。 - 不在本 spec 中定义用户资料修改。 # 对外契约 - POST /api/session - DELETE /api/session - 登录态使用 HttpOnly Cookie前端不直接读取 token。 # 验收标准 - [ ] 登录成功后返回 204。 - [ ] 未登录访问受保护接口返回 401。 - [ ] 刷新失败时清理本地状态并跳转登录页。 # 约束 - 不允许新增全局状态库。 - 数据库迁移必须单独提交。tasks.md则把任务拆到可执行粒度# 当前任务 - [ ] 为 /api/session 增加失败分支测试。 - [ ] 更新登录页错误提示。 - [ ] 补充刷新失败后的前端状态清理。 # 完成定义 - 单元测试通过。 - 类型检查通过。 - 不修改 openspec/specs 以外的契约文件。重点不是模板本身而是让 OpenSpec 成为 Claude Code 的“读取边界”。当编辑器侧允许读取openspec/**但拒绝读取.env、密钥文件、生产配置时编码智能体才会在可控范围内工作。4. Claude Code 接入片段settings.json 与 ANTHROPIC_*Claude Code 的配置要围绕settings.json和ANTHROPIC_*环境变量展开。常见做法是放在用户级~/.claude/settings.json或者放在项目级.claude/settings.json。项目级配置更适合团队统一但不要把真实 Key 提交进去。下面是一个可复制片段Key 用YOUR_API_KEY占位{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY, ANTHROPIC_MODEL: your-model-name }, permissions: { allow: [ Read(openspec/**), Edit(openspec/**), Bash(npm test:*), Bash(npm run typecheck:*) ], deny: [ Read(.env), Read(**/*secret*), Read(**/*.pem), Bash(rm -rf:*) ] } }这段配置的作用分三层第一层是通道层。ANTHROPIC_BASE_URL指向https://taotoken.net/apiANTHROPIC_API_KEY填YOUR_API_KEY对应值。如果 Claude Code 仍提示登录或 401先检查这里是否被 shell 环境变量覆盖。第二层是模型层。ANTHROPIC_MODEL用你的实际模型名替换。不要把模型名写死到 OpenSpec 的 spec 文件里因为 spec 约束的是业务契约不是供应商模型参数。第三层是权限层。允许读取和编辑openspec/**让智能体围绕 spec 工作拒绝读取.env、密钥文件和私钥。把测试和类型检查命令加入 allow可以减少每次手工确认。如果你在 shell 中临时覆盖可以这样验证export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYYOUR_API_KEY export ANTHROPIC_MODELyour-model-name claude进入 Claude Code 后先让它读取一个 spec 文件并总结验收标准再让它执行一个小任务。比如请先读取 openspec/specs/auth/spec.md 和 openspec/changes/active/2025-auth-refresh/spec-delta.md。 只总结本次变更涉及的接口、验收标准和非目标不要修改任何文件。如果它无法读取 spec或者读错目录问题通常在权限配置或工作目录而不是模型能力。先把读取路径跑通再让智能体改代码。5. Cursor 模型通道设置片段不要复制 Claude Code 的 settings.jsonCursor 和 Claude Code 的配置入口不同。Cursor 通常在 Models 或 API Keys 面板里配置自定义供应商不同版本字段名称可能变化。团队内部可以维护一份字段映射片段但不要直接把 Claude Code 的settings.json复制给 Cursor也不要把 Cursor 的字段写进 Claude Code。如果你在 Cursor 中使用 OpenAI 兼容自定义入口可以按下面字段映射填写{ provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY, model: your-model-name }如果 Cursor 当前版本要求从环境变量读取可以用本地文件作为字段参考# 仅作为 Cursor 自定义 OpenAI 入口的字段映射示例 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_API_KEYYOUR_API_KEY OPENAI_MODELyour-model-name这里要强调三点Cursor 的 Base URL 同样使用https://taotoken.net/api不要在 UI 里随手加多余路径。Cursor 的 Key 也用YOUR_API_KEY对应的值但建议和 Claude Code 分开创建方便按工具统计。Cursor 不读 Claude Code 的settings.jsonClaude Code 也不读 Cursor 的模型面板配置。团队要统一的是 OpenSpec 目录不是把所有工具配置混成一个文件。Cursor 接入后同样先用只读任务验证。比如在 Cursor 中打开项目要求它读取openspec/project.md和当前 change 的proposal.md输出任务清单不要直接编辑。确认 OpenSpec 目录被正确加载后再放开编辑权限。6. Codex 的 config.toml禁止把 ANTHROPIC_* 套进去Codex 走的是另一套配置体系通常使用config.toml例如~/.codex/config.toml。这里最容易犯的错误是把 Claude Code 的ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY直接写进 Codex 配置然后奇怪为什么没有生效。Codex 不读ANTHROPIC_*Claude Code 也不读 Codex 的 provider 配置。一个 Codex 配置示例可以写成这样model your-model-name model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后在本地设置环境变量export TAOTOKEN_API_KEYYOUR_API_KEY codex这段配置的关键点base_url使用https://taotoken.net/api不要写成ANTHROPIC_BASE_URL。env_key指向TAOTOKEN_API_KEY不要复用 Claude Code 的ANTHROPIC_API_KEY。model用你实际可用的模型名替换不要照抄示例。wire_api按 Codex 与模型供应商的兼容方式选择不确定时以 TaoToken 的 Claude Code 文档和工具文档为准。如果你同时维护 Claude Code、Cursor 和 Codex建议每个工具单独创建 Key或者至少用不同的环境变量名。这样 Token 消耗对照表才能分清是哪个工具、哪个项目、哪次任务造成的调用。7. CC Switch 三件套profile、Base URL、KeyCC Switch 常被用来切换编码工具或供应商配置。无论具体版本如何核心都是三件套profile 名称、Base URL、Key。团队可以把 TaoToken 做成一个独立 profile避免每次手工改settings.json。一个概念性配置片段如下{ profiles: [ { name: taotoken-claude, type: anthropic, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY }, { name: taotoken-codex, type: openai, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY } ] }使用 CC Switch 时要注意taotoken-claudeprofile 给 Claude Code 用走ANTHROPIC_*或 Claude Code 接受的配置方式。taotoken-codexprofile 给 Codex 用走config.toml不要在这里写ANTHROPIC_*。Base URL 统一写https://taotoken.net/apiKey 用YOUR_API_KEY替换。切换 profile 后重新打开 Claude Code 或 Codex确认实际读取的是新配置而不是旧 shell 环境。如果你还没有创建 Key可以回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_cc_switch 查看控制台入口。CC Switch 的好处是减少手工改文件但坏处是容易让团队忘记当前 profile 对应哪个 Key。建议在 profile 名称里带项目后缀例如taotoken-claude-auth、taotoken-codex-web并在 Token 对照表里记录同一名称。8. Token 消耗对照表OpenSpec 约束前后怎么量团队关注 Token 消耗时不能只看“有没有用 OpenSpec”还要固定模型、任务和提示词模板。建议做一张对照表同一需求分别跑两次一次不启用 OpenSpec一次启用 OpenSpec 并只读取相关 spec。数值不要照抄别人按你本地 Claude Code、Cursor、Codex 的日志或用量面板记录。任务是否启用 OpenSpec读取上下文输入 Token输出 Token总 Token返工轮次备注登录态刷新否全仓库检索 聊天历史填实际值填实际值输入 输出填实际值容易改到无关模块登录态刷新是project.md auth/spec.md change/spec-delta.md填实际值填实际值输入 输出填实际值改动范围可审查登录页错误提示否全仓库检索填实际值填实际值输入 输出填实际值需求边界不清登录页错误提示是auth/spec.md tasks.md填实际值填实际值输入 输出填实际值只改任务清单内文件记录时至少保留这些列日期与执行人。工具Claude Code、Cursor、Codex 中的哪一个。通道TaoToken 还是其他 Key。任务对应 OpenSpec 中哪个 change。是否启用 OpenSpec。读取了哪些 spec 文件。输入、输出、总 Token。返工轮次。最终 PR 或提交范围是否超出 spec。如果启用 OpenSpec 后总 Token 没有下降也不一定说明 OpenSpec 无效。可能原因包括spec 文件写得太长、读取了无关 change、Claude Code 权限没有限制到openspec/**、或者提示词仍然让智能体全仓库检索。对照表的价值是帮你定位这些变量而不是给出一个固定结论。9. 排障Claude Code 与 OpenSpec 常见错误配置阶段最常见的问题可以按下面顺序排查Claude Code 提示未登录或 401检查settings.json中ANTHROPIC_API_KEY是否替换为YOUR_API_KEY对应值Base URL 是否为https://taotoken.net/api并确认 shell 中没有旧的ANTHROPIC_*覆盖。Claude Code 读取不到 OpenSpec 文件检查permissions.allow是否包含Read(openspec/**)当前工作目录是否在项目根目录openspec是否被.gitignore或编辑器忽略。Cursor 自定义模型不可用检查 Cursor 的模型面板是否选择了自定义 OpenAI 兼容入口Base URL 是否填https://taotoken.net/apiKey 是否与 Claude Code 分开。不要把 Claude Code 的settings.json粘进 Cursor。Codex 报配置错误检查~/.codex/config.toml中base_url和env_key确认没有出现ANTHROPIC_*。Codex 的参数体系与 Claude Code 不同混用是最常见的低级错误。CC Switch 切换后仍走旧 Key关闭并重新打开 Claude Code 或 Codex检查当前 profile确认环境变量没有被 shell 启动脚本覆盖。建议在 profile 名称中标记项目和工具。OpenSpec 文件被智能体随意改动把openspec/specs/**设为只读或高审查级别把openspec/changes/active/**允许编辑。让智能体改 change 和代码不要让它在没有评审的情况下改稳定 spec。Token 消耗突然升高检查是否重复读取整个仓库、是否加载了无关 change、是否在提示词中要求“先搜索全部相关文件”。可以改成明确列出要读的 spec 文件路径。多人协作时 Key 混乱给每个成员或每个工具创建独立 Key至少在 TaoToken 控制台按项目命名。Token 对照表里记录 Key 别名不要记录完整 Key。10. 从模型对话到 Claude Code 文档建议的落地路径如果团队还没有完成通道验证建议按高转化路径走一遍不要一上来就大规模改配置先在模型对话里验证 Key 和 Base URL 是否可用https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_chat如果团队需要长期给编码工具使用再看 Coding Plan 是否匹配当前用量https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_plan进入控制台创建或管理 API Key并把YOUR_API_KEY替换为实际值https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_keys最后按 Claude Code 文档完成settings.json、ANTHROPIC_*和权限配置https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_docTaoToken 在这一套流程里只提供 Key 与通道OpenSpec 负责把需求演进固化成可审查的 spec。真正决定编码智能体是否听话的不是某一个模型参数而是你有没有把读取边界、任务边界和验收边界写清楚。先把openspec/目录落到仓库再把 Claude Code 的settings.json指向https://taotoken.net/api然后用 Token 消耗对照表持续观察。等这三步稳定后再扩展到 Cursor、Codex 和 CC Switch团队才能真正把 OpenSpec 约束落到日常编码流程里。更多入口可以从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentopenspec_final 开始。