排程任務

Cron 是 Gateway 內建的排程器。它會持久化作業、在正確時間喚醒代理，並可將輸出傳回聊天頻道或 Webhook 端點。

# 快速開始

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

openclaw cron list
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

# Cron 如何運作

• Cron 在 Gateway 程序內執行（不是在模型內）。
• 作業定義會持久化於 ~/.openclaw/cron/jobs.json，因此重新啟動不會遺失排程。
• 執行階段狀態會持久化在旁邊的 ~/.openclaw/cron/jobs-state.json。如果你在 git 中追蹤 cron 定義，請追蹤 jobs.json 並將 jobs-state.json 加入 gitignore。
• 分拆之後，較舊的 OpenClaw 版本可以讀取 jobs.json，但可能會將作業視為全新作業，因為執行階段欄位現在位於 jobs-state.json。
• 當 Gateway 執行中或停止時編輯 jobs.json，OpenClaw 會比較變更後的排程欄位與待執行階段時段中繼資料，並清除過期的 nextRunAtMs 值。純格式化或僅鍵順序改寫會保留待執行時段。
• 所有 cron 執行都會建立背景任務記錄。
• Gateway 啟動時，逾期的隔離代理回合作業會被重新排程到頻道連線視窗之外，而不是立即重播，因此 Discord/Telegram 啟動與原生命令設定在重新啟動後仍能保持回應。
• 一次性作業（--at）預設會在成功後自動刪除。
• 隔離的 cron 執行在完成時，會盡力關閉其 cron:<jobId> 工作階段追蹤的瀏覽器分頁/程序，因此分離的瀏覽器自動化不會留下孤立程序。
• 獲得狹義 cron 自我清理授權的隔離 cron 執行，仍可讀取排程器狀態以及經自我篩選的目前作業清單，因此狀態/Heartbeat 檢查可檢視自己的排程，而不會取得更廣泛的 cron 變更存取權。
• 隔離 cron 執行也會防範過期的確認回覆。如果第一個結果只是暫時狀態更新（on it、pulling everything together 與類似提示），且沒有任何子代理後代執行仍負責最終答案，OpenClaw 會在交付前重新提示一次以取得實際結果。
• 隔離 cron 執行會優先使用內嵌執行提供的結構化執行拒絕中繼資料，接著才回退到已知的最終摘要/輸出標記，例如 SYSTEM_RUN_DENIED 和 INVALID_REQUEST，因此被阻擋的命令不會被回報為成功執行。
• 隔離 cron 執行也會將執行層級的代理失敗視為作業錯誤，即使沒有產生回覆 payload 也是如此，因此模型/供應商失敗會增加錯誤計數器並觸發失敗通知，而不是將作業清除為成功。
• 當隔離代理回合作業達到 timeoutSeconds，cron 會中止底層代理執行並給予短暫清理視窗。如果執行未能排空，Gateway 擁有的清理會在 cron 記錄逾時之前強制清除該執行的工作階段所有權，因此佇列中的聊天工作不會被留在過期的處理工作階段後面。

# 排程類型

沒有時區的時間戳記會被視為 UTC。加入 --tz America/New_York 可使用本地牆鐘時間排程。

整點的週期性運算式會自動錯開最多 5 分鐘，以降低負載尖峰。使用 --exact 可強制精確時間，或使用 --stagger 30s 指定明確視窗。

# 月中日與週中日使用 OR 邏輯

Cron 運算式由 croner 解析。當月中日與週中日欄位都不是萬用字元時，croner 會在任一欄位相符時匹配，而不是兩者都相符。這是標準 Vixie cron 行為。

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

這會每月觸發約 5 到 6 次，而不是每月 0 到 1 次。OpenClaw 在此使用 Croner 的預設 OR 行為。若要要求兩個條件都成立，請使用 Croner 的 + 週中日修飾符（0 9 15 * +1），或在其中一個欄位上排程，並在作業的提示或命令中防護另一個條件。

# 執行樣式

# 隔離作業的 payload 選項

--model 會將所選的允許模型用作該作業的主要模型。這不同於聊天工作階段 /model 覆寫：當作業主要模型失敗時，已設定的回退鏈仍會套用。如果請求的模型不被允許或無法解析，cron 會以明確的驗證錯誤使該執行失敗，而不是默默回退到作業的代理/預設模型選擇。

Cron 作業也可以攜帶 payload 層級的 fallbacks。存在時，該清單會取代該作業已設定的回退鏈。當你想要嚴格的 cron 執行，只嘗試所選模型時，請在作業 payload/API 中使用 fallbacks: []。如果作業有 --model，但沒有 payload 或已設定的回退，OpenClaw 會傳遞明確的空回退覆寫，因此代理主要模型不會被附加為隱藏的額外重試目標。

隔離作業的模型選擇優先順序為：

1. Gmail hook 模型覆寫（當執行來自 Gmail 且該覆寫被允許時）
2. 每個作業 payload 的 model
3. 使用者選擇並儲存的 cron 工作階段模型覆寫
4. 代理/預設模型選擇

快速模式也會跟隨已解析的即時選擇。如果所選模型設定具有 params.fastMode，隔離 cron 預設會使用它。儲存的工作階段 fastMode 覆寫仍會在任一方向上優先於設定。

如果隔離執行遇到即時模型切換交接，cron 會使用切換後的供應商/模型重試，並在重試前為作用中執行持久化該即時選擇。當切換也攜帶新的驗證設定檔時，cron 也會為作用中執行持久化該驗證設定檔覆寫。重試有界限：在初始嘗試加上 2 次切換重試之後，cron 會中止而不是無限循環。

在隔離 cron 執行進入代理執行器之前，OpenClaw 會檢查已設定且可連線的本機供應商端點，包括 api: "ollama" 與 api: "openai-completions"，其 baseUrl 為 loopback、私人網路或 .local。如果該端點已關閉，該執行會被記錄為 skipped，並帶有清楚的供應商/模型錯誤，而不是開始模型呼叫。端點結果會快取 5 分鐘，因此許多到期作業若使用相同已故障的本機 Ollama、vLLM、SGLang 或 LM Studio 伺服器，會共用一次小型探測，而不是形成請求風暴。略過的供應商預檢執行不會增加執行錯誤退避；當你希望重複收到略過通知時，請啟用 failureAlert.includeSkipped。

# 交付與輸出

使用 --announce --channel telegram --to "-1001234567890" 進行頻道傳遞。對於 Telegram 論壇主題，使用 -1001234567890:topic:123；直接 RPC/config 呼叫端也可以將 delivery.threadId 以字串或數字傳入。Slack/Discord/Mattermost 目標應使用明確前綴（channel:<id>、user:<id>）。Matrix room ID 區分大小寫；請使用來自 Matrix 的確切 room ID 或 room:!room:server 形式。

當 announce 傳遞使用 channel: "last" 或省略 channel 時，像 telegram:123 這類帶有供應方前綴的目標，可以在 cron 回退到工作階段歷史記錄或單一已設定頻道之前選取頻道。只有載入的 Plugin 所宣告的前綴才是供應方選取器。如果 delivery.channel 已明確指定，目標前綴必須命名相同的供應方；例如，channel: "whatsapp" 搭配 to: "telegram:123" 會被拒絕，而不是讓 WhatsApp 將 Telegram ID 解讀為電話號碼。目標種類與服務前綴，例如 channel:<id>、user:<id>、imessage:<handle> 和 sms:<number>，仍然是頻道擁有的目標語法，而不是供應方選取器。

對於隔離工作，聊天傳遞是共用的。如果有可用的聊天路由，即使工作使用 --no-deliver，代理程式也可以使用 message 工具。如果代理程式傳送至已設定/目前的目標，OpenClaw 會略過回退 announce。否則，announce、webhook 和 none 只會控制執行器在代理程式回合後如何處理最終回覆。

當代理程式從作用中的聊天建立隔離提醒時，OpenClaw 會儲存保留下來的即時傳遞目標，用於回退 announce 路由。內部工作階段金鑰可能是小寫；當目前聊天內容可用時，不會從這些金鑰重建供應方傳遞目標。

隱含 announce 傳遞會使用已設定的頻道 allowlist 驗證並重新路由過期目標。DM pairing-store 核准不是回退自動化收件者；當排程工作應主動傳送至 DM 時，請設定 delivery.to 或設定頻道 allowFrom 項目。

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

• cron.failureDestination 會設定失敗通知的全域預設值。
• job.delivery.failureDestination 會針對每個工作覆寫該值。
• 如果兩者都未設定，且工作已透過 announce 傳遞，失敗通知現在會回退到該主要 announce 目標。
• 除非主要傳遞模式是 webhook，否則 delivery.failureDestination 只支援 sessionTarget="isolated" 工作。
• failureAlert.includeSkipped: true 會讓工作或全域 cron 警示政策選擇加入重複 skipped-run 警示。略過的執行會保留獨立的連續略過計數器，因此不會影響執行錯誤的退避。

# CLI 範例

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

# Webhook

Gateway 可以公開 HTTP webhook 端點以供外部觸發。在 config 中啟用：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

# 驗證

每個請求都必須透過標頭包含 hook token：

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

查詢字串 token 會被拒絕。

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

# Gmail PubSub 整合

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

# 精靈設定（建議）

openclaw webhooks gmail setup --account [email protected]

這會寫入 hooks.gmail config、啟用 Gmail preset，並將 Tailscale Funnel 用於推送端點。

# Gateway 自動啟動

當 hooks.enabled=true 且已設定 hooks.gmail.account 時，Gateway 會在開機時啟動 gog gmail watch serve，並自動續訂 watch。設定 OPENCLAW_SKIP_GMAIL_WATCHER=1 可選擇退出。

# 手動一次性設定

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

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --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",
    },
  },
}

# 管理工作

# List all jobs
openclaw cron list

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

# 設定

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

maxConcurrentRuns 會限制排程 cron 派送與隔離代理程式回合執行。隔離 cron 代理程式回合會在內部使用佇列的專用 cron-nested 執行通道，因此提高此值可讓獨立的 cron LLM 執行平行推進，而不是只啟動其外層 cron 包裝器。共用的非 cron nested 通道不會因為此設定而加寬。

執行階段狀態 sidecar 會從 cron.store 衍生：像 ~/clawd/cron/jobs.json 這類 .json 儲存會使用 ~/clawd/cron/jobs-state.json，而沒有 .json 後綴的儲存路徑會附加 -state.json。

如果你手動編輯 jobs.json，請不要將 jobs-state.json 納入原始碼控制。OpenClaw 會使用該 sidecar 來保存待處理 slot、作用中標記、上次執行中繼資料，以及告訴排程器外部編輯的工作何時需要新的 nextRunAtMs 的排程身分。

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

# 疑難排解

# 命令階梯

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

# 相關

• 自動化與工作 — 所有自動化機制一覽
• 背景工作 — Cron 執行的工作帳本
• Heartbeat — 週期性的主要工作階段回合
• 時區 — 時區設定