وظایف زمان‌بندی‌شده

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

openclaw cron runs --id <job-id>

Cron چگونه کار می‌کند

• Cron داخل فرایند Gateway اجرا می‌شود (نه داخل مدل).
• تعریف‌های کارها در ~/.openclaw/cron/jobs.json پایدار می‌مانند، بنابراین راه‌اندازی‌های دوباره زمان‌بندی‌ها را از دست نمی‌دهند.
• وضعیت اجرای زمان اجرا کنار آن در ~/.openclaw/cron/jobs-state.json پایدار می‌ماند. اگر تعریف‌های cron را در git ردیابی می‌کنید، jobs.json را ردیابی کنید و jobs-state.json را در gitignore قرار دهید.
• پس از جداسازی، نسخه‌های قدیمی‌تر OpenClaw می‌توانند jobs.json را بخوانند اما ممکن است کارها را تازه در نظر بگیرند، چون فیلدهای زمان اجرا اکنون در jobs-state.json قرار دارند.
• وقتی jobs.json هنگام اجرا یا توقف Gateway ویرایش شود، 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 همچنین شکست‌های عامل در سطح اجرا را حتی وقتی هیچ محتوای پاسخی تولید نشده باشد، خطای کار در نظر می‌گیرند؛ بنابراین شکست‌های مدل/ارائه‌دهنده شمارنده‌های خطا را افزایش می‌دهند و به‌جای پاک کردن کار به‌عنوان موفق، اعلان شکست را فعال می‌کنند.
• وقتی یک کار جداافتادهٔ نوبت عامل به timeoutSeconds برسد، cron اجرای عامل زیربنایی را لغو می‌کند و یک پنجرهٔ کوتاه برای پاک‌سازی به آن می‌دهد. اگر اجرا تخلیه نشود، پاک‌سازی تحت مالکیت Gateway پیش از اینکه cron وقفه را ثبت کند، مالکیت نشست آن اجرا را به‌اجبار پاک می‌کند تا کار گفت‌وگوی صف‌شده پشت یک نشست پردازش کهنه باقی نماند.
• اگر یک نوبت عامل جداافتاده پیش از شروع اجراکننده یا پیش از نخستین فراخوانی مدل متوقف شود، cron یک وقفهٔ ویژهٔ مرحله مانند setup timed out before runner start یا stalled before first model call (last phase: context-engine) ثبت می‌کند. این نگهبان‌ها ارائه‌دهنده‌های جاسازی‌شده و ارائه‌دهنده‌های متکی به CLI را پیش از اینکه فرایند CLI خارجی آن‌ها واقعا شروع شود پوشش می‌دهند، و مستقل از مقدارهای طولانی timeoutSeconds محدود می‌شوند تا شکست‌های شروع سرد/احراز هویت/زمینه به‌جای انتظار برای کل بودجهٔ کار، سریع آشکار شوند.

انواع زمان‌بندی

مهرهای زمانی بدون منطقهٔ زمانی به‌عنوان UTC در نظر گرفته می‌شوند. برای زمان‌بندی بر اساس ساعت دیواری محلی، --tz America/New_York را اضافه کنید.

عبارت‌های تکرارشوندهٔ ابتدای ساعت به‌طور خودکار تا ۵ دقیقه پراکنده می‌شوند تا جهش‌های بار کاهش یابد. برای اجبار به زمان‌بندی دقیق از --exact یا برای یک پنجرهٔ صریح از --stagger 30s استفاده کنید.

روز ماه و روز هفته از منطق OR استفاده می‌کنند

عبارت‌های Cron توسط croner تجزیه می‌شوند. وقتی هر دو فیلد روز ماه و روز هفته غیر wildcard باشند، croner زمانی تطبیق می‌دهد که هرکدام از فیلدها منطبق باشد، نه هر دو. این رفتار استاندارد cron به سبک Vixie است.

# 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

این به‌جای ۰ تا ۱ بار در ماه، حدود ۵ تا ۶ بار در ماه اجرا می‌شود. OpenClaw در اینجا از رفتار OR پیش‌فرض Croner استفاده می‌کند. برای الزام هر دو شرط، از تعدیل‌گر روز هفتهٔ + در Croner استفاده کنید (0 9 15 * +1) یا روی یک فیلد زمان‌بندی کنید و فیلد دیگر را در prompt یا فرمان کار خود محافظت کنید.

سبک‌های اجرا

گزینه‌های payload برای کارهای جداافتاده

--model از مدل مجاز انتخاب‌شده به‌عنوان مدل اصلی آن کار استفاده می‌کند. این با override یک نشست گفت‌وگو با /model یکسان نیست: زنجیره‌های fallback پیکربندی‌شده همچنان وقتی مدل اصلی کار شکست بخورد اعمال می‌شوند. اگر مدل درخواست‌شده مجاز نباشد یا قابل حل نباشد، cron به‌جای بازگشت بی‌صدا به انتخاب مدل عامل/پیش‌فرض کار، اجرا را با یک خطای اعتبارسنجی صریح شکست می‌دهد.

کارهای Cron همچنین می‌توانند fallbacks در سطح payload داشته باشند. در صورت وجود، آن فهرست جایگزین زنجیرهٔ fallback پیکربندی‌شده برای کار می‌شود. وقتی یک اجرای سخت‌گیرانهٔ cron می‌خواهید که فقط مدل انتخاب‌شده را امتحان کند، در payload/API کار از fallbacks: [] استفاده کنید. اگر یک کار --model داشته باشد اما fallbackهای payload یا پیکربندی‌شده نداشته باشد، OpenClaw یک override خالی صریح برای fallback می‌فرستد تا مدل اصلی عامل به‌عنوان هدف تلاش دوبارهٔ پنهان اضافه نشود.

اولویت انتخاب مدل برای کارهای جداافتاده چنین است:

1. override مدل hook در Gmail (وقتی اجرا از Gmail آمده باشد و آن override مجاز باشد)
2. model مربوط به payload هر کار
3. override مدل نشست cron ذخیره‌شدهٔ انتخاب‌شده توسط کاربر
4. انتخاب مدل عامل/پیش‌فرض

حالت سریع نیز از انتخاب زندهٔ حل‌شده پیروی می‌کند. اگر پیکربندی مدل انتخاب‌شده params.fastMode داشته باشد، cron جداافتاده به‌طور پیش‌فرض از آن استفاده می‌کند. یک override ذخیره‌شدهٔ نشست برای fastMode همچنان در هر دو جهت بر پیکربندی غلبه می‌کند.

اگر یک اجرای جداافتاده به واگذاری live model-switch برسد، cron با ارائه‌دهنده/مدل سوئیچ‌شده دوباره تلاش می‌کند و پیش از تلاش دوباره، آن انتخاب زنده را برای اجرای فعال پایدار می‌کند. وقتی سوئیچ یک پروفایل احراز هویت جدید هم همراه داشته باشد، cron override آن پروفایل احراز هویت را نیز برای اجرای فعال پایدار می‌کند. تلاش‌های دوباره محدود هستند: پس از تلاش اولیه به‌علاوهٔ ۲ تلاش دوبارهٔ سوئیچ، cron به‌جای حلقهٔ بی‌پایان، اجرا را لغو می‌کند.

پیش از آنکه یک اجرای Cron ایزوله وارد اجراکنندهٔ عامل شود، OpenClaw نقاط پایانی ارائه‌دهندهٔ محلی قابل‌دسترسی را برای ارائه‌دهنده‌های پیکربندی‌شدهٔ api: "ollama" و api: "openai-completions" که baseUrl آن‌ها loopback، شبکهٔ خصوصی یا .local است بررسی می‌کند. اگر آن نقطهٔ پایانی از کار افتاده باشد، اجرا به‌جای شروع یک فراخوانی مدل، با خطای روشن ارائه‌دهنده/مدل به‌صورت skipped ثبت می‌شود. نتیجهٔ نقطهٔ پایانی به‌مدت ۵ دقیقه در حافظهٔ نهان نگه داشته می‌شود، بنابراین بسیاری از کارهای موعددار که از همان سرور محلیِ ازکارافتادهٔ Ollama، vLLM، SGLang یا LM Studio استفاده می‌کنند، به‌جای ایجاد طوفان درخواست، در یک بررسی کوچک مشترک می‌شوند. اجراهای پروازِ پیش از ارائه‌دهنده که رد شده‌اند، backoff خطای اجرا را افزایش نمی‌دهند؛ وقتی اعلان‌های تکراریِ رد شدن را می‌خواهید، failureAlert.includeSkipped را فعال کنید.

تحویل و خروجی

برای تحویل به کانال، از --announce --channel telegram --to "-1001234567890" استفاده کنید. برای موضوعات انجمن Telegram، از -1001234567890:topic:123 استفاده کنید؛ فراخوان‌های مستقیم RPC/پیکربندی نیز می‌توانند delivery.threadId را به‌صورت رشته یا عدد ارسال کنند. مقصدهای Slack/Discord/Mattermost باید از پیشوندهای صریح استفاده کنند (channel:<id>، user:<id>). شناسه‌های اتاق Matrix به بزرگی و کوچکی حروف حساس هستند؛ از شناسهٔ دقیق اتاق یا قالب room:!room:server از Matrix استفاده کنید.

وقتی تحویل announce از channel: "last" استفاده می‌کند یا channel را حذف می‌کند، یک مقصد با پیشوند ارائه‌دهنده مانند telegram:123 می‌تواند پیش از آنکه cron به تاریخچهٔ نشست یا یک کانال پیکربندی‌شدهٔ واحد بازگردد، کانال را انتخاب کند. فقط پیشوندهایی که Plugin بارگذاری‌شده اعلام کرده است انتخابگر ارائه‌دهنده هستند. اگر delivery.channel صریح باشد، پیشوند مقصد باید همان ارائه‌دهنده را نام ببرد؛ برای مثال، channel: "whatsapp" همراه با to: "telegram:123" رد می‌شود، به‌جای اینکه اجازه دهد WhatsApp شناسهٔ Telegram را به‌عنوان شماره تلفن تفسیر کند. پیشوندهای نوع مقصد و سرویس مانند channel:<id>، user:<id>، imessage:<handle> و sms:<number> همچنان نحو مقصدِ متعلق به کانال هستند، نه انتخابگر ارائه‌دهنده.

برای کارهای ایزوله، تحویل چت مشترک است. اگر مسیر چت در دسترس باشد، عامل حتی وقتی کار از --no-deliver استفاده می‌کند می‌تواند از ابزار message استفاده کند. اگر عامل به مقصد پیکربندی‌شده/فعلی ارسال کند، OpenClaw اعلام جایگزین را رد می‌کند. در غیر این صورت announce، webhook و none فقط کنترل می‌کنند اجراکننده پس از نوبت عامل با پاسخ نهایی چه کند.

وقتی یک عامل از یک چت فعال یادآور ایزوله می‌سازد، OpenClaw مقصد تحویل زندهٔ حفظ‌شده را برای مسیر اعلام جایگزین ذخیره می‌کند. کلیدهای نشست داخلی ممکن است با حروف کوچک باشند؛ وقتی زمینهٔ چت فعلی در دسترس است، مقصدهای تحویل ارائه‌دهنده از آن کلیدها بازسازی نمی‌شوند.

تحویل announce ضمنی از allowlistهای کانال پیکربندی‌شده برای اعتبارسنجی و تغییرمسیر مقصدهای کهنه استفاده می‌کند. تأییدهای pairing-store پیام مستقیم گیرندهٔ اتوماسیون جایگزین نیستند؛ وقتی یک کار زمان‌بندی‌شده باید به‌صورت پیش‌دستانه به یک پیام مستقیم ارسال شود، delivery.to را تنظیم کنید یا ورودی allowFrom کانال را پیکربندی کنید.

اعلان‌های شکست مسیر مقصد جداگانه‌ای را دنبال می‌کنند:

• cron.failureDestination یک پیش‌فرض سراسری برای اعلان‌های شکست تنظیم می‌کند.
• job.delivery.failureDestination آن را برای هر کار بازنویسی می‌کند.
• اگر هیچ‌کدام تنظیم نشده باشند و کار از قبل از طریق announce تحویل بدهد، اعلان‌های شکست اکنون به همان مقصد announce اصلی بازمی‌گردند.
• delivery.failureDestination فقط روی کارهای sessionTarget="isolated" پشتیبانی می‌شود، مگر اینکه حالت تحویل اصلی webhook باشد.
• failureAlert.includeSkipped: true یک کار یا سیاست هشدار Cron سراسری را وارد هشدارهای تکراریِ اجرای ردشده می‌کند. اجراهای ردشده شمارندهٔ رد شدن متوالی جداگانه‌ای نگه می‌دارند، بنابراین روی 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 می‌تواند نقاط پایانی HTTP webhook را برای محرک‌های خارجی در معرض دسترس قرار دهد. در پیکربندی فعال کنید:

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

احراز هویت

هر درخواست باید توکن hook را از طریق header شامل کند:

• Authorization: Bearer <token> (توصیه‌شده)
• x-openclaw-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

محرک‌های inbox در Gmail را از طریق Google PubSub به OpenClaw وصل کنید.

راه‌اندازی با wizard (توصیه‌شده)

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

این فرمان پیکربندی hooks.gmail را می‌نویسد، preset مربوط به Gmail را فعال می‌کند، و از Tailscale Funnel برای نقطهٔ پایانی push استفاده می‌کند.

شروع خودکار Gateway

وقتی hooks.enabled=true و hooks.gmail.account تنظیم شده باشد، Gateway هنگام boot فرمان gog gmail watch serve را شروع می‌کند و 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: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",    },  },}

مدیریت کارها

# 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 هم dispatch زمان‌بندی‌شدهٔ cron و هم اجرای نوبت عامل ایزوله را محدود می‌کند. نوبت‌های عامل Cron ایزوله به‌صورت داخلی از مسیر اجرای اختصاصی cron-nested صف استفاده می‌کنند، بنابراین افزایش این مقدار باعث می‌شود اجراهای مستقل LLM در cron به‌جای اینکه فقط wrapperهای بیرونی cron خود را شروع کنند، به‌صورت موازی پیش بروند. مسیر مشترک غیر cron یعنی nested با این تنظیم گسترش داده نمی‌شود.

sidecar وضعیت runtime از cron.store مشتق می‌شود: یک store با پسوند .json مانند ~/clawd/cron/jobs.json از ~/clawd/cron/jobs-state.json استفاده می‌کند، درحالی‌که مسیر store بدون پسوند .json، -state.json را اضافه می‌کند.

اگر jobs.json را دستی ویرایش می‌کنید، jobs-state.json را از کنترل نسخه بیرون نگه دارید. OpenClaw از آن sidecar برای slotهای در انتظار، نشانگرهای فعال، فرادادهٔ آخرین اجرا، و هویت زمان‌بندی استفاده می‌کند که به زمان‌بند می‌گوید چه زمانی یک کار ویرایش‌شده از بیرون به 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 — نوبت‌های دوره‌ای نشست اصلی
• منطقه زمانی — پیکربندی منطقه زمانی