OpenClaw 自动化与定时任务实战指南

任务清单需放置在根目录的 HEARTBEAT.md 文件中。这里建议保持清单简洁，明确条件触发规则，并包含抑制逻辑。

# Heartbeat Checklist
每次心跳时按顺序检查以下项目：

## 优先级检查
- [ ] 检查邮箱中的紧急邮件
- [ ] 查看未来 2 小时内的日历事件
- [ ] 检查是否有待处理的提醒事项

## 抑制规则
- 深夜时段（23:00-08:00）不发送消息，除非紧急
- 如果上次检查无新内容，跳过本次报告

CLI 控制

可以通过命令行直接干预心跳行为：

# 查看上次心跳状态
openclaw system heartbeat last

# 立即触发心跳
openclaw system heartbeat run

# 发送系统事件唤醒
openclaw system event --mode now --text "检查电池状态"

Cron 定时任务配置

核心机制

Cron 是 OpenClaw 的精确定时任务系统，独立于主会话运行。它支持持久化存储，重启后任务依然存在，并提供主会话和隔离两种执行模式。

模式对比：

• 主会话模式：共享上下文，适合需要上下文的提醒。
• 隔离模式：全新会话，适合独立报告或批量任务，可指定不同模型。

任务创建与管理

1. 创建任务

一次性任务（at）：

openclaw cron add \
--name "会议提醒" \
--at "2026-02-01T09:00:00Z" \
--session main \
--system-event "10 分钟后开始站会" \
--wake now

周期性任务（cron）：

openclaw cron add \
--name "每日早间简报" \
--cron "0 7 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "生成今日简报：天气、日历、邮件摘要" \
--model opus \
--announce \
--channel whatsapp \
--to "+8613800138000"

2. 常用表达式

3. 任务管理

# 列出所有任务
openclaw cron list

# 查看执行历史
openclaw cron runs --id <jobId> --limit 50

# 手动执行
openclaw cron run <jobId>

# 删除任务
openclaw cron remove <jobId>

错误处理

周期性任务失败后会自动重试，间隔逐渐拉长（30 秒 → 1 分钟 → 5 分钟...）。一次性任务失败则会被禁用。查看日志时可过滤关键字：

openclaw logs --follow | grep cron

Hooks 事件钩子

事件驱动扩展

Hooks 允许在特定事件发生时执行自定义逻辑。OpenClaw 内置了 session-memory、command-logger 等钩子，也支持用户自定义。

常见事件类型：

• command:new / command:reset：用户指令触发
• gateway:startup：网关启动时
• message:received：收到消息时

自定义 Hook 开发

创建一个 Hook 需要两个文件：HOOK.md（元数据）和 handler.ts（处理逻辑）。

handler.ts 示例：

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") return;
  console.log(`[my-hook] /new 命令触发`);
  try {
    await doSomething(event.context);
    event.messages.push("✨ 自定义钩子已执行！");
  } catch (err) {
    console.error("[my-hook] 执行失败:", err);
  }
};
export default handler;

启用与管理

# 列出所有 Hooks
openclaw hooks list

# 启用/禁用
openclaw hooks enable session-memory
openclaw hooks disable command-logger

Webhook 外部触发

集成外部系统

Webhook 提供了 HTTP 接口，让外部系统能触发 Agent 执行任务。适用于邮件推送、GitHub 事件回调等场景。

端点调用

唤醒主会话：

curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer your-secure-token' \
-H 'Content-Type: application/json' \
-d '{ "text": "收到新邮件，请检查收件箱", "mode": "now" }'

运行独立 Agent：

curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer your-secure-token' \
-H 'Content-Type: application/json' \
-d '{ "message": "总结收件箱中的重要邮件", "deliver": true, "channel": "whatsapp" }'

安全建议： 务必设置专用 Token，限制 allowedAgentIds，并将端点绑定在可信网络。

实战案例

1. 每日早间简报

每天早上 7:00 生成天气、日历、邮件摘要。使用 Cron 隔离模式，指定输出渠道。

2. 项目健康监控

每小时检查 Git 变更、构建状态。利用 Heartbeat + 条件触发，仅异常时报警。

3. 会话记忆持久化

启用 session-memory Hook，每次 /new 命令自动保存上下文摘要到本地。

故障排查

常见问题诊断

Cron 任务不执行：

1. 确认 cron.enabled 为 true。
2. 检查 Gateway 是否运行。
3. 验证时区配置是否正确。

Heartbeat 未触发：

1. 检查 activeHours 是否在当前时间段内。
2. 查看 HEARTBEAT.md 是否有 actionable 内容。
3. 确认主会话是否繁忙（requests-in-flight）。

日志分析：

openclaw logs --follow | grep -E "(cron|heartbeat|error)"

通过合理组合上述机制，你可以构建出强大的自动化工作流，让 OpenClaw 真正成为得力的智能助手。