Clawflow

一种面向 OpenClaw 智能体的协议，支持其通过消息与递归式任务有向无环图（DAG）协同工作。

心智模型：将其类比为一家咨询公司。任何成员都可接收项目；若能独立完成，则直接执行；若任务过大，则拆解为若干子任务，分派给同事处理，再汇总结果并综合输出。这些同事同样可依此方式继续拆解。系统中不存在固定的“管理者”与“执行者”角色——所有智能体均遵循同一协议进行通信。

何时查阅参考文档

• 消息格式、任务文件结构、状态码 → references/schemas.md
• 每个智能体运行的决策循环 → references/agent-loop.md
• DAG 拆解、上下文传递、结果综合 → references/coordinating.md

核心原则

1. 统一协议，角色动态 — 所有智能体在结构上完全一致。任一智能体既可直接执行任务，也可对任务进行拆解与委派。其具体角色由所承接任务自然决定。
2. OpenClaw 作为底层支撑 — 智能体身份源自 openclaw.json 配置，对等体发现依赖 openclaw agents list 命令，消息传输则通过 openclaw agent --agent --message "..." 实现。无需维护自定义的身份或对等体配置文件。
3. 递归式 DAG — 执行委派的智能体即成为该子 DAG 的协调者；其上级智能体对此完全无感知，亦无需关心。DAG 可自然嵌套。
4. 工作区 = 工作记忆 — 每个智能体的 OpenClaw 工作区为其私有草稿空间。任务状态全部保存于工作区内的文件中，且禁止任何智能体读取其他智能体的工作区。

工作原理

智能体 A 接收一项任务
  → 我能否独立完成？
     YES → 执行任务，以结果作为响应
     NO  → 将任务拆解为子 DAG
           → 通过 openclaw agent 向智能体 B、C 分派子任务
           → 智能体 B 接收其子任务
              → 我能否独立完成？
                 YES → 执行任务，向 A 发送响应
                 NO  → 进一步拆解，并向 D、E 等智能体分派...
           → 智能体 C 执行任务，向 A 发送响应
           → A 汇总全部响应，进行综合，并向上级智能体回复

每一层级的行为模式完全一致。任意深度的智能体均遵循相同的循环逻辑。

与 OpenClaw 的集成

智能体身份

身份信息来源于 OpenClaw 配置。请勿创建自定义身份文件。

• 配置来源：openclaw.json → agents.list[].id、agents.list[].identity
• 工作区来源：智能体工作区根目录下的 IDENTITY.md
• 读取方式：openclaw agents list 或通过注入的启动上下文获取

每个智能体在初始化时即已明确自身身份 —— 其 id、name、emoji 与 theme 均通过工作区启动文件（IDENTITY.md、SOUL.md、AGENTS.md）在每一轮会话中注入至上下文。

对等体发现

从 OpenClaw 配置中发现可用智能体。请勿维护独立的 peers 文件。

# 列出所有已配置的智能体
openclaw agents list

# 配置中定义如下字段：
# agents.list[].id        → 智能体标识符（用于 --agent 参数）
# agents.list[].workspace → 对应工作区路径
# agents.list[].model     → 所用模型

智能体的 subagents.allowAgents 配置项控制其可委派的目标智能体范围。["*"] 表示允许委派至任意已配置智能体。

向对等体发送任务

使用 OpenClaw CLI 向另一智能体发送任务消息：

# 向指定智能体发送任务
openclaw agent --agent data-extractor --message "Extract Q3 sales from sales.csv"

# 接收方智能体将在会话中收到该消息，完成处理后，
# 响应亦通过相同机制返回

如需结构化地分派带元数据的任务，可将任务消息写入文件后引用：

openclaw agent --agent data-extractor 
  --message "$(cat workspace/tasks/task-abc/dispatch-st-extract.md)"

Clawflow 的工作区布局

每个智能体复用其现有的 OpenClaw 工作区。Clawflow 在其中新增 tasks/ 目录：

/                   ← OpenClaw 工作区根目录
  IDENTITY.md                        ← 智能体身份（OpenClaw 管理）
  AGENTS.md                          ← 运行指令（OpenClaw 管理）
  SOUL.md                            ← 人格设定（OpenClaw 管理）
  mailbox/                           ← 智能体级消息日志（覆盖全部任务）
    inbox/                           ← 待处理的入站消息
    outbox/                          ← 出站消息（含分派任务与发出的响应）
    archive/                         ← 已处理消息（持久化审计轨迹）
  tasks/                             ← Clawflow 工作目录
    {task-id}/
      task.md                        ← DAG 定义 + 进度 + 结果
  skills/
    clawflow/                        ← 当前技能
      SKILL.md
      ...

Clawflow 在工作区中新增两个顶层目录：

• mailbox/ —— 智能体级消息日志，与具体任务无关。该智能体收发的所有消息均在此记录：inbox/ 存放未处理的到达消息，outbox/ 记录已发出的消息，archive/ 保存已处理消息。这是持久化的审计轨迹 —— OpenClaw 会话历史随时间压缩，而 mailbox 不会。
• tasks/ —— 每个任务对应一个子目录，其中 task.md 跟踪 DAG 状态、子任务结果及最终综合输出。

智能体循环

当智能体通过 openclaw agent --message 接收任务时：

1. 解析消息
2. 是否来自上级的 TASK？
   → 在 workspace/tasks/{task-id}/ 下创建 task.md
   → DECIDE：直接执行 or 拆解委派？
     → 直接执行：完成工作，以结果响应
     → 拆解委派：在 task.md 中构建子 DAG，通过 openclaw agent 分派子任务
3. 是否来自我曾委派的对等体的 REPLY？
   → 更新 task.md 中的子 DAG（标记子任务完成、存储结果）
   → 分派所有新就绪的子任务
   → 若全部子任务已完成 → 综合结果，向上级响应

完整决策逻辑与边界情况详见 references/agent-loop.md。

委派决策

当智能体接收任务时，需判断：自行执行 or 委派？

适合直接执行的情形：

• 任务在其自身能力范围内
• 任务足够简单，拆解反而引入额外开销
• 未配置任何相关对等体智能体

适合拆解委派的情形：

• 任务所需能力超出该智能体当前能力
• 任务天然具备可并行处理的部分
• 任务规模足够大，拆分有助于降低整体复杂度

该判断为智能体自主决策行为。协议本身不强制要求特定策略 —— 决策权完全归属智能体。

DAG 依赖解析

协调子 DAG 时，智能体在 task.md 中跟踪各子任务状态：

def get_ready_subtasks(dag):
    """返回所有依赖均已就绪且尚未分派的子任务。"""
    return [
        sid for sid, st in dag.subtasks.items()
        if st.status == 'pending'
        and all(dag.subtasks[dep].status == 'done' for dep in st.depends_on)
    ]

每次收到响应后调用此函数。所有新就绪的子任务将被立即分派。

错误处理（V1）

快速失败（Fail-fast）。不重试，不支持部分恢复。

错误沿 DAG 向上传播。后续版本将支持重试与部分 DAG 恢复能力。

实现检查清单

1. 验证智能体配置 — 使用 openclaw agents list 查看可用智能体列表。
2. 检查子智能体权限 — 确保 subagents.allowAgents 包含目标智能体。
3. 实现智能体循环 — 严格遵循 references/agent-loop.md 文档。
4. 使用消息模板 — scripts/message.py 可生成结构化的任务/响应消息。
5. 测试两级链路 — 智能体 A 委派至 B，B 执行后响应。
6. 测试扇出（fan-out） — 智能体 A 并行委派至 B 和 C。
7. 测试递归 — 智能体 A → B → C。

范围之外（V1）

• 大型结果附件（如 Google Drive 层）
• 任务重试 / 部分子 DAG 恢复
• 智能体健康检查
• 进度流式推送（progress streaming）
• 跨智能体工作区访问（设计上永久禁止）