Skip to main content
Cron هو المجدول المضمّن في Gateway. يحتفظ بالمهام، ويوقظ الوكيل في الوقت المناسب، ويمكنه إرسال المخرجات إلى قناة دردشة أو Webhook أو عدم إرسالها إلى أي مكان.

بدء سريع

1

إضافة تذكير لمرة واحدة

2

التحقق من مهامك

3

عرض سجل التشغيل

آلية عمل Cron

  • يعمل Cron داخل عملية Gateway، وليس داخل النموذج. يجب أن يكون Gateway قيد التشغيل لكي تُنفَّذ الجداول.
  • تُحفَظ تعريفات المهام وحالة وقت التشغيل وسجل التشغيل في قاعدة بيانات حالة SQLite المشتركة في OpenClaw، لذلك لا تؤدي عمليات إعادة التشغيل إلى فقدان الجداول.
  • يُنشئ كل تنفيذ لـ Cron سجل مهمة في الخلفية.
  • تُحذف مهام المرة الواحدة (--at) تلقائيًا بعد نجاحها افتراضيًا؛ مرّر --keep-after-run للاحتفاظ بها.
  • ميزانية الوقت الفعلي لكل تشغيل: --timeout-seconds عند ضبطها. خلاف ذلك، تكون مهام دورات الوكيل المعزولة/المنفصلة محدودة بمراقب Cron الخاص البالغ 60 دقيقة قبل أن تنطبق مهلة دورة الوكيل الأساسية (agents.defaults.timeoutSeconds، وقيمتها الافتراضية 48 ساعة)؛ وتكون المهلة الافتراضية لمهام الأوامر 10 دقائق.
  • عند بدء تشغيل Gateway، يُعاد جدولة مهام دورات الوكيل المعزولة المتأخرة بدلًا من إعادة تشغيلها فورًا، لإبقاء أعمال تهيئة النموذج/الأدوات خارج نافذة اتصال القناة.
  • إذا شغّلت openclaw agent من Cron النظام أو من مجدول خارجي آخر، فغلّفه بتصعيد للإنهاء القسري رغم أن CLI يعالج بالفعل SIGTERM/SIGINT. تطلب عمليات التشغيل المدعومة من Gateway من Gateway إلغاء عمليات التشغيل المقبولة؛ وتتلقى عمليات التشغيل المحلية وعمليات التشغيل الاحتياطية المضمّنة إشارة الإلغاء نفسها. بالنسبة إلى GNU timeout، يُفضّل استخدام timeout -k 60 600 openclaw agent ... بدلًا من timeout 600 ... وحده — فقيمة -k هي الإجراء الاحتياطي إذا تعذّر على العملية إنهاء أعمالها في الوقت المحدد. بالنسبة إلى وحدات systemd، استخدم إشارة إيقاف SIGTERM مع نافذة سماح (TimeoutStopSec) قبل الإنهاء النهائي. تؤدي إعادة استخدام --run-id بينما لا يزال تشغيل Gateway الأصلي نشطًا إلى الإبلاغ عن النسخة المكررة بوصفها قيد التنفيذ بدلًا من بدء تشغيل ثانٍ.
  • تحاول عمليات التشغيل المعزولة، بأفضل جهد ممكن، إغلاق علامات تبويب/عمليات المتصفح المتتبعة لجلسة cron:<jobId> الخاصة بها عند الاكتمال، والتخلص من أي مثيلات وقت تشغيل MCP مضمّنة أُنشئت للمهمة عبر مسار التنظيف المشترك نفسه المستخدم في عمليات الجلسة الرئيسية والجلسات المخصصة. تُتجاهل حالات فشل التنظيف كي تظل نتيجة Cron هي المعتمدة.
  • يمكن لعمليات التشغيل المعزولة ذات منحة التنظيف الذاتي المحدودة لـ Cron قراءة حالة المجدول، وقائمة مصفاة ذاتيًا لا تحتوي إلا على مهمتها، وسجل تشغيل تلك المهمة، ولا يجوز لها إزالة سوى مهمتها الخاصة.
  • تحمي عمليات التشغيل المعزولة من ردود الإقرار القديمة: إذا كانت النتيجة الأولى مجرد تحديث مؤقت للحالة (on it وpulling everything together وتلميحات مشابهة) ولم يعد أي وكيل فرعي تابع مسؤولًا عن الإجابة النهائية، يعيد OpenClaw المطالبة مرة واحدة للحصول على النتيجة الفعلية قبل التسليم.
  • يُتعرّف على بيانات تعريف رفض التنفيذ المنظّمة (بما في ذلك مغلفات مضيف Node ذات UNAVAILABLE التي يبدأ خطؤها المتداخل بـ SYSTEM_RUN_DENIED أو INVALID_REQUEST) حتى لا يُبلّغ عن أمر محظور على أنه تشغيل ناجح، مع عدم الخلط بين نثر المساعد العادي وبين الرفض.
  • تُحتسب حالات فشل الوكيل على مستوى التشغيل أخطاءً في المهمة حتى دون وجود حمولة رد، لذلك تزيد حالات فشل النموذج/المزوّد عدادات الأخطاء وتطلق إشعارات الفشل بدلًا من اعتبار المهمة ناجحة.
  • عندما تبلغ مهمة timeoutSeconds، يلغي Cron التشغيل ويمنحه نافذة تنظيف قصيرة. وإذا لم يُنهِ أعماله خلالها، يزيل التنظيف المملوك لـ Gateway ملكية جلسة ذلك التشغيل قسرًا قبل أن يسجّل Cron انتهاء المهلة، كي لا تبقى أعمال الدردشة الموضوعة في قائمة الانتظار عالقة خلف جلسة معالجة قديمة.
  • تحصل حالات التعطل أثناء الإعداد/بدء التشغيل على مهلة خاصة بالمرحلة (مثل cron: isolated agent setup timed out before runner start أو cron: isolated agent run stalled before execution start (last phase: context-engine)). تغطي أدوات المراقبة هذه المزوّدين المضمّنين والمدعومين بـ CLI حتى قبل بدء عملية CLI الخارجية الخاصة بهم، وتُحدّ بصورة مستقلة عن قيم timeoutSeconds الطويلة لكي تظهر حالات فشل البدء البارد/المصادقة/السياق بسرعة.
تكون ملكية تسوية مهام Cron لوقت التشغيل أولًا، ثم تستند إلى السجل الدائم ثانيًا: تظل مهمة Cron النشطة حية ما دام وقت تشغيل Cron يتتبع تلك المهمة باعتبارها قيد التشغيل، حتى إذا ظل صف جلسة فرعية قديم موجودًا. بعد أن يتوقف وقت التشغيل عن امتلاك المهمة وتنقضي نافذة سماح مدتها 5 دقائق، تتحقق الصيانة من سجلات التشغيل المحفوظة وحالة المهمة لتشغيل cron:<jobId>:<startedAt> المطابق. تؤدي النتيجة النهائية هناك إلى إنهاء دفتر المهام؛ وإلا يمكن للصيانة المملوكة لـ Gateway وضع علامة lost على المهمة. يمكن لتدقيق CLI دون اتصال الاسترداد من السجل الدائم، لكن كون مجموعة مهامه النشطة داخل العملية فارغة لا يُعد دليلًا على انتهاء تشغيل مملوك لـ Gateway.

أنواع الجداول

تُعامَل الطوابع الزمنية التي لا تحتوي على منطقة زمنية على أنها UTC. أضف --tz America/New_York لتفسير تاريخ ووقت --at بلا إزاحة، أو لتقييم تعبير Cron، وفق منطقة IANA الزمنية تلك. تستخدم تعبيرات Cron التي لا تحتوي على --tz المنطقة الزمنية لمضيف Gateway. لا يصح استخدام --tz مع --every أو --on-exit. تُوزّع تلقائيًا التعبيرات المتكررة عند بداية الساعة (الدقيقة 0 مع حقل ساعة ذي حرف بدل) على مدة تصل إلى 5 دقائق لتقليل طفرات الحمل. استخدم --exact لفرض توقيت دقيق، أو --stagger 30s لتحديد نافذة صريحة (لجداول Cron فقط).

يستخدم يوم الشهر ويوم الأسبوع منطق OR

تُحلَّل تعبيرات Cron بواسطة croner. عندما لا يكون كل من حقلي يوم الشهر ويوم الأسبوع حرف بدل، يطابق croner إذا طابق أيٌّ من الحقلين، وليس كلاهما. هذا هو سلوك Vixie cron القياسي.
يؤدي هذا إلى التشغيل نحو 5-6 مرات شهريًا بدلًا من 0-1 مرة شهريًا. لاشتراط تحقق الشرطين، استخدم معدّل يوم الأسبوع + الخاص بـ croner‏ (0 9 15 * +1)، أو جدوِل وفق أحد الحقلين وتحقق من الآخر في مطالبة مهمتك أو أمرها.

مشغّلات الأحداث (مراقبات الشروط)

يضيف مشغّل الحدث برنامجًا نصيًا بلا واجهة لشرط إلى جدول every أو cron. يقيّم Cron البرنامج النصي عند حلول موعد المهمة وينفّذ الحمولة العادية فقط عندما يعيد البرنامج النصي fire: true:
يجب أن يعيد البرنامج النصي { fire, message?, state? }. تتوفر حالة JSON السابقة بوصفها trigger.state مجمّدة بعمق؛ أعد قيمة state جديدة للاحتفاظ بها. الحد الأقصى للحالة هو 16 KB. عندما تتضمن نتيجة تشغيل message، يلحقها Cron بنص حدث النظام أو رسالة دورة الوكيل قبل التنفيذ. يعطّل once: true المهمة بعد أول حمولة مُشغَّلة ناجحة لها. يحتفظ fire: false بحالة التقييم والعدادات، ثم يعيد الجدولة دون إنشاء سجل تشغيل. إذا فشل تشغيل حمولة مُشغَّلة، فلا تُحفَظ قيمة state المعادة — يرى التقييم التالي الحالة السابقة ويمكنه التشغيل مجددًا، لذلك اكتب البرامج النصية على هيئة عمليات تحقق للقراءة فقط، واحتفظ بالإجراءات داخل الحمولة. لمجداول المشغّلات حد أدنى قابل للضبط للفاصل الزمني (30 ثانية افتراضيًا). لكل تقييم ميزانية وقت فعلي قدرها 30 ثانية وما يصل إلى 5 استدعاءات للأدوات.
يتيح تفعيل cron.triggers.enabled للبرامج النصية التي يؤلفها الوكيل العمل دون واجهة باستخدام سياسة الأدوات الكاملة للوكيل المالك، بما فيها exec. تعامل مع هذا على أنه تنفيذ غير مراقب للتعليمات البرمجية بصلاحيات ذلك الوكيل؛ واتركه معطّلًا ما لم تكن جميع الوكلاء المسموح لهم بإنشاء مهام Cron موثوقين وفقًا لذلك.
أنشئ مراقبًا من ملف برنامج نصي محلي (- يقرأ البرنامج النصي من stdin):

الحمولات

تحمل كل مهمة نوع حمولة واحدًا بالضبط، ويُختار بواسطة العلامة:

خيارات دورة الوكيل

string
مطلوب
نص المطالبة (مطلوب لمهام الجلسة المعزولة/الحالية/المخصصة).
string
تجاوز النموذج؛ يجب أن يُحل إلى نموذج مسموح به، وإلا يفشل التشغيل بخطأ تحقق.
string
قائمة نماذج احتياطية لكل مهمة، على سبيل المثال --fallbacks openai/gpt-5.6-sol,openrouter/meta-llama/llama-3.3-70b-instruct:free. مرّر --fallbacks "" لتشغيل صارم بلا نماذج احتياطية.
boolean
عند cron edit، يزيل تجاوز النماذج الاحتياطية الخاص بالمهمة لكي تتبع المهمة أسبقية النماذج الاحتياطية المُعدّة. لا يمكن دمجه مع --fallbacks.
boolean
عند cron edit، يزيل تجاوز النموذج الخاص بالمهمة لكي تتبع المهمة أسبقية نموذج Cron المعتادة (تجاوز جلسة Cron المخزّن، وإلا نموذج الوكيل/النموذج الافتراضي). لا يمكن دمجه مع --model.
string
تجاوز مستوى التفكير (off|minimal|low|medium|high|xhigh|adaptive|max|ultra). تظل المستويات المتاحة معتمدة على النموذج المحدد وبيئة تشغيل الوكيل.
boolean
عند cron edit، يزيل تجاوز التفكير الخاص بالمهمة. لا يمكن دمجه مع --thinking.
boolean
تخطّي حقن ملف تمهيد مساحة العمل.
string
تقييد الأدوات التي يمكن للمهمة استخدامها، على سبيل المثال --tools exec,read.
يعيّن --model النموذج الأساسي للمهمة؛ ولا يستبدل تجاوز /model للجلسة، لذلك تظل سلاسل النماذج الاحتياطية المُعدّة مطبّقة فوقه. يؤدي النموذج الذي لا يمكن حله أو غير المسموح به إلى فشل التشغيل بخطأ تحقق صريح بدلًا من الرجوع بصمت إلى النموذج الافتراضي. إذا كانت لدى مهمة قيمة --model ولكن ليست لديها قائمة نماذج احتياطية صريحة أو مُعدّة، يمرّر OpenClaw تجاوزًا فارغًا للنماذج الاحتياطية بدلًا من إلحاق النموذج الأساسي للوكيل بصمت بوصفه هدفًا مخفيًا لإعادة المحاولة. أسبقية اختيار النموذج للمهام المعزولة، من الأعلى إلى الأدنى:
  1. حمولة كل مهمة model (إعداد صريح؛ يؤدي النموذج غير المسموح به إلى فشل التشغيل)
  2. تجاوز نموذج خطاف Gmail (فقط عندما يكون التشغيل صادرًا من Gmail ويكون ذلك التجاوز مسموحًا به)
  3. تجاوز نموذج جلسة Cron المخزّن الذي حدده المستخدم
  4. اختيار نموذج الوكيل/النموذج الافتراضي
يتبع الوضع السريع الاختيار الفعلي الذي تم حله. إذا كان إعداد النموذج المحدد يتضمن params.fastMode، يستخدمه Cron المعزول افتراضيًا؛ ويظل تجاوز الجلسة المخزّن fastMode (ثم تجاوز الوكيل fastModeDefault) متفوقًا على إعداد النموذج في كلا الاتجاهين. يستخدم الوضع التلقائي حد params.fastAutoOnSeconds الخاص بالنموذج، وتكون قيمته الافتراضية 60 ثانية. إذا واجه تشغيل عملية تسليم مباشرة بسبب تبديل النموذج، يعيد Cron المحاولة باستخدام المزوّد/النموذج الذي جرى التبديل إليه، ويحفظ ذلك الاختيار (وأي ملف تعريف مصادقة جديد) للتشغيل النشط. إعادة المحاولات محدودة: بعد المحاولة الأولية ومحاولتي تبديل، يُجهض Cron بدلًا من الدخول في حلقة. قبل بدء تشغيل معزول، يتحقق OpenClaw من نقاط النهاية المحلية القابلة للوصول لمزوّدي api: "ollama" وapi: "openai-completions" المُعدّين الذين تكون قيمة baseUrl لديهم عنوان استرجاع حلقيًا أو شبكة خاصة أو .local. يجتاز هذا الفحص التمهيدي سلسلة النماذج الاحتياطية المُعدّة للمهمة، ولا يضع علامة skipped على التشغيل إلا بعد تعذر الوصول إلى كل مرشح؛ ويُبقي --fallbacks "" هذا الاجتياز مقصورًا بصرامة على النموذج الأساسي فقط. تسجّل نقطة النهاية المتوقفة التشغيل بالحالة skipped مع خطأ واضح بدلًا من بدء استدعاء النموذج. تُخزّن النتيجة مؤقتًا لمدة 5 دقائق لكل نقطة نهاية (وليس لكل مهمة أو نموذج)، لذا لا تتسبب مهام كثيرة مستحقة تشترك في خادم Ollama/vLLM/SGLang/LM Studio محلي متوقف إلا في فحص واحد بدلًا من عاصفة طلبات. لا تزيد عمليات التشغيل التي يتخطاها الفحص التمهيدي مدة التراجع لأخطاء التنفيذ؛ عيّن failureAlert.includeSkipped لتفعيل تنبيهات التخطي المتكررة.

حمولات الأوامر

تشغّل حمولات الأوامر نصوصًا برمجية حتمية داخل مجدول Gateway من دون بدء دور مدعوم بنموذج. تُنفّذ على مضيف Gateway، وتلتقط stdout/stderr، وتسجّل التشغيل في سجل Cron، وتعيد استخدام أوضاع التسليم نفسها announce وwebhook وnone التي تستخدمها مهام دور الوكيل.
يمثّل Cron الخاص بالأوامر سطح أتمتة إداريًا للمشغّل في Gateway، وليس استدعاء tools.exec من وكيل. يتطلب إنشاء مهام Cron أو تحديثها أو إزالتها أو تشغيلها يدويًا operator.admin؛ وتُنفّذ عمليات تشغيل الأوامر المجدولة لاحقًا داخل عملية Gateway بوصفها أتمتة أنشأها ذلك المسؤول. تحكم سياسة تنفيذ الوكيل (tools.exec.mode، ومطالبات الموافقة، وقوائم الأدوات المسموح بها لكل وكيل) أدوات التنفيذ المرئية للنموذج، وليس حمولات Cron الخاصة بالأوامر.
يخزّن --command <shell> القيمة argv: ["sh", "-lc", <shell>]. استخدم --command-argv '["node","scripts/report.mjs"]' لتنفيذ argv بدقة من دون تحليل الصدفة. تتحكم القيم الاختيارية --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، وتوقظ Heartbeat اختياريًا (--wake now أو --wake next-heartbeat). يمكنها استخدام آخر سياق تسليم للجلسة الرئيسية المستهدفة للردود، لكنها لا تلحق أدوار Cron الروتينية بمسار الدردشة البشرية، ولا تمدد حداثة إعادة الضبط اليومية/عند الخمول للجلسة المستهدفة. تشغّل المهام المعزولة دور وكيل مخصصًا بجلسة جديدة. تحتفظ الجلسات المخصصة (session:xxx) بالسياق عبر عمليات التشغيل، مما يتيح تدفقات عمل مثل الاجتماعات اليومية التي تبني على الملخصات السابقة.أحداث Cron للجلسة الرئيسية هي تذكيرات أحداث نظام مكتفية ذاتيًا. وهي لا تتضمن تلقائيًا تعليمة “Read HEARTBEAT.md” الواردة في مطالبة Heartbeat الافتراضية؛ اذكر ذلك صراحةً في نص حدث Cron إذا كان ينبغي للتذكير الرجوع إلى HEARTBEAT.md.
معرّف نص/جلسة جديد لكل تشغيل. ينقل OpenClaw التفضيلات الآمنة (إعدادات التفكير/السرعة/الإسهاب، والتسميات، وتجاوزات النموذج/المصادقة الصريحة التي حددها المستخدم)، لكنه لا يرث سياق المحادثة المحيط من صف Cron أقدم: توجيه القناة/المجموعة، أو سياسة الإرسال أو الاصطفاف، أو رفع الامتيازات، أو الأصل، أو ارتباط بيئة تشغيل ACP. استخدم current أو session:<id> عندما ينبغي لمهمة متكررة أن تبني عمدًا على سياق المحادثة نفسه.
عندما تنسّق عمليات Cron المعزولة وكلاء فرعيين، يفضّل التسليم المخرجات النهائية لأحدث تابع على النص المرحلي القديم للأصل. إذا ظلت التوابع قيد التشغيل، يكبت OpenClaw ذلك التحديث الجزئي للأصل بدلًا من الإعلان عنه.بالنسبة إلى أهداف إعلان Discord النصية فقط، يرسل OpenClaw النص النهائي المعتمد للمساعد مرة واحدة بدلًا من إعادة تشغيل كل من النص المتدفق/المرحلي والإجابة النهائية. تظل الوسائط وحمولات Discord المنظّمة تُسلّم بصورة منفصلة حتى لا تُسقط المرفقات والمكوّنات.

التسليم والمخرجات

استخدم --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>) صياغة هدف مملوكة للقناة، وليست محددات للمزوّد. بالنسبة إلى المهام المعزولة، يكون تسليم الدردشة مشتركًا: إذا كان مسار دردشة متاحًا، يمكن للوكيل استخدام أداة message حتى مع --no-deliver. إذا أرسل الوكيل إلى الهدف المُعدّ/الحالي، يتخطى 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 لغة الرد من القناة أو الإعدادات المحلية أو الرسائل السابقة. ضع قاعدة اللغة في الرسالة المجدولة أو القالب:
بالنسبة إلى ملفات القوالب، أبقِ تعليمة اللغة في المطالبة المعروضة وتحقّق من ملء العناصر النائبة مثل {{language}} قبل تشغيل المهمة. إذا مزجت المخرجات بين اللغات، فاجعل القاعدة صريحة، مثل: “استخدم الصينية للنص السردي وأبقِ المصطلحات التقنية بالإنجليزية.”

أمثلة CLI

إدارة المهام

تؤدي أرشفة جلسة (من واجهة التحكم، أو عبر sessions.patch { archived: true } من مستدعٍ مسؤول عن إدارة المشغّلين) إلى تعطيل كل مهمة Cron مفعّلة مرتبطة بتلك الجلسة: جلسة cron:<jobId> المعزولة الخاصة بها، أو هدف session:<key>، أو مسار تسليم/إيقاظ sessionKey. لا تؤدي استعادة الجلسة إلى إعادة تمكين تلك المهام؛ استخدم openclaw cron enable <jobId>. تعرض الجلسات التي لها مهمة مرتبطة مفعّلة شارة ساعة في الشريط الجانبي لواجهة التحكم. يعود openclaw cron run <jobId> بعد إدراج التشغيل اليدوي في قائمة الانتظار. استخدم --wait لخطافات إيقاف التشغيل أو نصوص الصيانة البرمجية أو غيرها من عمليات الأتمتة التي يجب أن تتوقف حتى ينتهي التشغيل المدرج في قائمة الانتظار؛ إذ يستطلع runId المُعاد (مهلة افتراضية 10m، وفاصل استطلاع 2s) ويخرج بالرمز 0 للحالة ok، وبرمز غير صفري للحالات 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) تتبعه مطالبة وكيل موضعية. استخدم --webhook <url> في cron add|create أو cron edit لإرسال حمولة التشغيل المكتمل بأسلوب POST إلى نقطة نهاية HTTP؛ ولا يمكن الجمع بين تسليم Webhook وعلامات تسليم الدردشة (--announce، و--channel، و--to، و--thread-id، و--account). في cron edit، تُلغي --clear-channel و--clear-to و--clear-thread-id و--clear-account تعيين حقول التوجيه تلك كلٌّ على حدة (ويُرفض كل منها عند استخدامه مع علامة التعيين المطابقة له) — بخلاف --no-deliver، الذي يعطّل فقط تسليم الرجوع الاحتياطي للمشغّل.
ملاحظة حول تجاوز النموذج:
  • openclaw cron add|edit --model ... يغيّر النموذج المحدد للمهمة.
  • إذا كان النموذج مسموحًا، فسيصل ذلك المزوّد/النموذج المحدد بعينه إلى تشغيل الوكيل المعزول.
  • إذا لم يكن مسموحًا أو تعذّر حسمه، يفشل Cron التشغيل بخطأ تحقق صريح.
  • يمكن لتصحيحات حمولة cron.update في API تعيين model: null لمسح تجاوز نموذج مخزّن للمهمة.
  • openclaw cron edit <job-id> --clear-model يمسح ذلك التجاوز من CLI (وله التأثير نفسه لتصحيح model: null) ولا يمكن دمجه مع --model.
  • تظل سلاسل الرجوع الاحتياطي المضبوطة سارية لأن --model في Cron هو النموذج الأساسي للمهمة، وليس تجاوز /model للجلسة.
  • openclaw cron add|edit --fallbacks ... يعيّن fallbacks في الحمولة، مستبدلًا خيارات الرجوع الاحتياطي المضبوطة لتلك المهمة؛ ويعطّل --fallbacks "" الرجوع الاحتياطي ويجعل التشغيل صارمًا. يمسح openclaw cron edit <job-id> --clear-fallbacks التجاوز الخاص بالمهمة.
  • لا ينتقل --model عادي من دون قائمة رجوع احتياطي صريحة أو مضبوطة إلى النموذج الأساسي للوكيل بوصفه هدف إعادة محاولة إضافيًا صامتًا.

Webhooks

يمكن لـ Gateway إتاحة نقاط نهاية Webhook عبر HTTP للمشغلات الخارجية. مكّنها في الإعدادات:

المصادقة

يجب أن يتضمن كل طلب رمز الخطاف عبر الترويسة:
  • Authorization: Bearer <token> (موصى به)
  • x-openclaw-token: <token>
تُرفض الرموز المرسلة في سلسلة الاستعلام.
أدرج حدث نظام للجلسة الرئيسية في قائمة الانتظار:
string
مطلوب
وصف الحدث.
string
افتراضي:"now"
now أو next-heartbeat.
شغّل دورًا معزولًا للوكيل:
الحقول: message (مطلوب)، وname، وagentId، وsessionKey (يتطلب hooks.allowRequestSessionKey=true)، وidempotencyKey، وwakeMode، وdeliver، وchannel، وto، وmodel، وthinking، وtimeoutSeconds.
تُحسم أسماء الخطافات المخصصة عبر hooks.mappings في الإعدادات. يمكن للتعيينات تحويل حمولات اعتباطية إلى إجراءات wake أو agent باستخدام قوالب أو تحويلات برمجية.
أبقِ نقاط نهاية الخطافات خلف واجهة الاسترجاع أو شبكة tailnet أو وكيل عكسي موثوق.
  • استخدم رمزًا مخصصًا للخطافات؛ ولا تُعد استخدام رموز مصادقة Gateway.
  • أبقِ hooks.path في مسار فرعي مخصص؛ إذ يُرفض /.
  • عيّن hooks.allowedAgentIds لتقييد الوكيل الفعلي الذي يمكن للخطاف استهدافه، بما في ذلك الوكيل الافتراضي عند حذف agentId.
  • أبقِ hooks.allowRequestSessionKey=false ما لم تكن تحتاج إلى جلسات يحددها المستدعي.
  • إذا مكّنت hooks.allowRequestSessionKey، فعيّن أيضًا hooks.allowedSessionKeyPrefixes لتقييد أشكال مفاتيح الجلسات المسموح بها.
  • تُغلّف حمولات الخطافات بحدود أمان افتراضيًا.

تكامل Gmail PubSub

اربط مشغلات صندوق وارد Gmail بـ OpenClaw عبر Google PubSub.
المتطلبات الأساسية: CLI الخاص بـ gcloud، وgog (gogcli)، وخطافات OpenClaw مفعّلة، وTailscale لنقطة نهاية HTTPS العامة.

الإعداد باستخدام المعالج (موصى به)

يكتب هذا إعدادات hooks.gmail، ويمكّن الإعداد المسبق لـ Gmail، ويستخدم Tailscale Funnel افتراضيًا لنقطة نهاية الدفع (--tailscale funnel|serve|off).
تفصل الجلسة الخاصة بكل رسالة في إعداد Gmail المسبق سياق المحادثة؛ لكنها لا تقيّد أدوات الوكيل المستهدف أو مساحة عمله. من دون تعيين مخصص يضبط agentId، تعمل خطافات Gmail بصفتها الوكيل الافتراضي.بالنسبة إلى صناديق الوارد غير الموثوقة، وجّه الخطاف إلى وكيل قارئ مخصص، وامنح ذلك الوكيل وصولًا للقراءة فقط إلى مساحة العمل أو امنعه من الوصول إليها، واحظر الكتابة إلى نظام الملفات وصدفة الأوامر والمتصفح وغيرها من الأدوات غير الضرورية. إذا احتاج إلى إخطار الوكيل الرئيسي، فاسمح فقط بعملية التسليم المطلوبة من وكيل إلى وكيل. راجع حقن المطالبات، ووضع الحماية والأدوات متعددة الوكلاء، وtools.agentToAgent.

التشغيل التلقائي لـ Gateway

عندما يكون hooks.enabled=true مفعّلًا ويكون hooks.gmail.account معيّنًا، يبدأ Gateway تشغيل gog gmail watch serve عند الإقلاع ويجدد المراقبة تلقائيًا. عيّن OPENCLAW_SKIP_GMAIL_WATCHER=1 لإلغاء الاشتراك.

إعداد يدوي لمرة واحدة

1

اختيار مشروع GCP

اختر مشروع GCP الذي يملك عميل OAuth الذي يستخدمه gog:
2

إنشاء الموضوع ومنح صلاحية إرسال إشعارات Gmail

3

بدء المراقبة

تجاوز نموذج Gmail

استخدم أحدث جيل وأفضل فئة من النماذج المتاحة لدى مزودك لصناديق الوارد غير الموثوقة. القيمة أعلاه مثال؛ ويجب أن يكون النموذج موجودًا في الكتالوج وقائمة السماح اللذين أعددتهما.

الإعداد

قيم retry أعلاه هي القيم الافتراضية: ما يصل إلى 3 محاولات إعادة باستخدام تراجع 30s/60s/5m، مع إعادة المحاولة للفئات الخمس العابرة جميعها. يُرسل webhookToken بصفته Authorization: Bearer <token> في طلبات POST الخاصة بـ Webhook لـ Cron. يحدّ maxConcurrentRuns كلًا من إرسال Cron المجدول وتنفيذ دور الوكيل المعزول، وتبلغ قيمته الافتراضية 8. تستخدم أدوار وكيل Cron المعزولة داخليًا مسار التنفيذ cron-nested المخصص للطابور، لذا تتيح زيادة هذه القيمة لعمليات تشغيل LLM المستقلة الخاصة بـ Cron التقدم بالتوازي بدلًا من بدء أغلفة Cron الخارجية فقط. لا يوسّع هذا الإعداد مسار nested المشترك غير الخاص بـ Cron. يمثل cron.store مفتاح تخزين منطقيًا ومسار ترحيل لأداة doctor، وليس ملف JSON مباشرًا لتحريره يدويًا. توجد بيانات المهام في SQLite؛ استخدم CLI أو واجهة Gateway API لإجراء التغييرات. لتعطيل Cron: cron.enabled: false أو OPENCLAW_SKIP_CRON=1.
إعادة محاولة التشغيل لمرة واحدة: يُعاد تنفيذ الأخطاء العابرة (تجاوز حد المعدل، الحمل الزائد، الشبكة، انتهاء المهلة، خطأ الخادم) حتى retry.maxAttempts مرات (الافتراضي 3) باستخدام retry.backoffMs (الافتراضي 30s، و60s، و5m). تعطّل الأخطاء الدائمة المهمة فورًا.إعادة محاولة التشغيل المتكرر: تتراجع أخطاء التنفيذ المتتالية وفق جدول زمني ممتد (30s، و60s، و5m، و15m، و60m). يُعاد ضبط التراجع بعد التشغيل الناجح التالي.
يحذف cron.sessionRetention (الافتراضي 24h، ويعطّله false) إدخالات جلسات التشغيل المعزولة. يحتفظ سجل التشغيل بأحدث 2000 صف نهائي لكل مهمة؛ وتحتفظ الصفوف المفقودة بنافذة التنظيف البالغة 24 ساعة.
عند الترقية، شغّل openclaw doctor --fix لاستيراد ملفات ~/.openclaw/cron/jobs.json وjobs-state.json وruns/*.jsonl القديمة إلى SQLite وإعادة تسميتها باستخدام اللاحقة .migrated. تُستبعد صفوف المهام المشوهة من وقت التشغيل وتُنسخ إلى jobs-quarantine.json لإصلاحها أو مراجعتها لاحقًا.

استكشاف الأخطاء وإصلاحها

تسلسل الأوامر

  • تحقق من cron.enabled ومتغير البيئة OPENCLAW_SKIP_CRON.
  • تأكد من استمرار تشغيل Gateway.
  • بالنسبة إلى جداول cron، تحقق من المنطقة الزمنية (--tz) مقارنةً بالمنطقة الزمنية للمضيف.
  • يعني reason: not-due في مخرجات التشغيل أن التشغيل اليدوي فُحص باستخدام openclaw cron run <jobId> --due وأن موعد المهمة لم يحن بعد.
  • يعني وضع التسليم none أنه لا يُتوقع إرسال احتياطي من المشغّل. لا يزال بإمكان الوكيل الإرسال مباشرةً باستخدام أداة message عند توفر مسار محادثة.
  • يعني فقدان هدف التسليم أو عدم صلاحيته (channel/to) أنه تم تخطي الإرسال الصادر.
  • بالنسبة إلى Matrix، قد تفشل المهام المنسوخة أو القديمة التي تحتوي على معرّفات غرف delivery.to مكتوبة بأحرف صغيرة، لأن معرّفات غرف Matrix حساسة لحالة الأحرف. عدّل المهمة لاستخدام قيمة !room:server أو room:!room:server الدقيقة من Matrix.
  • تعني أخطاء مصادقة القناة (unauthorized، Forbidden) أن بيانات الاعتماد منعت التسليم.
  • إذا أعاد التشغيل المعزول رمز الصمت فقط (NO_REPLY / no_reply)، فإن OpenClaw يمنع التسليم الصادر المباشر ومسار الملخص الاحتياطي الموضوع في الطابور، لذلك لا يُنشر شيء في المحادثة.
  • إذا كان ينبغي للوكيل مراسلة المستخدم بنفسه، فتحقق من أن المهمة تحتوي على مسار صالح للاستخدام (channel: "last" مع محادثة سابقة، أو قناة/هدف صريح).
  • لا تعتمد حداثة إعادة الضبط اليومية أو عند الخمول على updatedAt؛ راجع إدارة الجلسات.
  • قد تحدّث تنبيهات Cron وعمليات تشغيل Heartbeat وإشعارات التنفيذ وأعمال حفظ السجلات في Gateway صف الجلسة لأغراض التوجيه/الحالة، لكنها لا تمدّد sessionStartedAt أو lastInteractionAt.
  • بالنسبة إلى الصفوف القديمة المنشأة قبل وجود هذين الحقلين، يستطيع OpenClaw استعادة sessionStartedAt من رأس جلسة نص JSONL عندما يظل الملف متاحًا. تستخدم صفوف الخمول القديمة التي لا تحتوي على lastInteractionAt وقت البدء المستعاد هذا خط أساس للخمول.
  • يستخدم Cron من دون --tz المنطقة الزمنية لمضيف Gateway.
  • تُعامل جداول at التي لا تحتوي على منطقة زمنية على أنها بتوقيت UTC.
  • يستخدم activeHours الخاص بـ Heartbeat آلية تحديد المنطقة الزمنية المضبوطة.

ذو صلة