Heartbeat

يشغّل Heartbeat دورات وكيل دورية في الجلسة الرئيسية حتى يتمكن النموذج من إظهار أي شيء يحتاج إلى انتباهك دون إغراقك بالرسائل.

Heartbeat هو دورة مجدولة في الجلسة الرئيسية — ولا ينشئ سجلات مهام خلفية. سجلات المهام مخصصة للعمل المنفصل (تشغيلات ACP، والوكلاء الفرعيين، ومهام cron المعزولة).

استكشاف الأخطاء وإصلاحها: المهام المجدولة

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

مثال على الإعداد:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files
        isolatedSession: true, // optional: fresh session each run (no conversation history)
        skipWhenBusy: true, // optional: also defer when subagent or nested lanes are busy
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

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

• الفاصل الزمني: 30m (أو 1h عندما يكون وضع المصادقة المكتشف هو مصادقة Anthropic عبر OAuth/الرمز، بما في ذلك إعادة استخدام 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 مفعّلة للوكيل الافتراضي، ويتم وسم التشغيل داخليًا.
• عند تعطيل Heartbeat باستخدام 0m، تحذف التشغيلات العادية أيضًا HEARTBEAT.md من سياق التمهيد حتى لا يرى النموذج تعليمات مخصصة لـ Heartbeat فقط.
• تُفحص ساعات النشاط (heartbeat.activeHours) في المنطقة الزمنية المضبوطة. خارج النافذة، يتم تخطي Heartbeat حتى النبضة التالية داخل النافذة.
• يؤجل Heartbeat تلقائيًا عندما يكون عمل cron نشطًا أو في قائمة الانتظار. اضبط heartbeat.skipWhenBusy: true للتأجيل أيضًا على المسارات الإضافية المشغولة (عمل وكيل فرعي أو أوامر متداخلة)؛ وهذا مفيد لـ Ollama المحلي وغيره من المضيفين المقيدين بزمن تشغيل واحد.

# الغرض من موجه Heartbeat

الموجه الافتراضي واسع عمدًا:

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

يمكن لـ Heartbeat التفاعل مع المهام الخلفية المكتملة، لكن تشغيل Heartbeat نفسه لا ينشئ سجل مهمة.

إذا أردت أن ينفذ Heartbeat شيئًا محددًا جدًا (مثل "check Gmail PubSub stats" أو "verify gateway health")، فاضبط agents.defaults.heartbeat.prompt (أو agents.list[].heartbeat.prompt) على نص مخصص (يُرسل حرفيًا).

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

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

خارج Heartbeat، يُزال 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)
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        target: "last", // default: none | options: 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 سلوك Heartbeat العام.
• يندمج agents.list[].heartbeat فوقه؛ إذا كان لدى أي وكيل كتلة heartbeat، فإن هؤلاء الوكلاء فقط يشغّلون Heartbeat.
• يضبط channels.defaults.heartbeat القيم الافتراضية للرؤية لكل القنوات.
• يتجاوز channels.<channel>.heartbeat القيم الافتراضية للقناة.
• يتجاوز channels.<channel>.accounts.<id>.heartbeat (القنوات متعددة الحسابات) إعدادات كل قناة.

# Heartbeat لكل وكيل

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

مثال: وكيلان، الوكيل الثاني فقط يشغّل Heartbeat.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          timeoutSeconds: 45,
          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 بساعات العمل في منطقة زمنية معينة:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

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

# إعداد 24/7

إذا كنت تريد تشغيل Heartbeat طوال اليوم، فاستخدم أحد هذه الأنماط:

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

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

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

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // optional: route to a specific topic/thread
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

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

everystring

فاصل Heartbeat (سلسلة مدة؛ الوحدة الافتراضية = دقائق).

modelstring

تجاوز اختياري للنموذج في تشغيلات Heartbeat (provider/model).

includeReasoningboolean

عند التمكين، يتم أيضًا تسليم رسالة Reasoning: المنفصلة عند توفرها (بالشكل نفسه مثل /reasoning on).

lightContextboolean

عندما تكون القيمة صحيحة، تستخدم تشغيلات Heartbeat سياق تمهيد خفيفًا وتحتفظ فقط بملف HEARTBEAT.md من ملفات تمهيد مساحة العمل.

isolatedSessionboolean

عندما تكون القيمة صحيحة، يعمل كل Heartbeat في جلسة جديدة بلا سجل محادثات سابق. يستخدم نمط العزل نفسه مثل cron sessionTarget: "isolated". يقلل تكلفة الرموز لكل Heartbeat بدرجة كبيرة. ادمجه مع lightContext: true لتحقيق أقصى توفير. يظل توجيه التسليم يستخدم سياق الجلسة الرئيسية.

skipWhenBusyboolean

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

sessionstring

مفتاح جلسة اختياري لتشغيلات Heartbeat.

• main (افتراضي): جلسة الوكيل الرئيسية.
• مفتاح جلسة صريح (انسخه من openclaw sessions --json أو واجهة CLI للجلسات).
• تنسيقات مفاتيح الجلسات: راجع الجلسات والمجموعات.

targetstring

• last: التسليم إلى آخر قناة خارجية مستخدمة.
• قناة صريحة: أي قناة مهيأة أو معرّف Plugin، مثل discord أو matrix أو telegram أو whatsapp.
• none (افتراضي): شغّل Heartbeat ولكن لا تسلّم خارجيًا.

directPolicy"allow" | "block"

يتحكم في سلوك التسليم المباشر/رسائل DM. allow: السماح بتسليم Heartbeat المباشر/رسائل DM. block: منع تسليم Heartbeat المباشر/رسائل DM (reason=dm-blocked).

tostring

تجاوز اختياري للمستلم (معرّف خاص بالقناة، مثل E.164 لـ WhatsApp أو معرّف دردشة Telegram). لمواضيع/سلاسل Telegram، استخدم <chatId>:topic:<messageThreadId>.

accountIdstring

معرّف حساب اختياري للقنوات متعددة الحسابات. عند استخدام target: "last"، ينطبق معرّف الحساب على آخر قناة تم حلّها إذا كانت تدعم الحسابات؛ وإلا فيتم تجاهله. إذا لم يطابق معرّف الحساب حسابًا مهيأً للقناة التي تم حلّها، يتم تخطي التسليم.

promptstring

يتجاوز نص الموجه الافتراضي (لا يتم دمجه).

ackMaxCharsnumber

الحد الأقصى للأحرف المسموح بها بعد HEARTBEAT_OK قبل التسليم.

suppressToolErrorWarningsboolean

عند ضبطه على true، يكبت حمولات تحذير أخطاء الأدوات أثناء تشغيل Heartbeat.

activeHoursobject

يقيّد تشغيل 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 حتى النبضة التالية داخل النافذة.

# سلوك التسليم

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

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

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

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

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

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

# أنماط شائعة

الهدف	الإعداد
السلوك الافتراضي (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 في مساحة العمل، فإن المطالبة الافتراضية تطلب من الوكيل قراءته. اعتبره "قائمة تحقق Heartbeat" الخاصة بك: صغيرة، وثابتة، وآمنة للإدراج كل 30 دقيقة.

في التشغيلات العادية، لا يُحقن HEARTBEAT.md إلا عندما تكون إرشادات Heartbeat مفعلة للوكيل الافتراضي. تعطيل وتيرة Heartbeat باستخدام 0m أو ضبط includeSystemPromptSection: false يحذفه من سياق التمهيد العادي.

إذا كان HEARTBEAT.md موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط ورؤوس markdown مثل # Heading)، يتخطى OpenClaw تشغيل Heartbeat لتوفير استدعاءات API. يُبلّغ عن ذلك التخطي باعتباره reason=empty-heartbeat-file. إذا كان الملف مفقودًا، يستمر Heartbeat في التشغيل ويقرر النموذج ما يجب فعله.

اجعله صغيرًا جدًا (قائمة تحقق قصيرة أو تذكيرات) لتجنب تضخم المطالبة.

مثال 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:

يدعم HEARTBEAT.md أيضًا كتلة tasks: منظمة صغيرة للفحوصات القائمة على الفواصل الزمنية داخل Heartbeat نفسه.

مثال:

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.

يكون وضع المهام مفيدًا عندما تريد أن يحتوي ملف Heartbeat واحد على عدة فحوصات دورية دون دفع تكلفة تشغيلها كلها في كل نبضة.

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

نعم — إذا طلبت منه ذلك.

HEARTBEAT.md هو مجرد ملف عادي في مساحة عمل الوكيل، لذلك يمكنك أن تقول للوكيل (في دردشة عادية) شيئًا مثل:

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

إذا أردت أن يحدث هذا بشكل استباقي، يمكنك أيضًا تضمين سطر صريح في مطالبة Heartbeat مثل: "إذا أصبحت قائمة التحقق قديمة، فحدّث HEARTBEAT.md بقائمة أفضل."

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

يمكنك إدراج حدث نظام في الطابور وتشغيل Heartbeat فوري باستخدام:

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

إذا كان لدى عدة وكلاء heartbeat مهيأ، فإن الإيقاظ اليدوي يشغل كل Heartbeats الخاصة بهؤلاء الوكلاء فورًا.

استخدم --mode next-heartbeat للانتظار حتى النبضة المجدولة التالية.

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

افتراضيًا، لا تسلّم Heartbeats إلا حمولة "الإجابة" النهائية.

إذا أردت الشفافية، ففعّل:

• agents.defaults.heartbeat.includeReasoning: true

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

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

تشغّل Heartbeats أدوار وكيل كاملة. الفواصل الزمنية الأقصر تستهلك رموزًا أكثر. لتقليل التكلفة:

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

# فيضان السياق بعد Heartbeat

إذا ترك Heartbeat سابق جلسة موجودة على نموذج محلي أصغر، مثل نموذج Ollama بنافذة 32k، وأبلغ دور الجلسة الرئيسية التالي عن فيضان في السياق، فأعد ضبط نموذج تشغيل الجلسة إلى النموذج الأساسي المهيأ. تنبه رسالة إعادة الضبط في OpenClaw إلى ذلك عندما يطابق آخر نموذج تشغيل heartbeat.model المهيأ.

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

# ذات صلة

• الأتمتة والمهام — جميع آليات الأتمتة بنظرة واحدة
• مهام الخلفية — كيف يُتتبع العمل المنفصل
• المنطقة الزمنية — كيف تؤثر المنطقة الزمنية في جدولة Heartbeat
• استكشاف الأخطاء وإصلاحها — تصحيح مشكلات الأتمتة