کارهای زمان‌بندی‌شده

Cron زمان‌بند داخلی Gateway است. کارها را به‌صورت پایدار نگه می‌دارد، عامل را در زمان مناسب بیدار می‌کند و می‌تواند خروجی را به یک کانال گفت‌وگو، یک Webhook یا هیچ مقصدی تحویل دهد.

شروع سریع

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Reminder" \  --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 اجرا می‌شود، نه درون مدل. برای فعال‌شدن زمان‌بندی‌ها، Gateway باید در حال اجرا باشد.
• تعریف کارها، وضعیت زمان اجرا و تاریخچه اجرا در پایگاه داده مشترک وضعیت SQLite متعلق به OpenClaw به‌صورت پایدار نگه‌داری می‌شوند؛ بنابراین راه‌اندازی مجدد باعث از دست رفتن زمان‌بندی‌ها نمی‌شود.
• هر اجرای Cron یک رکورد وظیفه پس‌زمینه ایجاد می‌کند.
• کارهای یک‌باره (--at) به‌طور پیش‌فرض پس از موفقیت خودکار حذف می‌شوند؛ برای نگه‌داشتن آن‌ها، --keep-after-run را ارسال کنید.
• بودجه زمانی واقعی هر اجرا: در صورت تنظیم، --timeout-seconds. در غیر این صورت، کارهای نوبت عامل ایزوله/جداشده پیش از آنکه مهلت زمانی نوبت عامل زیربنایی (agents.defaults.timeoutSeconds، با مقدار پیش‌فرض 48 ساعت) اعمال شود، به‌وسیله نگهبان 60 دقیقه‌ای خود Cron محدود می‌شوند؛ کارهای فرمان به‌طور پیش‌فرض 10 دقیقه و محموله‌های اسکریپت به‌طور پیش‌فرض 5 دقیقه مهلت دارند.
• هنگام راه‌اندازی Gateway، کارهای نوبت عامل ایزوله‌ای که موعدشان گذشته است، به‌جای بازپخش فوری دوباره زمان‌بندی می‌شوند تا کارهای راه‌اندازی اولیه مدل/ابزار خارج از بازه اتصال کانال انجام شوند.
• اگر openclaw agent را از Cron سیستم یا زمان‌بند خارجی دیگری اجرا می‌کنید، با وجود اینکه CLI از قبل SIGTERM/SIGINT را مدیریت می‌کند، آن را با سازوکار تشدید تا کشتن اجباری محصور کنید. اجراهای متکی به Gateway از Gateway می‌خواهند اجراهای پذیرفته‌شده را لغو کند؛ اجراهای --local نیز همان سیگنال لغو را دریافت می‌کنند. برای timeout در GNU، timeout -k 60 600 openclaw agent ... را به timeout 600 ... ساده ترجیح دهید — مقدار -k آخرین راه‌حل است، اگر فرایند نتواند به‌موقع تخلیه شود. برای واحدهای systemd، پیش از کشتن نهایی از سیگنال توقف SIGTERM با یک بازه مهلت (TimeoutStopSec) استفاده کنید. استفاده مجدد از یک --run-id در زمانی که اجرای اصلی Gateway هنوز فعال است، به‌جای شروع اجرای دوم، مورد تکراری را در حال اجرا گزارش می‌کند.

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

برچسب‌های زمانی بدون منطقه زمانی، UTC در نظر گرفته می‌شوند. برای تفسیر یک تاریخ‌وزمان --at بدون آفست یا ارزیابی عبارت Cron در آن منطقه زمانی IANA، --tz America/New_York را اضافه کنید. عبارت‌های Cron بدون --tz از منطقه زمانی میزبان Gateway استفاده می‌کنند. --tz همراه با --every یا --on-exit معتبر نیست.

عبارت‌های تکرارشونده ابتدای ساعت (دقیقه 0 با فیلد ساعت جای‌نگهدار) برای کاهش جهش بار، به‌طور خودکار تا 5 دقیقه پراکنده می‌شوند. برای اجبار زمان‌بندی دقیق از --exact یا برای یک بازه صریح از --stagger 30s استفاده کنید (فقط زمان‌بندی‌های Cron).

مهاجرت وظیفه Heartbeat

محیط موقت قدیمی Heartbeat از یک بلوک ساختاریافته tasks: پشتیبانی می‌کرد. پس از ارتقا، openclaw doctor --fix را اجرا کنید تا هر ورودی به یک کار عادی و قابل‌ویرایش Cron در نشست اصلی تبدیل شود. Doctor فاصله و زمان اجرای قبلی را حفظ می‌کند، پیش از حذف بلوک کارها را می‌سازد و در اجرای مجدد، همان کلیدهای اعلان را با اطمینان همگرا می‌کند.

این کارهای مهاجرت‌یافته محموله‌های عمومی systemEvent را حمل می‌کنند؛ بنابراین openclaw cron list، get، edit و remove به‌همراه ابزار Cron آن‌ها را مانند سایر کارها مدیریت می‌کنند. اجرای آن‌ها از بیدارسازی محافظت‌شده وظیفه Heartbeat استفاده می‌کند: ساعات فعال، حداقل فاصله، کنترل سیلاب و تلاش‌های مجدد هنگام مشغول‌بودن همچنان اعمال می‌شوند، درحالی‌که Cron آهنگ مستقل هر وظیفه را مدیریت می‌کند. کارهایی که موعدشان در یک بازه ادغام مشترک است، می‌توانند یک نوبت Heartbeat را به‌اشتراک بگذارند. یک رخداد زمان‌بندی‌شده خارج از ساعات فعال Heartbeat نادیده گرفته می‌شود و در رخداد بعدی کار دوباره امتحان می‌شود.

محیط موقت Heartbeat اکنون فقط نثر پایش است. Heartbeatهای زمان اجرا، متن tasks: را به‌عنوان زمان‌بندی تجزیه نمی‌کنند؛ کار تکرارشونده جدید را با Cron ایجاد کنید.

منابع جریانی

یک زمان‌بندی جریانی، فرمان argv نوشته‌شده توسط اپراتور را تحت Gateway در حال اجرا نگه می‌دارد و کار را از خطوط stdout و stderr آن فعال می‌کند. زمان‌بندی‌های جریانی رویدادمحورند، هرگز موعد زمانی ندارند و به cron.triggers.enabled: true نیاز دارند، زیرا فرمان طولانی‌مدت همان رده اعتماد اجرای بدون نظارت اسکریپت‌های محرک را دارد. غیرفعال‌کردن یا حذف کار، فرایند را متوقف می‌کند؛ خاموش‌شدن Gateway تا برچیدن درخت فرایند منتظر می‌ماند. شکست‌های سریع با عقب‌نشینی خطای داخلی Cron دوباره راه‌اندازی می‌شوند. پنج اجرای متوالی کوتاه‌تر از 60 ثانیه، کار را در وضعیت خطا نگه می‌دارند و از مسیر عادی هشدار شکست استفاده می‌کنند؛ برای پاک‌کردن سقف راه‌اندازی مجدد، کار را به‌صورت دستی دوباره فعال کنید.

openclaw cron add \  --name "Build event stream" \  --stream-command '["node","scripts/build-events.mjs"]' \  --stream-mode match \  --stream-match '^(failed|recovered):' \  --stream-batch-ms 250 \  --session isolated \  --message "Investigate these build events."

mode: "line" (مقدار پیش‌فرض) هر خط را می‌پذیرد. mode: "match" فقط خطوط منطبق با عبارت منظم کامپایل‌شده match را می‌پذیرد. یک دسته پس از batchMs سکوت (پیش‌فرض 250 میلی‌ثانیه، محدودشده به 50–5000) یا در maxBatchBytes (پیش‌فرض 16384، محدودشده به 1024–65536) بسته می‌شود. در سقف بایت، دسته با [truncated] پایان می‌یابد. حالت تطبیق همیشه خطوط کامل را با متن کاملشان ارزیابی می‌کند، حتی پس از maxBatchBytes (فقط دسته تحویلی بریده می‌شود)؛ خطی که در حد محدود دریافت خام بریده شده فقط یک پیشوند است، پس نامنطبق در نظر گرفته می‌شود تا الگوی دارای لنگر انتهایی روی بخش بریده‌شده فعال نشود. دسته به متن رویداد سیستم یا پیام نوبت عامل افزوده می‌شود. محموله‌های فرمان برای زمان‌بندی‌های جریانی رد می‌شوند، زیرا فرمان منبع و فرمان محموله مالکیت فرایندی مبهمی خواهند داشت.

برای هر کار فقط یک فعال‌سازی محموله و یک دسته در انتظار محدود نگه داشته می‌شود. خطوطی که هنگام اجرای محموله یا پیش از سپری‌شدن فاصله داخلی 30 ثانیه‌ای محرک می‌رسند، به‌جای ساختن یک صف نامحدود، در همان دسته در انتظار ادغام می‌شوند. یک مالک سریال‌شده، حذف‌های گیت، خطاهای محموله و ارسال‌های هنگام اجرا‌نبودن را در streamDroppedBatches ثبت می‌کند؛ ادغام‌های محدود streamCoalescedBatches را افزایش می‌دهند. محموله‌های شکست‌خورده دوباره امتحان نمی‌شوند، زیرا ممکن است هم‌توان نباشند. هویت منطقی منبع در راه‌اندازی‌های مجدد فرزند تحت نظارت ثابت می‌ماند، اما با غیرفعال‌شدن، حذف یا جایگزینی منبع تغییر می‌کند؛ بنابراین دسته‌های صف‌شده منبع بازنشسته حتی پس از ویرایش A به B و دوباره به A نمی‌توانند فعال شوند. پس از تکمیل توقف، فراخوانی‌های دیرهنگام یک فرزند قدیمی بی‌اثرند. V1 شامل منبع بومی WebSocket نیست؛ آن را با یک فرمان argv مانند websocat wss://example.invalid/events پل بزنید.

وقتی یک کار جریانی trigger.script نیز دارد، گیت برای هر دسته بسته‌شده یک‌بار اجرا می‌شود. دسته فعلی به‌صورت رشته عمیقاً منجمدشده trigger.streamBatch در کنار trigger.state در دسترس است. fire: false پس از پایدارسازی وضعیت گیت، آن دسته را حذف می‌کند. fire: true معناشناسی موجود پیام محرک را حفظ می‌کند و سپس دسته را به محموله حاصل می‌افزاید. یک کار جریانی می‌تواند به‌جای آن از محموله اسکریپت بدون گیت شرط استفاده کند؛ آن اسکریپت دسته را از طریق همان مقدار trigger.streamBatch دریافت می‌کند. ترکیب محموله اسکریپت با گیت شرط رد می‌شود، زیرا هر دو مالک شیار پایدار trigger.state خواهند بود.

آهنگ پویا (تنظیم سرعت)

کارهای تکرارشونده می‌توانند pacing.min و/یا pacing.max را روی رشته‌های مدت‌زمانی مانند 15m یا 4h تنظیم کنند؛ دست‌کم یک کران الزامی است. از --pacing-min و --pacing-max همراه با cron add|edit استفاده کنید (--clear-pacing هر دو کران را حذف می‌کند).

در طول یک اجرای ایزوله، یک کار با زمان‌بندی تطبیقی می‌تواند ابزار cron را با action: "next_check" و in: "30m" فراخوانی کند. پیشنهاد فقط بر همان کاری اعمال می‌شود که در حال حاضر اجرا می‌شود و از زمان تکمیل موفق اجرای آن محاسبه می‌شود. OpenClaw بدون نمایش پیام، آن را به محدوده‌های پیکربندی‌شده محدود می‌کند.

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

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

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

# مقصود: «ساعت 9 صبح روز پانزدهم، فقط اگر دوشنبه باشد»# نتیجهٔ واقعی: «ساعت 9 صبح در هر روز پانزدهم و ساعت 9 صبح در هر دوشنبه»0 9 15 * 1

این عبارت به‌جای 0-1 بار در ماه، تقریباً 5-6 بار در ماه اجرا می‌شود. برای الزام هر دو شرط، از اصلاح‌گر روز هفتهٔ + در croner ‏(0 9 15 * +1) استفاده کنید، یا زمان‌بندی را بر اساس یکی از فیلدها انجام دهید و فیلد دیگر را در اعلان یا فرمان کار خود بررسی کنید.

فعال‌سازهای رویداد (ناظرهای شرط)

یک فعال‌ساز رویداد، اسکریپت شرطیِ بدون رابطی را به یک برنامهٔ زمانی every، ‏cron یا stream اضافه می‌کند. برنامه‌های زمانی مبتنی بر زمان، آن را در موعد مقرر ارزیابی می‌کنند؛ برنامه‌های زمانی جریانی، آن را برای هر دستهٔ بسته‌شده ارزیابی می‌کنند. Cron فقط زمانی بار عادی را اجرا می‌کند که اسکریپت fire: true را برگرداند:

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // فقط زمانی فعال می‌شود که وضعیت مشاهده‌شده با ارزیابی قبلی متفاوت باشد.    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "تغییر وضعیت CI را بررسی کنید." },}

اسکریپت باید { fire, message?, state? } را برگرداند. وضعیت JSON قبلی به‌صورت trigger.state که به‌شکل عمیق منجمد شده است در دسترس قرار دارد؛ دروازه‌های جریان نیز دستهٔ فعلی را به‌صورت trigger.streamBatch دریافت می‌کنند. برای ماندگارکردن آن، مقدار جدیدی برای state برگردانید. وضعیت به 16 KB محدود است. وقتی نتیجه‌ای که باعث فعال‌شدن شده شامل message باشد، Cron پیش از اجرا آن را به متن رویداد سیستمی یا پیام نوبت عامل می‌افزاید. once: true پس از نخستین بار موفقیت‌آمیز اجرای بار فعال‌شده، کار را غیرفعال می‌کند.

fire: false وضعیت ارزیابی و شمارنده‌ها را ماندگار می‌کند، سپس بدون ایجاد سابقهٔ اجرا دوباره زمان‌بندی می‌کند. اگر اجرای بار فعال‌شده ناموفق باشد، state برگشتی ماندگار نمی‌شود — ارزیابی بعدی وضعیت قبلی را می‌بیند و می‌تواند دوباره فعال شود؛ بنابراین اسکریپت‌ها را به‌صورت بررسی‌های فقط‌خواندنی بنویسید و کنش‌ها را در بار نگه دارید. برنامه‌های زمانی فعال‌ساز حداقل فاصلهٔ داخلی 30 ثانیه دارند. هر ارزیابی بودجهٔ زمانی دیواری 30 ثانیه و حداکثر 5 فراخوانی ابزار دارد.

ناظرها را پیرامون وضعیت قابل اقدام طراحی کنید، نه فقط موفقیت: ناظری که هنگام ناموفق‌شدن یا پایان مهلت بررسی خود ساکت می‌شود، با وجود خرابی سالم به نظر می‌رسد. مشاهده را با trigger.state مقایسه کنید و برای حذف موارد تکراری وضعیت تازه‌ای برگردانید؛ به حافظهٔ مدل یا فرایند متکی نباشید. هنگام فعال‌شدن، message را خودبسنده کنید، زیرا به زمینهٔ کامل رویدادِ اجرای فعال‌شده تبدیل می‌شود.

یک ناظر از فایل اسکریپت محلی ایجاد کنید (- اسکریپت را از ورودی استاندارد می‌خواند):

openclaw cron add \  --name "ناظر CI مربوط به PR" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "به تغییر وضعیت CI پاسخ دهید" \  --session isolated

بارها

هر کار دقیقاً یک نوع بار دارد که با پرچم انتخاب می‌شود:

یک نوع بار دیگر، heartbeat، متعلق به سیستم است: Gateway برای هر عامل دارای Heartbeat، یک کار پایش Heartbeat را همگرا می‌کند (به Heartbeat مراجعه کنید). این بار در cron list --all ظاهر می‌شود، اما از طریق CLI یا API قابل ایجاد یا ویرایش نیست. پیکربندی Heartbeat هنگام راه‌اندازی، بارگذاری مجدد پیکربندی یا به‌وسیلهٔ openclaw doctor --fix در برنامهٔ زمانی پایش ماندگار نوشته می‌شود. وقتی Cron غیرفعال باشد، پایشگر تیک نمی‌زند و هیچ زمان‌سنج جایگزینی برای Heartbeat اجرا نمی‌شود.

گزینه‌های نوبت عامل

کارهای جدیدی که می‌توانند ابزار اجرا کنند، همیشه یک سیاست ابزار صریح ذخیره می‌کنند. کارهایی که یک عامل ایجاد می‌کند به ابزارهای در دسترس همان نوبت ایجادکننده محدود می‌شوند و عامل نمی‌تواند فهرست ذخیره‌شده را گسترش دهد. کارهایی که یک اپراتور احراز هویت‌شده بدون --tools ایجاد می‌کند، یک سیاست نامحدود * ذخیره می‌کنند؛ cron edit --clear-tools آن سیاست نامحدود صریح را بازمی‌گرداند. کارهای موجودی که پیش از سیاست ابزار صریح ایجاد شده‌اند، رفتار فعلی خود را حفظ می‌کنند تا زمانی که سیاست ابزارشان به‌صراحت ویرایش شود یا کار دوباره ایجاد شود.

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

اولویت انتخاب مدل برای کارهای ایزوله، از بیشترین به کمترین:

1. بار مختص کار model (پیکربندی صریح؛ مدل غیرمجاز اجرا را ناموفق می‌کند)
2. جایگزینی مدل هوک Gmail (فقط زمانی که اجرا از Gmail آمده باشد و آن جایگزینی مجاز باشد)
3. جایگزینی مدل ذخیره‌شدهٔ نشست Cron که کاربر انتخاب کرده است
4. انتخاب مدل عامل/پیش‌فرض

حالت سریع از انتخاب زندهٔ حل‌شده پیروی می‌کند. اگر پیکربندی مدل انتخاب‌شده params.fastMode داشته باشد، Cron ایزوله به‌طور پیش‌فرض از آن استفاده می‌کند؛ جایگزینی ذخیره‌شدهٔ نشست fastMode (و پس از آن fastModeDefault عامل) همچنان در هر دو جهت بر پیکربندی مدل اولویت دارد. حالت خودکار از آستانهٔ params.fastAutoOnSeconds مدل استفاده می‌کند که مقدار پیش‌فرض آن 60 ثانیه است.

اگر اجرا با واگذاری زندهٔ تغییر مدل روبه‌رو شود، Cron با ارائه‌دهنده/مدل تغییرکرده دوباره تلاش می‌کند و آن انتخاب (و هر نمایهٔ احراز هویت جدید) را برای اجرای فعال ماندگار می‌کند. تلاش‌های مجدد محدودند: پس از تلاش اولیه و 2 تلاش مجدد برای تغییر، Cron به‌جای ورود به حلقه اجرا را متوقف می‌کند.

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

بارهای فرمان

بارهای فرمان، اسکریپت‌های قطعی را در زمان‌بند Gateway بدون آغاز نوبت پشتیبانی‌شده توسط مدل اجرا می‌کنند. آن‌ها روی میزبان Gateway اجرا می‌شوند، stdout/stderr را ضبط می‌کنند، اجرا را در سابقهٔ Cron ثبت می‌کنند و همان حالت‌های تحویل announce، ‏webhook و none کارهای نوبت عامل را دوباره به‌کار می‌گیرند.

openclaw cron create "*/15 * * * *" \  --name "کاوش عمق صف" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> مقدار argv: ["sh", "-lc", <shell>] را ذخیره می‌کند. برای اجرای دقیق argv بدون تجزیهٔ پوسته، از --command-argv '["node","scripts/report.mjs"]' استفاده کنید. گزینه‌های اختیاری --command-env KEY=VALUE (قابل تکرار)، ‏--command-input، ‏--timeout-seconds (پیش‌فرض 10 دقیقه)، ‏--no-output-timeout-seconds و --output-max-bytes محیط فرایند، ورودی استاندارد و محدودیت‌های خروجی را کنترل می‌کنند.

متن تحویلی از خروجی فرایند استخراج می‌شود: stdout غیرخالی اولویت دارد؛ اگر stdout خالی و stderr غیرخالی باشد، stderr تحویل داده می‌شود؛ اگر هر دو موجود باشند، Cron یک بلوک کوچک stdout: / stderr: ارسال می‌کند. کد خروج 0 اجرا را به‌صورت ok ثبت می‌کند؛ خروج غیرصفر، سیگنال، پایان مهلت یا پایان مهلت بدون خروجی، error ثبت می‌کند و می‌تواند هشدارهای شکست را فعال کند. فرمانی که فقط NO_REPLY را چاپ کند، از سرکوب عادی توکن سکوت در Cron استفاده می‌کند و هیچ‌چیز به گفت‌وگو ارسال نمی‌کند.

بارهای اسکریپت

بارهای اسکریپت به‌صورت بدون رابط و در همان اجراکننده حالت کدِ اسکریپت‌های راه‌انداز اجرا می‌شوند، بدون آنکه نوبت محاوره‌ای عامل آغاز شود. پیش از ایجاد یا اجرای آن‌ها، cron.triggers.enabled را فعال کنید؛ این دروازه خودکارسازی خطرناک هم اسکریپت‌های راه‌انداز و هم بارهای اسکریپت را پوشش می‌دهد. کارهای اسکریپتی فقط از اهداف نشست main و isolated پشتیبانی می‌کنند.

openclaw cron create "0 * * * *" \  --name "بررسی ساعتی صف" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

برای خواندن JavaScript از فایل یا ورودی استاندارد، از --script <file|-> استفاده کنید. مهلت زمانی به‌طور پیش‌فرض 300 ثانیه است و حداکثر 900 ثانیه خواهد بود؛ بودجه ابزار به‌طور پیش‌فرض 50 فراخوانی است و حداکثر 200 فراخوانی خواهد بود. این بودجه‌های بار از بودجه‌های کوچک‌تر ارزیابی دروازه راه‌انداز جدا هستند.

اسکریپت می‌تواند شیئی با این فیلدهای اختیاری برگرداند:

• notify: متنی که از طریق حالت تحویل announce، webhook یا none کار تحویل داده می‌شود. در صورت حذف، چیزی تحویل داده نمی‌شود. برای یک کار main، متن به رویداد سیستمی تبدیل می‌شود.
• wake: مقدار "now" پس از قرار دادن notify در صف (یا یک رویداد فشرده تکمیل)، یک Heartbeat فوری درخواست می‌کند؛ مقدار "next-heartbeat" رویداد را برای Heartbeat بعدی در صف قرار می‌دهد.
• state: وضعیت JSON که به 16 KB محدود است و فقط پس از اجرای موفق ماندگار می‌شود. اجرای بعدی، مانند اسکریپت‌های راه‌انداز، یک نسخه ثابت‌شده را به‌صورت trigger.state دریافت می‌کند. چون آن فضای نام یک مالک ماندگار دارد، نمی‌توان بار اسکریپت را در همان کار با راه‌انداز شرطی ترکیب کرد.
• nextCheck: مدتی مانند "15m". این مقدار فقط برای کارهایی معتبر است که آهنگ اجرا در آن‌ها فعال شده باشد و از همان محدودسازی آهنگِ پیشنهادهای نوبت عامل استفاده می‌کند.

پرتاب استثنا، پایان مهلت زمانی، اتمام بودجه ابزار، نتایج نامعتبر و nextCheck بدون آهنگ اجرا، خطاهای عادی اجرای Cron هستند: بدون ماندگار کردن وضعیت بازگشتی، وارد تاریخچه اجرا، عقب‌نشینی و مدیریت هشدار خرابی می‌شوند.

سبک‌های اجرا

تحویل و خروجی

برای تحویل کانالی از --announce --channel telegram --to "-1001234567890" استفاده کنید. برای موضوعات انجمن Telegram از -1001234567890:topic:123 استفاده کنید؛ OpenClaw همچنین شکل کوتاه -1001234567890:123 متعلق به Telegram را می‌پذیرد. فراخوان‌های مستقیم RPC/پیکربندی می‌توانند 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 هدف زنده تحویلِ حفظ‌شده را برای مسیر اعلام جایگزین ذخیره می‌کند. کلیدهای داخلی نشست ممکن است با حروف کوچک باشند؛ وقتی زمینه گفت‌وگوی جاری در دسترس است، اهداف تحویل ارائه‌دهنده از آن کلیدها بازسازی نمی‌شوند.

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

اعلان‌های خرابی

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

• cron.failureDestination یک مقدار پیش‌فرض سراسری برای اعلان‌های خرابی تنظیم می‌کند.
• job.delivery.failureDestination آن را برای هر کار بازنویسی می‌کند.
• اگر هیچ‌کدام تنظیم نشده باشند و کار از قبل از طریق announce تحویل دهد، اعلان‌های خرابی به همان هدف اعلامی اصلی بازمی‌گردند.
• delivery.failureDestination فقط در کارهای sessionTarget="isolated" پشتیبانی می‌شود، مگر آنکه حالت تحویل اصلی webhook باشد.
• failureAlert.includeSkipped: true خط‌مشی هشدار Cron یک کار یا خط‌مشی سراسری را برای هشدارهای مکررِ اجرای نادیده‌گرفته‌شده فعال می‌کند. اجراهای نادیده‌گرفته‌شده شمارنده متوالی جداگانه‌ای دارند، بنابراین بر عقب‌نشینی خطای اجرا تأثیر نمی‌گذارند.
• openclaw cron edit تنظیم هشدار برای هر کار را ارائه می‌دهد: --failure-alert/--no-failure-alert، --failure-alert-after <n>، --failure-alert-channel، --failure-alert-to، --failure-alert-cooldown، --failure-alert-include-skipped/--failure-alert-exclude-skipped، --failure-alert-mode و --failure-alert-account-id.

زبان خروجی

کارهای Cron زبان پاسخ را از کانال، منطقه زبانی یا پیام‌های قبلی استنباط نمی‌کنند. قاعده زبان را در پیام یا قالب زمان‌بندی‌شده قرار دهید:

openclaw cron edit <jobId> \  --message "به‌روزرسانی‌ها را خلاصه کن. به زبان چینی پاسخ بده؛ URLها، کد و نام محصولات را بدون تغییر نگه دار."

برای فایل‌های قالب، دستور زبان را در اعلان رندرشده نگه دارید و پیش از اجرای کار بررسی کنید که جای‌نگهدارهایی مانند {{language}} مقداردهی شده باشند. اگر خروجی زبان‌ها را ترکیب می‌کند، قاعده را صریح بیان کنید؛ برای نمونه: «برای متن روایی از زبان چینی استفاده کن و اصطلاحات فنی را به انگلیسی نگه دار.»

نمونه‌های CLI

openclaw cron add \  --name "بررسی تقویم" \  --at "20m" \  --session main \  --system-event "Heartbeat بعدی: تقویم را بررسی کن." \  --wake now

openclaw cron create "0 7 * * *" \  "به‌روزرسانی‌های شب گذشته را خلاصه کن." \  --name "گزارش صبحگاهی" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "تحلیل عمیق" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "تحلیل عمیق هفتگی از پیشرفت پروژه." \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "استقرارهای امروز را به‌صورت JSON خلاصه کن." \  --name "خلاصه استقرارها" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "کاوش عمق صف" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

مدیریت کارها

# فهرست‌کردن کارهای فعالopenclaw cron list # شامل‌کردن کارهای غیرفعالopenclaw cron list --all # دریافت یک کار ذخیره‌شده به‌صورت JSONopenclaw cron get <jobId> # نمایش یک کار، شامل مسیر تحویل نهایی‌شدهopenclaw cron show <jobId> # فعال/غیرفعال‌کردن بدون حذفopenclaw cron enable <jobId>openclaw cron disable <jobId> # ویرایش یک کارopenclaw cron edit <jobId> --message "پرامپت به‌روزشده" --model "opus" # اجرای اجباری یک کار در همین لحظهopenclaw cron run <jobId> # اجرای اجباری یک کار در همین لحظه و انتظار برای وضعیت پایانی آنopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # اجرا فقط در صورت فرارسیدن موعدopenclaw cron run <jobId> --due # مشاهده تاریخچه اجراopenclaw cron runs --id <jobId> --limit 50 # مشاهده یک اجرای دقیقopenclaw cron runs --id <jobId> --run-id <runId> # حذف یک کارopenclaw cron remove <jobId> # انتخاب عامل (راه‌اندازی‌های چندعاملی)openclaw cron create "0 6 * * *" "صف عملیات را بررسی کن" --name "پایش عملیات" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

بایگانی‌کردن یک نشست (از طریق Control UI یا sessions.patch { archived: true } توسط یک فراخواننده مدیر اپراتور) همه کارهای Cron فعال متصل به آن نشست را غیرفعال می‌کند: نشست مجزای cron:<jobId> آن، یک مقصد session:<key> یا یک مسیر تحویل/بیدارسازی sessionKey. بازیابی نشست این کارها را دوباره فعال نمی‌کند؛ از openclaw cron enable <jobId> استفاده کنید. نشست‌هایی که یک کار متصل فعال دارند، در نوار کناری Control UI نشان ساعت نمایش می‌دهند.

openclaw cron run <jobId> پس از قرار‌دادن اجرای دستی در صف بازمی‌گردد. برای هوک‌های خاموش‌سازی، اسکریپت‌های نگهداشت یا دیگر خودکارسازی‌هایی که باید تا پایان اجرای در صف مسدود بمانند، از --wait استفاده کنید؛ این فرمان runId بازگردانده‌شده را پایش می‌کند (مهلت پیش‌فرض 10m، فاصله پایش 2s) و برای وضعیت ok با کد 0 و برای error، skipped یا پایان مهلت انتظار با کدی غیرصفر خارج می‌شود.

ابزار cron عامل، خلاصه‌های فشرده کار (id، name، enabled، nextRunAtMs، scheduleKind، lastRunStatus) را از cron(action: "list") بازمی‌گرداند؛ برای دریافت تعریف کامل یک کار از cron(action: "get", jobId: "...") استفاده کنید. فراخواننده‌های مستقیم Gateway می‌توانند compact: true را به cron.list ارسال کنند؛ حذف آن پاسخ کامل را همراه با پیش‌نمایش‌های تحویل حفظ می‌کند.

openclaw cron create نام مستعار openclaw cron add است. کارهای جدید می‌توانند از یک زمان‌بندی موقعیتی ("0 9 * * 1"، "every 1h"، "20m" یا یک برچسب زمانی ISO) و پس از آن یک پرامپت موقعیتی عامل استفاده کنند. برای POST کردن بار اجرای تکمیل‌شده به یک نقطه پایانی HTTP، از --webhook <url> در cron add|create یا cron edit استفاده کنید؛ تحویل Webhook را نمی‌توان با پرچم‌های تحویل چت (--announce، --channel، --to، --thread-id، --account) ترکیب کرد. در cron edit، --clear-channel، --clear-to، --clear-thread-id و --clear-account آن فیلدهای مسیریابی را جداگانه پاک کنید (هرکدام همراه با پرچم تنظیم متناظر خود رد می‌شوند) — برخلاف --no-deliver که فقط تحویل جایگزین اجراکننده را غیرفعال می‌کند.

Webhookها

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

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

احراز هویت

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

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

توکن‌های رشته پرس‌وجو رد می‌شوند.

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"ایمیل جدیدی دریافت شد","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"صندوق ورودی را خلاصه کن","name":"ایمیل","model":"openai/gpt-5.6-sol"}'

یکپارچه‌سازی Gmail PubSub

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

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

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

این فرمان پیکربندی hooks.gmail را می‌نویسد، پیش‌تنظیم Gmail را فعال می‌کند و Tailscale Funnel را به‌عنوان پیش‌فرض نقطه پایانی ارسال تنظیم می‌کند (--tailscale funnel|serve|off).

شروع خودکار Gateway

هنگامی که hooks.enabled=true فعال و hooks.gmail.account تنظیم شده باشد، Gateway هنگام راه‌اندازی gog gmail watch serve را آغاز می‌کند و پایش را خودکار تمدید می‌کند. برای انصراف، 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: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

برای صندوق‌های ورودی غیرقابل‌اعتماد، از بهترین مدل نسل جدید موجود نزد ارائه‌دهنده خود استفاده کنید. مقدار بالا یک نمونه است؛ مدل باید در کاتالوگ و فهرست مجاز پیکربندی‌شده شما وجود داشته باشد.

پیکربندی

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken در POSTهای Webhook مربوط به Cron به‌صورت Authorization: Bearer <token> ارسال می‌شود.

cron.store یک کلید منطقی ذخیره‌سازی و مسیر مهاجرت doctor است، نه یک فایل JSON زنده برای ویرایش دستی. داده‌های کار در SQLite قرار دارند؛ برای تغییرات از CLI یا API مربوط به Gateway استفاده کنید.

غیرفعال‌کردن 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 — نوبت‌های دوره‌ای نشست اصلی
• منطقهٔ زمانی — پیکربندی منطقهٔ زمانی