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 this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` 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 غير المضبوطة agents.defaults.timeoutSeconds عند ضبطها. وإلا، فإنها تستخدم وتيرة Heartbeat بحد أقصى 600 ثانية. اضبط agents.defaults.heartbeat.timeoutSeconds أو agents.list[].heartbeat.timeoutSeconds لكل وكيل لعمل Heartbeat أطول.
• يرسل موجه Heartbeat حرفيا كرسالة المستخدم. يتضمن موجه النظام قسما باسم "Heartbeat" فقط عندما تكون Heartbeat مفعلة للوكيل الافتراضي، ويتم تعليم التشغيل داخليا.
• عند تعطيل Heartbeat باستخدام 0m، تحذف التشغيلات العادية أيضا HEARTBEAT.md من سياق التمهيد حتى لا يرى النموذج تعليمات خاصة بـ Heartbeat فقط.
• يتم التحقق من ساعات النشاط (heartbeat.activeHours) في المنطقة الزمنية المضبوطة. خارج النافذة، يتم تخطي Heartbeat حتى النبضة التالية داخل النافذة.
• تؤجل Heartbeat تلقائيا أثناء كون عمل Cron نشطا أو في قائمة الانتظار. اضبط heartbeat.skipWhenBusy: true لتأجيل وكيل أيضا على مسارات الوكيل الفرعي المرتبطة بمفتاح جلسته أو مسارات الأوامر المتداخلة الخاصة به؛ لم تعد الوكلاء النظيرة تتوقف لمجرد أن وكيلا آخر لديه عمل وكيل فرعي قيد التنفيذ.

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

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

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

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

إذا أردت أن تنفذ Heartbeat شيئا محددا جدا (مثلا "تحقق من إحصاءات Gmail PubSub" أو "تحقق من صحة Gateway")، فاضبط 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 Thinking 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 this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        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" },      },    },  },}

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

سلوك التسليم

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

افتراضيًا، تُكتم إقرارات 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

أنماط شائعة

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

إذا كان ملف HEARTBEAT.md موجودًا في مساحة العمل، فإن الموجه الافتراضي يطلب من الوكيل قراءته. فكر فيه كأنه "قائمة تحقق Heartbeat" الخاصة بك: صغيرة، ومستقرة، وآمنة للنظر فيها كل 30 دقيقة.

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

في حزمة Codex الأصلية، لا يتم حقن محتوى HEARTBEAT.md في الدورة. إذا كان الملف موجودًا ويحتوي على محتوى غير مسافات بيضاء، تشير تعليمات وضع التعاون في Heartbeat إلى الملف وتطلب منه القراءة قبل المتابعة.

إذا كان HEARTBEAT.md موجودًا لكنه فارغ فعليًا (أسطر فارغة فقط، أو تعليقات Markdown/HTML، أو عناوين 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 أيضًا رسالة منفصلة مسبوقة بـ Thinking (بالشكل نفسه مثل /reasoning on). يمكن أن يكون هذا مفيدًا عندما يدير الوكيل عدة جلسات/نسخ Codex وتريد معرفة سبب قراره مراسلتك — لكنه قد يسرّب أيضًا تفاصيل داخلية أكثر مما تريد. يُفضّل إبقاؤه معطلًا في الدردشات الجماعية.

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

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

• استخدم isolatedSession: true لتجنب إرسال سجل المحادثة الكامل (~100K رمز إلى ~2-5K لكل تشغيل).
• استخدم 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
• استكشاف الأخطاء وإصلاحها — تصحيح مشكلات الأتمتة