openclaw cron

إدارة مهام cron لمجدول Gateway.

إنشاء المهام بسرعة

openclaw cron create اسم بديل لـ openclaw cron add. للمهام الجديدة، ضع الجدول أولًا والمطالبة ثانيًا:

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

استخدم --webhook <url> عندما ينبغي للمهمة إرسال الحمولة المكتملة عبر POST بدلًا من تسليمها إلى وجهة دردشة:

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

استخدم --command للمهام الحتمية الشبيهة بأوامر الصدفة التي تعمل داخل cron في OpenClaw دون بدء تشغيل معزول للوكيل/النموذج:

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>]. استخدم --command-argv '["node","scripts/report.mjs"]' لتنفيذ argv بدقة. تلتقط مهام الأوامر stdout/stderr، وتسجّل سجل cron المعتاد، وتوجّه المخرجات عبر أوضاع التسليم نفسها announce أو webhook أو none المستخدمة في المهام المعزولة. يُمنع تسليم الأمر الذي لا يطبع سوى NO_REPLY.

الجلسات

يقبل --session القيم main أو isolated أو current أو session:<id>.

التسليم

يعاين openclaw cron list وopenclaw cron show <job-id> مسار التسليم المحسوم. بالنسبة إلى channel: "last"، توضح المعاينة ما إذا كان المسار قد حُسم من الجلسة الرئيسية أو الحالية، أو سيفشل بشكل مغلق.

يمكن للوجهات ذات بادئة المزوّد إزالة الالتباس بين قنوات الإعلان غير المحسومة. على سبيل المثال، تحدد to: "telegram:123" قناة Telegram عند حذف delivery.channel أو ضبطها على last. ولا تعمل بوصفها محددات للمزوّد إلا البادئات التي يعلن عنها Plugin المحمّل. إذا كانت delivery.channel صريحة، فيجب أن تتطابق البادئة مع تلك القناة؛ ويُرفض الجمع بين channel: "whatsapp" وto: "telegram:123". وتظل بادئات الخدمات مثل imessage: وsms: صيغةً لوجهة تملكها القناة.

ملكية التسليم

يتشارك الوكيل والمشغّل مسؤولية تسليم دردشة cron المعزولة:

• يمكن للوكيل الإرسال مباشرةً باستخدام أداة message عند توفر مسار دردشة.
• يسلّم البديل الاحتياطي announce الرد النهائي فقط عندما لا يرسل الوكيل مباشرةً إلى الوجهة المحسومة.
• يرسل webhook الحمولة المكتملة إلى عنوان URL.
• يعطّل none التسليم الاحتياطي للمشغّل.

استخدم cron add|create --webhook <url> أو cron edit <job-id> --webhook <url> لضبط تسليم Webhook. لا تجمع --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 وتُعاد محاولته في جدول لاحق؛ وتُخزّن نتيجة إمكانية الوصول مؤقتًا لكل نقطة نهاية لمدة 5 دقائق كي لا تُغرق مهام كثيرة الخادم المحلي نفسه بفحوصات متكررة.

توجد مهام Cron وحالة وقت التشغيل المعلقة وسجل التشغيل في قاعدة بيانات حالة SQLite المشتركة. تُستورد ملفات jobs.json و<name>-state.json وruns/*.jsonl القديمة مرة واحدة، ثم تُعاد تسميتها بإضافة اللاحقة .migrated. بعد الاستيراد، عدّل الجداول باستخدام openclaw cron add|edit|remove بدلًا من تعديل ملفات JSON.

عمليات التشغيل اليدوية

يفرض 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.

خيار cron المسمى --model هو النموذج الأساسي للمهمة، وليس تجاوز /model لجلسة دردشة. وهذا يعني:

• تظل النماذج الاحتياطية المهيأة مطبقة عند فشل نموذج المهمة المحدد.
• تحل fallbacks في حمولة المهمة محل قائمة النماذج الاحتياطية المهيأة عند وجودها.
• تجعل قائمة النماذج الاحتياطية الفارغة الخاصة بالمهمة (--fallbacks "" أو fallbacks: [] في حمولة المهمة/API) تشغيل cron صارمًا.
• عندما تحتوي المهمة على --model ولا توجد قائمة نماذج احتياطية مهيأة، يمرّر OpenClaw تجاوزًا احتياطيًا فارغًا صريحًا كي لا يُضاف النموذج الأساسي للوكيل بوصفه وجهة إعادة محاولة مخفية.
• تمر فحوصات المزوّد المحلي الأولية على النماذج الاحتياطية المهيأة قبل وضع علامة skipped على تشغيل cron.

يُبلغ 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) باعتبارها إشارة الرفض المعتمدة. كما تراعي أغلفة 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"

يحذّر openclaw cron add عند حذف --agent من مهام دورات الوكيل، ويعود إلى الوكيل الافتراضي (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
• المهام المجدولة