# openclaw cron

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

# نشست‌ها

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

# تحویل

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

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

# مالکیت تحویل

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

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

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

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

# تحویل شکست

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

1. delivery.failureDestination روی کار.
2. cron.failureDestination سراسری.
3. هدف اعلام اصلی کار، وقتی مقصد شکست صریحی تنظیم نشده باشد.

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

# زمان‌بندی

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

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

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

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

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

برای کارهای ایزوله‌ای که یک ارائه‌دهندهٔ مدل محلی پیکربندی‌شده را هدف می‌گیرند، Cron پیش از شروع نوبت عامل، یک پیش‌پرواز سبک ارائه‌دهنده اجرا می‌کند. ارائه‌دهنده‌های api: "ollama" مربوط به local loopback، شبکهٔ خصوصی، و .local در /api/tags بررسی می‌شوند؛ ارائه‌دهنده‌های محلی سازگار با OpenAI مانند vLLM، SGLang، و LM Studio در /models بررسی می‌شوند. اگر نقطهٔ پایانی در دسترس نباشد، اجرا به‌عنوان skipped ثبت می‌شود و در زمان‌بندی بعدی دوباره تلاش می‌شود؛ نقاط پایانی مردهٔ مطابق به‌مدت ۵ دقیقه کش می‌شوند تا از کوبیدن هم‌زمان تعداد زیادی کار به همان سرور محلی جلوگیری شود.

نکته: تعریف‌های کار Cron در jobs.json قرار دارند، در حالی که وضعیت زمان اجرای در انتظار در jobs-state.json قرار دارد. اگر jobs.json از بیرون ویرایش شود، Gateway زمان‌بندی‌های تغییرکرده را دوباره بارگذاری می‌کند و جایگاه‌های در انتظارِ قدیمی را پاک می‌کند؛ بازنویسی‌های فقط قالب‌بندی جایگاه در انتظار را پاک نمی‌کنند.

# اجراهای دستی

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

# مدل‌ها

cron add|edit --model <ref> یک مدل مجاز را برای کار انتخاب می‌کند.

--model در Cron یک اصلیِ کار است، نه یک بازنویسی /model برای نشست گفت‌وگو. یعنی:

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

# تقدم مدل در Cron ایزوله

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

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

# حالت سریع

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

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

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

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

# سرکوب تأیید کهنه

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

# سرکوب توکن خاموش

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

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

اجراهای Cron ایزوله ابتدا فرادادهٔ رد اجرای ساخت‌یافته را از اجرای تعبیه‌شده ترجیح می‌دهند، سپس به نشانگرهای رد شناخته‌شده در خروجی نهایی، مانند SYSTEM_RUN_DENIED، INVALID_REQUEST، و عبارت‌های امتناع مربوط به اتصال تأیید، برمی‌گردند.

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

# نگهداشت

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

• cron.sessionRetention با پیش‌فرض 24h نشست‌های اجرای ایزولهٔ کامل‌شده را هرس می‌کند.
• cron.runLog.maxBytes و cron.runLog.keepLines فایل ~/.openclaw/cron/runs/<jobId>.jsonl را هرس می‌کنند.

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

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

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

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

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

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

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

openclaw cron list
openclaw cron list --agent ops
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50

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

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

تغییر هدف عامل و نشست:

openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"

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

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

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver

# مرتبط

• مرجع CLI
• وظایف زمان‌بندی‌شده