1. 为什么要在 Claude Code 里装 OpenSpec如果你已经用 Claude Code 写过一阵子代码大概率遇到过这种情况让它加一个接口它给你生成一堆看起来能跑、但字段命名和项目里其他模块对不上的代码再让它改它又把上一轮的约定忘了。问题不在模型能力而在于你直接让它写代码中间缺了一层规格。OpenSpec 解决的就是这件事。它是一个跑在项目里的规格驱动开发工具核心思路是先把要做什么、接口长什么样、任务怎么拆写成 markdown 规格文件再让 Claude Code 按规格生成代码。这样 AI 的产出有约束、可审核、可归档而不是每次自由发挥。Spec-Driven Development规格驱动开发这个词最近在 Claude Code 圈子里出现频率很高原因也简单当 AI 能一次写几百行代码时真正稀缺的不是生成速度而是生成的东西符合预期。OpenSpec 把预期显式写下来Claude Code 再执行闭环就成立了。这篇要交付的东西很具体本地用 npm 装好 OpenSpec、在项目里初始化规格目录、把 Claude Code 的请求统一走 TaoToken 的 Key 和 API 通道最后用三步验证——生成规格、产出代码、diff 校验。适合已经在用 Claude Code、想把手写 prompt 升级成规格流程的开发者。整个流程我按可复制的方式写命令和配置都能直接拿去用。需要提前说明一点OpenSpec 本身是本地 npm 包不涉及任何网络通道配置真正需要统一 Key 的是 Claude Code 这一侧。所以下面会分成两条线——OpenSpec 装在本机Claude Code 的模型请求走 TaoToken。2. 前置准备TaoToken 统一 Key 与 Claude Code 接入在装 OpenSpec 之前先把 Claude Code 的模型通道理顺否则后面/opsx:apply生成代码时会因为鉴权问题卡住。TaoToken 在这里扮演的角色是统一入口你不需要为每个模型单独维护一套 Key而是用同一个 Key 走同一个 API 地址Claude Code、Cline、Codex 这些工具都能复用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。第一步去控制台创建 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面新建一个 Key复制出来先存好。这个 Key 后面会写进 Claude Code 的环境变量。第二步确认你要用的 Model ID。在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以看到当前可用的模型列表记下你打算给 Claude Code 用的那个 Model ID比如某个 Claude 系列模型。Model ID 必须和列表里完全一致大小写、连字符都不能错这是后面 401 和 model not found 报错的高发点。第三步把 Claude Code 指向 TaoToken。Claude Code 读取的是环境变量最稳妥的方式是写进 shell 配置文件。以 macOS/Linux 的 zsh 为例编辑~/.zshrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你刚才复制的Key export ANTHROPIC_MODEL你的ModelID保存后执行source ~/.zshrc让配置生效。Windows 用户可以在系统环境变量里加同样三项或者在 PowerShell 里用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api临时设置。这里有个细节值得强调Base URL 只写到/api不要自己拼/v1/messages之类的路径Claude Code 会自己补全。多写一段路径是常见的 404 来源。如果你同时用 CC Switch 管理多个模型配置可以在 CC Switch 里新增一个 profile把 Base URL 填https://taotoken.net/api、Key 填 TaoToken 的 Key、Model 填对应 Model ID三件套齐全后切换过去即可。Cline 的 MCP 配置、Codex 的auth.json也是同样的三件套逻辑只是字段名不同。配置完成后先别急着装 OpenSpec用一条最小请求验证通道是否通。可以直接在终端跑claude -p 回复 ok 两个字母即可如果返回ok说明 Key、Base URL、Model ID 三者都对上了。如果报 401多半是 Key 复制时带了空格如果报 model not found回去核对 Model ID。这一步过了再进入 OpenSpec 安装。3. 可复制配置npm 安装 OpenSpec 与项目初始化通道验证通过后开始装 OpenSpec。它是标准的 npm 全局包命令很直接npm install -g fission-ai/openspeclatest装完验证版本openspec --version能打印出版本号就说明装好了。后续想升级用openspec update即可不用重新 install。接下来是初始化。OpenSpec 的配置是按项目进行的也就是说每个代码仓库单独初始化一次。先进入你的项目根目录cd /path/to/your/project openspec init执行后会弹出交互菜单问你要接入哪些 AI 工具。这里务必用空格键选中 Claude Code再回车确认。选中后它会在项目里生成两个关键目录openspec/存放规格文件.claude/存放 Claude Code 的配置和命令定义。初始化完成后启动 Claude Codeclaude进入交互界面后输入/查看命令列表应该能看到 OpenSpec 注入的命令/opsx:new新建变更/opsx:apply应用变更/opsx:archive归档变更如果看不到这几个命令说明初始化时没勾选 Claude Code或者.claude/目录被.gitignore忽略了。前者重新跑一次openspec init后者检查忽略规则。为了让 Claude Code 在生成代码时稳定走 TaoToken建议在项目里放一份显式配置。Claude Code 支持项目级 settings在项目根目录创建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: 你的ModelID } }这份 JSON 的作用是把通道配置固化到项目里团队其他人拉下代码后只要换成自己的 Key 就能用Base URL 和 Model ID 不用各自猜。注意 Key 不要提交到公开仓库建议把settings.json里的 Key 换成从环境变量读取或者把该文件加入.gitignore后单独分发。到这里OpenSpec 装好了、Claude Code 命令注入了、TaoToken 通道也固化了。三件套Base URL Key Model ID在环境变量和项目 settings 里各有一份互为兜底。4. 三步验证规格生成、代码产出、diff 校验配置齐了现在跑一遍完整闭环验证 Spec-Driven Development 是否真的生效。整个流程分三步每步都有明确的产出物。第一步生成规格。在 Claude Code 交互界面里输入/opsx:new 添加用户登录 APIClaude 会引导你填写三份文件proposal.md说明为什么做这个变更spec.md写接口规范路径、方法、请求体、响应体、错误码tasks.md拆实现步骤。这一步的关键是spec.md要写细字段类型、必填项、错误码都列清楚。你写得越具体后面生成的代码越贴合项目。写完后可以在openspec/目录下看到这次变更的文件夹里面就是这三份 markdown。这一步的产出是规格不是代码。第二步产出代码。规格审核没问题后输入/opsx:applyClaude Code 会读取spec.md里的约束按tasks.md的步骤生成代码。实测下来它会严格遵循 spec 里定义的字段名和错误码而不是像自由生成那样随手命名。生成过程中如果某个任务依赖前面的产出它会按顺序执行。这一步的产出是实际代码文件比如路由、控制器、类型定义。生成完先别急着提交进入第三步。第三步diff 校验。用 git 看这次变更动了哪些文件git diff --stat git diff重点核对三件事生成的字段名是否和spec.md一致、错误码是否覆盖了 spec 里列的场景、有没有顺手改动无关文件。如果发现偏差回到spec.md补充约束再跑一次/opsx:apply。这个改规格再重生成的循环正是规格驱动开发比直接写 prompt 稳的地方——修正的是规格不是零散的对话。三步都过了用/opsx:archive把这次变更归档规格文件保留在openspec/里作为项目文档。下次有人问这个接口为什么这么设计翻proposal.md就有答案。整个闭环跑通后你会发现Claude Code 的角色从自由发挥的代码生成器变成了按规格执行的工程助手。TaoToken 在这里保证的是通道稳定——不管你在哪个项目、用哪个模型Key 和 Base URL 都是同一套不用每次重新配。5. 常见报错排查401、local proxy failed 与 reading choices流程跑起来后报错基本集中在通道和配置两类。下面按真实遇到的顺序列几个高频问题。401 Unauthorized。最常见的原因是 Key 复制时带了首尾空格或者环境变量没生效。排查方法在终端执行echo $ANTHROPIC_AUTH_TOKEN看输出的 Key 是否完整、有没有多余空格。如果环境变量对但项目settings.json里也写了一份注意两份是否冲突——项目级配置会覆盖环境变量检查settings.json里的 Key 是不是旧的。local proxy failed / connection refused。这个报错通常出现在 Base URL 写错的情况下。确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要多写/v1或/messages。另外检查本机有没有残留的代理环境变量HTTP_PROXY、HTTPS_PROXY如果有先unset掉再试避免请求被转发到不可达的地址。Error reading choices / 响应解析失败。这类报错多半是 Model ID 不对或者模型返回了非预期格式。先核对ANTHROPIC_MODEL是否和模型列表里完全一致。如果 Model ID 对但仍然报错试着换一个模型验证通道本身是否正常——如果换模型后能通说明是原模型 ID 的问题如果换模型也报错问题在通道配置。OAuth 相关报错。Claude Code 某些版本会尝试走 OAuth 流程如果你用的是 API Key 模式需要在配置里明确禁用 OAuth。检查settings.json里有没有forceLoginMethod: apiKey之类的字段没有的话加上。这个报错的特征是提示你去浏览器授权但你的场景根本不需要授权。看不到 /opsx 命令。回到项目根目录确认openspec/和.claude/两个目录都存在。如果.claude/存在但命令没注入重新跑openspec init并确保勾选 Claude Code。还有一种情况是 Claude Code 版本太旧升级到最新版再试。排查时有个通用思路先用claude -p 回复 ok验证通道通道通了再查 OpenSpec 层。这样能把问题范围快速缩小到是通道问题还是工具问题避免在两层之间来回猜。6. 把规格流程固定下来TaoToken 通道与 OpenSpec 的配合跑通一次闭环不难难的是让它成为日常习惯。我的做法是把 TaoToken 的三件套写进项目模板新项目openspec init之后直接复制.claude/settings.jsonKey 从环境变量读Base URL 和 Model ID 固定不变。这样团队里每个人拉下代码只需要配一次自己的 Key通道和模型选择不用各自折腾。OpenSpec 的规格文件建议纳入版本管理proposal.md、spec.md、tasks.md都是项目资产不是临时文件。归档后的变更留在openspec/里相当于一份为什么这么设计的决策记录。下次改接口时先翻历史 spec比翻聊天记录靠谱得多。如果你还在用零散 prompt 让 Claude Code 写代码可以挑一个中等复杂度的需求试一次完整流程/opsx:new写规格、/opsx:apply生成、git diff校验、/opsx:archive归档。跑完这一轮你会对规格驱动和自由生成的差别有直观感受。通道侧需要长期编码或跑 Agent 场景的可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Claude Code 相关的接入说明可以看 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后留一个实操建议把/opsx:new的规格模板在项目里固化下来比如约定spec.md必须包含接口路径、请求字段、响应字段、错误码四段。模板越固定Claude Code 生成时越不容易跑偏diff 校验也越快。规格写得好AI 才真的像在按图纸施工。