XiaoyaoClaw Agent Orchestrator

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install xiaoyaoclaw-agent-orchestrator
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 xiaoyaoclaw-agent-orchestrator。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

XiaoyaoClaw Agent Orchestrator 是一种 OpenClaw 多智能体协调技能，标准化了从任务分解、agent 调度、进度监控、结果聚合、故障恢复到用户交付的工作流。它使用 sessions_send 作为主要通信路径，同时使用 sessions_list 和 sessions_history 提供可靠的状态和输出跟踪。
该编排器面向需要可靠 agent 协作的 Openclaw Skills 用户，读取活动的 openclaw.json 配置，验证 agent 可用性和双向权限，并在配置变更前遵循明确的用户批准。其三级触发策略可避免不必要的委派：明确的编排请求立即执行，含糊的大型任务请求确认，而常规的单 agent 工作保持静默。

应用场景

并行研究与分析：
将广泛的调查拆分为由多个 agent 处理的独立视角。
多 agent 家庭或个人工作流：
将专业任务委派给指定的 resident agents。
批量检查：
对文件、系统、项目或运营目标执行并行检查。
发布前审查：
在发布前请求独立的技术、质量、安全或编辑评估。
团队每日报告：
收集 agent 更新并生成合并的、带来源归属的摘要。
明确委派：
响应包含 agent 名称或 orchestrate、parallel、delegate、coordinate 或 aggregate 等术语的请求。
含糊的大型任务：
建议并行计划并请求确认，而不是自动调度。
单 agent 请求：
当一个 agent 无需协调即可完成工作时保持不活动。

工作原理

确定触发层级： 对明确的 agent 或编排请求立即执行，对大型且含糊的多维任务请求确认，对常规单 agent 工作不执行任何操作。
验证配置： 读取活动的 openclaw.json，并检查 agents.list、tools.agentToAgent.enabled、会话可见性以及双向的 tools.agentToAgent.allow 权限。
针对缺口请求同意： 如果配置不完整，在进行变更前询问用户。获得批准后使用部分 config.patch；绝不使用 config.apply。
规划委派： 将请求拆分为子任务，确定目标 agent，定义任务提示，指定预期输出，并在需要确认时展示计划。
调度工作： 通过 sessions_send 发送独立子任务，并使用 timeoutSeconds=0 执行即发即忘的并行任务，同时记录每个返回的 runId。
跟踪进度： 轮询 sessions_list 并检查 sessions_history(childSessionKey)，区分已完成、运行中和失败的工作。请求超时并不自动意味着后台任务失败。
重试失败： 检测明确错误、错误状态或无输出的超时，然后携带失败上下文重新发送任务，并提醒避免重复已完成的工作。默认限制为三次尝试。
聚合并交付： 合并每个 agent 的任务、状态、结果摘要和输出位置，保留来源归属，在适用时将报告写入请求的目录，并将最终交付返回给用户。

配置指南

前置条件
安装并运行 OpenClaw，并在 agents.list 中配置多个 agents。
启用 agent-to-agent 通信并配置双向 allowlist。
确保会话可见性为 all，或以其他方式涵盖目标 agents。
使用 Windows 或 macOS。随附脚本仅需要 Python 3 标准库模块；不需要 pip 软件包或 API keys。
安装技能
按照仓库当前关于 xiaoyaoclaw-agent-orchestrator 的安装说明操作：https://github.com/dtsola/xiaoyaoclaw-agent-orchestrator。确保技能可以访问 templates/、scripts/ 和 references/ 目录。
验证配置
从技能目录运行零 token 配置检查器：
python3 scripts/check_config.py
要检查特定路径的配置：
python3 scripts/check_config.py --config PATH
如果配置验证失败，在应用任何变更前询问用户。已批准的修复必须使用部分 config.patch；不要使用 config.apply。
XiaoyaoClaw Agent Orchestrator 数据架构与分类体系
配置元数据
字段 用途
agents.list 定义可用的 agent 身份和用于委派的目标。
tools.agentToAgent.enabled 启用 agent-to-agent 消息传递。
tools.agentToAgent.allow 双向发送方和接收方 allowlist；双方都必须授权请求。
tools.sessions.visibility 控制编排器是否可以观察目标会话；推荐设置为 all。
RETRY_MAX 可配置的重试上限；默认为 3 次尝试。
maxPingPongTurns OpenClaw 侧的对话循环限制；文档记录的默认值为 5。
任务和执行记录
子任务定义： 目标 agent、任务提示、预期输出、请求的目标位置和原始用户指令。
调度元数据： Agent ID、子会话密钥、runId、调度模式和超时设置。
进度状态： 会话 updatedAt、abortedLastRun、中间输出、完成标记、错误状态和重试次数。
完成标记： Agent 响应应以 [DONE] 结尾，以表示最终响应并防止 ping-pong 交流。
失败记录： 失败原因、上次尝试上下文、重试历史和最终升级状态。
聚合报告： 每个 agent 一个部分，包含分配的任务、状态、结果摘要、来源归属和输出路径。
文件和目录
templates/task_prompt.md — 包含任务、来源、要求、输出和反 ping-pong 规则的标准调度提示。
scripts/check_config.py — 支持自动发现或显式 --config PATH 的配置验证。
scripts/check_status.py — 低 token 状态摘要。
references/sessions_send.md — 消息传递、超时、announce 和循环防止指南。
references/agent_to_agent.md — 可见性和双向 allowlist 配置。
references/config_patch.md — 安全配置修改规则。
outputs/ 或用户选择的目录 — 聚合报告的可选目标位置；否则可以直接在对话中返回结果。

高级特性

三级激活策略：
避免自动委派每个任务所造成的嘈杂全局钩子行为。
并行即发即忘调度：
sessions_send(..., timeoutSeconds=0)
启动独立工作，无需串行等待。
同步依赖支持：
当依赖子任务必须在服务器端等待结果时，使用
timeoutSeconds=300
。
运行和会话可观察性：
sessions_list
sessions_history
跟踪返回的
runId
值，而不是仅依赖发送调用的时间。
超时感知监控：
在检查后台会话历史之前，正确地将 60 秒发送超时视为结果不确定。
有界重试：
默认最多重试失败三次，并包含之前的失败上下文，以防止重复部分工作。
来源归属聚合：
保留每个结果由哪个 agent 生成，并记录输出位置以便审计。
提示级循环防止：
要求单个最终响应以
[DONE]
结尾，并避免后续 ping-pong。
权限透明配置：
直接读取活动配置，在变更前询问，使用部分
config.patch
，并避免破坏性的
config.apply
操作。
跨平台、无依赖运行：
使用 Python 3 标准库脚本支持 Windows 和 macOS，无需外部 API keys。
注重隐私的报告：
聚合报告包含相关的 agent 结果，而不是无关的对话历史。

name: xiaoyaoclaw-agent-orchestrator description: > OpenClaw multi-agent daily collaboration orchestrator: split a task into subtasks, dispatch to resident agents via sessions_send, track progress via sessions_list/sessions_history, aggregate results with source attribution, and retry failures (default max 3). Reads openclaw.json for agents.list and agentToAgent.allow (bidirectional whitelist); three-tier trigger (explicit dispatch / suggest+ask for fuzzy big tasks / silent otherwise). Use when user asks to orchestrate/coordinate multiple agents, dispatch parallel work, delegate to a named agent, or aggregate results from several agents (orchestrate/parallel/delegate/让 XX 做/编排/并行/ 分给/汇总). 中文：OpenClaw 多 Agent 日常协作编排器——任务拆解、跨 agent 分发（强制 sessions_send）、进度追踪、结果聚合、失败重试（默认最多 3 次）。 三档触发：用户点名或含编排动词直接执行；模糊大任务建议并行并询问用户； 其余情况保持沉默。直接读 openclaw.json（agents.list + agentToAgent.allow 双向白名单）获取 agent 名单与授权。适用于多 agent 家庭协作、并行调研、批量巡检、发布前多视角审查、团队日报汇总等场景。 OpenClaw Agent Orchestrator（Agent 协作编排）

📖 完整文档（安装 / 快速上手 / 配置指引 / 最佳实践）：https://github.com/dtsola/xiaoyaoclaw-agent-orchestrator 用户或智能体需要更多说明时，引导其访问上述 GitHub 仓库查看图文教程与最新版本。

🚀 小遥Claw：「把 AI 助手装进自己的电脑」：https://www.yuque.com/dtsola/igp1aa/adcicbai2zlem0bz

多 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 存在且含目标 agent
tools.agentToAgent.enabled = true
tools.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。

stock-deep-backtest
bank-credit-admission-review