复杂任务指挥子代理（Complex Task Subagent）

安装

当前安装方式（推荐）

暂不支持 clawhub 安装，后续公开上架后可使用下发指令安装。

当前使用 git 安装且无需重启即可生效。

CODEBLOCK0

更新方法：

CODEBLOCK1

⚠️ 注意： 无需重启 OpenClaw Gateway，技能修改后自动生效。

快速开始

适用场景：当你需要通过子代理执行多阶段复杂任务时使用此技能。

触发条件：当用户提到以下关键词时，本技能会被自动激活：

• - "深度工作模式"
• "深夜工作模式"
• "深夜无人模式"
• "deepwork模式"
• "无人值守"
• "自动推进"
• "任务编排"
• "子代理"

核心价值：

• - 可靠的任务编排和状态管理
• 自动检测和推进已完成的阶段
• 超时和重试机制，提高鲁棒性
• 检查点驱动，支持任务恢复
• 集成 OpenClaw Heartbeat 实现无人值守
• 🌙 夜间无人模式：提前收集必要信息，在用户休息时自助决策完成任务
• 🔑 关键节点确认模式：重要决策点自动提醒用户，超时自动切换无人模式
• 💾 智能缓存管理：子代理临时缓存，正常完成自动回收，异常中断可恢复
• ⚡ 深度工作模式：完全无人值守的自动化任务执行框架

Cron 任务调用方法参考

想让定时任务发送消息到聊天窗口，必须先获取目标 ID（可以从终端获取）。

基本参数说明

参数	说明	必需
INLINECODE0	任务名称	✅
INLINECODE1

Cron 表达式（标准 5 字段格式） | ✅ | | --session | 会话类型（isolated） | ✅ | | --message | 要发送的消息内容或任务描述 | ✅ | | --agent | 指定子代理（可选，默认使用主 agent） | ⚠️ | | --tz | 时区（推荐：Asia/Shanghai） | ⚠️ | | --announce | 开启消息投递 | ✅ | | --channel | 指定渠道 | ✅ | | --to | 指定目标（用户/群组/话题 ID） | ✅ | | --best-effort-deliver | 失败不影响任务（推荐） | ⚠️ |

Cron 表达式周期规则

重要说明：

1. 1. 不支持相对时间：❌ "now + 10m"、"in 5 minutes" 等
2. 标准格式要求：✅ 必须是 5 个空格分隔的字段：INLINECODE12
3. 周期性执行：❌ 不支持一次性执行，只能周期性执行
4. 时区设置：⚠️ 默认使用 UTC，建议添加 --tz "Asia/Shanghai" 使用北京时间

Cron 表达式示例

CODEBLOCK2

获取目标 ID 的方法

从终端获取：

1. 1. 当前会话信息：查看终端输出的 inboundmeta，找到 chatid
2. 飞书群组 ID：从飞书群 URL 中提取
3. 用户 ID：从飞书设置中查看

示例：
CODEBLOCK3

完整示例（单行指令）

重要：所有指令必须在一行完成，换行符会导致解析错误。

CODEBLOCK4

重要提示

1. 1. 单行指令：❌ 多行会导致解析错误，✅ 必须在一行完成
2. 标准 cron 表达式：❌ 不支持相对时间，✅ 必须是 5 字段格式
3. 时区设置：⚠️ 默认 UTC，建议添加 --tz "Asia/Shanghai" 使用北京时间
4. Message 参数：✅ 可以填写任务要求，会由对应的代理收到并作出响应再返回给用户
5. Agent 参数：⚠️ 如果任务复杂，可以指定子代理 --agent "agentid"，否则使用默认 agent 的上下文
6. 隔离会话：使用 --session isolated 避免影响主会话
7. 最佳投递：添加 --best-effort-deliver 失败不影响任务执行

Message 参数的工作原理

经过测试验证：

• - ✅ --message 参数可以填写任务要求
• ✅ 任务会由对应的代理收到并作出响应
• ✅ 响应会返回给用户（通过指定的 channel 和 to）
• ✅ 可以指定 --agent 使用特定子代理，否则使用默认 agent 的上下文

示例：
CODEBLOCK5

Cron 任务管理命令

CODEBLOCK6

重要说明：

• - ❌ openclaw cron remove "任务名称" 不起作用
• ✅ 必须使用 openclaw cron remove <cron_id> 才能有效移除
• ✅ 通过 openclaw cron list 查询任务名称和 cron id 的对应关系

Cron 测试指令

快速测试 cron 功能：

CODEBLOCK7

注意：默认 cron 功能是正常的，除非出错才需要测试。

关于 Pairing 限制

OpenClaw 内置 cron tool 创建的任务（不是外部 CLI）：不存在设备配对问题。

如果使用外部 CLI 创建 cron 任务，可能会遇到 pairing 限制。解决方法：

编辑 ~/.openclaw/devices/pending.json，配置自动批准：

CODEBLOCK8

恢复原有配置的救命指令：
CODEBLOCK9

Heartbeat 配置方法参考

何时使用 Heartbeat 而不是 Cron：

1. 1. 需要动态查询：如天气、实时数据、计算任务
2. 需要复杂逻辑：如条件判断、多步骤任务
3. 需要智能响应：如根据结果决定后续操作
4. 需要节省上下文：避免主 agent 处理大量定时任务

Cron vs Heartbeat 对比

特性	Cron	Heartbeat
动态查询	❌ 只能发送固定消息或任务描述	✅ 可以执行复杂查询和计算
条件判断

❌ 无条件执行 | ✅ 可以根据结果决定操作 | | 执行频率 | ⚠️ 最小 1 分钟 | ✅ 可以自定义 | | 上下文消耗 | ⚠️ 使用主 agent 上下文 | ✅ 可以使用子代理，节省主 agent 上下文 | | 复杂性 | ✅ 简单固定任务 | ⚠️ 需要配置 |

为子代理配置 Heartbeat

为什么使用子代理：

• - ✅ 节省主 agent 上下文
• ✅ 隔离不同任务的逻辑
• ✅ 避免主 agent 被定时任务干扰

配置方法 1：使用 jq（推荐）

CODEBLOCK10

恢复原有配置的救命指令：
CODEBLOCK11

配置方法 2：使用热加载配置

CODEBLOCK12

Heartbeat Prompt 示例

简单查询：
CODEBLOCK13

复杂逻辑：
CODEBLOCK14

多任务检查：
CODEBLOCK15

Heartbeat 配置参数说明

参数	说明	示例
INLINECODE24	执行频率	INLINECODE25（5分钟）、"1h"（1小时）、"30m"（30分钟）
INLINECODE28

执行提示 | 要执行的任务描述 | | target | 目标（可选） | "last"（默认，最后一个会话） |

Heartbeat 频率选择建议

频率	适用场景	Token 消耗	推荐度
5 分钟	高优先级任务、实时监控	高	⭐⭐⭐
10 分钟

一般任务（推荐） | 中 | ⭐⭐⭐⭐⭐ | | 30 分钟 | 低优先级任务 | 低 | ⭐⭐⭐⭐ | | 1 小时 | 后台检查 | 很低 | ⭐⭐⭐ |

建议：

• - ✅ 高频任务（如实时天气、监控）：使用子代理 + heartbeat
• ✅ 低频任务（如每日提醒）：使用 cron
• ❌ 避免主 agent 处理大量定时任务

完整示例：为天气查询配置子代理 Heartbeat

CODEBLOCK16

Heartbeat 注意事项

1. 1. Token 消耗：每执行一次都会消耗 token，建议根据任务重要性选择合适的频率
2. 错误处理：如果 heartbeat 执行出错，会在下次心跳时重试
3. 权限问题：子代理需要相应的权限才能执行任务（如发送消息、查询 API）
4. 上下文隔离：子代理的 heartbeat 只影响该子代理，不会影响主 agent

我来帮你配置？

如果以上配置看起来比较复杂，我可以帮你完成配置。

授权流程：

1. 1. 询问你的同意：你是否授权我来执行配置？
2. 备份配置：我会自动备份你的配置文件
3. 生成救命指令：生成一键恢复原有配置的指令
4. 执行配置：帮你完成配置并重启 Gateway
5. 验证结果：确认配置是否成功

示例：

CODEBLOCK17

注意：

• - 所有配置操作都会先备份，确保可以恢复
• 我会生成救命指令，你可以随时恢复原有配置
• 手机端使用 pkill -f openclaw-gateway && sleep 2 && openclaw gateway --verbose 重启
• 正常系统使用 openclaw gateway restart 重启

架构概览

CODEBLOCK18

核心原则

1. 单一事实来源（SSOT）

所有状态变更应该更新到一个中心化的文件：task-progress.json。

为什么重要：

• - 避免状态不一致
• 简化调试和恢复
• 确保可追溯性

2. 检查点驱动

子代理完成任务后必须写入检查点文件，主会话基于检查点推进。

为什么重要：

• - 可靠性：同步写入，不会丢失
• 可恢复：任务中断后可以继续
• 可验证：可以检查任务完整性

3. 主会话主导

主会话应该掌握控制权，定期检查并推进任务。

为什么重要：

• - 逻辑清晰，易于维护
• 可以实现自动化
• 避免分布式协调的复杂性

4. 超时和重试

每个阶段都应该有超时机制和重试策略。

为什么重要：

• - 提高系统鲁棒性
• 可以自动恢复临时性故障
• 避免长时间卡死

5. 渐进式披露

使用 OpenClaw Heartbeat 实现无人值守的定期检查。

为什么重要：

• - 不依赖系统权限（如 cron）
• 与 OpenClaw 生态无缝集成
• 内置重试机制

6. 夜间无人模式

在任务开始前收集所有必要信息，在用户休息期间自助决策完成任务。

为什么重要：

• - 充分利用夜间时间
• 避免打扰用户休息
• 提高整体效率

7. 关键节点确认模式

在关键决策点自动提醒用户，超时后自动切换到无人模式。

为什么重要：

• - 平衡控制权和自动化
• 重要决策有人类参与
• 确保关键操作的安全性

8. 智能缓存管理

子代理工作期间使用临时缓存，正常完成自动回收，异常中断可恢复。

为什么重要：

• - 避免重复工作
• 支持任务恢复
• 提高容错性

9. 深度工作模式

完全无人值守的自动化任务执行，包括进度监控、自动推进、异常恢复。

为什么重要：

• - 最大化自动化程度
• 减少人为干预
• 实现真正的无人值守

任务结构

单一状态文件：task-progress.json

CODEBLOCK19

字段说明

字段	说明	必需
INLINECODE34	任务唯一标识	✅
INLINECODE35

任务名称 | ✅ | | status | 状态：in_progress/completed/failed | ✅ | | currentPhase | 当前阶段编号 | ✅ | | completedPhases | 已完成阶段数 | ✅ | | totalPhases | 总阶段数 | ✅ | | lastUpdated | 最后更新时间 | ✅ | | checkpointsDir | 检查点目录路径 | ✅ | | cacheDir | 子代理缓存目录路径 | ⚠️ | | executionMode | 执行模式：unattended/confirmation | ✅ | | userPreferences | 用户偏好设置 | ⚠️ | | notification | 通知状态追踪 | ⚠️ | | phases | 各阶段详细配置 | ✅ |

UserPreferences 字段说明

字段	说明	默认值
INLINECODE47	默认操作：ask/auto/ask-critical	ask
INLINECODE48

是否自动降级到无人模式 | true | | fallbackTimeout | 降级超时时间（毫秒） | 7200000 (2小时) | | nightModeEnabled | 是否启用夜间模式 | false | | nightModeStart | 夜间模式开始时间 | 22:00 | | nightModeEnd | 夜间模式结束时间 | 08:00 |

Notification 字段说明

字段	说明
INLINECODE53	最后一次提醒时间
INLINECODE54

已发送提醒次数 | | remindersSent | 已发送提醒的列表 |

Phase 字段说明

字段	说明	必需
INLINECODE56	阶段名称	✅
INLINECODE57

状态：pending/starting/running/completed/failed | ✅ | | startedAt | 开始时间（running 状态） | ⚠️ | | completedAt | 完成时间（completed 状态） | ⚠️ | | subagent | 子代理标签（用于 sessions_spawn） | ⚠️ | | timeout | 超时时间（毫秒） | ⚠️ | | maxRetries | 最大重试次数 | ⚠️ | | retries | 当前重试次数 | ⚠️ | | checkpoint | 检查点文件名 | ⚠️ | | output | 输出文件路径 | ⚠️ | | cacheFile | 子代理缓存文件名 | ⚠️ | | requiresConfirmation | 是否需要用户确认 | ⚠️ | | critical | 是否为关键操作 | ⚠️ | | confirmationTimeout | 确认超时时间（毫秒） | ⚠️ | | requiresGatewayRestart | 是否需要重启 Gateway | ⚠️ |

工作流程

阶段 0：模式选择（新增）

1. 1. 选择执行模式

夜间无人模式：
- 提前收集所有必要信息
- 设置 executionMode: "unattended"
- 用户休息期间自助决策

关键节点确认模式：
- 设置 executionMode: "confirmation"
- 关键操作需要用户确认
- 超时自动降级到无人模式

1. 2. 收集必要信息（无人模式）

CODEBLOCK20

1. 3. 配置用户偏好

编辑 task-progress.json 中的 userPreferences：

CODEBLOCK21

阶段 1：任务初始化

1. 1. 创建 task-progress.json

- 定义所有阶段和配置 - 设置初始状态为 "in_progress" - 所有阶段状态为 "pending" - 设置执行模式和用户偏好

1. 2. 创建 checkpoints 目录

CODEBLOCK22

1. 3. 创建 cache 目录（新增）

CODEBLOCK23

1. 4. 配置 OpenClaw Heartbeat

- 编辑 HEARTBEAT.md（见参考文档） - 调整心跳频率（推荐 10 分钟）

阶段 2：执行任务

1. 1. 启动子代理

CODEBLOCK24

1. 2. 子代理缓存管理（新增）

在子代理任务描述中明确要求使用缓存：

CODEBLOCK25

缓存文件示例：
CODEBLOCK26

1. 3. 关键节点确认（新增）

在需要用户确认的阶段：

CODEBLOCK27

提醒机制：
CODEBLOCK28

1. 4. 子代理执行任务

- 子代理完成任务后写入检查点文件 - 检查点文件包含任务结果和元数据 - 正常完成后标记缓存可回收

1. 5. 主会话检测到检查点

- Heartbeat 定期检查 checkpoints 目录 - 发现新检查点 → 验证完整性 - 更新 task-progress.json

1. 6. 自动推进下一阶段

- 检查下一阶段依赖条件 - 如果需要确认且未收到回复，进入等待状态 - 如果满足条件，启动下一阶段子代理

1. 7. 缓存回收（新增）

在子代理正常完成后：
CODEBLOCK29

在子代理异常中断后恢复：
CODEBLOCK30

阶段 3：超时和重试

1. 1. 超时检测

CODEBLOCK31

1. 2. 重新启动子代理

- 使用相同的 label 和任务描述 - 增加重试计数器

阶段 4：任务完成

1. 1. 所有阶段完成

- 检查所有阶段状态为 "completed" - 更新任务状态为 "completed"

1. 2. 同步到 Gitee

CODEBLOCK32

1. 3. 记录日志

CODEBLOCK33

检查点格式

检查点文件结构

CODEBLOCK34

写入检查点

在子代理中：
CODEBLOCK35

OpenClaw Heartbeat 集成

配置 HEARTBEAT.md

将以下内容添加到 HEARTBEAT.md（或创建独立的 HEARTBEAT-TASK.md）：

CODEBLOCK36

配置 openclaw.json

CODEBLOCK37

心跳频率选择

频率	适用场景	说明
5 分钟	高优先级任务	快速响应，但消耗更多 token
10 分钟

一般任务（推荐） | 平衡响应和成本 | | 30 分钟 | 低优先级任务 | 节省 token，响应较慢 | | 1 小时 | 后台任务 | 最小化 token 消耗 |

子代理最佳实践

子代理任务设计

好的任务描述：

• - ✅ "审核 /root/.openclaw/workspace/guide.md 文件，对比官方文档，记录所有虚构内容和不准确信息，输出到 /root/.openclaw/workspace/output/audit-report.md"

不好的任务描述：

• - ❌ "审核指南"
• ❌ "看看这个文件有没有问题"
• ❌ "帮我检查一下"

子代理超时设置

任务类型	超时时间	说明
文本审核/分析	30 分钟	读取、分析、输出
文档编写

1 小时 | 可能需要多次迭代 | | 代码生成 | 45 分钟 | 需要测试和调试 | | 数据处理 | 2 小时 | 取决于数据量 | | Gitee 同步 | 5 分钟 | 快速操作 |

子代理标签规范

使用描述性的标签，格式：subagent-<任务简述>

任务	标签示例
审核指南	INLINECODE79
创建文档

subagent-create-doc |
| 测试代码 | subagent-test-code |
| 同步 Gitee | subagent-sync-gitee |

常见问题和解决方案

问题 1：子代理完成后未推进下一阶段

症状：

• - 子代理显示完成
• 但 task-progress.json 状态未更新
• 下一阶段未启动

原因：

• - 子代理未写入检查点文件
• Heartbeat 未检测到检查点
• 检查点路径配置错误

解决方案：

1. 1. 检查 checkpoints 目录是否存在
2. 检查检查点文件是否有效 JSON
3. 检查 Heartbeat 配置是否正确

问题 2：子代理超时

症状：

• - 阶段状态一直是 "running"
• 超时时间已过

原因：

• - 子代理卡死
• 任务过于复杂
• 网络问题

解决方案：

1. 1. 检查子代理日志
2. 增加超时时间
3. 重试机制自动重启

问题 3：状态不一致

症状：

• - task-progress.json 和 checkpoints 不一致
• 已完成的阶段显示为 "running"

原因：

• - 手动修改了状态文件
• 多个进程同时修改

解决方案：

1. 1. 以 task-progress.json 为准（SSOT）
2. 使用检查点验证
3. 避免手动修改状态文件

问题 4：Gitee 同步失败

症状：

• - Git push 返回错误
• 任务标记为失败

原因：

• - 网络问题
• 认证问题
• 冲突

解决方案：

1. 1. 检查网络连接
2. 验证 SSH 密钥
3. 手动解决冲突后重试

完整示例

参见以下参考文档获取详细示例：

• - references/quick-start.md - 快速开始示例
• references/advanced-patterns.md - 高级模式
• references/troubleshooting.md - 故障排查

深度工作模式完整配置指南

以 xianyu-automation 项目为例，展示如何完整配置深度工作模式。

1. 项目工作区配置

确保所有相关 agent 共享同一个工作区：

CODEBLOCK38

2. 配置绘图模型（第三方 API）

方法 1：手工配置

编辑 ~/.openclaw/openclaw.json：

CODEBLOCK39

方法 2：热加载配置

CODEBLOCK40

使用 jq 修改配置

CODEBLOCK41

3. 配置多 Agent 共享工作区

在 ~/.openclaw/openclaw.json 中配置：

CODEBLOCK42

热加载配置

CODEBLOCK43

4. 配置 Skill 使用

在 agent 配置中启用需要的 skill：

CODEBLOCK44

5. 限制 Agent 调用权限

只允许咸鱼总指挥 agent 调用其他咸鱼相关 agent：

CODEBLOCK45

热加载权限配置

CODEBLOCK46

6. 飞书群聊配置

新建飞书群聊并设置机器人

1. 1. 通过飞书 API 创建群聊

CODEBLOCK47

1. 2. 添加机器人到群聊

CODEBLOCK48

1. 3. 设置机器人为管理员

CODEBLOCK49

1. 4. 配置 OpenClaw 默认机器人

编辑 ~/.openclaw/openclaw.json：

CODEBLOCK50

热加载飞书配置

CODEBLOCK51

7. 唤醒 Agent 并获取回应

方法 1：通过飞书群聊

在配置好的飞书群聊中，直接 @ 机器人：

CODEBLOCK52

方法 2：通过 OpenClaw CLI

CODEBLOCK53

方法 3：通过 API

CODEBLOCK54

8. 深度工作模式完整示例

创建任务配置文件

CODEBLOCK55

创建 HEARTBEAT-TASK.md

CODEBLOCK56

配置 Heartbeat

CODEBLOCK57

9. 完整的热加载指令序列

详细配置指令请参考：INLINECODE86

CODEBLOCK58

10. 使用 jq 修改配置的完整指令

详细配置指令请参考：INLINECODE87

CODEBLOCK59

11. 创建初始化脚本

详细脚本内容请参考：INLINECODE88

CODEBLOCK60

---

技能版本：2.0.0
最后更新：2026-03-15

更新日志

v2.0.0 (2026-03-15)

新增功能：

1. 1. 🌙 夜间无人模式

- 提前收集用户偏好和必要信息 - 在用户休息期间自助决策完成任务 - 支持预配置操作权限和降级策略

1. 2. 🔑 关键节点确认模式

- 重要决策点自动提醒用户 - 超时自动降级到无人模式 - 可配置提醒间隔和最大提醒次数

1. 3. 💾 智能缓存管理

- 子代理工作期间使用临时缓存 - 正常完成自动回收缓存 - 异常中断可从缓存恢复进度 - 支持缓存清理和统计

1. 4. ⚡ 深度工作模式

- 完全无人值守的自动化任务执行 - 集成 Heartbeat 实现自动推进 - 支持多 Agent 协作工作区 - 完整的配置指南和热加载指令

新增脚本：

• - scripts/select-execution-mode.sh - 执行模式选择脚本
• INLINECODE90 - 子代理缓存管理脚本
• INLINECODE91 - 通知提醒管理脚本

文档改进：

• - 添加了完整的深度工作模式配置指南（以 xianyu-automation 为例）
• 详细的热加载指令和 jq 配置示例
• 飞书群聊配置说明
• Agent 权限控制配置