openclaw cron

کارهای Cron زمان‌بند Gateway را مدیریت کنید.

ساخت سریع کارها

openclaw cron create نام مستعار openclaw cron add است. برای کارهای جدید، ابتدا زمان‌بندی و سپس پرامپت را قرار دهید:

openclaw cron create "0 7 * * *" \  "به‌روزرسانی‌های شبانه را خلاصه کن." \  --name "گزارش صبحگاهی" \  --agent ops

وقتی کار باید به‌جای تحویل به یک مقصد چت، محموله نهایی را POST کند، از --webhook <url> استفاده کنید:

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

برای کارهای قطعی به سبک پوسته که در Cron ‏OpenClaw و بدون آغاز اجرای مجزای عامل/مدل اجرا می‌شوند، از --command استفاده کنید:

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"]' استفاده کنید. کارهای فرمان، stdout/stderr را ثبت می‌کنند، تاریخچه عادی Cron را می‌نویسند و خروجی را از طریق همان حالت‌های تحویل announce، webhook یا none کارهای مجزا مسیریابی می‌کنند. فرمانی که فقط NO_REPLY را چاپ کند، سرکوب می‌شود.

نشست‌ها

--session مقادیر main، isolated، current یا session:<id> را می‌پذیرد.

تحویل

openclaw cron list و openclaw cron show <job-id> مسیر تحویل حل‌شده را پیش‌نمایش می‌کنند. برای channel: "last"، پیش‌نمایش نشان می‌دهد مسیر از نشست اصلی یا جاری حل شده است یا به‌شکل بسته و ایمن شکست خواهد خورد.

مقصدهای دارای پیشوند ارائه‌دهنده می‌توانند ابهام کانال‌های اعلان حل‌نشده را برطرف کنند. برای نمونه، وقتی delivery.channel حذف شده یا last باشد، to: "telegram:123"، Telegram را انتخاب می‌کند. فقط پیشوندهایی که Plugin بارگذاری‌شده معرفی می‌کند، انتخاب‌گر ارائه‌دهنده هستند. اگر delivery.channel صریح باشد، پیشوند باید با آن کانال مطابقت داشته باشد؛ channel: "whatsapp" همراه با to: "telegram:123" رد می‌شود. پیشوندهای سرویس مانند imessage: و sms: همچنان نحو مقصد تحت مالکیت کانال باقی می‌مانند.

مالکیت تحویل

تحویل چت Cron مجزا میان عامل و اجراکننده مشترک است:

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

برای تنظیم تحویل Webhook از cron add|create --webhook <url> یا cron edit <job-id> --webhook <url> استفاده کنید. --webhook را با پرچم‌های تحویل چت مانند --announce، --no-deliver، --channel، --to، --thread-id یا --account ترکیب نکنید.

cron edit <job-id> می‌تواند فیلدهای منفرد مسیریابی تحویل را با --clear-channel، --clear-to، --clear-thread-id و --clear-account حذف کند (ترکیب هرکدام با پرچم تنظیم متناظر آن رد می‌شود). برخلاف --no-deliver که فقط تحویل جایگزین اجراکننده را غیرفعال می‌کند، این گزینه‌ها فیلد ذخیره‌شده را حذف می‌کنند تا کار دوباره آن بخش از مسیر را بر اساس پیش‌فرض‌ها حل کند.

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

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

تحویل شکست

اعلان‌های شکست به‌ترتیب زیر حل می‌شوند:

1. delivery.failureDestination روی کار.
2. cron.failureDestination سراسری.
3. مقصد اعلان اصلی کار (وقتی هیچ‌یک از موارد بالا به مقصدی مشخص حل نشوند).

اجراهای مجزای Cron، شکست‌های سطح اجرای عامل را حتی وقتی هیچ محموله پاسخی تولید نشده باشد، خطای کار در نظر می‌گیرند؛ بنابراین شکست‌های مدل/ارائه‌دهنده همچنان شمارنده‌های خطا را افزایش می‌دهند و اعلان‌های شکست را فعال می‌کنند.

کارهای فرمان Cron یک نوبت مجزای عامل را آغاز نمی‌کنند. کد خروج صفر، ok را ثبت می‌کند؛ خروج غیرصفر، سیگنال، پایان مهلت یا پایان مهلت بدون خروجی، error را ثبت می‌کند و می‌تواند همان مسیر اعلان شکست را فعال کند.

اگر مهلت یک اجرای مجزا پیش از نخستین درخواست مدل پایان یابد، openclaw cron show و openclaw cron runs شامل خطایی مختص مرحله، مانند setup timed out before runner start، یا پیامی درباره توقف با نام آخرین مرحله شناخته‌شده راه‌اندازی خواهند بود (برای نمونه context-engine). برای ارائه‌دهندگان مبتنی بر CLI، دیده‌بان پیش از مدل تا زمان آغاز نوبت CLI خارجی فعال می‌ماند؛ بنابراین توقف در جست‌وجوی نشست، هوک، احراز هویت، پرامپت و راه‌اندازی CLI به‌عنوان شکست Cron پیش از مدل گزارش می‌شود.

زمان‌بندی

کارهای یک‌باره

--at <datetime> یک اجرای یک‌باره را زمان‌بندی می‌کند. تاریخ‌وزمان‌های بدون اختلاف زمانی UTC در نظر گرفته می‌شوند، مگر اینکه --tz <iana> را نیز وارد کنید که زمان ساعت محلی را در منطقه زمانی داده‌شده تفسیر می‌کند.

کارهای تکرارشونده

کارهای تکرارشونده پس از خطاهای متوالی از تأخیر تصاعدی تلاش مجدد استفاده می‌کنند: 30s، 1m، 5m، 15m، 60m. زمان‌بندی پس از اجرای موفق بعدی به حالت عادی بازمی‌گردد.

اجراهای ردشده جدا از خطاهای اجرا ردیابی می‌شوند. آن‌ها بر تأخیر تلاش مجدد اثر نمی‌گذارند، اما openclaw cron edit <job-id> --failure-alert-include-skipped می‌تواند اعلان‌های شکست را برای ارسال اعلان‌های مکرر اجرای ردشده فعال کند.

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

کارهای Cron، وضعیت در انتظار زمان اجرا و تاریخچه اجرا در پایگاه داده وضعیت SQLite مشترک قرار دارند. فایل‌های قدیمی jobs.json، <name>-state.json و runs/*.jsonl یک‌بار وارد و با پسوند .migrated تغییر نام داده می‌شوند. پس از واردسازی، به‌جای ویرایش فایل‌های JSON، زمان‌بندی‌ها را با openclaw cron add|edit|remove ویرایش کنید.

اجراهای دستی

openclaw cron run <job-id> به‌طور پیش‌فرض اجرا را اجباری می‌کند و به‌محض قرارگرفتن اجرای دستی در صف بازمی‌گردد. پاسخ‌های موفق شامل { ok: true, enqueued: true, runId } هستند. برای بررسی نتیجه بعدی از runId بازگردانده‌شده استفاده کنید:

openclaw cron run <job-id>openclaw cron runs --id <job-id> --run-id <run-id>

وقتی یک اسکریپت باید تا ثبت وضعیت پایانی همان اجرای صف‌شده مسدود بماند، --wait را اضافه کنید:

openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s

با --wait، CLI همچنان ابتدا cron.run را فراخوانی می‌کند و سپس cron.runs را برای runId بازگردانده‌شده پایش می‌کند. فرمان فقط زمانی با 0 خارج می‌شود که اجرا با وضعیت ok پایان یابد. وقتی اجرا با error یا skipped پایان یابد، پاسخ Gateway شامل runId نباشد، یا --wait-timeout منقضی شود (به‌طور پیش‌فرض 10m، با پایش هر 2s به‌طور پیش‌فرض)، فرمان با کد غیرصفر خارج می‌شود. --poll-interval باید بزرگ‌تر از صفر باشد.

مدل‌ها

cron add|edit --model <ref> یک مدل مجاز را برای کار انتخاب می‌کند. cron add|edit --fallbacks <list> مدل‌های جایگزین هر کار را تنظیم می‌کند، برای نمونه --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5؛ برای اجرای سخت‌گیرانه بدون جایگزین، --fallbacks "" را وارد کنید. cron edit <job-id> --clear-fallbacks جایگزینی مدل‌های پشتیبان هر کار را حذف می‌کند. cron edit <job-id> --clear-model جایگزینی مدل هر کار را حذف می‌کند تا کار از اولویت عادی انتخاب مدل Cron پیروی کند (در صورت وجود، جایگزینی ذخیره‌شده نشست Cron، و در غیر این صورت مدل عامل/پیش‌فرض)؛ این گزینه را نمی‌توان با --model ترکیب کرد. cron add|edit --thinking <level> جایگزینی تفکر هر کار را تنظیم می‌کند؛ cron edit <job-id> --clear-thinking آن را حذف می‌کند تا کار از اولویت عادی تفکر Cron پیروی کند و نمی‌توان آن را با --thinking ترکیب کرد.

--model در Cron یک مدل اصلی کار است، نه جایگزینی /model نشست چت. یعنی:

• وقتی مدل انتخاب‌شده کار شکست بخورد، مدل‌های جایگزین پیکربندی‌شده همچنان اعمال می‌شوند.
• fallbacks در محموله هر کار، در صورت وجود، جای فهرست جایگزین پیکربندی‌شده را می‌گیرد.
• فهرست خالی جایگزین هر کار (--fallbacks "" یا fallbacks: [] در محموله/API کار)، اجرای Cron را سخت‌گیرانه می‌کند.
• وقتی کاری دارای --model باشد اما هیچ فهرست جایگزینی پیکربندی نشده باشد، OpenClaw یک جایگزینی خالی و صریح برای مدل‌های جایگزین ارسال می‌کند تا مدل اصلی عامل به‌عنوان مقصد پنهان تلاش مجدد افزوده نشود.
• پیش‌بررسی‌های ارائه‌دهنده محلی پیش از علامت‌گذاری اجرای Cron به‌عنوان skipped، مدل‌های جایگزین پیکربندی‌شده را به‌ترتیب بررسی می‌کنند.

openclaw doctor کارهایی را گزارش می‌کند که از قبل payload.model برای آن‌ها تنظیم شده است، از جمله تعداد فضای نام ارائه‌دهنده و عدم تطابق با agents.defaults.model. وقتی رفتار احراز هویت، ارائه‌دهنده یا صورت‌حساب میان چت زنده و کارهای زمان‌بندی‌شده متفاوت به‌نظر می‌رسد، از این بررسی استفاده کنید.

اولویت مدل Cron مجزا

Cron مجزا، مدل فعال را به‌ترتیب زیر حل می‌کند:

1. جایگزینی هوک Gmail.
2. --model هر کار.
3. جایگزینی ذخیره‌شده مدل نشست Cron (وقتی کاربر یکی را انتخاب کرده باشد).
4. انتخاب مدل عامل یا مدل پیش‌فرض.

حالت سریع

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

تلاش‌های مجدد برای تغییر مدل زنده

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

خروجی اجرا و ردها

سرکوب تأیید دریافت منقضی‌شده

نوبت‌های Cron ایزوله، پاسخ‌های منقضی‌شده‌ای را که فقط حاوی تأیید دریافت هستند سرکوب می‌کنند. اگر نتیجهٔ نخست صرفاً یک به‌روزرسانی وضعیت موقت باشد و هیچ اجرای زیرعاملِ فرزندی مسئول پاسخ نهایی نباشد، Cron پیش از تحویل یک‌بار دیگر برای دریافت نتیجهٔ واقعی درخواست می‌کند.

سرکوب توکن سکوت

اگر یک اجرای Cron ایزوله فقط توکن سکوت (NO_REPLY یا no_reply) را برگرداند، Cron هم تحویل خروجی مستقیم و هم مسیر جایگزینِ خلاصهٔ صف‌شده را سرکوب می‌کند؛ بنابراین چیزی به گفتگو ارسال نمی‌شود.

ردهای ساخت‌یافته

اجراهای Cron ایزوله از فرادادهٔ ساخت‌یافتهٔ رد اجرا در اجرای تعبیه‌شده (خطاهای مرگبار ابزار اجرا با کد SYSTEM_RUN_DENIED یا INVALID_REQUEST) به‌عنوان سیگنال معتبر رد استفاده می‌کنند. آن‌ها همچنین پوشش‌دهنده‌های میزبان Node با کد UNAVAILABLE پیرامون یک خطای ساخت‌یافتهٔ تودرتو را که یکی از آن کدها را دارد، در نظر می‌گیرند.

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

cron list و تاریخچهٔ اجرا به‌جای گزارش فرمان مسدودشده به‌صورت ok، دلیل رد را نمایش می‌دهند.

نگهداری

رفتار نگهداری:

• cron.sessionRetention (مقدار پیش‌فرض 24h، یا false برای غیرفعال‌سازی) نشست‌های تکمیل‌شدهٔ اجرای ایزوله را پاک‌سازی می‌کند.
• تاریخچهٔ اجرا جدیدترین 2000 ردیف پایانی را برای هر کار Cron نگه می‌دارد. ردیف‌های گم‌شده بازهٔ استاندارد 24 ساعتهٔ پاک‌سازی کارهای گم‌شده را حفظ می‌کنند.

مهاجرت کارهای قدیمی‌تر

ویرایش‌های رایج

به‌روزرسانی تنظیمات تحویل بدون تغییر پیام:

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

غیرفعال‌سازی تحویل برای یک کار ایزوله:

openclaw cron edit <job-id> --no-deliver

فعال‌سازی زمینهٔ راه‌اندازی سبک برای یک کار ایزوله:

openclaw cron edit <job-id> --light-context

اطلاع‌رسانی به یک کانال مشخص:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

اطلاع‌رسانی به یک موضوع انجمن Telegram:

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

ایجاد یک کار ایزوله با زمینهٔ راه‌اندازی سبک:

openclaw cron create "0 7 * * *" \  "به‌روزرسانی‌های شبانه را خلاصه کن." \  --name "خلاصهٔ سبک صبحگاهی" \  --session isolated \  --light-context \  --no-deliver

--light-context فقط برای کارهای نوبت عامل ایزوله اعمال می‌شود. در اجراهای Cron، حالت سبک به‌جای تزریق مجموعهٔ کامل راه‌اندازی فضای کاری، زمینهٔ راه‌اندازی را خالی نگه می‌دارد.

ایجاد یک کار فرمان با argv، cwd، env، stdin و محدودیت‌های خروجی دقیق:

openclaw cron create "*/30 * * * *" \  --name "خروجی‌گیری موقعیت" \  --command-argv '["node","scripts/export-position.mjs"]' \  --command-cwd "/srv/app" \  --command-env "NODE_ENV=production" \  --command-input '{"mode":"summary"}' \  --timeout-seconds 120 \  --no-output-timeout-seconds 30 \  --output-max-bytes 65536 \  --webhook "https://example.invalid/openclaw/cron"

فرمان‌های رایج مدیریتی

اجرای دستی و بازرسی:

openclaw cron listopenclaw cron list --agent opsopenclaw cron get <job-id>openclaw cron show <job-id>openclaw cron run <job-id>openclaw cron run <job-id> --dueopenclaw cron run <job-id> --wait --wait-timeout 10mopenclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2sopenclaw cron runs --id <job-id> --limit 50openclaw cron runs --id <job-id> --run-id <run-id>

openclaw cron list به‌طور پیش‌فرض کارهای فعال را نمایش می‌دهد. برای گنجاندن کارهای غیرفعال، --all را ارسال کنید یا برای نمایش فقط کارهایی که شناسهٔ نرمال‌شدهٔ مؤثر عامل آن‌ها مطابقت دارد، از --agent <id> استفاده کنید؛ کارهای بدون شناسهٔ عامل ذخیره‌شده، متعلق به عامل پیش‌فرض پیکربندی‌شده در نظر گرفته می‌شوند.

openclaw cron get <job-id> مستقیماً JSON ذخیره‌شدهٔ کار را برمی‌گرداند. هنگامی که نمای خوانا برای انسان همراه با پیش‌نمایش مسیر تحویل می‌خواهید، از cron show <job-id> استفاده کنید.

cron list --json و cron show <job-id> --json برای هر کار یک فیلد سطح بالای status دارند که از enabled، state.runningAtMs و state.lastRunStatus محاسبه می‌شود. مقادیر: disabled، running، ok، error، skipped یا idle. وضعیت JSON استاندارد و بدون تزئین باقی می‌ماند تا ابزارهای خارجی بتوانند وضعیت کار را بدون محاسبهٔ مجدد آن بخوانند؛ خروجی خوانا برای انسان ممکن است وضعیت‌های تکراری error را با تعداد شکست تزئین کند.

ورودی‌های cron runs شامل اطلاعات تشخیصی تحویل دربارهٔ مقصد موردنظر Cron، مقصد حل‌شده، ارسال‌های ابزار پیام، استفاده از مسیر جایگزین و وضعیت تحویل‌شده هستند.

فضای موقت خصوصی هر کار (فهرست‌های بررسی Heartbeat و زمینهٔ مشابه پایش):

openclaw cron scratch <job-id>                  # محتوای فعلی فضای موقت را چاپ می‌کندopenclaw cron scratch <job-id> --json           # فضای موقت همراه با فرادادهٔ بازبینیopenclaw cron scratch <job-id> --set "text"     # فضای موقت را با متن دقیق جایگزین می‌کندopenclaw cron scratch <job-id> --file notes.md  # فضای موقت را از یک فایل جایگزین می‌کند (- برای stdin)openclaw cron scratch <job-id> --unset          # ردیف فضای موقت را حذف می‌کند

فضای موقت در پایگاه دادهٔ وضعیت مشترک ذخیره می‌شود، به 256 KiB محدود است و هرگز در خروجی cron list/cron get/cron runs گنجانده نمی‌شود. نوشتن‌ها با سازوکار مقایسه و جابه‌جایی در برابر بازبینی خوانده‌شده هنگام آغاز فرمان محافظت می‌شوند؛ برای تثبیت یک بازبینی صریح، به‌جای آن --expected-revision <n> را ارسال کنید. برای نحوهٔ استفادهٔ پایشگرهای Heartbeat از فضای موقت، به Heartbeat مراجعه کنید.

تغییر مقصد عامل و نشست:

openclaw cron edit <job-id> --agent opsopenclaw cron edit <job-id> --clear-agentopenclaw cron edit <job-id> --session currentopenclaw cron edit <job-id> --session "session:daily-brief"

وقتی --agent در کارهای نوبت عامل حذف شده باشد، openclaw cron add هشدار می‌دهد و به عامل پیش‌فرض (main) بازمی‌گردد. برای تثبیت یک عامل مشخص، هنگام ایجاد --agent <id> را ارسال کنید.

تنظیمات جزئی تحویل:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"openclaw cron edit <job-id> --webhook "https://example.invalid/openclaw/cron"openclaw cron edit <job-id> --best-effort-deliveropenclaw cron edit <job-id> --no-best-effort-deliveropenclaw cron edit <job-id> --no-deliver

مرتبط

• مرجع CLI
• کارهای زمان‌بندی‌شده