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 افزایش می‌دهد، اما فقط تا زمانی که heartbeat.every تنظیم نشده باشد. 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 برای عامل پیش‌فرض فعال باشد (و includeSystemPromptSection برابر false نباشد)؛ اجرا نیز به‌صورت داخلی علامت‌گذاری می‌شود.
• هنگامی که 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، اگر HEARTBEAT_OK در ابتدا یا انتهای پاسخ ظاهر شود، OpenClaw آن را به‌عنوان تأیید دریافت در نظر می‌گیرد. این توکن حذف می‌شود و اگر محتوای باقی‌مانده ≤ 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.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        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 # HEARTBEAT_OK را پنهان می‌کند (پیش‌فرض)      showAlerts: true # پیام‌های هشدار را نمایش می‌دهد (پیش‌فرض)      useIndicator: true # رویدادهای نشانگر را منتشر می‌کند (پیش‌فرض)  telegram:    heartbeat:      showOk: true # تأییدهای OK را در Telegram نمایش می‌دهد  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # تحویل هشدار برای این حساب را سرکوب می‌کند

ترتیب اولویت: به‌ازای حساب ← به‌ازای کانال ← پیش‌فرض‌های کانال ← پیش‌فرض‌های داخلی.

عملکرد هر پرچم

• showOk: وقتی مدل پاسخی صرفاً از نوع OK برمی‌گرداند، یک تأیید HEARTBEAT_OK ارسال می‌کند.
• showAlerts: وقتی مدل پاسخی غیر از OK برمی‌گرداند، محتوای هشدار را ارسال می‌کند.
• useIndicator: رویدادهای نشانگر را برای سطوح وضعیت رابط کاربری منتشر می‌کند.

اگر هر سه نادرست باشند، OpenClaw اجرای Heartbeat را کاملاً نادیده می‌گیرد (بدون فراخوانی مدل).

نمونه‌های به‌ازای کانال و به‌ازای حساب

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.md در فضای کاری وجود داشته باشد، پرامپت پیش‌فرض به عامل می‌گوید آن را بخواند. آن را «چک‌لیست Heartbeat» خود در نظر بگیرید: کوچک، پایدار و ایمن برای بررسی هر ۳۰ دقیقه.

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

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

اگر HEARTBEAT.md وجود داشته باشد اما عملاً خالی باشد (فقط خطوط خالی، توضیحات Markdown/HTML، عنوان‌های Markdown مانند # Heading، نشانگرهای حصار یا نمونه‌های خالی چک‌لیست)، OpenClaw برای صرفه‌جویی در فراخوانی‌های API اجرای Heartbeat را نادیده می‌گیرد. این نادیده‌گیری با reason=empty-heartbeat-file گزارش می‌شود. اگر فایل وجود نداشته باشد، Heartbeat همچنان اجرا می‌شود و مدل تصمیم می‌گیرد چه کاری انجام دهد.

برای جلوگیری از حجیم‌شدن پرامپت، آن را بسیار کوچک نگه دارید (چک‌لیست کوتاه یا یادآوری‌ها).

نمونهٔ HEARTBEAT.md:

# چک‌لیست Heartbeat - بررسی سریع: آیا چیزی فوری در صندوق‌های ورودی وجود دارد؟- اگر روز است و مورد دیگری در انتظار نیست، یک بررسی مختصر انجام دهید.- اگر کاری مسدود شده است، _آنچه کم است_ را یادداشت کنید و دفعهٔ بعد از Peter بپرسید.

بلوک‌های tasks:

HEARTBEAT.md همچنین از یک بلوک ساختاریافتهٔ کوچک tasks: برای بررسی‌های مبتنی بر فاصلهٔ زمانی در خود Heartbeat پشتیبانی می‌کند.

نمونه:

tasks: - name: inbox-triage  interval: 30m  prompt: "ایمیل‌های خوانده‌نشدهٔ فوری را بررسی کنید و هر مورد حساس به زمان را علامت بزنید."- name: calendar-scan  interval: 2h  prompt: "جلسه‌های پیش رو را که به آماده‌سازی یا پیگیری نیاز دارند بررسی کنید." # دستورالعمل‌های تکمیلی - هشدارها را کوتاه نگه دارید.- اگر پس از همهٔ کارهای سررسیدشده هیچ موردی نیازمند توجه نبود، HEARTBEAT_OK پاسخ دهید.

حالت کار زمانی مفید است که می‌خواهید یک فایل Heartbeat چندین بررسی دوره‌ای را نگه دارد، بدون اینکه در هر تیک هزینهٔ همهٔ آن‌ها را بپردازید.

آیا عامل می‌تواند HEARTBEAT.md را به‌روزرسانی کند؟

بله، اگر از آن بخواهید.

HEARTBEAT.md فقط یک فایل عادی در فضای کاری عامل است، بنابراین می‌توانید در یک گفت‌وگوی عادی چیزی شبیه این به عامل بگویید:

• «HEARTBEAT.md را به‌روزرسانی کن تا یک بررسی روزانهٔ تقویم اضافه شود.»
• «HEARTBEAT.md را بازنویسی کن تا کوتاه‌تر و متمرکز بر پیگیری صندوق ورودی باشد.»

اگر می‌خواهید این کار به‌صورت پیش‌دستانه انجام شود، می‌توانید یک خط صریح مانند این نیز در پرامپت Heartbeat بگنجانید: «اگر چک‌لیست قدیمی شد، HEARTBEAT.md را با نسخهٔ بهتری به‌روزرسانی کن.»

بیدارسازی دستی (برحسب درخواست)

برای قرار دادن یک رویداد سیستمی در صف و در صورت تمایل، فعال‌کردن فوری Heartbeat از openclaw system event استفاده کنید:

openclaw system event --text "پیگیری‌های فوری را بررسی کن" --mode now

اگر هیچ --session-key داده نشود و چند عامل دارای heartbeat پیکربندی‌شده باشند، --mode now Heartbeat هر یک از آن عامل‌ها را فوراً اجرا می‌کند.

کنترل‌های مرتبط Heartbeat در همان گروه CLI:

openclaw system heartbeat last     # نمایش آخرین رویداد Heartbeatopenclaw system heartbeat enable   # فعال‌کردن Heartbeatهاopenclaw system heartbeat disable  # غیرفعال‌کردن Heartbeatها

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

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

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

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

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

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

Heartbeatها پس از پایان اجرا، مدل زمان‌اجرای موجودِ نشست مشترک را حفظ می‌کنند؛ بنابراین Heartbeatی که نشست را به یک مدل محلی کوچک‌تر تغییر داده باشد (برای مثال یک مدل Ollama با پنجرهٔ ۳۲ هزار توکنی)، ممکن است آن مدل را برای نوبت بعدی نشست اصلی باقی بگذارد. اگر نوبت بعدی سپس سرریز زمینه را گزارش کند و آخرین مدل زمان‌اجرای نشست با heartbeat.model پیکربندی‌شده مطابقت داشته باشد، پیام بازیابی OpenClaw نشت مدل Heartbeat را به‌عنوان علت احتمالی مطرح می‌کند و راه‌حلی پیشنهاد می‌دهد.

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

مرتبط

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