OpenClaw 定时任务：用法与原理

1. 在系统里扮演什么角色

OpenClaw 的「定时」不是直接在机器上跑一段 shell，而是：到点向指定 Session 投递一条用户消息 → Agent 按对话逻辑执行（读技能、调工具、写回会话）。
因此定时任务里写的是 CLI 命令（常见是 sessions_send），消息正文里用自然语言说明要做什么；可重复、需控权的内容放在 Skill（SKILL.md）里，定时消息只负责触发与交代产出形式。

---

2. 两条常见路径

方式	适用	调度精度	说明
cron/ + *.cron	固定周期、明确时间点	按 crontab	由 OpenClaw 的 cron 子系统加载、触发 sessions_send。
HEARTBEAT.md	希望助手「周期性想起」一批事项	依赖 Gateway 读心跳的间隔（可粗）	把清单写进工作区心跳文件，不是标准 crontab。

二者可并存：cron 管「几点必须跑」，心跳管「每次醒来顺带扫一眼」。

---

3. Cron 文件方式（推荐用于定点任务）

3.1 目录与命名

在 具体 Agent 的工作区 下建 cron 目录，每个任务一个 *.cron 文件（示例 agent 名为 k8sagent，按实际替换）。

cd /root/.openclaw/workspace/k8sagent
mkdir -p cron
cd cron

3.2 文件格式（原理）

每一行：标准 crontab 五段（分 时 日 月 周）** + 空格 + 要执行的命令**。

到点后 OpenClaw 执行该行命令；典型写法是用 sessions_send 带上 --sessionKey 和 --message，等效于有人在该会话里发了一句话，Agent 再去匹配 Skill / 工具链。

确保运行 cron 的环境能拿到 OPENCLAW_SESSION_KEY（登录 shell、systemd 单元或部署脚本里 export）。

3.3 示例：test.cron

# 分 时 日 月 周
# 每周一 9:00：触发一次「生产集群巡检」类对话
0 9 * * 1 sessions_send --sessionKey "${OPENCLAW_SESSION_KEY}" --message "执行所有生产集群每周巡检，输出异常汇总报告"

把具体步骤、检查项、输出模板写在某个 巡检 Skill 里，定时消息只写简短指令，例如：

0 9 * * 1 sessions_send --sessionKey "${OPENCLAW_SESSION_KEY}" --message "执行数据库备份定时巡检 skill，输出异常汇总报告"

便于：权限与提示词集中在 Skill，定时任务只维护「何时、对哪个 Session 说一句什么话」。

3.4 加载与排查

openclaw cron reload
openclaw cron list
openclaw cron logs <任务ID>

• reload：重新加载 cron/ 下配置。
• list：查看已注册任务。
• logs：按任务 ID 看执行日志，用于确认是否触发、消息是否发出、是否有 CLI 报错。

---

4. 复杂编排：Taskflow + Cron（场景补充）

若需要：多步骤、中间等待外部结果、失败重试、状态落盘，单靠一条 sessions_send 往往不够稳。
做法是：用 Taskflow（或等价编排）定义流程，再用 cron 只负责「到点启动 / 推进某一步」；细节以当前 OpenClaw 版本里 Taskflow 文档为准（此处不展开 YAML/状态字段）。

---

5. 心跳文件 HEARTBEAT.md（辅助、非 crontab）

路径示例：/root/.openclaw/workspace/HEARTBEAT.md

内容为 Markdown 清单，Gateway 会按配置间隔读取并注入上下文，让助手周期性「记得」要做的事，例如：

# 心跳任务清单（助手每隔一段时间会读）
## 每次醒来必查
- 查看重要邮件、近期会议
- 检查某类服务器连通性（指定 skill）

## 每天查 2～3 次
- 流量/账单类巡检
- 脚本目录是否有报错日志

## 仅在被问及时处理
- 查天气、刷社交媒体

间隔与 Gateway 行为可通过配置调整，例如：

openclaw configure --section gateway

（具体项名以本机 configure 交互或文档为准。）

---

6. 小结

要点	内容
原理	定时器 → 执行 CLI（多为 sessions_send）→ Session 收到消息 → Agent + Skill/工具执行。
Skill	承载「做什么、怎么做、边界在哪」；cron 只负责触发。
Cron 文件	workspace/<agent>/cron/*.cron，改后 openclaw cron reload。
与心跳区别	Cron 定点；HEARTBEAT.md 是周期性提醒清单，精度与行为跟 Gateway 轮询相关。
复杂流	Taskflow 管编排，cron 管触发时机。