​

نبضات القلب (Gateway)

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

​

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

1. اترك نبضات القلب مُمكّنة (الافتراضي هو 30m، أو 1h لمصادقة Anthropic OAuth/setup-token) أو اضبط وتيرتك الخاصة.
2. أنشئ قائمة تحقق صغيرة HEARTBEAT.md في مساحة عمل الوكيل (اختياري لكنها مُستحسنة).
3. قرر أين يجب أن تذهب رسائل نبضات القلب (target: "last" هو الافتراضي).
4. اختياري: فعّل تسليم الاستدلال الخاص بنبضات القلب لزيادة الشفافية.
5. اختياري: قيّد نبضات القلب بساعات النشاط (التوقيت المحلي).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

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

• الفاصل الزمني: 30m (أو 1h عندما تكون مصادقة Anthropic OAuth/setup-token هي الوضع المكتشف). عيّن agents.defaults.heartbeat.every أو agents.list[].heartbeat.every لكل وكيل؛ استخدم 0m للتعطيل.
• نصّ الموجّه (قابل للتهيئة عبر agents.defaults.heartbeat.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.
• يُرسَل موجّه نبضات القلب كما هو حرفيًا كرسالة المستخدم. يتضمن موجّه النظام قسم «Heartbeat» وتُعلَّم العملية داخليًا.
• يتم التحقق من ساعات النشاط (heartbeat.activeHours) ضمن المنطقة الزمنية المُهيّأة. خارج النافذة، تُتخطّى نبضات القلب حتى العلامة التالية داخل النافذة.

​

ما الغرض من موجّه نبضات القلب

• المهام الخلفية: عبارة «Consider outstanding tasks» تحفّز الوكيل على مراجعة المتابعات (البريد الوارد، التقويم، التذكيرات، الأعمال المُصطفّة) وإبراز أي أمر عاجل.
• تفقّد بشري: عبارة «Checkup sometimes on your human during day time» تحفّز رسالة خفيفة عرضية من نوع «هل تحتاج إلى شيء؟»، مع تجنّب الإزعاج الليلي باستخدام منطقتك الزمنية المحلية المُهيّأة (راجع /concepts/timezone).

​

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

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

​

التهيئة

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific override
        accountId: "ops-bot", // optional multi-account channel id
        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, // max chars allowed after HEARTBEAT_OK
      },
    },
  },
}

​

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

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

​

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    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",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

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

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

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

• every: فاصل نبضات القلب (سلسلة مدة؛ وحدة افتراضية = دقائق).
• model: تجاوز اختياري للنموذج لتشغيلات نبضات القلب (provider/model).
• includeReasoning: عند التمكين، يسلّم أيضًا رسالة Reasoning: المنفصلة عند توفرها (بنفس شكل /reasoning on).
• session: مفتاح جلسة اختياري لتشغيلات نبضات القلب.
  • main (الافتراضي): الجلسة الرئيسية للوكيل.
  • مفتاح جلسة صريح (انسخه من openclaw sessions --json أو من sessions CLI).
  • تنسيقات مفاتيح الجلسات: راجع Sessions وGroups.
• target:
  • last (الافتراضي): التسليم إلى آخر قناة خارجية مستخدمة.
  • قناة صريحة: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: تشغيل نبضة القلب لكن من دون تسليم خارجي.
• to: تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram).
• accountId: معرّف حساب اختياري للقنوات متعددة الحسابات. عندما يكون target: "last"، ينطبق معرّف الحساب على آخر قناة مُحلَّلة إذا كانت تدعم الحسابات؛ وإلا فيُتجاهل. إذا لم يطابق معرّف الحساب حسابًا مُهيّأً للقناة المُحلَّلة، يُتخطّى التسليم.
• prompt: يتجاوز نص الموجّه الافتراضي (غير مدمج).
• ackMaxChars: الحد الأقصى لعدد الأحرف المسموح بها بعد HEARTBEAT_OK قبل التسليم.
• activeHours: يقيّد تشغيلات نبضات القلب بنافذة زمنية. كائن يحتوي على start (HH:MM، شامل)، وend (HH:MM حصري؛ يُسمح بـ 24:00 لنهاية اليوم)، وtimezone اختياري.
  • في حال الإغفال أو "user": يستخدم agents.defaults.userTimezone لديك إن كان مضبوطًا، وإلا يعود إلى المنطقة الزمنية لنظام المضيف.
  • "local": يستخدم دائمًا المنطقة الزمنية لنظام المضيف.
  • أي معرّف IANA (مثل America/New_York): يُستخدم مباشرة؛ وإن كان غير صالح يعود إلى سلوك "user" أعلاه.
  • خارج نافذة النشاط، تُتخطّى نبضات القلب حتى العلامة التالية داخل النافذة.

​

سلوك التسليم

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

​

ضوابط الرؤية

channels:
  defaults:
    heartbeat:
      showOk: false # Hide HEARTBEAT_OK (default)
      showAlerts: true # Show alert messages (default)
      useIndicator: true # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true # Show OK acknowledgments on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alert delivery for this account

​

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

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

​

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

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

​

أنماط شائعة

​

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

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

​

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

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

​

إيقاظ يدوي (عند الطلب)

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

​

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

• agents.defaults.heartbeat.includeReasoning: true

​

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