OpenClaw 的“定時(shí)任務(wù)（內(nèi)置 Cron）”本質(zhì)上就是：在進(jìn)程內(nèi)維護(hù)一個(gè) Cron 表達(dá)式調(diào)度器，周期性計(jì)算“下一次觸發(fā)時(shí)間”，到點(diǎn)后把任務(wù)投遞到執(zhí)行器（線程池/協(xié)程/隊(duì)列）里跑。

定時(shí)任務(wù)配置

OpenClaw 自帶一個(gè) Cron 調(diào)度系統(tǒng)，數(shù)據(jù)存儲(chǔ)在 .openclaw/cron 目錄中。

例如：路徑/root/openclaw-docker/data/.openclaw/cron/jobs.json 通常由 “OpenClaw 的數(shù)據(jù)目錄(data dir) + 固定子目錄 .openclaw/cron/ + 固定文件名 jobs.json” 共同決定。

也就是說(shuō)，真正可配置的一般只有前半段：/root/openclaw-docker/data（數(shù)據(jù)卷/工作目錄），后半段多半是程序?qū)懰赖南鄬?duì)路徑。

判斷這個(gè) jobs.json 路徑由哪里決定

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

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

2) 找到 openclaw 容器名后，導(dǎo)出完整啟動(dòng)/掛載信息

把 openclaw-docker-openclaw-gateway-1 換成你的容器名，docker inspect 里 Binds/Mounts 字段進(jìn)行判斷

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", ...}]

• 這表示：
  • 宿主機(jī) /root/openclaw-docker/data/.openclaw
    被 bind mount 到
  • 容器內(nèi) /home/node/.openclaw

OpenClaw 的 Cron 數(shù)據(jù)文件放在 .openclaw/cron/jobs.json 這個(gè)相對(duì)路徑下，所以：

• 容器內(nèi)路徑：/home/node/.openclaw/cron/jobs.json
• 宿主機(jī)對(duì)應(yīng)路徑：/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，很多程序默認(rèn)把數(shù)據(jù)放在 $HOME/.openclaw，這也進(jìn)一步印證容器內(nèi)會(huì)用 /home/node/.openclaw

jobs.json 配置說(shuō)明

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

頂層

• version：文件格式版本（用于兼容/升級(jí)遷移）。
• jobs：定時(shí)任務(wù)數(shù)組。

job 基本信息

• id：任務(wù)唯一標(biāo)識(shí)（UUID）
• agentId：由哪個(gè) agent 執(zhí)行（如 main）。
• name：任務(wù)展示名。
• enabled：是否啟用；false 表示不調(diào)度。
• 時(shí)間戳（毫秒）createdAtMs / updatedAtMs：創(chuàng)建/更新的 epoch 毫秒時(shí)間。

調(diào)度計(jì)劃schedule

• kind: "every"：按固定間隔觸發(fā)（不是 cron 表達(dá)式）。
• everyMs：間隔毫秒數(shù)；43200000 = 12 小時(shí)。

三種調(diào)度類型
類型 說(shuō)明 示例
at 一次性定時(shí) “30分鐘后提醒我”
every 固定間隔重復(fù) “每5分鐘檢查一次”
cron 標(biāo)準(zhǔn) Cron 表達(dá)式 0 9 * * 1-5（工作日每天9點(diǎn)）

示例（cron 調(diào)度）

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

字段說(shuō)明

• kind: "cron"：使用 cron 表達(dá)式觸發(fā)
• expr: "55 9 3 * *"：cron 表達(dá)式（常見(jiàn) 5 段：分 時(shí) 日 月 周）
• tz: "Asia/Shanghai"：按這個(gè)時(shí)區(qū)解釋 cron 時(shí)間（避免容器時(shí)區(qū)/UTC 造成偏差）

會(huì)話與喚醒

• sessionTarget: "isolated"：每次運(yùn)行用隔離會(huì)話（避免污染主對(duì)話/上下文）。
• wakeMode: "next-heartbeat"：到點(diǎn)后在“下一次心跳/調(diào)度 tick”執(zhí)行，可能有輕微延遲。

執(zhí)行模式:
Main Session：把任務(wù)當(dāng)作"用戶消息"注入主對(duì)話，像你手動(dòng)發(fā)消息一樣觸發(fā) Agent
Isolated Session：?jiǎn)?dòng)獨(dú)立會(huì)話執(zhí)行復(fù)雜任務(wù)（聯(lián)網(wǎng)搜索、生成報(bào)告等），完成后把結(jié)果匯報(bào)回主會(huì)話

執(zhí)行內(nèi)容payload

• kind: "agentTurn"：把一條“消息回合”投遞給 agent 來(lái)執(zhí)行。
• message：給 agent 的指令文本（這里示例為執(zhí)行 bash 腳本帶參數(shù)）。

～ payload.kind 如果是 systemEvent ，只是在 OpenClaw 界面里顯示一條系統(tǒng)消息

運(yùn)行狀態(tài)state（運(yùn)行后寫(xiě)回）

• nextRunAtMs：下次觸發(fā)時(shí)間（ms）。
• lastRunAtMs：上次觸發(fā)時(shí)間（ms）。
• lastStatus：上次狀態(tài)（示例 ok）。
• lastDurationMs：上次耗時(shí)（ms）。

配置方式

你在 OpenClaw 對(duì)話中直接用自然語(yǔ)言說(shuō)就行，
OpenClaw 會(huì)自動(dòng)創(chuàng)建 cron 任務(wù)，任務(wù)數(shù)據(jù)持久化到 /home/node/.openclaw/cron 目錄。

到此這篇關(guān)于OpenClaw內(nèi)置Cron的實(shí)現(xiàn)原理的文章就介紹到這了,更多相關(guān)OpenClaw 內(nèi)置 Cron內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論