先直接说结论：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 换成你实际的容器名。

从 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"]

这里 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//task.sh "" 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 * *"：标准的 5 段 Cron 表达式（分、时、日、月、周）。
• tz: "Asia/Shanghai"：指定时区，避免因为容器默认的 UTC 时间造成偏差。

会话与唤醒控制

• sessionTarget: "isolated"：每次运行使用隔离的会话，不会污染主对话的上下文。
• wakeMode: "next-heartbeat"：表示到点后，在下一个调度心跳 tick 执行，会有微小的延迟。

这里需要区分一下执行模式：

• Main Session：把任务当作一条“用户消息”注入主对话，效果就像你自己手动发送消息触发 Agent 一样。
• Isolated Session：启动一个独立的会话去执行复杂任务（比如联网搜索、生成报告），完成后把结果汇报回主会话。

执行内容 payload

• kind: "agentTurn"：表示把一条“消息回合”投递给 agent 去执行。
• message：发给 agent 的指令文本。这里的示例就是让 Agent 执行一个带参数的 bash 脚本。

补充一点：如果 payload.kind 是 systemEvent，那它只会在 OpenClaw 的界面里显示一条系统消息，不会真的去执行什么。

运行状态 state

• nextRunAtMs：下次触发的时间（毫秒）。
• lastRunAtMs：上次触发的时间（毫秒）。
• lastStatus：上次运行的状态（比如 ok）。
• lastDurationMs：上次执行耗时（毫秒）。

配置方式

实际操作起来其实很直观：直接在 OpenClaw 的对话里用自然语言跟它说就行。

OpenClaw 会自动帮你创建 Cron 任务，把数据持久化到 /home/node/.openclaw/cron 这个目录下。