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

Cron زمان‌بند داخلی Gateway است. کارها را پایدار نگه می‌دارد، agent را در زمان درست بیدار می‌کند و می‌تواند خروجی را به یک کانال چت یا نقطه پایانی 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 پایدار می‌ماند. اگر تعریف‌های cron را در git دنبال می‌کنید، jobs.json را دنبال کنید و jobs-state.json را در gitignore بگذارید.
• پس از جداسازی، نسخه‌های قدیمی‌تر OpenClaw می‌توانند jobs.json را بخوانند، اما ممکن است کارها را تازه در نظر بگیرند چون فیلدهای زمان اجرا اکنون در jobs-state.json قرار دارند.
• وقتی jobs.json در حالی ویرایش می‌شود که Gateway در حال اجرا یا متوقف است، OpenClaw فیلدهای زمان‌بندی تغییرکرده را با فراداده اسلات زمان اجرای در انتظار مقایسه می‌کند و مقدارهای کهنه nextRunAtMs را پاک می‌کند. بازنویسی‌های صرفا مربوط به قالب‌بندی یا فقط ترتیب کلیدها، اسلات در انتظار را حفظ می‌کنند.
• همه اجرای‌های cron رکوردهای کار پس‌زمینه ایجاد می‌کنند.
• هنگام راه‌اندازی Gateway، کارهای agent-turn ایزوله که موعدشان گذشته است، به‌جای بازپخش فوری، خارج از پنجره اتصال کانال دوباره زمان‌بندی می‌شوند تا راه‌اندازی Discord/Telegram و تنظیم فرمان‌های بومی پس از راه‌اندازی‌های دوباره پاسخ‌گو بماند.
• کارهای تک‌مرحله‌ای (--at) به‌طور پیش‌فرض پس از موفقیت، خودکار حذف می‌شوند.
• اجرای‌های cron ایزوله پس از کامل شدن اجرا، به‌صورت بهترین تلاش تب‌ها/فرایندهای مرورگر رهگیری‌شده را برای نشست cron:<jobId> خود می‌بندند تا اتوماسیون مرورگر جداشده فرایندهای بی‌صاحب باقی نگذارد.
• اجرای‌های cron ایزوله که مجوز محدود پاک‌سازی خودکار cron را دریافت می‌کنند، همچنان می‌توانند وضعیت زمان‌بند و فهرست خودفیلترشده‌ای از کار فعلی خود را بخوانند؛ بنابراین بررسی‌های وضعیت/Heartbeat می‌توانند زمان‌بندی خودشان را بدون دسترسی گسترده‌تر برای تغییر cron بررسی کنند.
• اجرای‌های cron ایزوله همچنین در برابر پاسخ‌های تأیید کهنه محافظت می‌کنند. اگر نتیجه اول فقط یک به‌روزرسانی وضعیت موقت باشد (on it، pulling everything together و راهنماهای مشابه) و هیچ اجرای subagent فرزند همچنان مسئول پاسخ نهایی نباشد، OpenClaw پیش از تحویل، یک‌بار دیگر برای نتیجه واقعی درخواست می‌دهد.
• اجرای‌های cron ایزوله ابتدا فراداده ساختاریافته انکار اجرا را از اجرای درون‌ساخت ترجیح می‌دهند، سپس به نشانگرهای شناخته‌شده خلاصه/خروجی نهایی مانند SYSTEM_RUN_DENIED و INVALID_REQUEST برمی‌گردند؛ بنابراین یک فرمان مسدودشده به‌عنوان اجرای موفق گزارش نمی‌شود.
• اجرای‌های cron ایزوله همچنین خطاهای agent در سطح اجرا را حتی وقتی هیچ payload پاسخی تولید نشده باشد، خطای کار تلقی می‌کنند؛ بنابراین خطاهای مدل/ارائه‌دهنده شمارنده‌های خطا را افزایش می‌دهند و به‌جای پاک کردن کار به‌عنوان موفق، اعلان‌های شکست را فعال می‌کنند.
• وقتی یک کار agent-turn ایزوله به timeoutSeconds می‌رسد، cron اجرای agent زیرین را لغو می‌کند و یک پنجره کوتاه برای پاک‌سازی به آن می‌دهد. اگر اجرا تخلیه نشود، پاک‌سازیِ متعلق به Gateway پیش از ثبت timeout توسط cron، مالکیت نشست آن اجرا را به‌اجبار پاک می‌کند تا کار چت صف‌شده پشت یک نشست پردازش کهنه باقی نماند.

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

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

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

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

عبارت‌های Cron توسط croner تجزیه می‌شوند. وقتی هر دو فیلد روز ماه و روز هفته غیر wildcard باشند، 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

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

# سبک‌های اجرا

# گزینه‌های payload برای کارهای ایزوله

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

اگر ورودی‌های قدیمی‌تر یا دستی‌ویرایش‌شده jobs.json مقدار payload.model را به‌صورت "default"، "null"، یک رشته خالی، یا JSON null ذخیره کرده‌اند، openclaw doctor --fix را اجرا کنید. Doctor این sentinelهای override پایدارشده نامعتبر را حذف می‌کند؛ زمان اجرا از آن‌ها به‌عنوان aliasهای fallback پشتیبانی نمی‌کند. برای استفاده از انتخاب عادی مدل agent/پیش‌فرض، فیلد مدل را حذف کنید.

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

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

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

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

اگر یک اجرای ایزوله به handoff تعویض مدل زنده برخورد کند، cron با provider/model تعویض‌شده retry می‌کند و پیش از retry، آن انتخاب زنده را برای اجرای فعال پایدار می‌کند. وقتی تعویض یک نمایه auth جدید هم همراه داشته باشد، cron آن override نمایه auth را نیز برای اجرای فعال پایدار می‌کند. retryها محدودند: پس از تلاش اولیه به‌اضافه ۲ retry تعویض، cron به‌جای حلقه بی‌پایان abort می‌کند.

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

# تحویل و خروجی

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

وقتی تحویل اعلام از 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 مقصد تحویل زندهٔ حفظ‌شده را برای مسیر اعلام پشتیبان ذخیره می‌کند. کلیدهای نشست داخلی ممکن است با حروف کوچک باشند؛ وقتی زمینهٔ چت فعلی در دسترس است، مقصدهای تحویل ارائه‌دهنده از آن کلیدها بازسازی نمی‌شوند.

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

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

• cron.failureDestination یک پیش‌فرض سراسری برای اعلان‌های شکست تنظیم می‌کند.
• job.delivery.failureDestination آن را برای هر کار بازنویسی می‌کند.
• اگر هیچ‌کدام تنظیم نشده باشد و کار از قبل از طریق announce تحویل دهد، اعلان‌های شکست اکنون به همان مقصد اصلی اعلام برمی‌گردند.
• delivery.failureDestination فقط در کارهای sessionTarget="isolated" پشتیبانی می‌شود، مگر اینکه حالت تحویل اصلی webhook باشد.
• failureAlert.includeSkipped: true یک کار یا سیاست هشدار سراسری cron را وارد هشدارهای تکراری اجرای ردشده می‌کند. اجراهای ردشده شمارندهٔ رد متوالی جداگانه‌ای نگه می‌دارند، بنابراین بر عقب‌نشینی خطای اجرا اثر نمی‌گذارند.

# نمونه‌های 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

# Webhooks

Gateway می‌تواند نقطه‌های پایانی HTTP Webhook را برای محرک‌های خارجی در معرض قرار دهد. در پیکربندی فعال کنید:

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

# احراز هویت

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

• 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

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

# راه‌اندازی جادویی (توصیه‌شده)

openclaw webhooks gmail setup --account [email protected]

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

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

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

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

# مرتبط

• اتوماسیون و Taskها — همهٔ سازوکارهای اتوماسیون در یک نگاه
• Taskهای پس‌زمینه — دفتر ثبت task برای اجرای cron
• Heartbeat — نوبت‌های دوره‌ای session اصلی
• Timezone — پیکربندی timezone