第10章自动化与定时任务

一句话：Cron 让 Agent 按时干活，Heartbeat 让 Agent 主动巡检，Hooks 让 Agent 响应外部事件——三板斧组合起来，Agent 就不再只是被动回复了。

10.1 Cron 定时任务

Cron 让你安排 Agent 在指定时间执行任务。

通过 CLI 添加 Cron 任务

# 每天早上 8 点生成新闻摘要，发送到 Telegram
openclaw cron add \
  --name "AI News" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "搜索过去24小时的 AI 新闻，生成摘要发送给我" \
  --announce --channel telegram --to "12345678"

# 20 分钟后提醒（一次性）
openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "提醒：20分钟后有站会" \
  --wake now --delete-after-run

# 管理任务
openclaw cron list                # 列出所有任务
openclaw cron run <job-id>        # 手动执行
openclaw cron runs --id <job-id>  # 查看执行历史
openclaw cron remove <job-id>     # 删除任务

通过配置文件设置 cron 全局参数

注意：cron jobs 通过 openclaw cron add CLI 创建和管理，配置文件中的 cron 段只控制全局参数（启用/并发/保留策略），不是 job 列表。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,        // 最大并发运行数
    sessionRetention: "24h",     // 完成的隔离 session 保留时长
  },
}

CLI 创建 job 示例：

openclaw cron add \
  --name "每日摘要" \
  --cron "0 8 * * *" \
  --message "请生成今日的 AI 新闻摘要，发送到 Telegram" \
  --announce --channel telegram

三种调度方式

方式	CLI 参数	用途
Cron 表达式	`--cron "0 8 * * *"`	定时重复
固定间隔	`--every "30m"`	每隔一段时间
一次性	`--at "20m"` 或 `--at "2026-03-25T16:00:00+08:00"`	单次执行

Cron 表达式语法（标准 5 字段）：

分 时 日 月 周
*  *  *  *  *

表达式	含义
`0 8 * * *`	每天 08:00
`0 8 * * 1-5`	工作日 08:00
`/30 * * *`	每 30 分钟
`0 9,18 * * *`	每天 09:00 和 18:00
`0 0 1 * *`	每月 1 号 00:00

Main Session vs Isolated Session

模式	CLI 参数	特点
Main Session	`--session main`	在主会话中执行，有历史上下文
Isolated Session	`--session isolated`	全新会话，无历史，可指定不同模型

delivery 模式

模式	说明
`"announce"`	将结果发送到指定渠道（默认）
`"webhook"`	POST 到指定 URL
`"none"`	静默执行（仅内部运行，不发送结果）

10.2 Heartbeat 心跳机制

Heartbeat 让 Agent 在没有用户消息的情况下也能定期”醒来”，主动检查是否有需要处理的事情。

基础配置

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",              // 心跳间隔
        target: "last",            // 发到最近活跃的会话
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Shanghai",
        },
      },
    },
  },
}

工作流程

每隔 every 时间，Gateway 触发一次心跳
检查当前时间是否在 activeHours 范围内
Agent 被唤醒，检查是否有需要处理的事项
无事可报 → 返回 HEARTBEAT_OK
有事汇报 → 发送消息到 target

成本优化（重要！）

默认情况下，每次心跳加载完整上下文，token 消耗较大。高频心跳（如每 10 分钟）成本会失控。

开启 lightContext: true，心跳运行时只注入 HEARTBEAT.md，大幅减少 token 消耗：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "10m",
        target: "last",
        lightContext: true,      // 轻量上下文，仅注入 HEARTBEAT.md
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Shanghai",
        },
      },
    },
  },
}

优化效果：

配置	每次 token 消耗	适用场景
默认（`lightContext: false`）	较大（加载完整上下文）	需要完整上下文的复杂任务
`lightContext: true`	大幅降低	简单定时检查（推荐）

当 lightContext: true 时，需要在 workspace 创建 HEARTBEAT.md：

# Heartbeat Instructions

每次心跳时检查以下内容：
1. 检查 memory/ 目录下是否有待处理的提醒
2. 如果有到期的提醒，发送给用户
3. 如果一切正常，返回 HEARTBEAT_OK

10.3 Webhook & Hooks

先在配置中启用 Webhook：

{
  hooks: {
    enabled: true,
    token: "your-shared-secret",  // 必须设置
  },
}

/hooks/wake — 触发主会话

向主会话添加系统事件，Agent 会在下次心跳或立即处理：

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer your-shared-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "收到一封来自 boss@company.com 的紧急邮件",
    "mode": "now"
  }'

text：事件描述（必填）
mode："now"（立即触发）或 "next-heartbeat"（等下次心跳）

/hooks/agent — 隔离执行

在独立 session 中执行任务，不影响主会话：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H "Authorization: Bearer your-shared-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析这封邮件并生成回复草稿",
    "name": "Email",
    "agentId": "main",
    "deliver": true,
    "channel": "telegram",
    "to": "12345678",
    "timeoutSeconds": 120
  }'

安全提醒：每个请求必须包含 Token（Bearer 认证），不支持 query string 传 token。

10.4 内置 Hooks

OpenClaw 内置了几个实用的 Hook：

Hook	作用
`session-memory`	发出 `/new` 时自动保存当前会话上下文到 memory
`command-logger`	记录所有命令事件到日志文件
`boot-md`	Gateway 启动时运行 BOOT.md
`bootstrap-extra-files`	在 Agent bootstrap 时注入额外的工作区文件

Hook Pack 安装

社区提供了更多 Hook Pack：

openclaw hooks install <pack-name>

10.5 小结

机制	用途	配置位置
Cron	定时执行任务	`cron` 对象 + CLI
Heartbeat	定期主动巡检	`agents.defaults.heartbeat`
Webhook	外部事件触发	`/hooks/wake`、`/hooks/agent`
内置 Hooks	自动化辅助	随版本捆绑

成本警告：Heartbeat 不开优化的话，每次心跳消耗较大。开启 lightContext: true 可大幅降低消耗，务必注意。

下一章进入 Skills 技能生态——让 Agent 学会更多技能。

第10章 自动化与定时任务