定时任务 (Cron) - Gateway 内置调度器

Gateway（网关）内置了一个轻量级的 Cron Scheduler（定时调度器），能够在指定时间自动唤醒 Agent（智能体）执行预设任务。所有任务持久化存储，即使 Gateway 重启也不会丢失。

基本概念

Cron 调度器的核心能力：

• 持久化存储：所有任务保存在 ~/.openclaw/cron/ 目录下，以 JSON 文件形式持久化
• 自动唤醒：到达调度时间时，Gateway 自动唤醒 Agent 执行任务
• 多种调度模式：支持一次性、固定间隔、cron 表达式三种方式
• 灵活的执行与分发：支持主会话和隔离会话两种执行模式

调度类型 (Schedule Types)

at - 一次性任务

使用 ISO 8601 时间戳指定一个精确的执行时间点，任务执行一次后自动移除。

{
  "schedule": {
    "type": "at",
    "time": "2026-03-06T09:00:00+08:00"
  }
}

every - 固定间隔

以毫秒为单位指定执行间隔，任务将周期性重复执行。

{
  "schedule": {
    "type": "every",
    "interval": 3600000
  }
}

换算参考

• 1 分钟 = 60000 ms
• 1 小时 = 3600000 ms
• 1 天 = 86400000 ms

cron - Cron 表达式

支持标准 5 字段 cron 表达式（分 时 日 月 周），也支持 6 字段表达式（秒 分 时 日 月 周）。可选搭配 IANA Timezone（IANA 时区）。

{
  "schedule": {
    "type": "cron",
    "expression": "0 7 * * *",
    "timezone": "Asia/Shanghai"
  }
}

时区注意

如果不指定 timezone，默认使用 Gateway 服务器的系统时区。强烈建议显式指定时区以避免混乱。

执行模式 (Execution Modes)

主会话模式 (Main Session)

任务触发时，将一个 System Event（系统事件）入队，在下一次 Heartbeat（心跳）时由当前主会话的 Agent 处理。

{
  "session": "main",
  "message": "请生成今日晨报"
}

隔离模式 (Isolated)

在独立的 cron: 前缀会话中启动一个全新的 Agent Turn（代理回合），与主会话互不干扰。默认使用 announce 分发方式。

{
  "session": "isolated",
  "message": "执行每小时数据同步"
}

分发选项 (Delivery Options)

选项	说明
announce	将结果推送到聊天界面（默认）
webhook	将结果 POST 到指定 URL
none	仅内部执行，不做额外输出

{
  "delivery": {
    "type": "webhook",
    "url": "https://your-server.com/callback",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  }
}

CLI 命令

添加定时任务

openclaw cron add \
  --name "每日晨报" \
  --cron "0 7 * * *" \
  --timezone "Asia/Shanghai" \
  --session isolated \
  --message "请生成今日晨报，包含昨日任务进度和今日待办"

查看任务列表

openclaw cron list

输出示例：

ID          NAME        SCHEDULE        NEXT RUN             STATUS
a1b2c3d4    每日晨报     0 7 * * *       2026-03-06 07:00     enabled
e5f6g7h8    数据同步     every 3600000   2026-03-05 15:00     enabled

手动运行任务

openclaw cron run --id a1b2c3d4

编辑任务

openclaw cron edit --id a1b2c3d4 --message "生成今日晨报，额外包含销售数据汇总"

查看运行历史

openclaw cron runs --id a1b2c3d4

配置对象 (Configuration)

在 openclaw.json 中配置 Cron 调度器的全局行为：

{
  "cron": {
    "enabled": true,
    "store": "~/.openclaw/cron/",
    "sessionRetention": "24h",
    "runLog": {
      "maxBytes": 10485760,
      "keepLines": 5000
    },
    "retry": {
      "maxRetries": 3,
      "backoffBase": 1000,
      "backoffMax": 60000
    }
  }
}

字段	默认值	说明
enabled	true	是否启用 Cron 调度器
store	~/.openclaw/cron/	任务持久化存储路径
sessionRetention	"24h"	隔离会话日志保留时长
runLog.maxBytes	10485760	运行日志最大字节数
runLog.keepLines	5000	运行日志保留行数
retry.maxRetries	3	最大重试次数

重试策略 (Retry Policy)

OpenClaw 对不同类型的错误采取不同的重试策略：

• 瞬态错误 (Transient Errors)：如 Rate Limit（速率限制）、网络超时等，采用 Exponential Backoff（指数退避）策略自动重试
• 永久性错误 (Permanent Errors)：如配置错误、权限不足等，立即禁用任务并记录错误原因

关键区别

• 周期性任务 (Recurring Jobs)：在退避期间任务保持 enabled 状态，退避结束后恢复正常调度
• 一次性任务 (One-Shot Jobs)：最多重试 3 次，全部失败后标记为 failed

实战示例

每日晨报

openclaw cron add \
  --name "morning-report" \
  --cron "0 7 * * 1-5" \
  --timezone "Asia/Shanghai" \
  --session isolated \
  --delivery announce \
  --message "生成工作日晨报：1. 昨日任务完成情况 2. 今日重点待办 3. 阻塞事项提醒"

每小时数据同步

openclaw cron add \
  --name "hourly-sync" \
  --every 3600000 \
  --session isolated \
  --delivery webhook \
  --webhook-url "https://api.example.com/sync-callback" \
  --message "从CRM系统同步最新客户数据到本地数据库"

🇨🇳 中国用户须知

• Cron 表达式务必配合 timezone: "Asia/Shanghai" 使用，避免因服务器时区不同导致任务在错误时间触发
• 如果 Gateway 部署在海外服务器，时区差异尤为重要
• 推荐使用 crontab.guru 在线验证 cron 表达式