1. 从空目录到 Todo Demo我为什么要用三个 Agent 跑一遍Claude Code 的 Agent Teams 是实验特性简单说就是让一个主会话里同时跑多个带角色的 Agent各自有独立上下文能互相发消息、派任务、等结果。它适合谁适合已经会用 Claude Code 单 Agent 写代码、想观察多角色协作边界的人。我这次的目标很具体一个空目录三个 Agent分别负责 FastAPI 后端、React 前端、联调验证共用一条 TaoToken 统一 Key 通道把 Todo Demo 从零跑到端到端可用。为什么强调统一 Key因为三个 Agent 并行时每个 Teammate 都是独立的模型调用实例如果各自配一套 Key额度、限流、日志会散成三份排查问题时根本对不上账。我试过把 Key 分散配置结果 QA Agent 跑到一半报 429前端 Agent 却还在正常请求定位花了十几分钟。统一走 TaoToken 的 API 通道后所有 Agent 的请求都从同一个入口出出问题只看一处日志就行。这篇笔记给的是可跟做的骨架settings.json 和 config.toml 怎么填、三个 Agent 的分工提示词模板长什么样、Todo Demo 端到端跑通要做哪些验证动作、以及我踩过的坑。不追求业务复杂度只看协作流程能不能串起来。2. TaoToken 前置统一 Key 与 API 通道怎么接TaoToken 在这里的角色是统一模型调用入口。你不需要给每个 Agent 单独申请 Key而是拿一个 Key通过它的 API 地址让 Claude Code 的所有模型请求都走这条通道。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不加 UTM 参数。先拿 Key。进入控制台创建 API Key页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制那串 sk- 开头的字符串后面配置要用。这里有个容易混的点Claude Code 读的是环境变量不是你在某个配置文件里写死就行。所以统一 Key 的落地方式是——把 Key 写进环境变量让主会话和所有 Teammate 继承同一份。下面两节分别给 settings.json 和 config.toml 的骨架你按自己系统选一种。注意Key 只放环境变量或本地配置文件不要提交到 git也不要在提示词里明文粘贴。3. 可复制配置settings.json 与 config.toml 骨架3.1 settings.json 配置骨架Claude Code 的用户级配置在~/.claude/settings.json。这个文件负责开启 Agent Teams 实验开关并把模型请求指向 TaoToken 通道。下面是我实际用的骨架把sk-你的Key换成你自己的{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, teammateMode: auto }几个参数说明。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS置 1 才会启用多 Agent 能力不设的话你只能跑单 Agent。ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址注意结尾不要多加斜杠。ANTHROPIC_API_KEY就是刚才拿到的统一 Key。teammateMode设 autoClaude Code 会根据终端环境自己决定用分屏还是进程内模式。如果你不想改全局配置也可以在项目目录下建.claude/settings.json只对当前项目生效。我建议实验阶段用项目级避免污染其他项目。3.2 config.toml 配置骨架有些环境走的是 config.toml 形式比如你在用支持 TOML 配置的客户端或包装层。骨架如下[env] CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1 ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY sk-你的Key ANTHROPIC_MODEL claude-sonnet-4-5 [agent_teams] teammate_mode auto max_teammates 3max_teammates限制同时活跃的 Teammate 数量这次实验就是 3 个。设太大 Token 消耗会失控后面排错章节会讲。3.3 验证配置是否生效配完先别急着开团队跑一条最小请求确认通道通。用 curl 直接打 TaoToken 的 APIcurl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content字段带文本就说明 Key 和通道都正常。如果返回 401检查 Key 有没有复制全返回 404检查 base URL 是不是写成了带/v1的完整路径导致重复。4. 三个 Agent 的分工提示词模板配置通了接下来是团队组建。Agent Teams 的关键在于提示词要把角色边界写死否则三个 Agent 会互相抢活。下面是我用的分工模板你可以直接改。4.1 Team Lead 总指令在空目录启动 Claude Code 后第一段输入总指令核心是把 API 契约先定下来项目Todo List 应用 技术栈后端 Python 3.11 FastAPI SQLite前端 React 18 Vite TailwindCSS测试 pytest httpx Playwright API 契约唯一真实数据源 Base URL: http://localhost:8000/api/v1 GET /todos 获取全部返回 [{id, title, completed, created_at}] POST /todos 创建请求 {title: ...}返回 201 PUT /todos/{id} 更新请求 {title:..., completed:true} DELETE /todos/{id} 删除返回 {message:deleted} 状态码200 成功、201 创建、404 未找到、422 校验失败 字段id int, title str, completed bool, created_at ISO8601 请先输出 API_CONTRACT.md再启动三个 Teammate backend-dev 实现 FastAPI 后端交付可运行服务 uvicorn main:app --reload frontend-dev 实现 React 前端proxy 指向 8000 端口 qa-engineer 先写测试框架开发完成后执行联调验证这段指令管用的原因有三个。契约写在提示词里三个 Agent 不用猜接口。交付物具体到运行命令Agent 知道什么算做完。QA 被当成独立角色不是顺便测测。4.2 后端 Agent 提示词你是 Backend Dev。严格按 API_CONTRACT.md 实现不擅自扩展接口。 任务用 FastAPI 搭 main.py / models.py / schemas.py / database.py SQLAlchemy SQLite 定义 Todo 模型实现完整 CRUD加 Pydantic 校验和 CORS。 交付可独立运行的后端命令 uvicorn main:app --reload。 完成后用 SendMessage 通知 Team Lead。4.3 前端 Agent 提示词你是 Frontend Dev。只读 API_CONTRACT.md发现歧义发消息问 Team Lead不要猜。 任务Vite React TailwindCSS 初始化实现列表展示、添加输入框、 完成切换、删除按钮封装 API 调用层配置 proxy 到 8000 端口。 交付可独立运行的前端npm run dev 能起。4.4 QA Agent 提示词你是 QA Engineer最苛刻的质量守门人宁可误报不可漏报。 阶段 1开发开始前先写集成测试和契约测试框架。 阶段 2后端完成后执行代码审查、单元测试、集成测试、契约测试。 阶段 3前端完成后执行构建验证和 E2E 测试。 遇到数字或文字对不上时先停下来确认不要猜着干。角色定义越鲜明协作越顺。反面例子是三个角色都叫开发者你会看到它们互相抢活、重复实现。5. 端到端验证Todo Demo 跑通要做哪些动作三个 Agent 跑起来后验证不能只看它说完成了。下面是我实际执行的验证动作按顺序做。5.1 后端独立验证后端 Agent 报告完成后先单独验证后端能不能起cd backend pip install -r requirements.txt uvicorn main:app --reload另开一个终端打接口curl -s -X POST http://localhost:8000/api/v1/todos \ -H content-type: application/json \ -d {title:写实验笔记}返回 201 且带id、created_at字段说明创建通了。再打 GET 确认列表里有这条curl -s http://localhost:8000/api/v1/todos5.2 前端独立验证cd frontend npm install npm run dev浏览器打开 Vite 给的地址添加一条 Todo看列表是否出现。如果请求报 CORS检查后端 CORS 配置有没有放行前端端口。5.3 端到端联调验证前后端都起来后走一遍完整用户路径打开页面 → 添加 Todo → 勾选完成 → 删除 → 列表恢复为空。这一步 QA Agent 会用 Playwright 自动跑你也可以手动过一遍。5.4 验证结果对照验证项命令/动作通过标准后端启动uvicorn main:app --reload无报错监听 8000创建接口POST /todos返回 201 带 id查询接口GET /todos返回数组含新建项更新接口PUT /todos/{id}completed 字段变化删除接口DELETE /todos/{id}返回 deleted前端启动npm run dev页面可访问端到端手动走一遍增删改查全通我这次跑下来后端 7 个文件、前端 12 个文件自动化测试 72 项全过覆盖率 99%。数字只说明这个 Demo 跑通了不代表能外推到真实业务。6. 本篇常见错排查6.1 Agent 起不来或只有一个在跑先查版本。Agent Teams 需要 Claude Code v2.1.32用claude --version确认。再查环境变量有没有生效echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS应该输出 1。如果 settings.json 改了但没生效重启会话。6.2 请求报 401 或 403大概率是 Key 问题。检查ANTHROPIC_API_KEY有没有复制全前后有没有多余空格。如果 Key 是对的还报错去控制台看额度是否用完页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。6.3 请求报 404检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1。基址只到/api客户端会自己拼/v1/messages你多写一层就重复了。6.4 三个 Agent 互相抢活这是提示词没写清角色边界。回到第 4 节把每个 Agent 的职责和交付物写具体。特别是 QA要明确它是独立角色不是开发的附属。6.5 Token 消耗过快每个 Teammate 是独立实例3 个 Agent 并行消耗是单人的数倍。省钱关键是委派模式Team Lead 只管协调不写代码。如果 Team Lead 也下场写代码上下文会变重消耗翻倍。另外max_teammates别设太大线性任务别硬拆。6.6 端口冲突后端 8000、前端 5173 是默认端口。如果被占用后端换uvicorn main:app --port 8001前端在 vite.config.js 改 server.port同时更新 proxy 目标。6.7 数据库脏状态导致复现失败实验收尾要关进程、删数据库。SQLite 有三件套.db、.db-wal、.db-shm只删.db下次可能读到残留 WAL。清理命令rm -f todo.db todo.db-wal todo.db-shm7. 收尾与下一步实验跑完Team Lead 给三个 Agent 发 shutdown_request然后清理 Team 资源。这一步别省否则下次复现会被脏状态干扰。如果你想把这条链路用得更顺几个入口按需取验证模型对话效果走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 长期编码或 Agent 场景看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入细节和报错对照查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。最后留一句实操建议先写契约再开工角色任务具体到交付物给 QA 独立地位遇到冲突先停。这四条比任何配置都值钱。
Agent Teams 实验笔记：用 TaoToken 统一 Key 让 Claude Code 三个 Agent 跑通 Todo Demo
1. 从空目录到 Todo Demo我为什么要用三个 Agent 跑一遍Claude Code 的 Agent Teams 是实验特性简单说就是让一个主会话里同时跑多个带角色的 Agent各自有独立上下文能互相发消息、派任务、等结果。它适合谁适合已经会用 Claude Code 单 Agent 写代码、想观察多角色协作边界的人。我这次的目标很具体一个空目录三个 Agent分别负责 FastAPI 后端、React 前端、联调验证共用一条 TaoToken 统一 Key 通道把 Todo Demo 从零跑到端到端可用。为什么强调统一 Key因为三个 Agent 并行时每个 Teammate 都是独立的模型调用实例如果各自配一套 Key额度、限流、日志会散成三份排查问题时根本对不上账。我试过把 Key 分散配置结果 QA Agent 跑到一半报 429前端 Agent 却还在正常请求定位花了十几分钟。统一走 TaoToken 的 API 通道后所有 Agent 的请求都从同一个入口出出问题只看一处日志就行。这篇笔记给的是可跟做的骨架settings.json 和 config.toml 怎么填、三个 Agent 的分工提示词模板长什么样、Todo Demo 端到端跑通要做哪些验证动作、以及我踩过的坑。不追求业务复杂度只看协作流程能不能串起来。2. TaoToken 前置统一 Key 与 API 通道怎么接TaoToken 在这里的角色是统一模型调用入口。你不需要给每个 Agent 单独申请 Key而是拿一个 Key通过它的 API 地址让 Claude Code 的所有模型请求都走这条通道。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不加 UTM 参数。先拿 Key。进入控制台创建 API Key页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制那串 sk- 开头的字符串后面配置要用。这里有个容易混的点Claude Code 读的是环境变量不是你在某个配置文件里写死就行。所以统一 Key 的落地方式是——把 Key 写进环境变量让主会话和所有 Teammate 继承同一份。下面两节分别给 settings.json 和 config.toml 的骨架你按自己系统选一种。注意Key 只放环境变量或本地配置文件不要提交到 git也不要在提示词里明文粘贴。3. 可复制配置settings.json 与 config.toml 骨架3.1 settings.json 配置骨架Claude Code 的用户级配置在~/.claude/settings.json。这个文件负责开启 Agent Teams 实验开关并把模型请求指向 TaoToken 通道。下面是我实际用的骨架把sk-你的Key换成你自己的{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, teammateMode: auto }几个参数说明。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS置 1 才会启用多 Agent 能力不设的话你只能跑单 Agent。ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址注意结尾不要多加斜杠。ANTHROPIC_API_KEY就是刚才拿到的统一 Key。teammateMode设 autoClaude Code 会根据终端环境自己决定用分屏还是进程内模式。如果你不想改全局配置也可以在项目目录下建.claude/settings.json只对当前项目生效。我建议实验阶段用项目级避免污染其他项目。3.2 config.toml 配置骨架有些环境走的是 config.toml 形式比如你在用支持 TOML 配置的客户端或包装层。骨架如下[env] CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1 ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY sk-你的Key ANTHROPIC_MODEL claude-sonnet-4-5 [agent_teams] teammate_mode auto max_teammates 3max_teammates限制同时活跃的 Teammate 数量这次实验就是 3 个。设太大 Token 消耗会失控后面排错章节会讲。3.3 验证配置是否生效配完先别急着开团队跑一条最小请求确认通道通。用 curl 直接打 TaoToken 的 APIcurl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content字段带文本就说明 Key 和通道都正常。如果返回 401检查 Key 有没有复制全返回 404检查 base URL 是不是写成了带/v1的完整路径导致重复。4. 三个 Agent 的分工提示词模板配置通了接下来是团队组建。Agent Teams 的关键在于提示词要把角色边界写死否则三个 Agent 会互相抢活。下面是我用的分工模板你可以直接改。4.1 Team Lead 总指令在空目录启动 Claude Code 后第一段输入总指令核心是把 API 契约先定下来项目Todo List 应用 技术栈后端 Python 3.11 FastAPI SQLite前端 React 18 Vite TailwindCSS测试 pytest httpx Playwright API 契约唯一真实数据源 Base URL: http://localhost:8000/api/v1 GET /todos 获取全部返回 [{id, title, completed, created_at}] POST /todos 创建请求 {title: ...}返回 201 PUT /todos/{id} 更新请求 {title:..., completed:true} DELETE /todos/{id} 删除返回 {message:deleted} 状态码200 成功、201 创建、404 未找到、422 校验失败 字段id int, title str, completed bool, created_at ISO8601 请先输出 API_CONTRACT.md再启动三个 Teammate backend-dev 实现 FastAPI 后端交付可运行服务 uvicorn main:app --reload frontend-dev 实现 React 前端proxy 指向 8000 端口 qa-engineer 先写测试框架开发完成后执行联调验证这段指令管用的原因有三个。契约写在提示词里三个 Agent 不用猜接口。交付物具体到运行命令Agent 知道什么算做完。QA 被当成独立角色不是顺便测测。4.2 后端 Agent 提示词你是 Backend Dev。严格按 API_CONTRACT.md 实现不擅自扩展接口。 任务用 FastAPI 搭 main.py / models.py / schemas.py / database.py SQLAlchemy SQLite 定义 Todo 模型实现完整 CRUD加 Pydantic 校验和 CORS。 交付可独立运行的后端命令 uvicorn main:app --reload。 完成后用 SendMessage 通知 Team Lead。4.3 前端 Agent 提示词你是 Frontend Dev。只读 API_CONTRACT.md发现歧义发消息问 Team Lead不要猜。 任务Vite React TailwindCSS 初始化实现列表展示、添加输入框、 完成切换、删除按钮封装 API 调用层配置 proxy 到 8000 端口。 交付可独立运行的前端npm run dev 能起。4.4 QA Agent 提示词你是 QA Engineer最苛刻的质量守门人宁可误报不可漏报。 阶段 1开发开始前先写集成测试和契约测试框架。 阶段 2后端完成后执行代码审查、单元测试、集成测试、契约测试。 阶段 3前端完成后执行构建验证和 E2E 测试。 遇到数字或文字对不上时先停下来确认不要猜着干。角色定义越鲜明协作越顺。反面例子是三个角色都叫开发者你会看到它们互相抢活、重复实现。5. 端到端验证Todo Demo 跑通要做哪些动作三个 Agent 跑起来后验证不能只看它说完成了。下面是我实际执行的验证动作按顺序做。5.1 后端独立验证后端 Agent 报告完成后先单独验证后端能不能起cd backend pip install -r requirements.txt uvicorn main:app --reload另开一个终端打接口curl -s -X POST http://localhost:8000/api/v1/todos \ -H content-type: application/json \ -d {title:写实验笔记}返回 201 且带id、created_at字段说明创建通了。再打 GET 确认列表里有这条curl -s http://localhost:8000/api/v1/todos5.2 前端独立验证cd frontend npm install npm run dev浏览器打开 Vite 给的地址添加一条 Todo看列表是否出现。如果请求报 CORS检查后端 CORS 配置有没有放行前端端口。5.3 端到端联调验证前后端都起来后走一遍完整用户路径打开页面 → 添加 Todo → 勾选完成 → 删除 → 列表恢复为空。这一步 QA Agent 会用 Playwright 自动跑你也可以手动过一遍。5.4 验证结果对照验证项命令/动作通过标准后端启动uvicorn main:app --reload无报错监听 8000创建接口POST /todos返回 201 带 id查询接口GET /todos返回数组含新建项更新接口PUT /todos/{id}completed 字段变化删除接口DELETE /todos/{id}返回 deleted前端启动npm run dev页面可访问端到端手动走一遍增删改查全通我这次跑下来后端 7 个文件、前端 12 个文件自动化测试 72 项全过覆盖率 99%。数字只说明这个 Demo 跑通了不代表能外推到真实业务。6. 本篇常见错排查6.1 Agent 起不来或只有一个在跑先查版本。Agent Teams 需要 Claude Code v2.1.32用claude --version确认。再查环境变量有没有生效echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS应该输出 1。如果 settings.json 改了但没生效重启会话。6.2 请求报 401 或 403大概率是 Key 问题。检查ANTHROPIC_API_KEY有没有复制全前后有没有多余空格。如果 Key 是对的还报错去控制台看额度是否用完页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。6.3 请求报 404检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/v1。基址只到/api客户端会自己拼/v1/messages你多写一层就重复了。6.4 三个 Agent 互相抢活这是提示词没写清角色边界。回到第 4 节把每个 Agent 的职责和交付物写具体。特别是 QA要明确它是独立角色不是开发的附属。6.5 Token 消耗过快每个 Teammate 是独立实例3 个 Agent 并行消耗是单人的数倍。省钱关键是委派模式Team Lead 只管协调不写代码。如果 Team Lead 也下场写代码上下文会变重消耗翻倍。另外max_teammates别设太大线性任务别硬拆。6.6 端口冲突后端 8000、前端 5173 是默认端口。如果被占用后端换uvicorn main:app --port 8001前端在 vite.config.js 改 server.port同时更新 proxy 目标。6.7 数据库脏状态导致复现失败实验收尾要关进程、删数据库。SQLite 有三件套.db、.db-wal、.db-shm只删.db下次可能读到残留 WAL。清理命令rm -f todo.db todo.db-wal todo.db-shm7. 收尾与下一步实验跑完Team Lead 给三个 Agent 发 shutdown_request然后清理 Team 资源。这一步别省否则下次复现会被脏状态干扰。如果你想把这条链路用得更顺几个入口按需取验证模型对话效果走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 长期编码或 Agent 场景看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入细节和报错对照查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。最后留一句实操建议先写契约再开工角色任务具体到交付物给 QA 独立地位遇到冲突先停。这四条比任何配置都值钱。
