企业官网建设流程全解析

1. 单 Agent 撞墙之后：为什么需要子代理系统

如果你已经用 Claude Code 写过一段时间代码，大概率遇到过这种场景：让它调研一个模块的认证逻辑，它读了十几个文件，然后你让它接着改代码，它开始"忘事"——前面读过的文件路径记不清了，改到一半又回头重新搜索。这不是模型变笨了，而是单 Agent 模式的固有瓶颈。

单 Agent 一次只能想一件事、做一件事。面对"宽"任务时，问题会被放大：串行阻塞让调研阶段你只能干等；上下文污染让调研、实现、验证互相干扰，每一步都在消耗同一个上下文窗口；能力错配则更隐蔽——探索代码库只需要快速只读模型，实现功能却需要强推理模型加全量工具权限，单 Agent 只能选一套配置硬扛。

Claude Code 的解法是子代理（Subagent）系统：让主 Agent 像调用普通工具一样"生出"子 Agent，每个子 Agent 拥有独立的对话循环、独立的上下文窗口、裁剪后的工具集，甚至可以用不同的模型。这套系统里最值得拆的是三种协作机制——Fork、Swarm（Agent Teams）、Coordinator Mode，它们分别对应"分身""组队""编排"三种拓扑。

这篇指南面向多代理协作开发场景，我会把三种机制的配置片段、统一 Key 接入步骤、以及可复现的验证动作都写清楚。你不需要改 Claude Code 源码，只需要准备好配置文件和一个能统一管理模型调用的入口。我实测下来，把 Key 接入这一步做扎实，后面切换模型、跑并行任务会省掉大量重复配置的麻烦。

先说清楚适合谁：如果你只是偶尔让 Claude Code 补个函数，单 Agent 够用；但如果你在做跨模块重构、多假设调试、或者需要"研究→实现→验证"流水线的工程任务，子代理系统能明显改变你的工作方式。下面从统一入口 AgentTool 讲起，再逐个拆三种模式。

2. TaoToken 前置：统一 Key 接入与 settings.json 配置

在动子代理之前，得先把模型调用入口理顺。Claude Code 的子代理系统允许不同子 Agent 用不同模型——Fork 建议不换模型以复用 Prompt Cache，Explore 默认走轻量模型，实现类任务走强推理模型。如果每个模型都要单独配一套 Key 和 Base URL，配置文件会迅速失控。

TaoToken 在这里的角色是统一入口：一个 Key、一个 Base URL，背后可以路由到不同模型。这样你在 settings.json 里只需要维护一份凭证，子代理切换模型时改 Model ID 即可。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （注意 API 地址不带 UTM 参数）。

接入分三步：拿 Key、写配置、验证连通。先到控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在 API Keys 页面生成，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。生成的 Key 形如sk-开头的一串字符，复制后先存到环境变量里，别直接写进会提交到 Git 的文件。

Claude Code 读取配置的优先级是：环境变量 > 项目级.claude/settings.json> 用户级~/.claude/settings.json。我建议把 Key 放环境变量，把模型和 Base URL 放项目级配置，这样团队协作时配置文件可以进版本库，Key 不会泄露。

环境变量这样设（Linux/macOS 写进~/.zshrc或~/.bashrc，Windows 用系统环境变量面板）：

export TAOTOKEN_API_KEY="sk-你的Key" export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="$TAOTOKEN_API_KEY"

注意ANTHROPIC_BASE_URL不要带末尾斜杠，也不要带 UTM 参数，否则部分客户端会拼接出错误路径。设完执行source ~/.zshrc让配置生效，然后用echo $ANTHROPIC_BASE_URL确认输出是https://taotoken.net/api。

项目级settings.json负责声明模型和子代理行为。在项目根目录建.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" }, "model": "claude-sonnet-4-5", "permissions": { "allow": ["Bash(git:*)", "Read", "Grep", "Glob"], "deny": ["Bash(rm -rf:*)"] }, "subagents": { "explore": { "model": "claude-haiku-4-5" }, "implement": { "model": "claude-sonnet-4-5" } } }

这里subagents字段是示意结构，不同 Claude Code 版本字段名可能略有差异，以你本地claude --version对应的文档为准。核心思路是：Base URL 和 Key 全局统一，模型按子代理角色分配。如果你用的是 Codex 系客户端，配置落在~/.codex/auth.json，结构是：

{ "OPENAI_API_KEY": "sk-你的Key", "OPENAI_BASE_URL": "https://taotoken.net/api" }

三件套记牢：Base URL 填https://taotoken.net/api，Key 填控制台生成的sk-串，Model ID 填你要用的模型名（如claude-sonnet-4-5）。这三样在任何客户端里都是必填项，缺一个就会报认证或路由错误。

配置写完先别急着跑子代理，用一次最小请求验证连通。模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以在网页里直接发一条消息确认 Key 有效。命令行侧用 curl 验证：

curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: $TAOTOKEN_API_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":"ping"}]}'

返回 JSON 里带content字段就说明链路通了。这一步过了，再进子代理配置，否则后面报错你分不清是 Key 问题还是子代理配置问题。

3. 可复制配置：Fork、Swarm、Coordinator 三套片段

这一节给可直接粘贴的配置。三种模式互斥关系要先记住：Coordinator 和 Fork 互斥，开启 Coordinator 会自动禁用 Fork；Swarm 是独立实验特性，需要单独开关。

3.1 Fork 配置：共享 Prompt Cache 的轻量分身

Fork 是默认路径——调用 AgentTool 时不指定subagent_type就走 Fork。它的核心是 Prompt Cache 共享：所有 Fork 子 Agent 共享父 Agent 的完整 assistant 消息前缀，字节完全一致，只有最后一个 text 块携带各自指令。官方明确说"Forks are cheap because they share your prompt cache"。

Fork 的配置重点在"不要换模型"。在settings.json里给 Fork 显式锁定与父 Agent 相同的模型：

{ "subagents": { "fork": { "model": "claude-sonnet-4-5", "inheritContext": true, "tools": ["Read", "Grep", "Glob"] } } }

inheritContext: true表示继承父对话上下文。Fork 之间没有横向通信，只向父进程返回结果字符串。运行时每个 Fork 有独立的消息历史、文件状态缓存、中断控制器和工具权限上下文，互不干扰。

调用 Fork 的 AgentTool 请求长这样：

{ "name": "Agent", "input": { "description": "并行搜索三个模块的认证逻辑", "prompt": "在 src/auth、src/api、src/middleware 三个目录下分别找出所有与 token 校验相关的函数，返回文件路径和行号", "run_in_background": true } }

不写subagent_type就是 Fork。run_in_background: true让它异步执行，主对话继续。

3.2 Swarm 配置：Mailbox 与共享任务列表

Swarm 官方名 Agent Teams，默认禁用，需要把CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS加进 settings.json 或环境变量：

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "agentTeams": { "backend": "auto", "maxTeammates": 4, "mailboxDir": ".claude/teams" } }

backend有三个值：tmux/iTerm2分屏让每个队友占一个窗格，in-process让队友跑在同一 Node.js 进程走 leader queue 同步，auto自动检测——已在 tmux 会话里就分屏，否则 in-process。

Swarm 的关键不是多进程，而是 team file、mailbox、SendMessage 这套团队协议。队友之间可以直接 SendMessage，不需要经过负责人中转；但团队创建、清理、成员发现、权限聚合、UI 呈现仍然围着 lead 转。消息传递通过基于文件的 Mailbox 系统实现，带锁文件做并发控制。

一个关键约束：你的文本输出别人看不到，必须通过 SendMessage 工具通信。模型必须明确知道直接写回复文本不会让队友看到。创建队友的调用：

{ "name": "Agent", "input": { "team_name": "refactor-team", "name": "backend-worker", "prompt": "负责 src/backend 下的接口重构，完成后用 SendMessage 通知 lead", "subagent_type": "GeneralPurpose" } }

共享任务列表协调整个团队。任务有三种状态：待处理、进行中、已完成，任务之间可以有依赖——有未解决依赖的待处理任务无法被认领，依赖完成后自动解除阻止。

3.3 Coordinator 配置：零上下文 worker 编排

Coordinator Mode 藏在编译时功能标志后面，通过环境变量激活：

CLAUDE_CODE_COORDINATOR_MODE=1 claude

写进 settings.json：

{ "env": { "CLAUDE_CODE_COORDINATOR_MODE": "1" }, "coordinator": { "maxWorkers": 6, "workerTools": ["Read", "Write", "Edit", "Bash", "Grep"], "notificationFormat": "xml" } }

Coordinator 模式下协调者的工具集被严格限制：只有 Agent（生成 worker）、SendMessage（向现有 worker 发后续消息）、TaskStop（终止 worker）、SyntheticOutput（合成输出）、subscribe_pr_activity/unsubscribe_pr_activity（GitHub PR 事件订阅）。注意缺失了什么——BashTool、FileReadTool、FileWriteTool、GrepTool 全都没有，协调者把所有实际工作委托给 workers。

核心原则：工作 Agent 无法看到协调者的对话，每个 worker 都以零上下文启动。协调者必须编写自包含提示词，包含文件路径、行号、错误信息、什么算"完成"。这不是约定，是架构层面的强制隔离。

Worker 输出通过 XML<task-notification>在 user-role 消息中回传。四阶段工作流是 Research（多 worker 并发调研）→ Synthesis（协调者综合成实现规格）→ Implementation（派实现者，多个实现者不能同时编辑同一文件）→ Verification（派验证者跑测试、查类型、质疑实现）。

4. 验证请求：跑通 Fork 分支、Swarm 并行、Coordinator 调度

配置写完必须验证，否则你不知道子代理是真跑起来了还是静默失败。这一节给三个可复现的验证动作。

4.1 验证 Fork 分支

Fork 的验证点是"共享缓存 + 独立返回"。在 Claude Code 里发一条会触发并行探索的指令：

帮我同时调研 src/auth 和 src/payment 两个模块的错误处理逻辑，分别列出所有 try-catch 块的位置

观察输出：主 Agent 应该调用 AgentTool 两次（或一次带多个 Fork），每个 Fork 返回独立结果。验证缓存命中的方法是看响应延迟——第二个 Fork 的启动延迟应明显低于第一个，因为共享了 Prompt Cache 前缀。

命令行侧可以用/tasks查看后台任务列表。如果 Fork 设了run_in_background: true，你应该看到local_agent类型的任务在跑。任务类型有七种：local_bash、local_agent、remote_agent、in_process_teammate、local_workflow、monitor_mcp、dream，每种有单字符 ID 前缀用于视觉识别。

4.2 验证 Swarm 并行

Swarm 验证点是"队友互发消息 + 共享任务列表"。先确认实验开关生效：

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

输出1才算开启。然后创建团队并派两个队友：

创建一个团队，派两个队友分别检查前端和后端的类型定义是否一致，让他们直接互相沟通确认

如果 backend 是 tmux 分屏，你应该看到新窗格弹出，每个队友一个窗格，可以点击窗格直接交互。如果是 in-process，队友跑在同一进程里，通过 leader queue 同步。验证消息传递：让一个队友用 SendMessage 给另一个队友发消息，观察对方是否收到并响应。记住文本输出别人看不到，必须走 SendMessage 工具。

任务依赖验证：创建一个任务 B 依赖任务 A，确认 B 在 A 完成前无法被认领，A 完成后 B 自动解除阻止。

4.3 验证 Coordinator 调度

Coordinator 验证点是"零上下文 worker + XML 回传"。启动：

CLAUDE_CODE_COORDINATOR_MODE=1 claude

发一条需要多阶段的任务：

调研这个项目的数据库层，然后实现一个带重试的连接池，最后跑测试验证

观察协调者行为：它应该先派多个 Research worker 并发调研（各自聚焦数据模型、API 层、测试套件），然后综合成实现规格，再派 Implementation worker 写代码，最后派 Verification worker 跑测试。协调者自己不调用 Bash/Read/Write/Grep——如果你看到协调者直接读文件，说明模式没生效。

Worker 输出通过 XML<task-notification>回传。你可以在日志里搜这个标签确认。信息漏斗是这套模式的核心：用户只跟协调者对话，协调者把几千 token 的 worker 输出压缩成人能理解的摘要。

三个验证都过了，说明你的统一 Key 接入和子代理配置都正确。如果某个模式没跑起来，进下一节排查。

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

子代理系统的报错往往跨越多层——可能是 Key 问题、可能是配置字段名不对、可能是模式互斥。这一节对照真实报错给排查路径。

5.1 401 Unauthorized

最常见。报错形如：

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}

排查顺序：先确认ANTHROPIC_AUTH_TOKEN或x-api-key头带的是控制台生成的sk-串，不是别的。然后确认 Base URL 是https://taotoken.net/api，不带末尾斜杠、不带 UTM。再确认环境变量真的生效了——echo $ANTHROPIC_AUTH_TOKEN看输出。如果用了项目级 settings.json，注意环境变量优先级高于配置文件，两边都设了且值不同会以环境变量为准。

还有一种隐蔽情况：Key 复制时带了首尾空格或换行。用echo -n "$TAOTOKEN_API_KEY" | wc -c数一下长度，和预期对比。

5.2 local proxy failed

报错形如：

Error: local proxy failed to connect: ECONNREFUSED 127.0.0.1:xxxx

这通常出现在客户端配置了本地代理端口但代理没起来。检查你的客户端配置里有没有HTTP_PROXY/HTTPS_PROXY指向本地端口。如果有，要么启动对应服务，要么清掉这两个环境变量让请求直连。Claude Code 子代理在 in-process 模式下共享主进程的网络配置，主进程代理不通，所有子代理都会失败。

5.3 reading choices 报错

报错形如：

TypeError: Cannot read properties of undefined (reading 'choices')

这是响应格式不匹配。choices是 OpenAI 兼容格式的字段，如果你用的是 Anthropic 原生格式的客户端却收到了 OpenAI 格式响应（或反过来），就会解析失败。检查你的客户端走的是/v1/messages（Anthropic 格式）还是/v1/chat/completions（OpenAI 格式）。TaoToken 的 Base URL 是https://taotoken.net/api，具体路径按客户端要求拼接。Codex 系客户端走 OpenAI 格式，Claude Code 走 Anthropic 格式，别混。

5.4 OAuth 相关报错

报错形如：

OAuth token expired or invalid

如果你用的是 API Key 模式，不应该出现 OAuth 报错。出现说明客户端还在尝试 OAuth 流程。检查配置里有没有残留的 OAuth 凭证文件（如~/.claude/credentials.json里的旧 token），清掉后强制走 API Key。Claude Code 的认证优先级是 API Key > OAuth，但如果 API Key 没设对，它会回落到 OAuth 然后失败。

5.5 模式互斥导致的静默失败

Coordinator 和 Fork 互斥。如果你同时设了CLAUDE_CODE_COORDINATOR_MODE=1和 Fork 相关配置，Fork 会被自动禁用，表现为"Fork 不生效但不报错"。排查时先确认当前模式：echo $CLAUDE_CODE_COORDINATOR_MODE，如果是1，Fork 配置就是无效的。

Swarm 的CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS没设或设成非1值时，创建团队会静默失败或报"agent teams not enabled"。先确认开关。

5.6 三件套自查清单

任何认证/路由类报错，先过一遍三件套：Base URL 是不是https://taotoken.net/api；Key 是不是控制台生成的sk-串且无空格；Model ID 是不是客户端支持的模型名。这三样对了，90% 的报错会消失。剩下 10% 看模式互斥和代理配置。

如果排查完还是不通，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各客户端的完整配置示例。API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以重新生成 Key 排除 Key 本身的问题。

6. 按场景选模式：从轻量分身到项目编排

三种模式不是替代关系，是不同形状工作的不同工具。选错了要么浪费 token，要么根本跑不动。

Fork 适合快速并行探索和微任务。成本极低是因为共享 Prompt Cache，启动多个 Fork 的开销远低于启动多个独立子 Agent。典型场景：同时搜索三个不同模块的代码、并行读取多个文件做初步分析、快速验证多个假设。限制是上下文继承父对话，可能受无关信息干扰，且 Fork 之间无横向通信。记住不要在 Fork 上换模型，换了就复用不了缓存。

Swarm 适合需要讨论和协作的复杂工作。队友有独立 context window，可以直接互发消息，共享任务列表支持依赖管理。典型场景：多个队友同时调查问题不同方面然后互相质疑发现、新模块各占一块互不干扰、竞争假设调试并行测试不同理论、跨前端后端测试的协调改动。代价是每个队友是独立 Claude 实例，token 消耗随活跃队友数增加，且不共享 Prompt Cache。

Coordinator 适合需要全局视野、多阶段流水线的大型任务。协调者自己不执行工具，只拆任务、派活、综合结果。典型场景：研究→综合→实现→验证的复杂工程任务。worker 零上下文启动，协调者必须写自包含提示词。这是最彻底的自动化编排，也是最重的模式。

一个实用的选择流程：任务能在一次对话里说清且只需要结果 → Fork；任务需要多个角色讨论、有共享状态 → Swarm；任务有明确阶段划分、需要协调者做信息漏斗 → Coordinator。

长期跑编码和 Agent 任务的话，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，适合把统一 Key 接入后的多模型调用集中管理。Claude Code 专项接入参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有 Anthropic 格式的完整配置。

最后给一个我踩过的坑：Swarm 的 tmux 分屏模式下，如果你在非 tmux 环境里设了backend: "tmux"，队友窗格不会弹出，任务会卡住。用backend: "auto"让它自动检测，或者显式设in-process。这个坑不报错，只是没反应，排查起来很费时间。