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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api 。
第一步，去控制台创建 Key。打开 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面新建一个 Key，复制出来先存好。这个 Key 后面会写进 Claude Code 的环境变量。
第二步，确认你要用的 Model ID。在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 可以看到当前可用的模型列表，记下你打算给 Claude Code 用的那个 Model ID，比如某个 Claude 系列模型。Model ID 必须和列表里完全一致，大小写、连字符都不能错，这是后面 401 和 model not found 报错的高发点。
第三步，把 Claude Code 指向 TaoToken。Claude Code 读取的是环境变量，最稳妥的方式是写进 shell 配置文件。以 macOS/Linux 的 zsh 为例，编辑~/.zshrc：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你刚才复制的Key" export ANTHROPIC_MODEL="你的ModelID"保存后执行source ~/.zshrc让配置生效。Windows 用户可以在系统环境变量里加同样三项，或者在 PowerShell 里用$env:ANTHROPIC_BASE_URL="https://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/openspec@latest装完验证版本：
openspec --version能打印出版本号就说明装好了。后续想升级，用openspec update即可，不用重新 install。
接下来是初始化。OpenSpec 的配置是"按项目"进行的，也就是说每个代码仓库单独初始化一次。先进入你的项目根目录：
cd /path/to/your/project openspec init执行后会弹出交互菜单，问你要接入哪些 AI 工具。这里务必用空格键选中 Claude Code，再回车确认。选中后它会在项目里生成两个关键目录：openspec/存放规格文件，.claude/存放 Claude Code 的配置和命令定义。
初始化完成后，启动 Claude Code：
claude进入交互界面后输入/查看命令列表，应该能看到 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.json，Key 从环境变量读，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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。Claude Code 相关的接入说明可以看 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。
最后留一个实操建议：把/opsx:new的规格模板在项目里固化下来，比如约定spec.md必须包含"接口路径、请求字段、响应字段、错误码"四段。模板越固定，Claude Code 生成时越不容易跑偏，diff 校验也越快。规格写得好，AI 才真的像在按图纸施工。
