排程任務

Cron 是閘道內建的排程器。它會持久保存工作、在正確時間喚醒代理，並可將輸出傳送至聊天頻道、網路鉤子，或不傳送至任何地方。

快速開始

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Reminder" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

Cron 的運作方式

• Cron 在閘道程序內部執行，而非在模型內部。閘道必須處於執行狀態，排程才會觸發。
• 工作定義、執行階段狀態及執行歷程會持久保存於 OpenClaw 的共用 SQLite 狀態資料庫，因此重新啟動不會遺失排程。
• 每次 Cron 執行都會建立一筆背景任務記錄。
• 單次工作（--at）預設會在成功後自動刪除；傳入 --keep-after-run 可保留工作。
• 每次執行的實際經過時間預算：設定時使用 --timeout-seconds。否則，隔離／分離式代理回合工作會受到 Cron 自身 60 分鐘監控機制的限制，早於底層代理回合逾時（agents.defaults.timeoutSeconds，預設 48 小時）生效；命令工作預設為 10 分鐘。
• 閘道啟動時，逾期的隔離式代理回合工作會重新排程，而不會立即重播，以免模型／工具啟動工作進入頻道連線時段。
• 如果你透過系統 Cron 或其他外部排程器驅動 openclaw agent，即使命令列介面已處理 SIGTERM／SIGINT，仍應以強制終止升級機制包裝它。由閘道支援的執行會要求閘道中止已接受的執行；本機與嵌入式備援執行則會收到相同的中止訊號。若使用 GNU timeout，請優先使用 timeout -k 60 600 openclaw agent ...，而不是單純的 timeout 600 ...——如果程序無法及時完成收尾，-k 值就是最後的保障。若使用 systemd 單元，請使用 SIGTERM 停止訊號並保留寬限時間（TimeoutStopSec），之後才進行最終強制終止。若原始閘道執行仍在進行中時重複使用 --run-id，系統會將重複項目回報為執行中，而非啟動第二次執行。

排程類型

沒有時區的時間戳記會視為 UTC。加入 --tz America/New_York，即可使用該 IANA 時區解讀不含時差的 --at 日期時間，或評估 Cron 運算式。未使用 --tz 的 Cron 運算式會採用閘道主機的時區。--tz 不適用於 --every 或 --on-exit。

每小時整點重複執行的運算式（分鐘為 0，小時欄位為萬用字元）會自動錯開最多 5 分鐘，以降低負載尖峰。使用 --exact 可強制精確時間，或使用 --stagger 30s 設定明確的時段（僅限 Cron 排程）。

月中日期與星期採用 OR 邏輯

Cron 運算式由 croner 剖析。當月中日期與星期欄位都不是萬用字元時，只要任一欄位相符，croner 即視為相符，而非要求兩者皆相符。這是標準的 Vixie Cron 行為。

# 預期：「15 日上午 9 點，且僅限星期一」# 實際：「每月 15 日上午 9 點，以及每個星期一上午 9 點」0 9 15 * 1

這會導致每月觸發約 5–6 次，而非每月 0–1 次。若要同時符合兩個條件，請使用 croner 的 + 星期修飾符（0 9 15 * +1），或依其中一個欄位排程，再於工作的提示或命令中檢查另一個欄位。

事件觸發器（條件監看器）

事件觸發器會將無頭條件指令碼加入 every 或 cron 排程。工作到期時，Cron 會評估指令碼，並且只在指令碼傳回 fire: true 時執行一般承載資料：

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // 僅在觀察到的狀態與上次評估不同時觸發。    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "Investigate the CI status change." },}

指令碼必須傳回 { fire, message?, state? }。先前的 JSON 狀態可透過深度凍結的 trigger.state 取得；傳回新的 state 值即可持久保存。狀態上限為 16 KB。當觸發結果包含 message 時，Cron 會在執行前將其附加至系統事件文字或代理回合訊息。once: true 會在首次成功執行已觸發的承載資料後停用工作。

fire: false 會持久保存評估狀態與計數器，接著重新排程，而不建立執行歷程。如果已觸發的承載資料執行失敗，傳回的 state 不會持久保存——下次評估會看到先前的狀態，且可再次觸發，因此請將指令碼撰寫為唯讀檢查，並將動作保留在承載資料中。觸發器排程具有可設定的最小間隔（預設為 30 秒）。每次評估的實際經過時間預算為 30 秒，最多可呼叫工具 5 次。

從本機指令碼檔案建立監看器（- 會從標準輸入讀取指令碼）：

openclaw cron add \  --name "PR CI watcher" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Respond to the CI status change" \  --session isolated

承載資料

每個工作恰好包含一種承載資料類型，由旗標選擇：

代理回合選項

--model 會設定工作的主要模型；它不會取代工作階段的 /model 覆寫，因此已設定的備援鏈仍會套用在其上。無法解析或不允許的模型會讓執行失敗並顯示明確的驗證錯誤，而不會無聲地回退至預設值。如果工作有 --model，但沒有明確或已設定的備援清單，OpenClaw 會傳遞空的備援覆寫，而不會無聲地附加代理程式主要模型作為隱藏的重試目標。

隔離工作的模型選擇優先順序如下，由高至低：

1. 每個工作的承載資料 model（明確設定；不允許的模型會讓執行失敗）
2. Gmail 鉤子的模型覆寫（僅限執行來自 Gmail 且允許該覆寫時）
3. 使用者選取並儲存的排程工作階段模型覆寫
4. 代理程式／預設模型選擇

快速模式會遵循解析後的即時選擇。如果所選模型設定含有 params.fastMode，隔離排程預設會使用該值；已儲存的工作階段 fastMode 覆寫（其次為代理程式的 fastModeDefault）仍會優先於模型設定，無論設定為開啟或關閉。自動模式會使用模型的 params.fastAutoOnSeconds 臨界值，預設為 60 秒。

如果執行期間發生即時模型切換的交接，排程會使用切換後的供應商／模型重試，並在目前執行期間保存該選擇（以及任何新的驗證設定檔）。重試次數有上限：初始嘗試加上 2 次切換重試後，排程會中止，而不會持續循環。

隔離執行開始前，OpenClaw 會檢查已設定的 api: "ollama" 與 api: "openai-completions" 供應商中，baseUrl 為回送位址、私人網路或 .local 的本機端點是否可連線。此預先檢查會遍歷工作的已設定備援鏈，只有在所有候選端點都無法連線後，才會將執行標記為 skipped；--fallbacks "" 會讓遍歷嚴格限定於主要模型。端點無法使用時，系統會將執行記錄為 skipped 並附上清楚的錯誤，而不會開始模型呼叫。結果會依端點快取 5 分鐘（不是依工作或模型），因此許多到期工作共用失效的本機 Ollama/vLLM/SGLang/LM Studio 伺服器時，只需進行一次探測，而不會引發大量請求。預先檢查時略過的執行不會增加執行錯誤的退避時間；設定 failureAlert.includeSkipped 可選擇接收重複的略過警示。

命令承載資料

命令承載資料會在閘道排程器內執行確定性的指令碼，而不會啟動由模型支援的輪次。命令會在閘道主機上執行、擷取 stdout/stderr、將執行記錄於排程歷程中，並重複使用與代理程式輪次工作相同的 announce、webhook 和 none 傳遞模式。

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> 會儲存 argv: ["sh", "-lc", <shell>]。若要不經殼層剖析而精確執行 argv，請使用 --command-argv '["node","scripts/report.mjs"]'。選用的 --command-env KEY=VALUE（可重複指定）、--command-input、--timeout-seconds（預設 10 分鐘）、--no-output-timeout-seconds 和 --output-max-bytes 可控制程序環境、stdin 與輸出限制。

傳遞的文字取自程序輸出：非空白的 stdout 優先；如果 stdout 為空白而 stderr 非空白，則傳遞 stderr；如果兩者都有內容，排程會傳送一小段 stdout: / stderr: 區塊。結束代碼 0 會將執行記錄為 ok；非零結束代碼、訊號、逾時或無輸出逾時會記錄為 error，並可能觸發失敗警示。僅輸出 NO_REPLY 的命令會使用一般排程的靜默權杖抑制機制，不會將任何內容傳回聊天。

執行方式

傳送與輸出

使用 --announce --channel telegram --to "-1001234567890" 傳送至頻道。對於 Telegram 論壇主題，請使用 -1001234567890:topic:123；OpenClaw 也接受由 Telegram 定義的 -1001234567890:123 簡寫。直接使用 RPC／設定的呼叫端可將 delivery.threadId 傳入為字串或數字。Slack／Discord／Mattermost 目標使用明確的前綴（channel:<id>、user:<id>）。Matrix 聊天室 ID 區分大小寫；請使用確切的聊天室 ID，或使用來自 Matrix 的 room:!room:server 格式。

當公告傳送使用 channel: "last" 或省略 channel 時，像 telegram:123 這類帶有提供者前綴的目標，可以在排程退回使用工作階段歷程或單一已設定頻道之前選取頻道。只有載入之外掛所公告的前綴才是提供者選擇器。如果明確指定 delivery.channel，目標前綴必須指向相同的提供者；若使用 channel: "whatsapp" 搭配 to: "telegram:123"，系統會拒絕該組合，而不會讓 WhatsApp 將 Telegram ID 解讀為電話號碼。目標種類與服務前綴（channel:<id>、user:<id>、imessage:<handle>、sms:<number>）仍是由頻道擁有的目標語法，而非提供者選擇器。

對於隔離工作，聊天傳送功能是共用的：如果有可用的聊天路由，即使使用 --no-deliver，代理仍可使用 message 工具。如果代理傳送至已設定／目前的目標，OpenClaw 會略過備援公告。否則，announce、webhook 和 none 只控制代理回合結束後，執行器如何處理最終回覆。

當代理從進行中的聊天建立隔離提醒時，OpenClaw 會儲存保留的即時傳送目標，供備援公告路由使用。內部工作階段金鑰可能為小寫；當目前聊天情境可用時，不會從這些金鑰重建提供者傳送目標。

隱含的公告傳送會使用已設定的頻道允許清單來驗證過時目標並重新路由。DM 配對儲存區的核准對象不會成為備援自動化的收件者；當排程工作應主動傳送至 DM 時，請設定 delivery.to，或設定頻道的 allowFrom 項目。

失敗通知

失敗通知遵循獨立的目的地路徑：

• cron.failureDestination 設定失敗通知的全域預設值。
• job.delivery.failureDestination 會針對個別工作覆寫該值。
• 如果兩者都未設定，且工作已透過 announce 傳送，失敗通知會退回使用該主要公告目標。
• 除非主要傳送模式為 webhook，否則僅有 sessionTarget="isolated" 工作支援 delivery.failureDestination。
• failureAlert.includeSkipped: true 讓個別工作或全域排程警示原則納入重複略過執行的警示。略過的執行會保有獨立的連續略過計數器，因此不會影響執行錯誤的退避機制。
• openclaw cron edit 提供個別工作的警示調整選項：--failure-alert／--no-failure-alert、--failure-alert-after <n>、--failure-alert-channel、--failure-alert-to、--failure-alert-cooldown、--failure-alert-include-skipped／--failure-alert-exclude-skipped、--failure-alert-mode 和 --failure-alert-account-id。

輸出語言

排程工作不會根據頻道、地區設定或先前訊息推斷回覆語言。請將語言規則放入排程訊息或範本中：

openclaw cron edit <jobId> \  --message "摘要更新內容。請以中文回覆；URL、程式碼和產品名稱保持不變。"

對於範本檔案，請在算繪後的提示詞中保留語言指示，並在工作執行前確認 {{language}} 等預留位置已填入。如果輸出混合多種語言，請明確指定規則，例如：“敘述文字使用中文，技術術語保留英文。”

命令列介面範例

openclaw cron add \  --name "行事曆檢查" \  --at "20m" \  --session main \  --system-event "下次心跳偵測：檢查行事曆。" \  --wake now

openclaw cron create "0 7 * * *" \  "摘要整理夜間更新。" \  --name "晨間簡報" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "深入分析" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "每週深入分析專案進度。" \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "以 JSON 摘要整理今天的部署。" \  --name "部署摘要" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "佇列深度探測" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

管理工作

# 列出所有工作openclaw cron list # 以 JSON 取得一項已儲存的工作openclaw cron get <jobId> # 顯示一項工作，包括解析後的傳遞路由openclaw cron show <jobId> # 啟用／停用而不刪除openclaw cron enable <jobId>openclaw cron disable <jobId> # 編輯工作openclaw cron edit <jobId> --message "更新後的提示詞" --model "opus" # 立即強制執行工作openclaw cron run <jobId> # 立即強制執行工作，並等待其終止狀態openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # 僅在到期時執行openclaw cron run <jobId> --due # 檢視執行歷程openclaw cron runs --id <jobId> --limit 50 # 檢視某次確切的執行openclaw cron runs --id <jobId> --run-id <runId> # 刪除工作openclaw cron remove <jobId> # 選擇代理程式（多代理程式設定）openclaw cron create "0 6 * * *" "檢查維運佇列" --name "維運巡查" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

封存工作階段（透過控制介面，或由操作員管理員呼叫者執行 sessions.patch { archived: true }）會停用綁定至該工作階段的所有已啟用排程工作：其隔離的 cron:<jobId> 工作階段、session:<key> 目標，或傳遞／喚醒的 sessionKey 通道。還原工作階段不會重新啟用這些工作；請使用 openclaw cron enable <jobId>。具有已啟用綁定工作的工作階段會在控制介面側邊欄顯示時鐘徽章。

openclaw cron run <jobId> 會在手動執行排入佇列後返回。對於關閉掛鉤、維護指令碼，或其他必須封鎖至佇列中的執行完成為止的自動化，請使用 --wait；它會輪詢返回的 runId（預設逾時 10m，輪詢間隔 2s），狀態為 ok 時以 0 結束，狀態為 error、skipped 或等待逾時時則以非零值結束。

代理程式的 cron 工具透過 cron(action: "list") 返回精簡的工作摘要（id、name、enabled、nextRunAtMs、scheduleKind、lastRunStatus）；若要取得單一工作的完整定義，請使用 cron(action: "get", jobId: "...")。直接呼叫閘道的呼叫者可將 compact: true 傳給 cron.list；省略此項則會保留包含傳遞預覽的完整回應。

openclaw cron create 是 openclaw cron add 的別名。新工作可以使用位置式排程（"0 9 * * 1"、"every 1h"、"20m" 或 ISO 時間戳記），後接位置式代理程式提示詞。在 cron add|create 或 cron edit 上使用 --webhook <url>，可將已完成執行的承載資料以 POST 傳送至 HTTP 端點；網路鉤子傳遞不能與聊天傳遞旗標（--announce、--channel、--to、--thread-id、--account）併用。在 cron edit 上，--clear-channel、--clear-to、--clear-thread-id 和 --clear-account 會個別取消設定對應的路由欄位（每個旗標皆不能與其對應的設定旗標併用）——這與 --no-deliver 不同，後者只會停用執行器的備援傳遞。

網路鉤子

閘道可以公開 HTTP 網路鉤子端點，供外部觸發。請在設定中啟用：

{  hooks: {    enabled: true,    token: "共用密鑰",    path: "/hooks",  },}

驗證

每個請求都必須透過標頭包含掛鉤權杖：

• Authorization: Bearer <token>（建議）
• x-openclaw-token: <token>

查詢字串權杖會遭到拒絕。

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"收到新電子郵件","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"摘要整理收件匣","name":"電子郵件","model":"openai/gpt-5.6-sol"}'

Gmail PubSub 整合

透過 Google PubSub 將 Gmail 收件匣觸發器連接至 OpenClaw。

精靈設定（建議）

openclaw webhooks gmail setup --account openclaw@gmail.com

這會寫入 hooks.gmail 設定、啟用 Gmail 預設集，並預設使用 Tailscale Funnel 作為推送端點（--tailscale funnel|serve|off）。

閘道自動啟動

當 hooks.enabled=true 且已設定 hooks.gmail.account 時，閘道會在啟動時執行 gog gmail watch serve，並自動續期監看。設定 OPENCLAW_SKIP_GMAIL_WATCHER=1 可選擇停用。

手動一次性設定

gcloud auth logingcloud config set project <project-id>gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

gog gmail watch start \  --account openclaw@gmail.com \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Gmail 模型覆寫

{  hooks: {    gmail: {      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

設定

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 8,    triggers: {      enabled: false,      minIntervalMs: 30000,    },    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },    webhookToken: "替換為專用網路鉤子權杖",    sessionRetention: "24h",    runLog: { maxBytes: "2mb", keepLines: 2000 },  },}

上述 retry 值為預設值：最多重試 3 次，退避時間為 30s/60s/5m，並對全部五種暫時性錯誤類別進行重試。排程網路鉤子的 POST 請求會將 webhookToken 作為 Authorization: Bearer <token> 傳送。

maxConcurrentRuns 同時限制排程分派和隔離代理程式回合的執行，預設值為 8。隔離的排程代理程式回合會在內部使用佇列專用的 cron-nested 執行通道，因此提高此值可讓彼此獨立的排程 LLM 執行並行推進，而不是只能啟動其外層排程包裝器。此設定不會擴大共用的非排程 nested 通道。

cron.store 是邏輯儲存區金鑰和 doctor 遷移路徑，不是可手動編輯的即時 JSON 檔案。工作資料存放於 SQLite；請使用命令列介面或閘道 API 進行變更。

停用排程：cron.enabled: false 或 OPENCLAW_SKIP_CRON=1。

疑難排解

命令階梯

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

相關內容

• 自動化 — 一覽所有自動化機制
• 背景工作 — 排程執行的工作帳本
• 心跳偵測 — 定期執行主要工作階段回合
• 時區 — 時區設定