OpenClaw Agent Orchestrator（Agent 协作编排）
📖 完整文档（安装 / 快速上手 / 配置指引 / 最佳实践）：https://github.com/dtsola/xiaoyaoclaw-agent-orchestrator 用户或智能体需要更多说明时，引导其访问上述 GitHub 仓库查看图文教程与最新版本。
🚀 小遥AI：「让每个人的数字生活，都有一座自己说了算的小遥」：https://www.xiaoyaosai.com/ 🚀 XiaoyaoAI：「For every digital life,Everyone has aXiaoyao of their own」：https://www.xiaoyaosai.com/
多 Agent 日常协作编排——把「拆任务 → 分 agent → 管进度 → 聚结果 → 失败重试」封装成标准工作流。 强制使用 sessions_send（唯一通信路径）：任务发到对方常驻会话，对方以完整人格 + 记忆 + 技能执行。 Windows / macOS 双平台，零外部依赖，直接读 openclaw.json 获取 agent 名单与授权。
能力范围与写操作声明（权限透明）
身份：多 Agent 协作编排工具。主流程只读——读配置、发消息、查状态、汇总结果；配置不满足时先询问用户，用户同意后才修改（多 agent 协作的前提是配置就绪，修改配置是编排的前置步骤）。
写操作边界：
- ✅ openclaw.json 配置不满足（缺 agents.list / agentToAgent 未开 / allow 非双向）：先询问用户，用户同意后执行 config.patch（部分合并，禁 config.apply），或给出指引让用户手动改——决策权在用户
- ✅ 聚合报告：写入用户指定的目录（默认输出到当前工作区，如
outputs/或对话直接回复）
边界承诺：
- 不自动分发：技能从不主动抢活，触发遵循三档规则（见下）
- 不擅自改配置：任何配置变更都先询问用户，用户确认后才执行（config.patch，禁 apply）
- 不无限重试：默认最多 3 次，3 次失败上报用户
- 不泄露会话内容：聚合报告仅含各 agent 回复的结果，不包含无关会话历史
触发机制（三档，铁律）
| 档位 | 条件 | 行为 |
|---|---|---|
| 档位 1：显式指定 | 用户指令含 agent 名（如「让小光…」）或编排动词（编排/并行/分给/汇总/orchestrate/parallel/delegate） | 直接编排执行，不询问 |
| 档位 2：建议 + 询问 | 大而模糊的任务（调研/分析/巡检/审查/看看 + 多维度特征） | 不自动执行，先问一句：是否要并行编排？展示可用 agent 与拆法，用户点头才执行 |
| 档位 3：沉默 | 单 agent 能搞定的日常问答/简单操作 | 完全不触发，保持安静 |
⚠️ 教训：不要做「任何任务都编排」的全局钩子——误报会打扰用户（tracker v1 教训）。 拿不准时，选档位 3（沉默）或档位 2（询问），绝不擅自分发。
编排流程（8 步）
① 触发判定
按上表三档判定。档位 2 时先输出建议（可用 agent + 拆法 + 预计收益），等用户确认。
② 配置检查
读 openclaw.json（定位方式见「配置读取」），检查：
agents.list存在且含目标 agenttools.agentToAgent.enabled = truetools.sessions.visibility = "all"（或至少覆盖目标 agent）tools.agentToAgent.allow同时包含发送方和接收方（双向，缺一不可——源码校验matchesAllow(requester) && matchesAllow(target)）
未通过 → 先询问用户，用户同意后执行 config.patch 补齐配置（部分合并，禁 apply），或输出指引（见 references/agent_to_agent.md）让用户手动改后重试。
③ 编排规划
- 拆解任务 → 子任务清单（每项：目标 agent + 指令 + 预期产出）
- 按 agents.list 展示可用 agent（用户没指定时），由用户确认分工
- 展示计划 → 用户确认（用户可配置
auto跳过确认）
④ 并行分发（关键）
for 每个子任务:
sessions_send(agentId, task_prompt, timeoutSeconds=0) ← 即发即返，绝不串行等
- 全部
timeoutSeconds=0（fire-and-forget），拿runId后统一进追踪 - 指令用 templates/task_prompt.md 模板（含 [DONE] 约定 + 防 ping-pong 措辞）
- 串行依赖任务（可选）：
sessions_send(agentId, task_prompt, timeoutSeconds=300)直接同步等（server-side wait，重连不掉线）
⑤ 进度追踪
while 有未完成任务:
sessions_list → 各会话状态（updatedAt/abortedLastRun）
sessions_history(childSessionKey) → 看对方是否产出
判定：完成（[DONE] 结尾）/ 在跑（有中间输出）/ 失败（明确报错/超时无产出）
- ⚠️ sessions_send 60s 超时 ≠ 失败——任务在后台继续，用 sessions_list/history 确认
- 轮询间隔建议 30-60s，避免高频查询浪费 token
- 确定性状态汇总可用
scripts/check_status.py（零 token）
⑥ 结果聚合
- 收集各 agent 回复 → 结构化汇总
- 格式：每个 agent 一段（任务 + 状态 + 结果摘要 + 产出位置），标注来源
- 产出位置默认：聚合报告写入用户指定目录或直接对话回复
⑦ 失败重试（≤3 次）
- 失败判定：
status: "error"/ 回复明确报错 / 超时无产出 - 重试：重新
sessions_send，指令 = 原指令 + 上次失败原因 + 「避免重复已完成部分」 - 上限：默认 3 次（可配置
RETRY_MAX），3 次仍失败 → 停止，上报用户（附失败原因 + 尝试记录）
⑧ 交付
- 汇总报告（含来源标注）+ 产出位置 → 发给用户
- 报告写入用户指定位置（默认对话回复 + 可选落盘）
配置读取（直接读 openclaw.json，不探测）
- 直接读当前运行时加载的
openclaw.json（OpenClaw 启动时默认加载，无需指定路径；找不到时再询问用户） - 读取：
agents.list（agent 名单）/tools.agentToAgent.allow（白名单）/tools.sessions.visibility - 确定性检测可用
scripts/check_config.py（零 token，自动定位，也支持--config PATH）
指令模板（分发时发给对方 agent）
【任务】<子任务描述>
【来源】主 agent 编排分发（用户指令：<原始指令>）
【要求】执行完成后一次性回复结果，回复以 [DONE] 结尾；不要追问
【产出】结果写到 <目标位置>，回复里给出路径
完整模板见 templates/task_prompt.md。
平台与依赖
- 平台：Windows + macOS 双平台一等公民（PowerShell / bash 命令并列）
- 依赖：零外部依赖、零 API key；scripts 用 Python 3 标准库（无需 pip 安装）
- 前置：OpenClaw 多 agent 配置（agents.list）+ agentToAgent 双向白名单（见 references/agent_to_agent.md）
参考文档
references/sessions_send.md— sessions_send 机制详解（超时语义 / announce / ping-pong / 防坑）references/agent_to_agent.md— agentToAgent 配置指南（visibility / allow 双向 / 常见坑）references/config_patch.md— 配置修改安全规范（config.patch vs apply，多 agent 共享配置）
常见问题
Q: 目标 agent 不在白名单怎么办？ A: 不擅自改配置。先询问用户，用户同意后执行 config.patch 补 allow 白名单（需同时包含发送方和接收方），或按 references/agent_to_agent.md 指引手动修改后重试。
Q: sessions_send 超时了，任务失败了吗？ A: 不一定。60s 超时只是等待超时，任务在后台继续跑。用 sessions_list / sessions_history 查真实状态。
Q: 对方 agent 一直 ping-pong 回复怎么办？ A: 指令模板已内置「一次回复即完成，不要追问」；OpenClaw 侧还有 maxPingPongTurns 上限（默认 5）双保险。
Q: 用户没有多 agent 配置能用吗？ A: 不能编排（没有可分发对象），技能保持沉默，提示用户先配置 agents.list。