1. 多 Agent 接力交付为什么会翻车：规约缺失下的典型故障

多 Agent 接力交付，指的是把一次完整的软件交付拆成需求分析、方案设计、编码实现、验证回归几个阶段，每个阶段交给一个独立的 Agent 会话去执行，上一个 Agent 的产出作为下一个 Agent 的输入。听起来像是流水线，实际上大多数团队跑出来的效果是：第一棒交出去一份模糊的需求，第二棒基于模糊需求做了错误的设计，第三棒照着错误设计写了能编译但业务逻辑不对的代码，第四棒跑了一遍测试全绿然后宣布交付完成。等到真实业务场景一跑，问题全暴露。

我见过最典型的翻车方式有三种。第一种是字段幻觉在接力中被放大。需求 Agent 没有拿到真实的表结构，凭通用命名习惯编了一个字段名，设计 Agent 看到这个字段名觉得合理就写进了接口定义，编码 Agent 照着接口定义写了 SQL，验证 Agent 跑单测时用的是 mock 数据所以没报错。四棒接力下来，错误不但没被拦截，反而被每一棒加固了一层。第二种是验证标准在传递中丢失。需求阶段说“报表生成时间不超过 30 秒”，传到设计阶段变成了“接口响应要快”，传到编码阶段变成了“先跑通再说”，传到验证阶段就只剩“能返回数据就算通过”。第三种是上下文腐烂。第一个 Agent 会话里确认过的边界条件，到第三个 Agent 会话时已经不在上下文窗口里了，新会话默认按自己的理解补全，补出来的东西和最初的约定不一致。

这些问题的根因不是模型能力不够，而是接力过程中缺少硬约束。Agent 之间的交接如果只靠自然语言描述，信息损耗率极高。你需要的是把规约、Skill、验证、可观测四层串成一条可复现的流水线，让每一棒的输入输出都有明确的格式和验收标准。下面我会给出可复制的配置模板，并演示把 endpoint 统一改到 TaoToken 通道后跑通一次完整交付。

2. TaoToken 统一 Key 通道在多 Agent 接力中的前置配置

多 Agent 接力场景下，每个 Agent 会话可能使用不同的模型，比如需求分析用长上下文模型，编码用代码能力强的模型，验证用推理能力强的模型。如果每个模型都单独配一套 Key 和 endpoint，管理成本高，而且容易出现某个会话 Key 过期导致接力中断。TaoToken 的做法是提供一个统一的 API 通道，你只需要一个 Key，就可以在多个模型之间切换，所有 Agent 会话都指向同一个 Base URL。

先拿到 Key。访问 https://taotoken.net/api-keys 创建一个 API Key，复制保存。这个 Key 就是后续所有 Agent 会话共用的凭证。

然后确认你要用的模型 ID。访问 https://taotoken.net/models 可以看到当前支持的模型列表，记下你打算在接力各阶段使用的模型 ID，比如需求分析阶段用一个长上下文模型，编码阶段用一个代码模型。模型 ID 的格式通常是provider/model-name这种形式，具体以页面显示为准。

接下来是配置环节。多 Agent 接力通常涉及三类工具：Claude Code 类的命令行 Agent、Cline 类的编辑器插件 Agent、以及 Codex 类的配置文件驱动 Agent。这三类工具的配置方式不同，但核心都是三件套：Base URL、API Key、Model ID。Base URL 统一填https://taotoken.net/api，API Key 填你刚才创建的那个，Model ID 按阶段选择。

如果你用的是 Claude Code，需要设置环境变量。在终端里执行：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的TaoToken Key" export ANTHROPIC_MODEL="你的模型ID"

如果你希望持久化，把这三行写进~/.bashrc或~/.zshrc。Windows 用户在系统环境变量里添加对应的项。

如果你用的是 Cline 插件，在插件的设置页面里找到 API Provider 配置，选择 Anthropic 兼容模式，Base URL 填https://taotoken.net/api，API Key 填你的 Key，Model ID 填你要用的模型。Cline 的 MCP 功能如果需要额外配置，MCP Server 的启动参数里也要带上同样的 Base URL 和 Key。

如果你用的是 Codex 类的工具，配置文件通常在~/.codex/auth.json或项目根目录的.codex/config.toml。auth.json 的格式如下：

{ "api_key": "你的TaoToken Key", "base_url": "https://taotoken.net/api" }

config.toml 的格式如下：

[model] provider = "anthropic" model_id = "你的模型ID" base_url = "https://taotoken.net/api" api_key = "你的TaoToken Key"

配置完成后，先跑一个最小验证请求，确认通道可用。用 curl 测试：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: 你的TaoToken Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "你的模型ID", "max_tokens": 100, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回内容里包含正常的回复文本，说明通道通了。如果返回 401，检查 Key 是否复制完整；如果返回 model not found，检查模型 ID 是否和文档一致。

3. 可复制的多 Agent 接力配置模板与 Skill 编排

这一节给出可以直接复制到项目里的配置模板。整个接力流程分四棒：需求规约 Agent、方案设计 Agent、编码实现 Agent、验证回归 Agent。每一棒的输出都是下一棒的输入，格式固定，不允许自由发挥。

先建一个目录结构：

project/ ├── .agent/ │ ├── relay.json │ ├── specs/ │ │ ├── brd.md │ │ ├── fsd.md │ │ └── plan.md │ ├── skills/ │ │ ├── requirement-analysis.md │ │ ├── design-review.md │ │ ├── tdd-implement.md │ │ └── verification-gate.md │ └── logs/ │ └── skill-usage.log ├── CLAUDE.md └── src/

relay.json定义接力顺序和每棒的模型配置：

{ "relay": [ { "stage": "requirement", "agent": "claude-code", "model": "你的需求分析模型ID", "input": "用户原始需求", "output": ".agent/specs/brd.md", "skill": "requirement-analysis", "gate": "brd-review-passed" }, { "stage": "design", "agent": "claude-code", "model": "你的设计模型ID", "input": ".agent/specs/brd.md", "output": ".agent/specs/fsd.md", "skill": "design-review", "gate": "fsd-review-passed" }, { "stage": "implement", "agent": "cline", "model": "你的编码模型ID", "input": ".agent/specs/fsd.md", "output": "src/", "skill": "tdd-implement", "gate": "unit-test-passed" }, { "stage": "verify", "agent": "claude-code", "model": "你的验证模型ID", "input": "src/", "output": ".agent/specs/verification-report.md", "skill": "verification-gate", "gate": "all-checks-passed" } ] }

CLAUDE.md里写硬规则，这些规则在每个 Agent 会话启动时都会被加载：

## 硬性规则（违反 = 任务失败） 1. 严禁猜测字段名 — 不确定的字段必须查 `.agent/specs/fsd.md` 或停下询问 2. 每个任务必须先写测试再写实现 — 测试文件命名 `*Test.java` 或 `*.test.ts` 3. 完成声明必须附带验证证据 — 禁止使用“应该”“大概”“看起来” 4. 跨阶段交接必须使用固定格式 — 见 `.agent/relay.json` 的 output 字段 5. 任何 Agent 会话不得修改上一棒的输出文件 — 只能追加或新建 6. 验证不通过时不得进入下一棒 — 必须输出完整错误报告并停止 7. 所有 API 调用必须走统一 Base URL — 不得硬编码其他 endpoint

Skill 文件定义每个阶段的行为模式。以requirement-analysis.md为例：

# Skill: requirement-analysis ## 触发条件 当 relay.json 中 stage 为 requirement 时自动加载。 ## 行为 1. 读取用户原始需求 2. 反问至少 5 个边界问题，覆盖：用户范围、数据时效、输出格式、触发时机、反向边界 3. 等待用户回答后，产出 BRD 文档，格式必须包含：业务背景、用户故事、验收标准、字段映射表 4. 字段映射表必须标注每个字段的来源（数据库字段名或用户确认） 5. 输出到 .agent/specs/brd.md ## 禁止 - 不得在用户回答前开始写 BRD - 不得使用未确认的字段名 - 不得省略反向边界（不做什么）

design-review.md类似，要求设计 Agent 读取 BRD 后产出 FSD，包含数据流、API 设计、表结构、索引、权限边界。tdd-implement.md要求编码 Agent 按红绿重构循环执行，每个任务先写测试。verification-gate.md要求验证 Agent 执行 IDENTIFY、RUN、READ、VERIFY、THEN 五步，输出验证报告。

可观测层用一个 PostToolUse hook 实现。在 Claude Code 的配置里添加：

{ "hooks": { "PostToolUse": [ { "matcher": "Skill", "command": "python3 .agent/hooks/log-skill.py" } ] } }

log-skill.py的内容：

import sys import json from datetime import datetime def main(): try: payload = json.loads(sys.stdin.read()) if payload.get("tool_name") != "Skill": return 0 skill = payload.get("tool_input", {}).get("skill", "<unknown>") session = payload.get("session_id", "<no-session>") ts = datetime.now().isoformat() with open(".agent/logs/skill-usage.log", "a") as f: f.write(f"{ts}\t{session}\t{skill}\n") except Exception: pass return 0 if __name__ == "__main__": sys.exit(main())

这个 hook 出错时返回 0，不会阻塞主流程。日志文件里能看到每个 Skill 被调用的时间和会话 ID，后续可以用脚本统计哪些 Skill 高频使用、哪些从未触发。

4. 验证请求与成功结果：跑通一次完整交付

配置完成后，跑一次完整接力。假设需求是“给现有报表工具增加一个按仓库筛选的导出功能”。

第一棒，需求 Agent 启动。在 Claude Code 里输入：

加载 .agent/skills/requirement-analysis.md，执行 requirement 阶段。 原始需求：给现有报表工具增加一个按仓库筛选的导出功能。

Agent 会反问边界问题，比如：筛选是单选还是多选？导出格式是 Excel 还是 CSV？数据范围是当前月还是可选日期？权限怎么控制？反向边界是什么？你回答后，Agent 产出brd.md。检查文件里是否有字段映射表和验收标准。

第二棒，设计 Agent 启动：

加载 .agent/skills/design-review.md，读取 .agent/specs/brd.md，执行 design 阶段。

Agent 产出fsd.md，包含 API 路径、请求参数、响应格式、涉及的数据库表和视图、索引建议。检查 API 设计是否和现有系统风格一致。

第三棒，编码 Agent 启动。在 Cline 里打开项目，输入：

加载 .agent/skills/tdd-implement.md，读取 .agent/specs/fsd.md，执行 implement 阶段。

Agent 会按任务拆解逐个实现，每个任务先写测试。你可以在终端里跑测试：

mvn test

或者：

npm test

测试全绿后，编码阶段完成。

第四棒，验证 Agent 启动：

加载 .agent/skills/verification-gate.md，读取 src/ 和 .agent/specs/fsd.md，执行 verify 阶段。

Agent 执行五步验证：IDENTIFY 确认要验证的接口和字段，RUN 实际调用接口，READ 读取返回结果，VERIFY 对比 FSD 里的验收标准，THEN 输出验证报告。报告里会列出每条验收标准的通过情况。

成功结果长这样：

## 验证报告 - AC-01: 按仓库筛选返回正确数据 — PASS（实际返回 3 个仓库的数据，与预期一致） - AC-02: 导出 Excel 格式正确 — PASS（列名与 FSD 一致，共 8 列） - AC-03: 无权限仓库不返回 — PASS（越权请求返回 403） - AC-04: 1 万行数据导出 ≤ 30 秒 — PASS（实测 12 秒） - AC-05: 审计字段完整 — PASS（CREATE_DATE_TIME 等 5 个字段均存在） 结论：全部通过，可进入下一阶段。

如果某条不通过，报告里会附带错误信息和复现步骤，接力停止，等修复后重新验证。

5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth

接力过程中最容易卡住的几个报错，这里逐个拆解。

401 Unauthorized。这个报错说明 Key 无效或没传对。检查三件事：第一，Key 是否复制完整，有没有多余空格；第二，请求头里的字段名是否正确，Anthropic 兼容模式用x-api-key，OpenAI 兼容模式用Authorization: Bearer；第三，Base URL 是否写成了https://taotoken.net/api，不要多加/v1或漏掉/api。如果用的是 Claude Code，检查环境变量ANTHROPIC_API_KEY是否生效，可以用echo $ANTHROPIC_API_KEY确认。

local proxy failed。这个报错通常出现在 Cline 或类似插件里，原因是插件尝试走本地代理但代理没启动。解决办法是检查插件的网络设置，把代理模式关掉，直接走 Base URL。如果插件里有“Use Local Proxy”之类的选项，取消勾选。另外检查系统环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口，有的话清掉。

reading choices 报错。这个报错说明返回的 JSON 结构里没有choices字段，通常是模型 ID 写错了，或者请求发到了不兼容的 endpoint。检查模型 ID 是否和文档一致，检查 Base URL 是否指向了正确的兼容模式。如果用的是 OpenAI 兼容格式但模型只支持 Anthropic 格式，也会出现这个报错。解决办法是确认模型支持的请求格式，调整请求体结构。

OAuth 相关报错。如果工具提示需要 OAuth 登录或 token 过期，说明它没有走 API Key 模式。检查工具的配置里是否选择了 API Key 认证方式，而不是 OAuth。Claude Code 默认走 OAuth，需要显式设置ANTHROPIC_API_KEY环境变量来切换到 Key 模式。Codex 类的工具检查auth.json里是否同时存在 OAuth token 和 API Key，如果有冲突，删掉 OAuth 相关字段，只保留 API Key 和 Base URL。

Skill 未触发。如果 Agent 没有按预期加载 Skill，检查 Skill 文件的路径是否和 relay.json 里写的一致，检查 Skill 文件的触发条件是否匹配当前阶段。另外确认 CLAUDE.md 里的硬规则是否被正确加载，可以在会话开始时让 Agent 复述一遍规则来验证。

接力中断。如果某一棒完成后下一棒没有启动，检查上一棒的输出文件是否存在且格式正确。relay.json 里的 gate 字段定义了进入下一棒的条件，如果 gate 没满足，接力会停。查看.agent/logs/skill-usage.log确认上一棒的 Skill 是否被调用，查看输出文件确认内容是否完整。

6. 把 endpoint 统一到 TaoToken 后的长期编码与 Agent 接力实践

多 Agent 接力交付的核心不是让每个 Agent 更聪明，而是让每一棒的输入输出可预测、可验证、可追溯。规约层定义行为边界，Skill 层封装领域能力，验证层强制证据，可观测层记录真实调用。四层串起来，接力才可复现。

把 endpoint 统一到 TaoToken 通道后，最大的变化是 Key 管理成本降下来了。以前每个 Agent 会话可能要配不同的 Key，现在一个 Key 走所有模型。切换模型只需要改 Model ID，Base URL 和 Key 不变。这对于需要频繁切换模型的接力场景很实用，比如需求阶段用长上下文模型，编码阶段用代码模型，验证阶段用推理模型，切换时只改一个配置项。

如果你打算长期跑这套流程，建议把 Coding Plan 用起来。访问 https://taotoken.net/coding-plan 可以看到适合长期编码场景的方案。对于需要频繁调用多个模型的 Agent 接力，Coding Plan 的额度模型比按次计费更可控。

接入文档在 https://taotoken.net/doc，里面有各工具的详细配置步骤和常见问题。模型对话功能在 https://taotoken.net/chat，可以用来快速测试某个模型在特定任务上的表现，确认适合后再写进 relay.json。

控制台在 https://taotoken.net/console，可以查看调用量、余额、Key 状态。API Keys 管理在 https://taotoken.net/api-keys，可以创建多个 Key 分配给不同的 Agent 或环境。

Claude Code 的 Anthropic 兼容接入说明在 https://taotoken.net/claude-code-anthropic，里面有环境变量配置和常见报错处理。

这套流程跑顺之后，你会发现接力交付的瓶颈不再是模型能力，而是规约写得够不够细、验证标准定得够不够硬。规约写得好，Agent 接力就是流水线；规约写得糊，Agent 接力就是传话游戏。