المهام المجدولة

Cron هو المجدول المدمج في Gateway. يحتفظ بالمهام، ويوقظ الوكيل في الوقت المناسب، ويمكنه تسليم المخرجات مرة أخرى إلى قناة دردشة أو نقطة نهاية Webhook.

البدء السريع

openclaw cron add \  --name "Reminder" \  --at "2026-02-01T16:00:00Z" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

كيف يعمل Cron

• يعمل Cron داخل عملية Gateway (وليس داخل النموذج).
• تبقى تعريفات المهام محفوظة في ~/.openclaw/cron/jobs.json كي لا تؤدي إعادة التشغيل إلى فقدان الجداول.
• تبقى حالة التنفيذ وقت التشغيل محفوظة بجانبها في ~/.openclaw/cron/jobs-state.json. إذا كنت تتبع تعريفات Cron في git، فتتبع jobs.json وضع jobs-state.json في gitignore.
• بعد التقسيم، يمكن لإصدارات OpenClaw الأقدم قراءة jobs.json لكنها قد تعامل المهام كأنها جديدة لأن حقول وقت التشغيل أصبحت الآن في jobs-state.json.
• عند تحرير jobs.json أثناء تشغيل Gateway أو توقفه، يقارن OpenClaw حقول الجدولة المتغيرة مع بيانات تعريف خانة وقت التشغيل المعلقة ويمسح قيم nextRunAtMs القديمة. أما إعادة الكتابة التي تقتصر على التنسيق أو ترتيب المفاتيح فقط فتحافظ على الخانة المعلقة.
• تنشئ كل تنفيذات Cron سجلات مهام في الخلفية.
• عند بدء تشغيل Gateway، يعاد جدولة مهام دور الوكيل المعزولة المتأخرة خارج نافذة اتصال القناة بدلا من إعادة تشغيلها فورا، كي يبقى بدء تشغيل Discord/Telegram وإعداد الأوامر الأصلية مستجيبا بعد إعادة التشغيل.
• تحذف المهام أحادية التنفيذ (--at) نفسها تلقائيا بعد النجاح افتراضيا.
• تغلق تشغيلات Cron المعزولة، وفق أفضل جهد، علامات تبويب/عمليات المتصفح المتتبعة لجلسة cron:<jobId> الخاصة بها عند اكتمال التشغيل، كي لا تترك أتمتة المتصفح المنفصلة عمليات يتيمة خلفها.
• يمكن لتشغيلات Cron المعزولة التي تتلقى منحة التنظيف الذاتي الضيقة الخاصة بـ Cron أن تظل قادرة على قراءة حالة المجدول، وقائمة مفلترة ذاتيا بمهمتها الحالية، وسجل تشغيل تلك المهمة، بحيث يمكن لفحوصات الحالة/Heartbeat فحص جدولها الخاص دون الحصول على وصول أوسع لتعديل Cron.
• تحمي تشغيلات Cron المعزولة أيضا من ردود الإقرار القديمة. إذا كانت النتيجة الأولى مجرد تحديث حالة مؤقت (on it، وpulling everything together، وتلميحات مشابهة) ولم يعد أي تشغيل لوكيل فرعي تابع مسؤولا عن الإجابة النهائية، يعيد OpenClaw طلب النتيجة الفعلية مرة واحدة قبل التسليم.
• تفضل تشغيلات Cron المعزولة بيانات تعريف رفض التنفيذ المنظمة من التشغيل المضمن، ثم تعود إلى علامات الملخص/المخرجات النهائية المعروفة مثل SYSTEM_RUN_DENIED وINVALID_REQUEST، بحيث لا يبلغ عن أمر محظور كتشغيل ناجح.
• تعامل تشغيلات Cron المعزولة أيضا إخفاقات الوكيل على مستوى التشغيل كأخطاء مهمة حتى عند عدم إنتاج حمولة رد، بحيث تزيد إخفاقات النموذج/الموفر عدادات الأخطاء وتطلق إشعارات الفشل بدلا من اعتبار المهمة ناجحة.
• عندما تصل مهمة دور وكيل معزولة إلى timeoutSeconds، يوقف Cron تشغيل الوكيل الأساسي ويمنحه نافذة تنظيف قصيرة. إذا لم ينته التشغيل، يمسح التنظيف المملوك لـ Gateway قسرا ملكية جلسة ذلك التشغيل قبل أن يسجل Cron انتهاء المهلة، كي لا يبقى عمل الدردشة في الطابور خلف جلسة معالجة قديمة.
• إذا توقف دور وكيل معزول قبل بدء المشغل أو قبل أول استدعاء للنموذج، يسجل Cron انتهاء مهلة خاصا بالمرحلة مثل setup timed out before runner start أو stalled before first model call (last phase: context-engine). تغطي آليات المراقبة هذه الموفرين المضمنين والموفرين المدعومين بـ CLI قبل أن تبدأ عملية CLI الخارجية فعليا، وتكون محددة بسقف مستقل عن قيم timeoutSeconds الطويلة كي تظهر إخفاقات البدء البارد/المصادقة/السياق بسرعة بدلا من انتظار ميزانية المهمة الكاملة.

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

تعامل الطوابع الزمنية بلا منطقة زمنية كـ UTC. أضف --tz America/New_York للجدولة وفق ساعة الحائط المحلية.

توزع تعبيرات التكرار عند رأس الساعة تلقائيا بفارق يصل إلى 5 دقائق لتقليل طفرات الحمل. استخدم --exact لفرض توقيت دقيق أو --stagger 30s لنافذة صريحة.

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

تحلل تعبيرات Cron بواسطة croner. عندما يكون حقلا يوم الشهر ويوم الأسبوع غير شاملين، يطابق croner عندما يطابق أي من الحقلين، وليس كلاهما. هذا هو سلوك Vixie cron القياسي.

# Intended: "9 AM on the 15th, only if it's a Monday"# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"0 9 15 * 1

ينطلق هذا نحو 5 إلى 6 مرات شهريا بدلا من 0 إلى 1 مرة شهريا. يستخدم OpenClaw هنا سلوك OR الافتراضي في Croner. لاشتراط تحقق كلا الشرطين، استخدم معدّل يوم الأسبوع + الخاص بـ Croner (0 9 15 * +1) أو جدوله على حقل واحد وافحص الآخر في موجه المهمة أو أمرها.

أنماط التنفيذ

خيارات الحمولة للمهام المعزولة

يستخدم --model النموذج المسموح المحدد كنموذج أساسي لتلك المهمة. ليس هذا مماثلا لتجاوز /model الخاص بجلسة الدردشة: لا تزال سلاسل الرجوع المهيأة تنطبق عندما يفشل نموذج المهمة الأساسي. إذا لم يكن النموذج المطلوب مسموحا به أو تعذر حله، يفشل Cron التشغيل بخطأ تحقق صريح بدلا من الرجوع بصمت إلى اختيار وكيل/نموذج المهمة الافتراضي.

يمكن لمهام Cron أيضا حمل fallbacks على مستوى الحمولة. عند وجودها، تستبدل تلك القائمة سلسلة الرجوع المهيأة للمهمة. استخدم fallbacks: [] في حمولة المهمة/API عندما تريد تشغيل Cron صارما يجرب النموذج المحدد فقط. إذا كانت للمهمة --model ولكن لا توجد بدائل رجوع في الحمولة ولا في التهيئة، يمرر OpenClaw تجاوز رجوع فارغا صريحا بحيث لا يضاف نموذج الوكيل الأساسي كهدف إعادة محاولة إضافي مخفي.

أسبقية اختيار النموذج للمهام المعزولة هي:

1. تجاوز نموذج خطاف Gmail (عندما يأتي التشغيل من Gmail ويكون ذلك التجاوز مسموحا)
2. model في حمولة كل مهمة
3. تجاوز نموذج جلسة Cron المخزن والمحدد من المستخدم
4. اختيار نموذج الوكيل/الافتراضي

يتبع الوضع السريع الاختيار الحي المحلول أيضا. إذا كانت تهيئة النموذج المحدد تحتوي على params.fastMode، يستخدم Cron المعزول ذلك افتراضيا. يظل تجاوز fastMode المخزن في الجلسة هو الغالب على التهيئة في أي اتجاه.

إذا واجه تشغيل معزول تسليما حيا لتبديل النموذج، يعيد Cron المحاولة بالموفر/النموذج الذي تم التحويل إليه ويحفظ ذلك الاختيار الحي للتشغيل النشط قبل إعادة المحاولة. عندما يحمل التبديل أيضا ملف مصادقة جديدا، يحفظ Cron تجاوز ملف المصادقة ذلك للتشغيل النشط أيضا. إعادة المحاولات محدودة: بعد المحاولة الأولية إضافة إلى محاولتي تبديل، يوقف Cron التشغيل بدلا من الدوران إلى الأبد.

قبل أن يدخل تشغيل cron معزول إلى مشغّل الوكيل، يتحقق OpenClaw من نقاط نهاية المزوّد المحلي القابلة للوصول لمزوّدي api: "ollama" وapi: "openai-completions" المكوّنين الذين تكون قيمة baseUrl لديهم loopback أو شبكة خاصة أو .local. إذا كانت نقطة النهاية تلك متوقفة، يُسجّل التشغيل كـ skipped مع خطأ واضح في المزوّد/النموذج بدلًا من بدء استدعاء نموذج. تُخزّن نتيجة نقطة النهاية مؤقتًا لمدة 5 دقائق، لذلك تشترك عدة مهام مستحقة تستخدم خادم Ollama أو vLLM أو SGLang أو LM Studio المحلي نفسه والمتوقف في فحص صغير واحد بدلًا من إنشاء عاصفة طلبات. لا تزيد تشغيلات الفحص المسبق للمزوّد المتخطاة تراجع أخطاء التنفيذ؛ فعّل failureAlert.includeSkipped عندما تريد إشعارات تخطٍ متكررة.

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

استخدم --announce --channel telegram --to "-1001234567890" للتسليم إلى قناة. بالنسبة إلى مواضيع منتدى Telegram، استخدم -1001234567890:topic:123؛ ويمكن لمستدعي 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 عامة الاشتراك في تنبيهات التشغيلات المتخطاة المتكررة. تحتفظ التشغيلات المتخطاة بعدّاد تخطٍ متتالٍ منفصل، لذلك لا تؤثر في تراجع أخطاء التنفيذ.

أمثلة CLI

openclaw cron add \  --name "Calendar check" \  --at "20m" \  --session main \  --system-event "Next heartbeat: check calendar." \  --wake now

openclaw cron add \  --name "Morning brief" \  --cron "0 7 * * *" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Summarize overnight updates." \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "Deep analysis" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Weekly deep analysis of project progress." \  --model "opus" \  --thinking high \  --announce

Webhook

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

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",  },}

المصادقة

يجب أن يتضمن كل طلب رمز الخطاف عبر الترويسة:

• Authorization: Bearer <token> (موصى به)
• x-openclaw-token: <token>

تُرفض رموز سلسلة الاستعلام.

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

تكامل Gmail PubSub

اربط محفزات صندوق وارد Gmail بـ OpenClaw عبر Google PubSub.

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

openclaw webhooks gmail setup --account [email protected]

يكتب هذا إعدادات hooks.gmail، ويفعّل الإعداد المسبق لـ Gmail، ويستخدم Tailscale Funnel لنقطة نهاية الدفع.

بدء Gateway تلقائيًا

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

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

gcloud auth logingcloud config set project <project-id>gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

تجاوز نموذج Gmail

{  hooks: {    gmail: {      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

إدارة المهام

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw cron edit <jobId> --clear-agent

الإعدادات

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 1,    retry: {      maxAttempts: 3,      backoffMs: [60000, 120000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "server_error"],    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",    runLog: { maxBytes: "2mb", keepLines: 2000 },  },}

يحد maxConcurrentRuns من كل من إرسال cron المجدول وتنفيذ دورة الوكيل المعزولة. تستخدم دورات وكلاء cron المعزولة مسار التنفيذ المخصص cron-nested في قائمة الانتظار داخليًا، لذلك يتيح رفع هذه القيمة لتشغيلات LLM مستقلة في cron التقدم بالتوازي بدلًا من بدء أغلفة cron الخارجية فقط. لا يوسّع هذا الإعداد مسار nested المشترك غير الخاص بـ cron.

تُشتق حاوية حالة وقت التشغيل الجانبية من cron.store: يستخدم مخزن .json مثل ~/clawd/cron/jobs.json المسار ~/clawd/cron/jobs-state.json، بينما يضيف مسار مخزن بلا لاحقة .json اللاحقة -state.json.

إذا عدّلت jobs.json يدويًا، فاترك jobs-state.json خارج التحكم بالمصدر. يستخدم OpenClaw تلك الحاوية الجانبية للفتحات المعلقة، والعلامات النشطة، وبيانات آخر تشغيل الوصفية، وهوية الجدول التي تخبر المجدول متى تحتاج مهمة عُدّلت خارجيًا إلى nextRunAtMs جديد.

تعطيل cron: cron.enabled: false أو OPENCLAW_SKIP_CRON=1.

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

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

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

ذات صلة

• الأتمتة — جميع آليات الأتمتة في لمحة
• المهام الخلفية — سجل المهام لتنفيذات cron
• Heartbeat — أدوار الجلسة الرئيسية الدورية
• المنطقة الزمنية — تكوين المنطقة الزمنية