التكوين والعمليات

النبض

النبض مقابل Cron؟ راجع Cron مقابل النبض للحصول على إرشادات حول وقت استخدام كل منهما.

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

البدء السريع (للمبتدئين)

اترك نبضات القلب مفعلة (الإعداد الافتراضي هو 30m، أو 1h لـ Anthropic OAuth/رمز الإعداد) أو اضبط وتيرتك الخاصة.
أنشئ قائمة تحقق صغيرة HEARTBEAT.md في مساحة عمل الوكيل (اختياري ولكنه موصى به).
قرر إلى أين يجب أن تذهب رسائل النبض (target: "none" هو الافتراضي؛ اضبط target: "last" لتوجيهها إلى آخر جهة اتصال).
اختياري: تمكين تسليم استدلال النبض للشفافية.
اختياري: استخدام سياق التمهيد الخفيف إذا كانت عمليات النبض تحتاج فقط إلى HEARTBEAT.md.
اختياري: تقييد النبضات لساعات النشاط (الوقت المحلي).

مثال على التكوين:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // تسليم صريح لآخر جهة اتصال (الافتراضي هو "none")
        directPolicy: "allow", // الافتراضي: السماح بالأهداف المباشرة/الرسائل الخاصة؛ اضبط "block" لقمعها
        lightContext: true, // اختياري: حقن فقط HEARTBEAT.md من ملفات التمهيد
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // اختياري: إرسال رسالة `Reasoning:` منفصلة أيضًا
      },
    },
  },
}

الإعدادات الافتراضية

الفاصل الزمني: 30m (أو 1h عند اكتشاف وضع المصادقة Anthropic OAuth/رمز الإعداد). اضبط agents.defaults.heartbeat.every أو لكل وكيل agents.list[].heartbeat.every؛ استخدم 0m لتعطيله.
نص المطالبة (قابل للتخصيص عبر agents.defaults.heartbeat.prompt): اقرأ HEARTBEAT.md إذا كان موجودًا (سياق مساحة العمل). اتبعه بدقة. لا تستنتج أو تكرر مهام قديمة من الدردشات السابقة. إذا لم يكن هناك شيء يحتاج إلى اهتمام، رد بـ HEARTBEAT_OK.
يتم إرسال مطالبة النبض حرفيًا كرسالة المستخدم. تتضمن مطالبة النظام قسم "النبض" ويتم وضع علامة على التشغيل داخليًا.
يتم التحقق من ساعات النشاط (heartbeat.activeHours) في المنطقة الزمنية المكونة. خارج النافذة الزمنية، يتم تخطي النبضات حتى النقطة الزمنية التالية داخل النافذة.

الغرض من مطالبة النبض

المطالبة الافتراضية واسعة عمدًا:

المهام الخلفية: "ضع في اعتبارك المهام المعلقة" تدفع الوكيل لمراجعة المتابعات (صندوق الوارد، التقويم، التذكيرات، العمل في قائمة الانتظار) وإبراز أي شيء عاجل.
التحقق من الإنسان: "تحقق أحيانًا من إنسانك خلال وقت النهار" تدفع برسالة عرضية خفيفة الوزن "هل تحتاج إلى أي شيء؟"، ولكنها تتجنب الرسائل المزعجة في وقت الليل باستخدام منطقتك الزمنية المحلية المكونة (انظر /concepts/timezone).

إذا كنت تريد أن يقوم النبض بشيء محدد جدًا (مثل "تحقق من إحصائيات Gmail PubSub" أو "تحقق من صحة بوابة النظام")، اضبط agents.defaults.heartbeat.prompt (أو agents.list[].heartbeat.prompt) على نص مخصص (يتم إرساله حرفيًا).

عقد الاستجابة

إذا لم يكن هناك شيء يحتاج إلى اهتمام، رد بـ HEARTBEAT_OK.
أثناء تشغيلات النبض، يعامل OpenClaw HEARTBEAT_OK كإقرار عندما يظهر في بداية أو نهاية الرد. تتم إزالة الرمز ويتم إسقاط الرد إذا كان المحتوى المتبقي ≤ ackMaxChars (الافتراضي: 300).
إذا ظهر HEARTBEAT_OK في منتصف الرد، لا يتم معاملته بشكل خاص.
للتنبيهات، لا تضمن HEARTBEAT_OK؛ أعد فقط نص التنبيه.

خارج تشغيلات النبض، يتم إزالة HEARTBEAT_OK الشارد في بداية/نهاية الرسالة وتسجيله؛ يتم إسقاط الرسالة التي تحتوي فقط على HEARTBEAT_OK.

التكوين

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // الافتراضي: 30m (0m يعطل)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // الافتراضي: false (تسليم رسالة Reasoning: منفصلة عند التوفر)
        lightContext: false, // الافتراضي: false؛ true يحتفظ فقط بـ HEARTBEAT.md من ملفات تمهيد مساحة العمل
        target: "last", // الافتراضي: none | الخيارات: last | none | <معرف القناة> (أساسي أو إضافة، مثل "bluebubbles")
        to: "+15551234567", // تجاوز اختياري خاص بالقناة
        accountId: "ops-bot", // معرف قناة متعدد الحسابات اختياري
        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300, // الحد الأقصى للأحرف المسموح بها بعد HEARTBEAT_OK
      },
    },
  },
}

النطاق والأولوية

agents.defaults.heartbeat يحدد سلوك النبض العام.
agents.list[].heartbeat يدمج فوقه؛ إذا كان لأي وكيل كتلة heartbeat، فقط هؤلاء الوكلاء يقومون بتشغيل النبضات.
channels.defaults.heartbeat يحدد الإعدادات الافتراضية للرؤية لجميع القنوات.
channels.<channel>.heartbeat يتجاوز إعدادات القناة الافتراضية.
channels.<channel>.accounts.<id>.heartbeat (قنوات متعددة الحسابات) يتجاوز الإعدادات لكل قناة.

النبضات لكل وكيل

إذا تضمنت أي مدخلات في agents.list[] كتلة heartbeat، فقط هؤلاء الوكلاء يقومون بتشغيل النبضات. تدمج الكتلة لكل وكيل فوق agents.defaults.heartbeat (حتى تتمكن من تعيين الإعدادات الافتراضية المشتركة مرة واحدة وتجاوزها لكل وكيل). مثال: وكيلان، فقط الوكيل الثاني يقوم بتشغيل النبضات.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // تسليم صريح لآخر جهة اتصال (الافتراضي هو "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        },
      },
    ],
  },
}

مثال على ساعات النشاط

تقييد النبضات لساعات العمل في منطقة زمنية محددة:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // تسليم صريح لآخر جهة اتصال (الافتراضي هو "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // اختياري؛ يستخدم userTimezone الخاص بك إذا تم تعيينه، وإلا المنطقة الزمنية للمضيف
        },
      },
    },
  },
}

خارج هذه النافذة (قبل الساعة 9 صباحًا أو بعد الساعة 10 مساءً بالتوقيت الشرقي)، يتم تخطي النبضات. ستشغل النقطة الزمنية المجدولة التالية داخل النافذة بشكل طبيعي.

إعداد 24/7

إذا كنت تريد أن تعمل النبضات طوال اليوم، استخدم أحد هذه الأنماط:

احذف activeHours تمامًا (لا قيود على النافذة الزمنية؛ هذا هو السلوك الافتراضي).
اضبط نافذة كاملة اليوم: activeHours: { start: "00:00", end: "24:00" }.

لا تضبط نفس وقت start و end (على سبيل المثال 08:00 إلى 08:00). يتم التعامل مع ذلك على أنه نافذة عرض صفرية، لذلك يتم دائمًا تخطي النبضات.

مثال متعدد الحسابات

استخدم accountId لاستهداف حساب محدد على القنوات متعددة الحسابات مثل Telegram:

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // اختياري: التوجيه إلى موضوع/محادثة محددة
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

ملاحظات على الحقول

every: فاصل النبض (سلسلة مدة؛ الوحدة الافتراضية = دقائق).
model: تجاوز اختياري للنموذج لتشغيلات النبض (provider/model).
includeReasoning: عند التمكين، قم أيضًا بتسليم رسالة Reasoning: المنفصلة عند التوفر (بنفس شكل /reasoning on).
lightContext: عندما تكون true، تستخدم تشغيلات النبض سياق تمهيد خفيف الوزن وتحتفظ فقط بـ HEARTBEAT.md من ملفات تمهيد مساحة العمل.
session: مفتاح جلسة اختياري لتشغيلات النبض.
- main (الافتراضي): الجلسة الرئيسية للوكيل.
- مفتاح جلسة صريح (انسخ من openclaw sessions --json أو سطر أوامر الجلسات).
- تنسيقات مفاتيح الجلسة: انظر الجلسات و المجموعات.
target:
- last: التسليم إلى آخر قناة خارجية مستخدمة.
- قناة صريحة: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
- none (الافتراضي): تشغيل النبض ولكن لا تقم بالتسليم خارجيًا.
directPolicy: يتحكم في سلوك التسليم المباشر/الرسائل الخاصة:
- allow (الافتراضي): السماح بالتسليم المباشر/الرسائل الخاصة للنبض.
- block: قمع التسليم المباشر/الرسائل الخاصة (reason=dm-blocked).
to: تجاوز مستلم اختياري (معرف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرف دردشة Telegram). لمواضيع/محادثات Telegram، استخدم <chatId>:topic:<messageThreadId>.
accountId: معرف حساب اختياري للقنوات متعددة الحسابات. عندما يكون target: "last"، ينطبق معرف الحساب على القناة الأخيرة التي تم حلها إذا كانت تدعم الحسابات؛ وإلا يتم تجاهله. إذا لم يتطابق معرف الحساب مع حساب مكون للقناة التي تم حلها، يتم تخطي التسليم.
prompt: يتجاوز نص المطالبة الافتراضي (لا يتم دمجه).
ackMaxChars: الحد الأقصى للأحرف المسموح بها بعد HEARTBEAT_OK قبل التسليم.
suppressToolErrorWarnings: عندما تكون true، تقمع حمولات تحذيرات أخطاء الأداة أثناء تشغيلات النبض.
activeHours: يقيد تشغيلات النبض لنافذة زمنية. كائن به start (HH:MM، شامل؛ استخدم 00:00 لبداية اليوم)، end (HH:MM حصري؛ 24:00 مسموح به لنهاية اليوم)، و timezone اختياري.
- محذوف أو "user": يستخدم agents.defaults.userTimezone الخاص بك إذا تم تعيينه، وإلا يتراجع إلى المنطقة الزمنية لنظام المضيف.
- "local": يستخدم دائمًا المنطقة الزمنية لنظام المضيف.
- أي معرف IANA (مثل America/New_York): يستخدم مباشرة؛ إذا كان غير صالح، يتراجع إلى سلوك "user" أعلاه.
- يجب ألا يكون start و end متساويين لنافذة نشطة؛ القيم المتساوية تعامل على أنها عرض صفري (دائمًا خارج النافذة).
- خارج نافذة النشاط، يتم تخطي النبضات حتى النقطة الزمنية التالية داخل النافذة.

سلوك التسليم

تعمل النبضات في الجلسة الرئيسية للوكيل افتراضيًا (agent:<id>:<mainKey>)، أو global عندما يكون session.scope = "global". اضبط session لتجاوزها إلى جلسة قناة محددة (Discord/WhatsApp/إلخ.).
session يؤثر فقط على سياق التشغيل؛ يتم التحكم في التسليم بواسطة target و to.
للتسليم إلى قناة/مستلم محدد، اضبط target + to. مع target: "last"، يستخدم التسليم آخر قناة خارجية لتلك الجلسة.
يسمح تسليم النبض بالأهداف المباشرة/الرسائل الخاصة افتراضيًا. اضبط directPolicy: "block" لقمع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دورة النبض.
إذا كانت قائمة الانتظار الرئيسية مشغولة، يتم تخطي النبض وإعادة المحاولة لاحقًا.
إذا لم يحل target إلى أي وجهة خارجية، يحدث التشغيل ولكن لا يتم إرسال أي رسالة صادرة.
الردود الخاصة بالنبض فقط لا تحافظ على نشاط الجلسة؛ يتم استعادة آخر updatedAt حتى يتصرف انتهاء صلاحية الخمول بشكل طبيعي.

عناصر التحكم في الرؤية

افتراضيًا، يتم قمع إقرارات HEARTBEAT_OK بينما يتم تسليم محتوى التنبيه. يمكنك ضبط هذا لكل قناة أو لكل حساب:

channels:
  defaults:
    heartbeat:
      showOk: false # إخفاء HEARTBEAT_OK (الافتراضي)
      showAlerts: true # عرض رسائل التنبيه (الافتراضي)
      useIndicator: true # إصدار أحداث المؤشر (الافتراضي)
  telegram:
    heartbeat:
      showOk: true # عرض إقرارات OK على Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # قمع تسليم التنبيهات لهذا الحساب

الأولوية: لكل حساب → لكل قناة → إعدادات القناة الافتراضية → الإعدادات الافتراضية المضمنة.

ما يفعله كل علم

showOk: يرسل إقرار HEARTBEAT_OK عندما يعيد النموذج رد OK فقط.
showAlerts: يرسل محتوى التنبيه عندما يعيد النموذج رد غير OK.
useIndicator: يصدر أحداث مؤشر لأسطح حالة واجهة المستخدم.

إذا كانت جميع الثلاثة false، يتخطى OpenClaw تشغيل النبض بالكامل (لا استدعاء للنموذج).

أمثلة لكل قناة مقابل لكل حساب

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # جميع حسابات Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # قمع التنبيهات لحساب ops فقط
  telegram:
    heartbeat:
      showOk: true

الأنماط الشائعة

الهدف	التكوين
السلوك الافتراضي (OK صامتة، تنبيهات مفعلة)	(لا حاجة لتكوين)
صامت بالكامل (لا رسائل، لا مؤشر)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
المؤشر فقط (لا رسائل)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
OKs في قناة واحدة فقط	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (اختياري)

إذا كان ملف HEARTBEAT.md موجودًا في مساحة العمل، تخبر المطالبة الافتراضية الوكيل بقراءته. فكر فيه على أنه "قائمة التحقق للنبض" الخاصة بك: صغيرة، مستقرة، وآمنة للتضمين كل 30 دقيقة. إذا كان HEARTBEAT.md موجودًا ولكنه فارغ فعليًا (فقط أسطر فارغة وعناوين ماركداون مثل # Heading)، يتخطى OpenClaw تشغيل النبض لتوفير استدعاءات API. إذا كان الملف مفقودًا، لا يزال النبض يعمل ويقرر النموذج ما يجب فعله. احتفظ به صغيرًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة. مثال HEARTBEAT.md:

# قائمة تحقق النبض

- مسح سريع: أي شيء عاجل في صناديق الوارد؟
- إذا كان وقت النهار، قم بتحقق خفيف الوزن إذا لم يكن هناك شيء آخر معلق.
- إذا كانت المهمة متوقفة، اكتب _ما هو المفقود_ واسأل بيتر في المرة القادمة.

هل يمكن للوكيل تحديث HEARTBEAT.md؟

نعم — إذا طلبت منه ذلك. HEARTBEAT.md هو مجرد ملف عادي في مساحة عمل الوكيل، لذا يمكنك إخبار الوكيل (في دردشة عادية) بشيء مثل:

"قم بتحديث HEARTBEAT.md لإضافة فحص تقويم يومي."
"أعد كتابة HEARTBEAT.md بحيث تكون أقصر ومركزة على متابعات صندوق الوارد."

إذا كنت تريد أن يحدث هذا بشكل استباقي، يمكنك أيضًا تضمين سطر صريح في مطالبة النبض الخاصة بك مثل: "إذا أصبحت قائمة التحقق قديمة، قم بتحديث HEARTBEAT.md بأخرى أفضل." ملاحظة أمانية: لا تضع أسرارًا (مفاتيح API، أرقام هواتف، رموز خاصة) في HEARTBEAT.md — تصبح جزءًا من سياق المطالبة.

الإيقاظ اليدوي (حسب الطلب)

يمكنك إضافة حدث نظام إلى قائمة الانتظار وتشغيل نبض فوري باستخدام:

openclaw system event --text "Check for urgent follow-ups" --mode now

إذا كان لدى وكلاء متعددين heartbeat مكونًا، فإن الإيقاظ اليدوي يشغل نبض كل من هؤلاء الوكلاء فورًا. استخدم --mode next-heartbeat للانتظار حتى النقطة الزمنية المجدولة التالية.

تسليم الاستدلال (اختياري)

افتراضيًا، يقوم النبض بتسليم حمولة "الإجابة" النهائية فقط. إذا كنت تريد شفافية، قم بتمكين:

agents.defaults.heartbeat.includeReasoning: true

عند التمكين، سيقوم النبض أيضًا بتسليم رسالة منفصلة ببادئة Reasoning: (بنفس شكل /reasoning on). يمكن أن يكون هذا مفيدًا عندما يدير الوكيل جلسات/قواعد برمجية متعددة وتريد أن ترى لماذا قرر إشعارك — ولكنه قد يتسرب أيضًا بمزيد من التفاصيل الداخلية مما تريد. يُفضل إبقاؤه معطلًا في الدردشات الجماعية.

الوعي بالتكلفة

تعمل النبضات على تشغيل دورات وكيل كاملة. الفواصل الزمنية الأقصر تستهلك المزيد من الرموز المميزة. احتفظ بـ HEARTBEAT.md صغيرًا وفكر في model أرخص أو target: "none" إذا كنت تريد فقط تحديثات الحالة الداخلية.

فحوصات الصحة الطبيب