使用 OpenClaw Cron 排程任務：自動化執行與提醒指南

快速開始

Cron 是 Gateway 內建的排程工具。它能持久化儲存任務、在指定時間喚醒代理程式，並將執行結果回傳至聊天頻道或 webhook 端點。

# Add a one-shot reminder
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

# Check your jobs
openclaw cron list

# See run history
openclaw cron runs --id <job-id>

Cron 如何運作

Cron 在 Gateway 進程中執行，而不是在模型內部。任務定義會持久化儲存在 ~/.openclaw/cron/jobs.json，因此重啟不會導致排程遺失。

1. 執行狀態會同步儲存在 ~/.openclaw/cron/jobs-state.json。如果你使用 GitHub 管理 cron 定義，請務必追蹤 jobs.json 並將 jobs-state.json 加入 gitignore。
2. 在版本拆分後，舊版 OpenClaw 仍可讀取 jobs.json，但可能會將任務視為全新任務，因為執行階段欄位現在已移至 jobs-state.json。
3. 所有 cron 執行都會建立 background task 記錄。
4. 單次執行任務（使用 --at）預設會在成功後自動刪除。
5. 隔離的 cron 執行會在完成時，盡力關閉該 cron:<jobId> 工作階段所追蹤的瀏覽器分頁或進程，確保自動化腳本不會留下孤兒進程。
6. 隔離的 cron 執行也會防範過時的確認回覆。如果第一個結果僅為中間狀態更新（例如「處理中」、「正在整理資料」等提示），且沒有後續的子代理程式負責最終答案，OpenClaw 會在交付前重新提示一次以獲取實際結果。

Cron 的任務協調由執行階段負責：只要 cron 執行階段認為該任務仍在執行，即使舊的子工作階段列存在，該 cron 任務仍會保持活躍。一旦執行階段停止擁有該任務，且 5 分鐘的寬限期結束，維護程序就會將該任務標記為 lost。

排程類型

類型	CLI flag	說明
at	--at	單次時間戳（ISO 8601 或相對時間，如 20m）
every	--every	固定間隔
cron	--cron	5 欄位或 6 欄位 cron 表達式，可選配 --tz

未指定時區的時間戳會被視為 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），或在一個欄位上排程，並在任務的提示詞或指令中加入另一個條件的判斷。

執行風格

風格	--session 值	執行位置	適用場景
主工作階段	main	下一個心跳週期	提醒、系統事件
隔離	isolated	專屬 cron:<jobId>	報告、背景雜務
當前工作階段	current	建立時綁定	需要上下文的循環工作
自訂工作階段	session:custom-id	持久化命名工作階段	累積歷史紀錄的工作流

1. 主工作階段任務會加入系統事件佇列，並可選擇喚醒心跳（--wake now 或 --wake next-heartbeat）。
2. 隔離任務會以全新的工作階段執行專屬的代理程式回合。
3. 自訂工作階段（session:xxx）會在多次執行間保留上下文，適合需要基於先前摘要進行每日站立會議等工作流。

對於隔離任務，執行階段的清理程序現在包含盡力清理該 cron 工作階段的瀏覽器資源。清理失敗會被忽略，以確保 cron 的最終結果優先。

當隔離的 cron 執行協調子代理程式時，交付結果會優先選擇最終的後代輸出，而非過時的父層中間文字。如果後代仍在執行，OpenClaw 會抑制該部分父層更新，而不進行公告。

隔離任務的 Payload 選項

• --message：提示文字（隔離任務必填）
• --model / --thinking：模型與思考層級覆寫
• --light-context：跳過工作區啟動檔案注入
• --tools exec,read：限制任務可使用的工具

--model 會使用該任務允許的選定模型。若請求的模型未獲准，cron 會記錄警告並退回到該任務的代理程式或預設模型選擇。已設定的後備鏈（fallback chains）仍然適用，但若僅進行模型覆寫而無明確的任務級後備列表，則不再將代理程式的主要模型作為隱藏的額外重試目標。

隔離任務的模型選擇優先順序為：

1. Gmail hook 模型覆寫（當執行來自 Gmail 且該覆寫被允許時）
2. 任務級 Payload model
3. 儲存的 cron 工作階段模型覆寫
4. 代理程式/預設模型選擇

快速模式（Fast mode）同樣遵循解析後的即時選擇。如果選定的模型配置包含 params.fastMode，隔離 cron 預設會使用該設定。儲存的工作階段 fastMode 覆寫在任何情況下皆優先於配置。

若隔離執行遇到即時模型切換（handoff），cron 會使用切換後的提供者/模型重試，並在重試前持久化該即時選擇。當切換同時帶有新的驗證設定檔時，cron 也會持久化該驗證設定檔的覆寫。重試次數有限制：在初始嘗試加上 2 次切換重試後，cron 會中止執行，避免無限迴圈。

傳送與輸出

當你在使用 OpenClaw 進行任務處理時，系統提供了多種傳送模式來管理你的執行結果。下表說明了這些模式的運作方式：

模式	運作說明
announce	將摘要傳送到目標頻道（這是隔離模式的預設值）
webhook	將完成事件的 payload 以 POST 方式傳送到指定 URL
none	僅限內部使用，不進行任何傳送

若要進行頻道傳送，請使用 --announce --channel telegram --to "-1001234567890"。針對 Telegram 論壇主題，請使用 -1001234567890:topic:123 的格式。至於 Slack、Discord 或 Mattermost 目標，則應使用明確的前綴（例如 channel:<id> 或 user:<id>）。

對於由 cron 管理的隔離任務，執行器會負責最終的傳送路徑。系統會提示 Agent 回傳純文字摘要，接著該摘要會透過 announce、webhook 傳送，或是設定為 none 以保持在內部。請注意，--no-deliver 並不會將傳送權限交還給 Agent，而是會讓該次執行保持在內部狀態。

如果原始任務明確要求傳送訊息給外部接收者，Agent 應在輸出中註明該訊息的目標對象與位置，而不是嘗試直接發送。

失敗通知則遵循獨立的傳送路徑：

1. cron.failureDestination 設定了失敗通知的全域預設值。
2. job.delivery.failureDestination 會覆寫該任務的個別設定。
3. 若兩者皆未設定，且任務已透過 announce 進行傳送，失敗通知將會退回到該主要的 announce 目標。
4. delivery.failureDestination 僅支援 sessionTarget="isolated" 的任務，除非主要的傳送模式為 webhook。

CLI 範例

你可以透過 OpenClaw 的 CLI 指令快速設定各類任務，以下提供幾種常見的執行情境供你參考。

單次提醒（主 session）：

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

AI Setup Assistant

Webhooks

Gateway 可以為外部觸發器公開 HTTP webhook 端點。請在設定中啟用此功能：

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

驗證

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

1. Authorization: Bearer <token> (推薦使用)
2. x-openclaw-token: <token>

查詢字串中的 token 將會被拒絕。

POST /hooks/wake

為主要 session 加入系統事件佇列：

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"}'

1. text (必填)：事件描述
2. mode (選填)：now (預設) 或 next-heartbeat

POST /hooks/agent

執行一個隔離的 agent 任務：

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-mini"}'

欄位包含：message (必填)、name、agentId、wakeMode、deliver、channel、to、model、thinking、timeoutSeconds。

映射 hooks (POST /hooks/<name>)

自訂的 hook 名稱會透過設定中的 hooks.mappings 進行解析。映射可以透過模板或程式碼轉換，將任意 payload 轉換為 wake 或 agent 動作。

安全性

1. 將 hook 端點保持在 loopback、tailnet 或受信任的反向代理之後。
2. 使用專用的 hook token；不要重複使用 Gateway 的驗證 token。
3. 將 hooks.path 保持在專用的子路徑上；/ 路徑將被拒絕。
4. 設定 hooks.allowedAgentIds 以限制明確的 agentId 路由。
5. 除非你需要呼叫者選擇 session，否則請保持 hooks.allowRequestSessionKey=false。
6. 如果你啟用了 hooks.allowRequestSessionKey，請同時設定 hooks.allowedSessionKeyPrefixes 以限制允許的 session key 格式。
7. hook 的 payload 預設會被安全邊界包裝。

Gmail PubSub 整合

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

先決條件：gcloud CLI、gog (gogcli)、已啟用的 OpenClaw hooks，以及用於公開 HTTPS 端點的 Tailscale。

設定精靈 (推薦)

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

這會寫入 hooks.gmail 設定，啟用 Gmail 預設值，並使用 Tailscale Funnel 作為推送端點。

Gateway 自動啟動

當 hooks.enabled=true 且設定了 hooks.gmail.account 時，Gateway 會在啟動時執行 gog gmail watch serve 並自動更新監控。若要停用，請設定 OPENCLAW_SKIP_GMAIL_WATCHER=1。

手動一次性設定

1. 選擇擁有 gog 所使用 OAuth 客戶端的 GCP 專案：

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

2. 建立主題並授予 Gmail 推送存取權：

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

3. 啟動監控：

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

管理任務

你可以透過 OpenClaw 輕鬆管理你的排程任務，確保自動化流程順暢執行。以下是常用的指令，幫助你快速查看、編輯或刪除這些任務。

1. 列出所有任務：

   # List all jobs
   openclaw cron list

2. 編輯現有任務的訊息或模型：

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

3. 強制立即執行任務：

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

4. 僅在排程時間到達時執行：

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

5. 查看任務的執行歷史記錄：

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

6. 刪除不再需要的任務：

   # Delete a job
   openclaw cron remove <jobId>

7. 在多 Agent 環境下選擇特定的 Agent：

# List all jobs
openclaw cron list

# 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

關於模型覆寫的注意事項：

• openclaw cron add|edit --model ... 指令會變更該任務所選定的模型。
• 若該模型是被允許的，系統會將該特定的供應商與模型用於隔離的 Agent 執行。
• 若該模型不被允許，cron 會發出警告，並退回到任務預設的 Agent 或模型選擇。
• 設定好的備援鏈（fallback chains）仍然有效，但若僅使用 --model 進行覆寫且沒有明確的個別任務備援列表，系統將不再將其視為靜默的額外重試目標。

設定

你可以透過 OpenClaw 的設定檔來調整 cron 的運作行為，包括重試機制、日誌限制以及 webhook 權杖等參數。

{
  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 },
  },
}

執行階段的狀態側邊檔（sidecar）是從 cron.store 推導出來的：例如 ~/clawd/cron/jobs.json 這類 JSON 儲存位置會使用 ~/clawd/cron/jobs-state.json，而若儲存路徑沒有 .json 後綴，則會自動附加 -state.json。

若要停用 cron，請設定 cron.enabled: false 或使用環境變數 OPENCLAW_SKIP_CRON=1。

單次重試（One-shot retry）：針對暫時性錯誤（如速率限制、過載、網路問題、伺服器錯誤），系統會進行最多 3 次的指數退避（exponential backoff）重試。若是永久性錯誤，任務會立即停用。

循環重試（Recurring retry）：在重試之間會採用指數退避（從 30 秒到 60 分鐘不等）。退避時間會在下一次成功執行後重置。

維護機制：cron.sessionRetention（預設為 24h）會清理隔離的執行階段條目。cron.runLog.maxBytes 與 cron.runLog.keepLines 則會自動清理執行日誌檔案。

疑難排解

當你在使用 OpenClaw 進行自動化任務或處理 Gateway 連線時遇到問題，通常可以透過檢查系統狀態與日誌來快速定位原因。以下指令能幫助你診斷 OpenClaw 的執行狀況。

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 任務未觸發

如果你發現設定的任務沒有按預期執行，請先檢查環境變數與主機設定。通常這類問題與排程器未啟動或時區設定不匹配有關。

1. 檢查 cron.enabled 設定以及 OPENCLAW_SKIP_CRON 環境變數是否正確。
2. 確認 Gateway 是否處於持續運作狀態。
3. 針對 cron 排程，請確認指令中的時區參數 (--tz) 與主機時區是否一致。
4. 若執行結果顯示 reason: not-due，代表你使用 openclaw cron run <jobId> --due 進行手動測試時，該任務尚未到達預定執行時間。

Cron 任務已觸發但未送出訊息

當任務執行完畢但沒有收到預期的通知時，通常是因為傳遞模式或權限設定導致訊息被攔截。

1. 若傳遞模式為 none，代表系統預期不會發送外部訊息。
2. 若傳遞目標 (channel 或 to) 遺失或無效，系統會自動跳過輸出。
3. 若出現頻道驗證錯誤（如 unauthorized 或 Forbidden），代表憑證設定有誤，導致無法送出訊息。
4. 如果獨立執行的任務僅回傳靜默 token (NO_REPLY / no_reply)，OpenClaw 會抑制直接的外部傳遞，同時也會抑制後備的佇列摘要路徑，因此聊天室中不會收到任何訊息。
5. 對於由 cron 管理的獨立任務，請勿預期 Agent 會使用訊息工具作為後備方案。執行器負責最終的傳遞；使用 --no-deliver 會將結果保留在內部，而非允許直接發送。

時區注意事項

時區設定錯誤是導致排程時間偏移的常見原因，請務必留意不同指令對時區的處理方式。

1. 若 cron 未設定 --tz，將會預設使用 Gateway 主機的時區。
2. 若 at 排程未指定時區，系統會將其視為 UTC 時間。
3. 心跳檢測 (heartbeat) 的 activeHours 會使用已設定的時區解析規則。

相關文件

• Automation & Tasks — 概覽所有自動化機制
• Background Tasks — cron 執行的任務帳本
• Heartbeat — 定期主會話輪詢
• Timezone — 時區設定說明

AI Setup Assistant