​

Heartbeat ‏(Gateway)

Heartbeat أم Cron؟ راجع Automation & Tasks للحصول على إرشادات حول وقت استخدام كل منهما.

​

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

1. اترك heartbeats مفعلة (الافتراضي هو 30m، أو 1h لمصادقة Anthropic OAuth/token، بما في ذلك إعادة استخدام Claude CLI) أو عيّن وتيرتك الخاصة.
2. أنشئ قائمة تحقق صغيرة في HEARTBEAT.md أو كتلة tasks: في مساحة عمل الوكيل (اختياري لكنه موصى به).
3. قرر أين يجب أن تذهب رسائل heartbeat ‏(target: "none" هو الافتراضي؛ اضبط target: "last" للتوجيه إلى آخر جهة اتصال).
4. اختياري: فعّل تسليم reasoning الخاص بـ heartbeat من أجل الشفافية.
5. اختياري: استخدم سياق bootstrap خفيفًا إذا كانت تشغيلات heartbeat تحتاج فقط إلى HEARTBEAT.md.
6. اختياري: فعّل الجلسات المعزولة لتجنب إرسال السجل الكامل للمحادثة في كل heartbeat.
7. اختياري: قيد heartbeats بالساعات النشطة (التوقيت المحلي).

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

​

القيم الافتراضية

• الفاصل الزمني: 30m ‏(أو 1h عندما يكون وضع مصادقة Anthropic OAuth/token هو وضع المصادقة المكتشف، بما في ذلك إعادة استخدام Claude CLI). اضبط 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” ويتم تعليم التشغيل داخليًا.
• يتم التحقق من الساعات النشطة (heartbeat.activeHours) في المنطقة الزمنية المكوّنة. وخارج هذه النافذة، يتم تخطي heartbeats حتى التوقيت التالي داخل النافذة.

​

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

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

​

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

• إذا لم يكن هناك ما يحتاج إلى انتباه، فردّ بـ HEARTBEAT_OK.
• أثناء تشغيلات heartbeat، يعامل OpenClaw الرمز HEARTBEAT_OK كإقرار عندما يظهر في بداية أو نهاية الرد. تتم إزالة الرمز ويتم إسقاط الرد إذا كان المحتوى المتبقي ≤ ackMaxChars ‏(الافتراضي: 300).
• إذا ظهر 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 فقط من ملفات bootstrap لمساحة العمل
        isolatedSession: false, // الافتراضي: false؛ قيمة true تشغّل كل heartbeat في جلسة جديدة (من دون سجل محادثة)
        target: "last", // الافتراضي: none | الخيارات: last | none | <channel id> (أساسي أو plugin، مثل "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 سلوك heartbeat العام.
• يتم دمج agents.list[].heartbeat فوقه؛ وإذا كان لأي وكيل كتلة heartbeat، فإن هؤلاء الوكلاء فقط هم الذين يشغّلون heartbeats.
• يضبط channels.defaults.heartbeat القيم الافتراضية للظهور لكل القنوات.
• يتجاوز channels.<channel>.heartbeat القيم الافتراضية للقناة.
• يتجاوز channels.<channel>.accounts.<id>.heartbeat ‏(للقنوات متعددة الحسابات) الإعدادات لكل قناة.

​

Heartbeats لكل وكيل

{
  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 إن كانت معيّنة، وإلا المنطقة الزمنية للمضيف
        },
      },
    },
  },
}

​

إعداد 24/7

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

​

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

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

​

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

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

​

سلوك التسليم

• تعمل Heartbeats في الجلسة الرئيسية للوكيل افتراضيًا (agent:<id>:<mainKey>)، أو global عندما تكون session.scope = "global". اضبط session للتجاوز إلى جلسة قناة محددة (Discord/WhatsApp/إلخ).
• يؤثر session في سياق التشغيل فقط؛ أما التسليم فيتحكم فيه target وto.
• للتسليم إلى قناة/مستلم محدد، اضبط target + to. ومع target: "last"، يستخدم التسليم آخر قناة خارجية لتلك الجلسة.
• تسمح عمليات تسليم Heartbeat بأهداف direct/DM افتراضيًا. اضبط directPolicy: "block" لمنع الإرسال إلى الأهداف المباشرة مع الاستمرار في تشغيل دور heartbeat.
• إذا كانت الطوابير الرئيسية مشغولة، يتم تخطي heartbeat وإعادة المحاولة لاحقًا.
• إذا جرى حل target إلى عدم وجود وجهة خارجية، يظل التشغيل يحدث ولكن لا يتم إرسال أي رسالة صادرة.
• إذا كانت showOk وshowAlerts وuseIndicator كلها معطلة، فيتم تخطي التشغيل مسبقًا على أنه reason=alerts-disabled.
• إذا كان تسليم التنبيهات فقط معطلًا، فلا يزال بإمكان OpenClaw تشغيل heartbeat، وتحديث الطوابع الزمنية للمهام المستحقة، واستعادة الطابع الزمني للخمول للجلسة، ومنع حمولة التنبيه الخارجية.
• الردود الخاصة بـ heartbeat فقط لا تبقي الجلسة نشطة؛ إذ تتم استعادة قيمة updatedAt الأخيرة بحيث يعمل انتهاء الصلاحية عند الخمول بشكل طبيعي.
• يمكن أن تقوم background tasks المنفصلة بصف نظام حدث وتوقظ heartbeat عندما ينبغي أن تلاحظ الجلسة الرئيسية شيئًا بسرعة. ولا يجعل هذا الإيقاظ تشغيل heartbeat مهمة خلفية.

​

عناصر التحكم في الظهور

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: يصدر أحداث مؤشرات لأسطح حالة واجهة المستخدم.

​

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

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # كل حسابات Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # منع التنبيهات لحساب ops فقط
  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.

​

كتل tasks:

tasks:

- name: inbox-triage
  interval: 30m
  prompt: "Check for urgent unread emails and flag anything time sensitive."
- name: calendar-scan
  interval: 2h
  prompt: "Check for upcoming meetings that need prep or follow-up."

# Additional instructions

- Keep alerts short.
- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

• يقوم OpenClaw بتحليل كتلة tasks: والتحقق من كل مهمة مقابل interval الخاص بها.
• يتم تضمين المهام المستحقة فقط في مطالبة heartbeat لذلك التوقيت.
• إذا لم تكن هناك مهام مستحقة، يتم تخطي heartbeat بالكامل (reason=no-tasks-due) لتجنب استدعاء نموذج بلا فائدة.
• يتم الاحتفاظ بالمحتوى غير المتعلق بالمهام في HEARTBEAT.md وإلحاقه كسياق إضافي بعد قائمة المهام المستحقة.
• تُخزَّن الطوابع الزمنية لآخر تشغيل للمهام في حالة الجلسة (heartbeatTaskState)، لذا تبقى الفواصل الزمنية محفوظة عبر عمليات إعادة التشغيل العادية.
• لا يتم تقديم الطوابع الزمنية للمهام إلا بعد أن يكمل تشغيل heartbeat مسار الرد الطبيعي. ولا تضع التشغيلات المتخطاة بسبب empty-heartbeat-file / no-tasks-due علامة على المهام على أنها مكتملة.

​

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

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

​

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

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

​

تسليم Reasoning ‏(اختياري)

• agents.defaults.heartbeat.includeReasoning: true

​

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

• استخدم isolatedSession: true لتجنب إرسال السجل الكامل للمحادثة (تقريبًا من ~100K رمز إلى ~2-5K لكل تشغيل).
• استخدم lightContext: true لحصر ملفات bootstrap في HEARTBEAT.md فقط.
• عيّن model أرخص (مثل ollama/llama3.2:1b).
• أبقِ HEARTBEAT.md صغيرًا.
• استخدم target: "none" إذا كنت تريد فقط تحديثات الحالة الداخلية.

​

ذو صلة

• Automation & Tasks — جميع آليات الأتمتة في لمحة
• Background Tasks — كيفية تتبع العمل المنفصل
• Timezone — كيف تؤثر المنطقة الزمنية في جدولة heartbeat
• Troubleshooting — تصحيح مشكلات الأتمتة