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 (یا وقتی حالت احراز هویت شناسایی‌شده Anthropic OAuth/توکنی است، شامل استفاده مجدد از Claude CLI، 1h). 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 با سقف ۶۰۰ ثانیه استفاده می‌کنند. برای کارهای Heartbeat طولانی‌تر، agents.defaults.heartbeat.timeoutSeconds یا برای هر عامل agents.list[].heartbeat.timeoutSeconds را تنظیم کنید.
• پرامپت Heartbeat عیناً به‌عنوان پیام کاربر ارسال می‌شود. پرامپت سیستم فقط زمانی یک بخش «Heartbeat» دارد که Heartbeatها برای عامل پیش‌فرض فعال باشند، و اجرا به‌صورت داخلی علامت‌گذاری می‌شود.
• وقتی Heartbeatها با 0m غیرفعال شوند، اجراهای معمولی نیز HEARTBEAT.md را از زمینه راه‌اندازی حذف می‌کنند تا مدل دستورالعمل‌های مخصوص Heartbeat را نبیند.
• ساعت‌های فعال (heartbeat.activeHours) در منطقه زمانی پیکربندی‌شده بررسی می‌شوند. بیرون از پنجره، Heartbeatها تا تیک بعدی داخل پنجره رد می‌شوند.
• Heartbeatها هنگام فعال یا در صف بودن کار Cron به‌صورت خودکار به تعویق می‌افتند. برای اینکه یک عامل هنگام درگیر بودن زیرعامل دارای کلید نشست خودش یا مسیرهای فرمان تودرتوی خودش نیز به تعویق بیفتد، heartbeat.skipWhenBusy: true را تنظیم کنید؛ عامل‌های هم‌سطح دیگر فقط به‌خاطر اینکه عامل دیگری کار زیرعامل در حال اجرا دارد متوقف نمی‌شوند.

پرامپت Heartbeat برای چیست

پرامپت پیش‌فرض عمداً گسترده است:

• وظایف پس‌زمینه: «در نظر گرفتن وظایف باقی‌مانده» عامل را به بررسی پیگیری‌ها (صندوق ورودی، تقویم، یادآورها، کارهای صف‌شده) و مطرح‌کردن موارد فوری ترغیب می‌کند.
• سرکشی انسانی: «گاهی در طول روز از انسان خود سرکشی کن» به یک پیام سبک و گاه‌به‌گاه از نوع «چیزی لازم دارید؟» ترغیب می‌کند، اما با استفاده از منطقه زمانی محلی پیکربندی‌شده شما از هرزپیام شبانه جلوگیری می‌کند (Timezone را ببینید).

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 باشد (پیش‌فرض: ۳۰۰)، پاسخ کنار گذاشته می‌شود.
• اگر 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        },      },    },  },}

بیرون از این پنجره (پیش از ۹ صبح یا پس از ۱۰ شب به وقت شرق)، Heartbeatها رد می‌شوند. تیک زمان‌بندی‌شده بعدی داخل پنجره به‌صورت عادی اجرا می‌شود.

راه‌اندازی ۲۴/۷

اگر می‌خواهید Heartbeatها تمام روز اجرا شوند، از یکی از این الگوها استفاده کنید:

• activeHours را کاملاً حذف کنید (بدون محدودیت پنجره زمانی؛ این رفتار پیش‌فرض است).
• یک پنجره تمام‌روز تنظیم کنید: activeHours: { start: "00:00", end: "24:00" }.

نمونه چندحسابی

برای هدف‌گیری یک حساب مشخص در کانال‌های چندحسابی مانند Telegram از accountId استفاده کنید:

{  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: وقتی مدل یک پاسخ فقط OK برمی‌گرداند، یک تأیید HEARTBEAT_OK می‌فرستد.
• showAlerts: وقتی مدل یک پاسخ غیر OK برمی‌گرداند، محتوای هشدار را می‌فرستد.
• useIndicator: رویدادهای نشانگر را برای سطح‌های وضعیت UI منتشر می‌کند.

اگر هر سه 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» خود در نظر بگیرید: کوچک، پایدار، و امن برای بررسی هر ۳۰ دقیقه.

در اجراهای عادی، HEARTBEAT.md فقط وقتی تزریق می‌شود که راهنمای Heartbeat برای عامل پیش‌فرض فعال باشد. غیرفعال کردن آهنگ Heartbeat با 0m یا تنظیم includeSystemPromptSection: false آن را از زمینهٔ راه‌اندازی عادی حذف می‌کند.

در harness بومی Codex، محتوای HEARTBEAT.md به نوبت تزریق نمی‌شود. اگر فایل وجود داشته باشد و محتوای غیر فاصلهٔ سفید داشته باشد، دستورهای حالت همکاری Heartbeat، Codex را به فایل ارجاع می‌دهند و به آن می‌گویند پیش از ادامه آن را بخواند.

اگر HEARTBEAT.md وجود داشته باشد اما عملاً خالی باشد (فقط خط‌های خالی، نظرهای Markdown/HTML، تیترهای Markdown مانند # Heading، نشانگرهای fence، یا stubهای خالی فهرست بررسی)، 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 پیکربندی‌شده داشته باشند، بیدارسازی دستی هرکدام از آن Heartbeatهای عامل را فوراً اجرا می‌کند.

برای انتظار تا تیک زمان‌بندی‌شدهٔ بعدی، از --mode next-heartbeat استفاده کنید.

تحویل استدلال (اختیاری)

به‌طور پیش‌فرض، Heartbeatها فقط محمولهٔ «پاسخ» نهایی را تحویل می‌دهند.

اگر شفافیت می‌خواهید، این را فعال کنید:

• agents.defaults.heartbeat.includeReasoning: true

وقتی فعال باشد، Heartbeatها همچنین یک پیام جداگانه با پیشوند Thinking تحویل می‌دهند (همان شکل /reasoning on). این می‌تواند زمانی مفید باشد که عامل چند نشست/کدکس را مدیریت می‌کند و می‌خواهید ببینید چرا تصمیم گرفته به شما پینگ بزند؛ اما همچنین می‌تواند جزئیات داخلی بیشتری از آنچه می‌خواهید افشا کند. بهتر است در چت‌های گروهی آن را خاموش نگه دارید.

آگاهی از هزینه

Heartbeatها نوبت‌های کامل عامل را اجرا می‌کنند. بازه‌های کوتاه‌تر توکن‌های بیشتری مصرف می‌کنند. برای کاهش هزینه:

• از isolatedSession: true استفاده کنید تا از ارسال تاریخچهٔ کامل مکالمه جلوگیری شود (از حدود ۱۰۰ هزار توکن به حدود ۲ تا ۵ هزار در هر اجرا).
• از lightContext: true استفاده کنید تا فایل‌های راه‌اندازی فقط به HEARTBEAT.md محدود شوند.
• یک model ارزان‌تر تنظیم کنید (برای نمونه ollama/llama3.2:1b).
• HEARTBEAT.md را کوچک نگه دارید.
• اگر فقط به‌روزرسانی‌های وضعیت داخلی می‌خواهید، از target: "none" استفاده کنید.

سرریز زمینه پس از Heartbeat

اگر یک Heartbeat قبلاً یک نشست موجود را روی یک مدل محلی کوچک‌تر باقی گذاشته باشد، برای نمونه یک مدل Ollama با پنجرهٔ 32k، و نوبت بعدی نشست اصلی سرریز زمینه گزارش کند، مدل زمان‌اجرای نشست را به مدل اصلی پیکربندی‌شده بازنشانی کنید. پیام بازنشانی OpenClaw وقتی آخرین مدل زمان‌اجرا با heartbeat.model پیکربندی‌شده مطابقت داشته باشد، این را صریح بیان می‌کند.

Heartbeatهای فعلی پس از کامل شدن اجرا، مدل زمان‌اجرای موجود نشست مشترک را حفظ می‌کنند. همچنان می‌توانید از isolatedSession: true برای اجرای Heartbeatها در یک نشست تازه استفاده کنید، آن را با lightContext: true برای کوچک‌ترین پرامپت ترکیب کنید، یا یک مدل Heartbeat با پنجرهٔ زمینهٔ به‌اندازهٔ کافی بزرگ برای نشست مشترک انتخاب کنید.

مرتبط

• اتوماسیون — همه سازوکارهای اتوماسیون در یک نگاه
• وظایف پس‌زمینه — نحوه رهگیری کارهای جداشده
• منطقه زمانی — نحوه تأثیر منطقه زمانی بر زمان‌بندی Heartbeat
• عیب‌یابی — اشکال‌زدایی مشکلات اتوماسیون