Heartbeat

Heartbeat در نشست اصلی نوبت‌های دوره‌ای عامل را اجرا می‌کند تا مدل بتواند هر چیزی را که نیازمند توجه است، بدون ارسال پیام‌های مزاحم به شما، مطرح کند.

Heartbeat یک نوبت زمان‌بندی‌شده در نشست اصلی است — رکوردهای background task ایجاد نمی‌کند. رکوردهای کار برای کارهای جداشده هستند (اجرای ACP، زیرعامل‌ها، کارهای cron ایزوله).

عیب‌یابی: Scheduled Tasks

شروع سریع (مبتدی)

نمونه پیکربندی:

{  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 `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 را تنظیم کنید؛ عامل‌های هم‌سطح دیگر فقط به‌دلیل اینکه عامل دیگری کار زیرعامل در جریان دارد متوقف نمی‌شوند.

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

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

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

Heartbeat می‌تواند به background tasks تکمیل‌شده واکنش نشان دهد، اما خودِ اجرای 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 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 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" }.

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

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

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

اگر 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 فقط یک فایل عادی در workspace عامل است، بنابراین می‌توانید به عامل (در یک چت عادی) چیزی شبیه این بگویید:

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

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

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

می‌توانید یک رویداد سیستمی را در صف بگذارید و یک Heartbeat فوری را با این دستور فعال کنید:

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

اگر چندین عامل heartbeat پیکربندی کرده باشند، بیدارسازی دستی هر یک از آن Heartbeatهای عامل را فوراً اجرا می‌کند.

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

تحویل Reasoning (اختیاری)

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

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

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

• از isolatedSession: true استفاده کنید تا از ارسال تاریخچه کامل مکالمه جلوگیری شود (~100K token به ~2-5K در هر اجرا).
• از lightContext: true استفاده کنید تا فایل‌های bootstrap فقط به HEARTBEAT.md محدود شوند.
• یک model ارزان‌تر تنظیم کنید (مثلاً ollama/llama3.2:1b).
• HEARTBEAT.md را کوچک نگه دارید.
• اگر فقط به‌روزرسانی‌های وضعیت داخلی می‌خواهید، از target: "none" استفاده کنید.

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

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

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

مرتبط

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