1. 为什么你的多 Agent 系统只是“多个窗口在聊天”
我见过太多人演示多 Agent 系统时，本质上做的是同一件事：开好几个对话窗口，让几个模型互相“聊天”，然后说这是 Multi-Agent。这不是多 Agent，这是多个单 Agent 在凑热闹。真正的多 Agent 系统要解决的问题跟这个差远了——当一个复杂任务需要多种专业能力协同完成时，系统如何稳定、高效、可控地把这件事做完。
OpenClaw 是我近期研究比较多的开源框架，它在多 Agent 协作链路上做得比较认真。今天我不讲概念，直接从 Router 和 Planner 的协作链路切入，拆解任务分发、上下文隔离与结果聚合的底层机制，并给出一份可复制的config.toml骨架，配合 TaoToken 统一 Key/API 通道，让你本地启动后能立刻验证 Agent 路由与规划器联动是否正常。
如果你正在搭建多 Agent 应用，或者被“上下文爆炸”“角色混乱”“成本失控”这几个问题卡住，这篇内容适合你。全文会围绕 OpenClaw 的六层运行时结构展开，重点放在 Router 和 Planner 的协作细节上，最后给出可跟做的配置和排障步骤。
2. 先理解 OpenClaw 的六层运行时结构
在动手写配置之前，你需要先搞清楚 OpenClaw 把一次用户请求拆成了哪几层。自顶向下有六层，每一层的职责边界都很清晰，遵循“上层决策，下层执行，层与层之间只通过接口通信，不共享内部状态”的原则。
用户请求进入系统后，依次经过：
① Router（路由层）：意图识别，决定谁来接。 ② Planner（任务拆解层）：把大任务拆成子任务图（DAG）。 ③ Agent Scheduler（调度器）：决定谁先跑、谁并行、失败怎么办。 ④ Agent Execution（执行层）：每个 Agent 跑自己的 ReAct 循环。 ⑤ Skill / Tool（能力层）：真正调用工具、执行操作。 ⑥ Aggregator（汇总层）：合并结果，返回给用户。
类比一下：Router 是公司前台，Planner 是项目经理，Scheduler 是排班系统，Agent 是员工，Skill 是员工手里的专业工具，Aggregator 是最后的汇报会。每个角色都知道自己的边界在哪。
这里有一个很多人会忽略的设计细节：在 OpenClaw 里，Agent 不是一个函数，而是一个持久运行的 asyncio 事件循环。它不是“被调用一次，返回结果，结束”，而是一直在跑，持续监听自己的消息队列（Mailbox），有任务来了就处理，处理完了等下一个。这个区别非常关键，它是真并发的基础——多个 Agent 可以同时在不同的事件循环里处理不同的任务，互不阻塞。
2.1 Router 的 8 级优先级路由机制
Router 是所有外部请求的入口。用户的消息，不管来自 Telegram、飞书还是 API，都先经过 Router，然后才进入 Agent 体系。Router 干的事情本质上是两件：意图识别和任务路由。
它不是一个简单的关键词匹配，而是“轻量分类模型 + Prompt 规则系统”的组合。识别出“这是一个写代码的请求”，然后路由到 Code Agent；识别出“这是一个数据分析请求”，路由到 Analysis Agent。
OpenClaw 里 Router 有一套 8 级优先级路由机制，从最精确的“绑定到特定 Agent”，到最兜底的“默认 Agent 处理”，每一级都有明确的匹配规则。这保证了每一条消息都有确定性的去向，不会因为“没人接”而丢失。这个设计有个很重要的价值：可追踪性。每一条消息从进入系统的第一步开始，就有了完整的路由记录。出了问题，你知道从哪里查。
2.2 Planner 的任务拆解是一次推理，不是写配置
Planner 是整个多 Agent 系统能跑起来的起点，也是 OpenClaw 和传统工作流引擎最本质的区别。传统工作流引擎（比如 n8n、Airflow）里，任务拆解是人写配置文件来定义的。你要告诉系统“第一步做什么、第二步做什么、分支条件是什么”，这是人的工作。
OpenClaw 里，Planner 本身是一个 LLM。用户说“帮我分析这个项目，并生成一份报告”，Planner 会把这句话拆成任务图（DAG）：
① 获取项目数据 → 无前置依赖，可以立刻开始 ② 分析代码结构 → 依赖①的结果 ③ 生成结构化总结 → 依赖②的结果 ④ 排版输出报告 → 依赖③的结果
这个拆解过程本身是一次 LLM 推理，输出的是结构化的 DAG JSON，交给下一层的 Scheduler 来执行。这意味着 Planner 能处理模糊的、自然语言描述的任务，不需要用户提前把任务拆好。任务分解是 AI 的工作，不是用户的工作。
2.3 Scheduler 的 DAG 调度与容错
如果说 Planner 是项目经理，那 Scheduler 就是排班系统，负责把任务图翻译成实际的执行顺序。它有四种调度策略：串行（Chain）、并行（Parallel）、条件执行（If/Else）、递归执行（Loop）。实际工作流里用得最多的是 DAG 调度——有依赖关系，但可以部分并发。
DAG 调度的核心逻辑是：把 Planner 生成的任务图做一遍拓扑排序，所有入度为 0（没有前置依赖）的节点，同时发给对应的 Agent 执行。某个节点完成后，它的下游节点入度减一，减到 0 了就立刻触发。实现上用的是asyncio.wait(FIRST_COMPLETED)——同时监听所有在跑的任务，任意一个完成就立刻处理，解锁下游，而不是傻等所有任务都完成再继续。
容错方面，Scheduler 内置了 WatchDog 协程。如果某个 Agent 超时未回复，任务会被转入 Dead Letter Queue（死信队列），触发重试或降级策略。单个 Agent 的失败不会让整个工作流崩掉。
3. TaoToken 前置：统一 Key 与 API 通道
在配置 OpenClaw 之前，你需要先解决模型接入的问题。OpenClaw 支持多模型可插拔，但如果你每个 Agent 都单独配一套 Key，管理成本会很高，而且不同 Agent 之间的身份隔离和状态隔离也容易出问题。
我试过用 TaoToken 作为统一入口，把多个模型的调用收敛到一个 API 通道上。它的作用是让你用一个 Key 就能访问多种模型，OpenClaw 里每个 Agent 可以指定不同的模型，但底层走同一个 API 地址，省去了反复切换配置的麻烦。
具体操作上，你需要先拿到 API Key。访问https://taotoken.net/api-keys创建你的密钥，然后在 OpenClaw 的配置里把base_url指向https://taotoken.net/api。注意这里不要加任何多余路径，OpenClaw 的 LLM 客户端会自动拼接/v1/chat/completions这类端点。
如果你对模型对话效果想先做个快速验证，可以打开https://taotoken.net/models在网页端直接测试几个模型，确认哪个模型在你的任务场景下表现更稳，再写进config.toml。对于长期跑编码任务或 Agent 工作流的场景，可以考虑 Coding Plan，它在持续调用场景下更划算，具体可以看https://taotoken.net/coding-plan。
注意：OpenClaw 的 Agent 配置里，每个 Agent 可以有自己的
model字段和api_key字段。如果你想让所有 Agent 共用同一个 Key，就在全局配置里设置llm.api_key，Agent 级别不覆盖即可。如果你想让不同 Agent 走不同 Key（比如 Code Agent 用高配额 Key，Chat Agent 用低配额 Key），就在 Agent 级别单独覆盖。
4. 可复制的 config.toml 骨架
下面这份config.toml是我在本地跑通 OpenClaw 多 Agent 路由与 Planner 联动的最小骨架。你可以直接复制，把api_key换成你自己的，然后按需调整 Agent 列表。
# OpenClaw 全局配置 [llm] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-your-taotoken-key" default_model = "gpt-4o-mini" timeout = 60 max_retries = 2 # Router 配置 [router] enabled = true priority_levels = 8 default_agent = "chat_agent" intent_model = "gpt-4o-mini" log_routing = true # Planner 配置 [planner] enabled = true model = "gpt-4o" max_subtasks = 8 dag_output_format = "json" validate_dag = true # Scheduler 配置 [scheduler] strategy = "dag" max_concurrent_agents = 4 watchdog_timeout = 120 dead_letter_enabled = true retry_on_failure = 1 # 消息总线配置 [message_bus] backend = "asyncio" queue_maxsize = 1000 dead_letter_queue = true # Agent 定义 [[agents]] id = "chat_agent" role = "通用对话助手" model = "gpt-4o-mini" skills = ["knowledge_retrieval"] max_steps = 5 [[agents]] id = "code_agent" role = "代码分析与生成" model = "gpt-4o" skills = ["python_executor", "file_reader"] max_steps = 10 [[agents]] id = "analysis_agent" role = "数据分析与报告" model = "gpt-4o" skills = ["python_executor", "vector_search"] max_steps = 8 # Aggregator 配置 [aggregator] enabled = true merge_strategy = "structured" deduplicate = true这份配置里几个关键点值得说明。router.priority_levels = 8对应前面提到的 8 级优先级路由，router.log_routing = true会把每条消息的路由决策写进日志，方便你排查“为什么这条消息被路由到了错误的 Agent”。planner.validate_dag = true会在 Planner 输出 DAG 后做一次结构校验，防止 LLM 拆出循环依赖或孤立节点。
scheduler.max_concurrent_agents = 4控制同时运行的 Agent 数量上限。如果你本地机器资源有限，可以调到 2 或 3。watchdog_timeout = 120表示单个 Agent 超过 120 秒未返回结果就触发死信队列。
Agent 定义部分，每个 Agent 的skills列表决定了它能调用哪些工具。code_agent绑定了python_executor和file_reader，analysis_agent绑定了python_executor和vector_search。Skill 是独立注册的公共资源，Agent 按需取用，不需要在 Agent 代码里硬编码工具逻辑。
5. 本地启动与验证 Agent 路由、Planner 联动
配置写好后，启动 OpenClaw 并验证 Router 和 Planner 是否正常联动。下面是具体步骤。
第一步，启动服务。在 OpenClaw 项目根目录执行：
python -m openclaw.server --config ./config.toml --log-level INFO启动后你会看到类似输出：
[INFO] Router initialized with 8 priority levels [INFO] Planner loaded model=gpt-4o [INFO] Scheduler strategy=dag max_concurrent=4 [INFO] MessageBus backend=asyncio queue_maxsize=1000 [INFO] Agents registered: chat_agent, code_agent, analysis_agent [INFO] Server listening on http://127.0.0.1:8080第二步，验证 Router 路由。发一条明确指向代码任务的请求：
curl -X POST http://127.0.0.1:8080/v1/chat \ -H "Content-Type: application/json" \ -d '{"message": "帮我分析这段 Python 代码的性能瓶颈", "session_id": "test-001"}'观察日志里是否出现[ROUTER] intent=code_analysis -> agent=code_agent。如果路由到了chat_agent，说明你的 Router 意图识别规则需要调整，可以在config.toml的[router]段里增加关键词或调整优先级。
第三步，验证 Planner 拆解。发一条复合任务请求：
curl -X POST http://127.0.0.1:8080/v1/chat \ -H "Content-Type: application/json" \ -d '{"message": "分析这个项目的代码结构，扫描依赖漏洞，然后生成一份技术评估报告", "session_id": "test-002"}'观察日志里是否出现 Planner 输出的 DAG JSON。正常情况下你会看到类似：
{ "nodes": [ {"id": "n1", "task": "获取项目数据", "agent": "code_agent", "deps": []}, {"id": "n2", "task": "分析代码结构", "agent": "code_agent", "deps": ["n1"]}, {"id": "n3", "task": "扫描依赖漏洞", "agent": "analysis_agent", "deps": ["n1"]}, {"id": "n4", "task": "生成评估报告", "agent": "analysis_agent", "deps": ["n2", "n3"]} ] }第四步，验证 Scheduler 并发调度。在日志里搜索[SCHEDULER] dispatching，你应该能看到 n2 和 n3 在 n1 完成后被同时 dispatch，而不是串行等待。
第五步，验证 Aggregator 汇总。最终返回的响应应该是一份结构化报告，而不是多个 Agent 原始输出的简单拼接。如果返回内容里有明显的格式冲突或重复段落，检查[aggregator]段的merge_strategy和deduplicate配置。
6. 本篇常见错排查
6.1 Router 路由错误：消息被路由到了默认 Agent
现象：所有请求都进了chat_agent，code_agent和analysis_agent从未被触发。
排查：先看日志里[ROUTER]行的intent字段。如果intent=unknown，说明意图识别模型没有匹配到任何规则。检查config.toml里router.intent_model是否可用，以及router.priority_levels是否被正确加载。如果intent识别正确但agent字段不对，检查 Agent 的role描述是否和意图标签匹配。
6.2 Planner 输出非法 DAG：循环依赖或孤立节点
现象：Planner 返回的 DAG JSON 里，节点 A 依赖 B，B 又依赖 A，或者某个节点没有任何入边和出边。
排查：把planner.validate_dag设为true，OpenClaw 会在 DAG 进入 Scheduler 之前做一次拓扑排序校验，发现循环依赖会直接报错并拒绝执行。如果频繁出现非法 DAG，说明 Planner 的 prompt 需要调整，可以在[planner]段里增加dag_constraints描述，明确要求“不允许循环依赖，每个节点必须至少有一条入边或出边”。
6.3 Scheduler 并发不生效：任务串行执行
现象：日志里 n2 和 n3 是先后 dispatch 的，没有并发。
排查：检查scheduler.max_concurrent_agents是否大于 1。如果配置是 1，所有任务都会串行。另外检查 Agent 的max_steps是否设置过小，导致 Agent 还没跑完就被 WatchDog 中断，Scheduler 误以为任务失败而重新调度。
6.4 上下文污染：不同 Agent 的输出互相干扰
现象：code_agent的输出里出现了analysis_agent的中间结果。
排查：OpenClaw 默认实现了三层隔离（身份隔离、状态隔离、工作隔离），正常情况下不会出现上下文污染。如果出现了，检查你是否在SharedContext里写了过多共享字段。多个 Agent 同时写同一个 key 会触发乐观锁冲突，冲突后的重试逻辑如果处理不当，可能导致旧数据被写入。建议把SharedContext的写入频率降到最低，Agent 之间的信息传递尽量走消息总线。
6.5 API 调用失败：401 或 403
现象：Agent 启动后调用模型时报 401 Unauthorized 或 403 Forbidden。
排查：检查config.toml里llm.api_key是否正确，以及llm.base_url是否指向https://taotoken.net/api。如果你在 Agent 级别覆盖了api_key，检查那个 Key 是否有效。另外确认llm.provider设置为openai-compatible，OpenClaw 会按 OpenAI 兼容格式发送请求。
7. 接入与排障入口
如果你在配置 OpenClaw 多 Agent 系统时遇到 Router 路由或 Planner 联动的问题，可以先从 API Key 和接入文档入手排查。访问https://taotoken.net/api-keys检查你的 Key 状态和配额，然后对照https://taotoken.net/doc里的接入说明确认base_url和请求格式是否正确。
如果你只是想先验证某个模型在 Planner 任务拆解场景下的表现，可以直接打开https://taotoken.net/models在网页端测试，确认模型能稳定输出结构化 DAG 后再写进config.toml。对于需要长期跑编码任务或多 Agent 工作流的场景，https://taotoken.net/coding-plan提供了更适合持续调用的方案，你可以根据实际调用量选择。
最后提醒一点：OpenClaw 的 Agent 数量不是越多越好。当同时运行的 Agent 数量很多时，消息总线的调度开销会上升，SharedContext 的写冲突概率也会增加。目前在单机上跑几十个 Agent 没有问题，但要做大规模分布式部署，还需要额外的基础设施支撑。先把“1 个 Orchestrator Agent + 2 个 Worker Agent”的最小系统跑通，理解清楚消息如何流转，再往上叠。
