OpenClaw内置Cron的实现原理

2026-03-04 11:15:44 西京刀客

OpenClaw 的“定时任务（内置 Cron）”本质上就是：在进程内维护一个 Cron 表达式调度器，周期性计算“下一次触发时间”，到点后把任务投递到执行器（线程池/协程/队列）里跑。

定时任务配置

OpenClaw 自带一个 Cron 调度系统，数据存储在 .openclaw/cron 目录中。

例如：路径/root/openclaw-docker/data/.openclaw/cron/jobs.json 通常由 “OpenClaw 的数据目录(data dir) + 固定子目录 .openclaw/cron/ + 固定文件名 jobs.json” 共同决定。

也就是说，真正可配置的一般只有前半段：/root/openclaw-docker/data（数据卷/工作目录），后半段多半是程序写死的相对路径。

判断这个 jobs.json 路径由哪里决定

1) 看容器是怎么起的（compose 还是 docker run）

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Command}}\t{{.Mounts}}'

2) 找到 openclaw 容器名后，导出完整启动/挂载信息

把 openclaw-docker-openclaw-gateway-1 换成你的容器名，docker inspect 里 Binds/Mounts 字段进行判断

docker inspect openclaw-docker-openclaw-gateway-1 --format 'Name={{.Name}}
Cmd={{json .Config.Cmd}}
Entrypoint={{json .Config.Entrypoint}}
Env={{json .Config.Env}}
Binds={{json .HostConfig.Binds}}
Mounts={{json .Mounts}}'

比如输出：

Binds=["/root/openclaw-docker/data/.openclaw:/home/node/.openclaw:rw", ...]
Mounts=[{"Type":"bind","Source":"/root/openclaw-docker/data/.openclaw","Destination":"/home/node/.openclaw", ...}]

这表示：
- 宿主机 /root/openclaw-docker/data/.openclaw
  被 bind mount 到
- 容器内 /home/node/.openclaw

OpenClaw 的 Cron 数据文件放在 .openclaw/cron/jobs.json 这个相对路径下，所以：

容器内路径：/home/node/.openclaw/cron/jobs.json
宿主机对应路径：/root/openclaw-docker/data/.openclaw/cron/jobs.json

另外需要注意Env的配置,如：

Env=["HTTP_PROXY=http://172.17.0.1:1080","TERM=xterm-256color","NODE_OPTIONS=--use-env-proxy","NO_PROXY=localhost,127.0.0.1,172.17.0.0/16,10.0.0.0/8","HOME=/home/node"

Env 里还有 HOME=/home/node，很多程序默认把数据放在 $HOME/.openclaw，这也进一步印证容器内会用 /home/node/.openclaw

jobs.json 配置说明

{
  "version": 1,
  "jobs": [
    {
      "id": "UUID-EXAMPLE-0001",
      "agentId": "main",
      "name": "定时执行脚本任务（示例）",
      "enabled": true,
      "createdAtMs": 1700000000000,
      "updatedAtMs": 1700003600000,
      "schedule": {
        "kind": "every",
        "everyMs": 43200000
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "执行 bash /home/node/<REDACTED_DIR>/task.sh \"<REDACTED_KEYWORD>\" 2"
      },
      "state": {
        "nextRunAtMs": 1700043200000,
        "lastRunAtMs": 1700003600000,
        "lastStatus": "ok",
        "lastDurationMs": 16204
      }
    }
  ]
}

顶层

version：文件格式版本（用于兼容/升级迁移）。
jobs：定时任务数组。

job 基本信息

id：任务唯一标识（UUID）
agentId：由哪个 agent 执行（如 main）。
name：任务展示名。
enabled：是否启用；false 表示不调度。
时间戳（毫秒）createdAtMs / updatedAtMs：创建/更新的 epoch 毫秒时间。

调度计划schedule

kind: "every"：按固定间隔触发（不是 cron 表达式）。
everyMs：间隔毫秒数；43200000 = 12 小时。

三种调度类型
类型说明示例
at 一次性定时 “30分钟后提醒我”
every 固定间隔重复 “每5分钟检查一次”
cron 标准 Cron 表达式 0 9 * * 1-5（工作日每天9点）

示例（cron 调度）

"schedule": {
  "kind": "cron",
  "expr": "55 9 3 * *",
  "tz": "Asia/Shanghai"
}

字段说明

kind: "cron"：使用 cron 表达式触发
expr: "55 9 3 * *"：cron 表达式（常见 5 段：分时日月周）
tz: "Asia/Shanghai"：按这个时区解释 cron 时间（避免容器时区/UTC 造成偏差）

会话与唤醒

sessionTarget: "isolated"：每次运行用隔离会话（避免污染主对话/上下文）。
wakeMode: "next-heartbeat"：到点后在“下一次心跳/调度 tick”执行，可能有轻微延迟。

执行模式:
Main Session：把任务当作"用户消息"注入主对话，像你手动发消息一样触发 Agent
Isolated Session：启动独立会话执行复杂任务（联网搜索、生成报告等），完成后把结果汇报回主会话

执行内容payload

kind: "agentTurn"：把一条“消息回合”投递给 agent 来执行。
message：给 agent 的指令文本（这里示例为执行 bash 脚本带参数）。

～ payload.kind 如果是 systemEvent ，只是在 OpenClaw 界面里显示一条系统消息

运行状态state（运行后写回）

nextRunAtMs：下次触发时间（ms）。
lastRunAtMs：上次触发时间（ms）。
lastStatus：上次状态（示例 ok）。
lastDurationMs：上次耗时（ms）。

配置方式

你在 OpenClaw 对话中直接用自然语言说就行，
OpenClaw 会自动创建 cron 任务，任务数据持久化到 /home/node/.openclaw/cron 目录。

到此这篇关于OpenClaw内置Cron的实现原理的文章就介绍到这了,更多相关OpenClaw 内置 Cron内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！