openclaw cron

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

ایجاد سریع کارها

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --agent ops

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

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

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

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --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 می‌تواند اعلان‌های شکست را برای اطلاع‌رسانی اجراهای ردشدهٔ تکراری فعال کند.

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

کارهای 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 مدل انتخاب‌شده استفاده می‌کند که مقدار پیش‌فرض آن ۶۰ ثانیه است.

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

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

خروجی اجرا و رد درخواست‌ها

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

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

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

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

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

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

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

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

نگه‌داری

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

• cron.sessionRetention (پیش‌فرض 24h، یا false برای غیرفعال‌سازی) نشست‌های تکمیل‌شدهٔ اجراهای مجزا را هرس می‌کند.
• cron.runLog.keepLines (پیش‌فرض 2000) ردیف‌های نگه‌داری‌شدهٔ تاریخچهٔ اجرا در SQLite را برای هر کار هرس می‌کند. cron.runLog.maxBytes (پیش‌فرض 2000000) برای سازگاری با گزارش‌های اجرای قدیمی مبتنی بر فایل همچنان پذیرفته می‌شود؛ هرس SQLite بر مبنای تعداد ردیف است.

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

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

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

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 * * *" \  "Summarize overnight updates." \  --name "Lightweight morning brief" \  --session isolated \  --light-context \  --no-deliver

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

یک کار فرمانی با argv، دایرکتوری کاری، متغیرهای محیطی، ورودی استاندارد و محدودیت‌های خروجی دقیق ایجاد کنید:

openclaw cron create "*/30 * * * *" \  --name "Position export" \  --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 به‌طور پیش‌فرض همهٔ کارهای منطبق را نشان می‌دهد. برای نمایش فقط کارهایی که شناسهٔ عامل عادی‌سازی‌شدهٔ مؤثر آن‌ها منطبق است، --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، مقصد حل‌شده، ارسال‌های ابزار پیام، استفاده از مسیر جایگزین و وضعیت تحویل.

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

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
• کارهای زمان‌بندی‌شده