Clawflow
A protocol for OpenClaw agents collaborating through messages and recursive task DAGs.
Mental model: Think of a consulting firm. Anyone can receive a project. If they can
do it alone, they do. If it's too big, they break it into pieces, hand each piece to a
colleague, collect the results, and synthesise. Those colleagues might do the same.
There are no fixed "managers" and "workers." Every agent speaks the same protocol.
When to Read References
- - Message formats, task file structure, status codes → INLINECODE0
- The decision loop every agent runs → INLINECODE1
- DAG decomposition, context passing, synthesis → INLINECODE2
Core Principles
- 1. One protocol, fluid roles — every agent is structurally identical. Any agent can
execute work directly
or decompose and delegate. The role emerges from the task.
- 2. OpenClaw is the backbone — agent identity comes from
openclaw.json config,
peer discovery from
openclaw agents list, and message transport from
openclaw agent --agent <id> --message "...". No custom identity or peer files.
- 3. Recursive DAGs — an agent that delegates becomes a coordinator for that sub-DAG.
Its parent doesn't know or care. DAGs nest naturally.
- 4. Workspace = working memory — each agent's OpenClaw workspace is its private
scratchpad. Task state lives in workspace files. No agent reads another's workspace.
How It Works
CODEBLOCK0
Every level looks the same. An agent at any depth follows the same loop.
Integration with OpenClaw
Agent Identity
Comes from the OpenClaw configuration. Do NOT create custom identity files.
- - Config source:
openclaw.json → agents.list[].id, INLINECODE8 - Workspace source:
IDENTITY.md in the agent's workspace root - Read with:
openclaw agents list or from injected bootstrap context
Each agent already knows who it is — its id, name, emoji, and theme are
injected into the session context on every turn via the workspace bootstrap files
(IDENTITY.md, SOUL.md, AGENTS.md).
Peer Discovery
Discover available agents from OpenClaw configuration. Do NOT maintain a separate
peers file.
CODEBLOCK1
An agent's subagents.allowAgents config controls which agents it can delegate to.
["*"] means it can reach any agent.
Sending Tasks to Peers
Use the OpenClaw CLI to send a task message to another agent:
CODEBLOCK2
For structured task dispatch with metadata, write the task message to a file and
reference it:
CODEBLOCK3
Workspace Layout for Clawflow
Each agent uses its existing OpenClaw workspace. Clawflow adds a tasks/ directory:
CODEBLOCK4
Clawflow adds two top-level directories to the workspace:
- -
mailbox/ — agent-level message log, independent of any task. Every message
the agent sends or receives is logged here.
inbox/ holds unprocessed arrivals,
outbox/ logs what was sent,
archive/ holds processed messages. This is the
durable audit trail — OpenClaw session history compacts over time, the mailbox doesn't.
- -
tasks/ — one subdirectory per task with a task.md tracking DAG state, subtask
results, and the final synthesised output.
The Agent Loop
When an agent receives a task (via openclaw agent --message):
CODEBLOCK5
Read references/agent-loop.md for the full decision logic and edge cases.
Delegation Decision
When an agent receives a task, it decides: do it myself or delegate?
Execute directly when:
- - The task is within the agent's own capabilities
- It's simple enough that decomposition adds overhead
- No relevant peer agents are configured
Decompose and delegate when:
- - The task requires capabilities the agent doesn't have
- The task has naturally parallel parts
- The task is large enough that breaking it up reduces complexity
This is a judgment call. The protocol doesn't force it — the agent decides.
DAG Dependency Resolution
When coordinating a sub-DAG, the agent tracks subtask status in task.md:
CODEBLOCK6
Called after every reply. Newly unblocked subtasks get dispatched immediately.
Error Handling (V1)
Fail-fast. No retries, no partial recovery.
| Scenario | Behaviour |
|---|
| Peer fails a subtask | Agent marks its own task failed, replies with error to parent |
| Duplicate message |
Idempotency check — skip if task already in-progress or done |
| Agent crashes | Task file in workspace preserves state; restart resumes from task.md |
Errors propagate upward. Future versions will add retry and partial recovery.
Implementation Checklist
- 1. Verify agent configuration —
openclaw agents list to see available agents. - Check subagent permissions — ensure
subagents.allowAgents includes target agents. - Implement the agent loop — follow
references/agent-loop.md. - Use message templates —
scripts/message.py generates structured task/reply messages. - Test a 2-level chain — agent A delegates to B, B executes and replies.
- Test fan-out — agent A delegates to B and C in parallel.
- Test recursion — agent A → B → C.
Out of Scope (V1)
- - Large result attachments (Google Drive layer)
- Task retry / partial DAG recovery
- Agent health checks
- Progress streaming
- Cross-agent workspace access (by design, forever)
技能名称: clawflow
详细描述:
Clawflow
一种协议，用于通过消息和递归任务DAG进行协作的OpenClaw智能体。
心智模型：想象一家咨询公司。任何人都可以接收项目。如果他们能独立完成，就自己做。如果项目太大，就将其分解成小块，将每块交给同事，收集结果，并进行综合。那些同事也可能做同样的事情。没有固定的“经理”和“员工”。每个智能体都使用相同的协议进行通信。
何时查阅参考资料
- - 消息格式、任务文件结构、状态码 → references/schemas.md
- 每个智能体运行的决策循环 → references/agent-loop.md
- DAG分解、上下文传递、综合 → references/coordinating.md
核心原则
- 1. 单一协议，灵活角色 — 每个智能体在结构上完全相同。任何智能体都可以直接执行工作，或者进行分解和委派。角色由任务决定。
- OpenClaw是核心支柱 — 智能体身份来自openclaw.json配置，对等体发现来自openclaw agents list，消息传输来自openclaw agent --agent --message ...。无需自定义身份或对等体文件。
- 递归DAG — 进行委派的智能体成为该子DAG的协调者。其父智能体不知道也不关心。DAG自然嵌套。
- 工作区 = 工作记忆 — 每个智能体的OpenClaw工作区是其私人草稿板。任务状态存在于工作区文件中。没有智能体读取另一个智能体的工作区。
工作原理
智能体A接收一个任务
→ 我能独立完成吗？
是 → 执行，回复结果
否 → 分解为子DAG
→ 通过 openclaw agent 将子任务分派给智能体B、C
→ 智能体B接收其子任务
→ 我能独立完成吗？
是 → 执行，回复给A
否 → 进一步分解，分派给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配置中发现可用的智能体。不要维护单独的对等体文件。
bash
列出所有已配置的智能体
openclaw agents list
配置定义了它们：
agents.list[].id → 智能体标识符（用于 --agent 标志）
agents.list[].workspace → 其工作区路径
agents.list[].model → 其模型
智能体的subagents.allowAgents配置控制它可以委派给哪些智能体。[*]表示它可以联系任何智能体。
向对等体发送任务
使用OpenClaw CLI向另一个智能体发送任务消息：
bash
向特定智能体发送任务
openclaw agent --agent data-extractor --message 从 sales.csv 中提取第三季度销售数据
接收智能体在其会话中获取此消息，进行处理，
响应通过相同的机制返回
对于带有元数据的结构化任务分派，将任务消息写入文件并引用它：
bash
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会话历史会随时间压缩，但邮箱不会。
- tasks/ — 每个任务一个子目录，包含一个task.md，用于跟踪DAG状态、子任务结果和最终综合输出。
智能体循环
当智能体接收到一个任务时（通过openclaw agent --message）：
- 1. 解析消息
- 它是来自父智能体的TASK吗？
→ 在 workspace/tasks/{task-id}/ 中创建 task.md
→ 决策：直接执行还是分解？
→ 直接：完成工作，回复结果
→ 分解：在 task.md 中构建子DAG，通过 openclaw agent 分派子任务
- 3. 它是来自我委派的对等体的REPLY吗？
→ 更新 task.md 中的子DAG（标记子任务完成，存储结果）
→ 分派任何新解除阻塞的子任务
→ 如果所有子任务都完成 → 综合结果，回复给父智能体
完整的决策逻辑和边界情况请阅读references/agent-loop.md。
委派决策
当智能体接收到一个任务时，它决定：自己做还是委派？
直接执行的情况：
- - 任务在智能体自身能力范围内
- 任务足够简单，分解会增加开销
- 没有配置相关的对等智能体
分解并委派的情况：
- - 任务需要智能体不具备的能力
- 任务有自然可并行的部分
- 任务足够大，分解可以降低复杂性
这是一个判断问题。协议不强制——由智能体决定。
DAG依赖解析
在协调子DAG时，智能体在task.md中跟踪子任务状态：
python
def getreadysubtasks(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）
快速失败。无重试，无部分恢复。
| 场景 | 行为 |
|---|
| 对等体子任务失败 | 智能体将其自身任务标记为失败，回复错误给父智能体 |
| 重复消息 |
幂等性检查——如果任务已在进行中或已完成，则跳过 |
| 智能体崩溃 | 工作区中的任务文件保存状态；重启从 task.md 恢复 |
错误向上传播。未来版本将添加重试和部分恢复。
实施检查清单
- 1. 验证智能体配置 — 使用openclaw agents list查看可用智能体。
- 检查子智能体权限 — 确保subagents.allowAgents包含目标智能体。
- 实现智能体循环 — 遵循references/agent-loop.md。
- 使用消息模板 — scripts/message.py生成结构化的任务/回复消息。
- 测试2级链 — 智能体A委派给B，B执行并回复。
- 测试扇出 — 智能体A并行委派给B和C。
- 测试递归 — 智能体A → B → C。
范围外（V1）
- - 大型结果附件（Google Drive层）
- 任务重试 / 部分DAG恢复
- 智能体健康检查
- 进度流式传输
- 跨智能体工作
