งานตามกำหนดเวลา

Cron คือ scheduler ในตัวของ Gateway โดยจะคงอยู่ของ jobs, ปลุก agent ในเวลาที่ถูกต้อง และสามารถส่ง output กลับไปยัง chat channel หรือ webhook endpoint ได้

เริ่มต้นอย่างรวดเร็ว

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 listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

Cron ทำงานอย่างไร

• Cron รัน ภายใน process ของ Gateway (ไม่ใช่ภายใน model)
• นิยามของ job จะคงอยู่ที่ ~/.openclaw/cron/jobs.json ดังนั้นการรีสตาร์ตจะไม่ทำให้ schedules สูญหาย
• สถานะการดำเนินงานระหว่าง runtime จะคงอยู่ข้างกันใน ~/.openclaw/cron/jobs-state.json หากคุณติดตามนิยาม cron ใน git ให้ติดตาม jobs.json และเพิ่ม jobs-state.json ใน gitignore
• หลังการแยกนี้ OpenClaw เวอร์ชันเก่าสามารถอ่าน jobs.json ได้ แต่อาจถือว่า jobs เป็นรายการใหม่เพราะ runtime fields ตอนนี้อยู่ใน jobs-state.json
• เมื่อ jobs.json ถูกแก้ไขระหว่างที่ Gateway กำลังรันหรือหยุดอยู่ OpenClaw จะเปรียบเทียบ schedule fields ที่เปลี่ยนแปลงกับ metadata ของ pending runtime slot และล้างค่า nextRunAtMs ที่ล้าสมัย การแก้เฉพาะรูปแบบหรือการเขียนใหม่ที่เปลี่ยนเฉพาะลำดับคีย์จะคง pending slot ไว้
• การดำเนินการ cron ทั้งหมดจะสร้างบันทึก background task
• เมื่อ Gateway เริ่มทำงาน jobs แบบ isolated agent-turn ที่เลยกำหนดแล้วจะถูกกำหนดเวลาใหม่ให้ออกจากช่วง channel-connect แทนที่จะ replay ทันที เพื่อให้การเริ่มต้น Discord/Telegram และการตั้งค่า native-command ยังคงตอบสนองได้ดีหลังรีสตาร์ต
• Jobs แบบครั้งเดียว (--at) จะลบตัวเองหลังสำเร็จตามค่าเริ่มต้น
• การรัน cron แบบ isolated จะพยายามปิด browser tabs/processes ที่ติดตามไว้สำหรับ session cron:<jobId> ของตนเมื่อการรันเสร็จสิ้น เพื่อไม่ให้การทำ browser automation แบบแยกตัวทิ้ง processes กำพร้าไว้
• การรัน cron แบบ isolated ที่ได้รับสิทธิ์ cron self-cleanup แบบแคบยังสามารถอ่านสถานะ scheduler, รายการ current job ของตนที่ถูกกรองเฉพาะตัวเอง และประวัติการรันของ job นั้นได้ เพื่อให้การตรวจสอบ status/heartbeat ตรวจสอบ schedule ของตนเองได้โดยไม่ต้องได้สิทธิ์แก้ไข cron ที่กว้างกว่า
• การรัน cron แบบ isolated ยังป้องกัน stale acknowledgement replies ด้วย หากผลลัพธ์แรกเป็นเพียง interim status update (on it, pulling everything together และคำใบ้ที่คล้ายกัน) และไม่มี descendant subagent run ที่ยังรับผิดชอบคำตอบสุดท้ายอยู่ OpenClaw จะ prompt ซ้ำหนึ่งครั้งเพื่อขอผลลัพธ์จริงก่อนส่งมอบ
• การรัน cron แบบ isolated จะเลือกใช้ structured execution-denial metadata จาก embedded run ก่อน จากนั้นจึง fallback ไปยัง final summary/output markers ที่รู้จัก เช่น SYSTEM_RUN_DENIED และ INVALID_REQUEST เพื่อไม่ให้คำสั่งที่ถูกบล็อกถูกรายงานว่าเป็นการรันที่สำเร็จ
• การรัน cron แบบ isolated ยังถือว่า agent failures ระดับ run เป็น job errors แม้ไม่มี reply payload ถูกสร้างขึ้น เพื่อให้ model/provider failures เพิ่ม error counters และเรียก failure notifications แทนที่จะล้าง job ว่าสำเร็จ
• เมื่อ job แบบ isolated agent-turn ถึง timeoutSeconds cron จะ abort agent run พื้นฐานและให้ช่วง cleanup สั้น ๆ หาก run ไม่ drain การ cleanup ที่ Gateway เป็นเจ้าของจะ force-clear session ownership ของ run นั้นก่อนที่ cron จะบันทึก timeout เพื่อไม่ให้งาน chat ที่เข้าคิวค้างอยู่หลัง stale processing session
• หาก isolated agent-turn ค้างก่อน runner เริ่มต้นหรือก่อน model call แรก cron จะบันทึก phase-specific timeout เช่น setup timed out before runner start หรือ stalled before first model call (last phase: context-engine) watchdogs เหล่านี้ครอบคลุม embedded providers และ CLI-backed providers ก่อนที่ process ของ CLI ภายนอกจะเริ่มจริง และถูกจำกัดแยกจากค่า timeoutSeconds ที่ยาว เพื่อให้ cold-start/auth/context failures ปรากฏอย่างรวดเร็วแทนที่จะรอจนเต็มงบเวลาของ job

ประเภท schedule

Timestamps ที่ไม่มี timezone จะถูกถือว่าเป็น UTC เพิ่ม --tz America/New_York สำหรับการกำหนดเวลาแบบ local wall-clock

Expressions แบบ recurring top-of-hour จะถูก stagger อัตโนมัติได้สูงสุด 5 นาทีเพื่อลด load spikes ใช้ --exact เพื่อบังคับ timing ที่แม่นยำ หรือ --stagger 30s สำหรับ window ที่ระบุชัดเจน

Day-of-month และ day-of-week ใช้ตรรกะ OR

Cron expressions ถูก parse โดย croner เมื่อทั้ง fields day-of-month และ day-of-week ไม่ใช่ wildcard, croner จะ match เมื่อ field ใด field หนึ่ง match ไม่ใช่ทั้งคู่ นี่คือพฤติกรรมมาตรฐานของ 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

สิ่งนี้จะ fire ประมาณ 5-6 ครั้งต่อเดือนแทนที่จะเป็น 0-1 ครั้งต่อเดือน OpenClaw ใช้พฤติกรรม OR เริ่มต้นของ Croner ที่นี่ หากต้องการบังคับทั้งสองเงื่อนไข ให้ใช้ modifier day-of-week + ของ Croner (0 9 15 * +1) หรือ schedule บน field หนึ่งแล้ว guard อีก field ใน prompt หรือ command ของ job

รูปแบบการดำเนินการ

ตัวเลือก payload สำหรับ isolated jobs

--model ใช้ selected allowed model เป็น primary model ของ job นั้น ไม่เหมือนกับ chat-session /model override: configured fallback chains ยังคงมีผลเมื่อ job primary ล้มเหลว หาก requested model ไม่ได้รับอนุญาตหรือ resolve ไม่ได้ cron จะทำให้ run ล้มเหลวด้วย explicit validation error แทนที่จะ fallback ไปยัง agent/default model selection ของ job แบบเงียบ ๆ

Cron jobs ยังสามารถมี payload-level fallbacks ได้ด้วย เมื่อมีอยู่ list นั้นจะแทนที่ configured fallback chain สำหรับ job ใช้ fallbacks: [] ใน job payload/API เมื่อคุณต้องการ strict cron run ที่ลองเฉพาะ selected model หาก job มี --model แต่ไม่มีทั้ง payload fallbacks และ configured fallbacks OpenClaw จะส่ง explicit empty fallback override เพื่อไม่ให้ agent primary ถูกต่อท้ายเป็น hidden extra retry target

ลำดับความสำคัญของการเลือก model สำหรับ isolated jobs คือ:

1. Gmail hook model override (เมื่อ run มาจาก Gmail และ override นั้นได้รับอนุญาต)
2. Per-job payload model
3. User-selected stored cron session model override
4. Agent/default model selection

Fast mode จะตาม resolved live selection ด้วย หาก selected model config มี params.fastMode, isolated cron จะใช้ค่านั้นตามค่าเริ่มต้น Stored session fastMode override ยังชนะ config ได้ทั้งสองทิศทาง

หาก isolated run เจอ live model-switch handoff, cron จะ retry ด้วย switched provider/model และ persist live selection นั้นสำหรับ active run ก่อน retry เมื่อ switch นั้นมี auth profile ใหม่มาด้วย cron จะ persist auth profile override นั้นสำหรับ active run ด้วย Retries ถูกจำกัด: หลังจาก initial attempt บวก switch retries 2 ครั้ง cron จะ abort แทนที่จะวน loop ตลอดไป

ก่อนที่การรัน Cron แบบแยกจะเข้าสู่ agent runner, OpenClaw จะตรวจสอบ endpoint ของ local provider ที่เข้าถึงได้สำหรับ provider ที่กำหนดค่าเป็น api: "ollama" และ api: "openai-completions" ซึ่งมี baseUrl เป็น loopback, private-network หรือ .local หาก endpoint นั้นหยุดทำงาน การรันจะถูกบันทึกเป็น skipped พร้อมข้อผิดพลาด provider/model ที่ชัดเจนแทนที่จะเริ่มการเรียก model ผลลัพธ์ของ endpoint จะถูกแคชไว้ 5 นาที ดังนั้นงานที่ถึงกำหนดจำนวนมากซึ่งใช้เซิร์ฟเวอร์ local Ollama, vLLM, SGLang หรือ LM Studio เดียวกันที่หยุดทำงาน จะใช้ probe ขนาดเล็กร่วมกันหนึ่งครั้งแทนที่จะสร้าง request storm การรัน provider-preflight ที่ถูกข้ามจะไม่เพิ่ม execution-error backoff; เปิดใช้ failureAlert.includeSkipped เมื่อต้องการการแจ้งเตือนการข้ามซ้ำ ๆ

การส่งมอบและเอาต์พุต

ใช้ --announce --channel telegram --to "-1001234567890" สำหรับการส่งไปยังช่องทาง สำหรับหัวข้อฟอรัม Telegram ให้ใช้ -1001234567890:topic:123; ผู้เรียกผ่าน RPC/config โดยตรงยังสามารถส่ง delivery.threadId เป็นสตริงหรือตัวเลขได้ด้วย เป้าหมาย Slack/Discord/Mattermost ควรใช้ prefix ที่ชัดเจน (channel:<id>, user:<id>) ID ห้อง Matrix แยกตัวพิมพ์เล็กใหญ่; ใช้ ID ห้องที่ตรงกันทุกตัวอักษรหรือรูปแบบ room:!room:server จาก Matrix

เมื่อการส่งแบบ announce ใช้ channel: "last" หรือละเว้น channel เป้าหมายที่มี prefix ของ provider เช่น telegram:123 สามารถเลือกช่องทางก่อนที่ Cron จะ fallback ไปยังประวัติ session หรือช่องทางเดียวที่กำหนดค่าไว้ เฉพาะ prefix ที่ Plugin ที่โหลดประกาศไว้เท่านั้นที่เป็นตัวเลือก provider หาก delivery.channel ถูกระบุอย่างชัดเจน prefix ของเป้าหมายต้องระบุ provider เดียวกัน เช่น channel: "whatsapp" พร้อม to: "telegram:123" จะถูกปฏิเสธแทนที่จะปล่อยให้ WhatsApp ตีความ Telegram ID เป็นหมายเลขโทรศัพท์ prefix สำหรับชนิดเป้าหมายและบริการ เช่น channel:<id>, user:<id>, imessage:<handle> และ sms:<number> ยังคงเป็นไวยากรณ์เป้าหมายที่ช่องทางเป็นเจ้าของ ไม่ใช่ตัวเลือก provider

สำหรับงานแบบแยก การส่งแชทจะถูกใช้ร่วมกัน หากมีเส้นทางแชทพร้อมใช้งาน agent สามารถใช้เครื่องมือ message ได้แม้งานจะใช้ --no-deliver หาก agent ส่งไปยังเป้าหมายที่กำหนดค่าไว้/ปัจจุบัน OpenClaw จะข้าม fallback announce มิฉะนั้น announce, webhook และ none จะควบคุมเฉพาะสิ่งที่ runner ทำกับการตอบกลับสุดท้ายหลังจากรอบ agent เท่านั้น

เมื่อ agent สร้าง reminder แบบแยกจากแชทที่ใช้งานอยู่ OpenClaw จะจัดเก็บเป้าหมายการส่งแบบสดที่เก็บรักษาไว้สำหรับเส้นทาง fallback announce คีย์ session ภายในอาจเป็นตัวพิมพ์เล็ก; เป้าหมายการส่งของ provider จะไม่ถูกสร้างใหม่จากคีย์เหล่านั้นเมื่อมีบริบทแชทปัจจุบันพร้อมใช้งาน

การส่ง announce แบบแฝงใช้ allowlist ของช่องทางที่กำหนดค่าไว้เพื่อตรวจสอบและเปลี่ยนเส้นทางเป้าหมายที่ล้าสมัย การอนุมัติจาก DM pairing-store ไม่ใช่ผู้รับ fallback automation; ตั้งค่า delivery.to หรือกำหนดค่ารายการ allowFrom ของช่องทางเมื่อ scheduled job ควรส่งไปยัง DM เชิงรุก

การแจ้งเตือนความล้มเหลวใช้เส้นทางปลายทางแยกต่างหาก:

• cron.failureDestination ตั้งค่า default ส่วนกลางสำหรับการแจ้งเตือนความล้มเหลว
• job.delivery.failureDestination override ค่านั้นต่อ job
• หากไม่ได้ตั้งค่าทั้งสองอย่างและ job ส่งผ่าน announce อยู่แล้ว ตอนนี้การแจ้งเตือนความล้มเหลวจะ fallback ไปยังเป้าหมาย announce หลักนั้น
• delivery.failureDestination รองรับเฉพาะ job ที่เป็น sessionTarget="isolated" เว้นแต่โหมดการส่งหลักจะเป็น webhook
• failureAlert.includeSkipped: true เลือกให้ job หรือนโยบายแจ้งเตือน Cron ส่วนกลางรับการแจ้งเตือน skipped-run ซ้ำ ๆ การรันที่ถูกข้ามจะเก็บตัวนับการข้ามต่อเนื่องแยกต่างหาก จึงไม่กระทบ execution-error backoff

ตัวอย่าง 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 สามารถเปิดเผย endpoint HTTP Webhook สำหรับ trigger ภายนอกได้ เปิดใช้ใน config:

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

การยืนยันตัวตน

ทุก request ต้องมี hook token ผ่าน header:

• Authorization: Bearer <token> (แนะนำ)
• x-openclaw-token: <token>

token ใน query string จะถูกปฏิเสธ

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

เชื่อม trigger inbox ของ Gmail เข้ากับ OpenClaw ผ่าน Google PubSub

การตั้งค่าด้วย wizard (แนะนำ)

openclaw webhooks gmail setup --account [email protected]

คำสั่งนี้เขียน config hooks.gmail, เปิดใช้ preset Gmail และใช้ Tailscale Funnel สำหรับ push endpoint

การเริ่ม Gateway อัตโนมัติ

เมื่อ hooks.enabled=true และตั้งค่า hooks.gmail.account แล้ว Gateway จะเริ่ม gog gmail watch serve ตอน boot และต่ออายุ watch อัตโนมัติ ตั้งค่า 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:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Override model สำหรับ Gmail

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

การจัดการ job

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw 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 จำกัดทั้ง scheduled cron dispatch และการทำงานของ agent-turn แบบแยก agent turn ของ Cron แบบแยกใช้ lane การทำงานเฉพาะของคิวที่ชื่อ cron-nested ภายใน ดังนั้นการเพิ่มค่านี้จะทำให้การรัน Cron LLM อิสระคืบหน้าแบบขนานแทนที่จะเริ่มเฉพาะ wrapper Cron ชั้นนอก lane nested ที่ไม่ใช่ Cron และใช้ร่วมกันจะไม่ถูกขยายด้วยการตั้งค่านี้

state sidecar ตอน runtime ได้มาจาก cron.store: store แบบ .json เช่น ~/clawd/cron/jobs.json ใช้ ~/clawd/cron/jobs-state.json ส่วน path ของ store ที่ไม่มี suffix .json จะต่อท้ายด้วย -state.json

หากคุณแก้ไข jobs.json ด้วยมือ ให้เก็บ jobs-state.json ออกจาก source control OpenClaw ใช้ sidecar นั้นสำหรับ slot ที่ pending, marker ที่ active, metadata ของการรันล่าสุด และ schedule identity ที่บอก scheduler ว่า job ที่ถูกแก้ไขจากภายนอกต้องมี nextRunAtMs ใหม่

ปิดใช้ Cron: 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

ที่เกี่ยวข้อง

• ระบบอัตโนมัติ — กลไกระบบอัตโนมัติทั้งหมดโดยสรุป
• งานเบื้องหลัง — บัญชีแยกประเภทรายการงานสำหรับการดำเนินการ cron
• Heartbeat — เทิร์นเซสชันหลักตามรอบเวลา
• เขตเวลา — การกำหนดค่าเขตเวลา