Heartbeat

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

Heartbeat یک نوبت زمان‌بندی‌شده در نشست اصلی است و رکورد وظیفه پس‌زمینه ایجاد نمی‌کند. رکوردهای وظیفه برای کارهای مستقل هستند (اجرای ACP، زیرعامل‌ها، کارهای cron ایزوله).

در لایه زیرین، تناوب Heartbeat در اختیار زمان‌بند cron است: Gateway برای هر عامل دارای Heartbeat فعال، یک کار cron متعلق به سیستم نگه می‌دارد (در openclaw cron list --all به‌صورت Heartbeat (agent-id) قابل مشاهده است). پیکربندی Heartbeat همچنان ورودی وضعیت مطلوب است، درحالی‌که زمان‌بندی پایشگرِ پایدارشده، تیک واقعی و دوره انتظار بعدی اجراکننده را کنترل می‌کند. Gateway تغییرات پیکربندی را هنگام راه‌اندازی و بارگذاری مجدد پیکربندی اعمال می‌کند؛ openclaw doctor --fix می‌تواند پیش از راه‌اندازی بعدی Gateway، ردیف‌های پایشگرِ مفقود یا قدیمی را ایجاد کند. agents.*.heartbeat را ویرایش کنید، نه کار cron را.

Heartbeatهای زمان‌بندی‌شده به cron نیاز دارند. وقتی cron.enabled برابر false یا OPENCLAW_SKIP_CRON=1 باشد، Gateway هنگام راه‌اندازی هشداری ثبت می‌کند و Heartbeatهای زمان‌بندی‌شده را اجرا نمی‌کند؛ بیدارسازی‌های دستی و رویدادمحور Heartbeat همچنان در دسترس می‌مانند. هیچ تایمر جایگزین جداگانه‌ای برای Heartbeat وجود ندارد.

عیب‌یابی: وظایف زمان‌بندی‌شده

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

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

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // ارسال صریح به آخرین مخاطب (مقدار پیش‌فرض "none" است)        directPolicy: "allow", // پیش‌فرض: اجازه به مقصدهای مستقیم/DM؛ برای جلوگیری، "block" را تنظیم کنید        lightContext: true, // اختیاری: رد کردن فایل‌های راه‌اندازی فضای کاری برای اجرای Heartbeat        isolatedSession: true, // اختیاری: نشست تازه در هر اجرا (بدون تاریخچه مکالمه)        // activeHours: { start: "08:00", end: "24:00" },      },    },  },}

مقادیر پیش‌فرض

• فاصله: 30m. اعمال مقادیر پیش‌فرض ارائه‌دهنده Anthropic، وقتی حالت احراز هویت تعیین‌شده OAuth/توکن باشد (از جمله استفاده مجدد از Claude CLI)، این مقدار را به 1h افزایش می‌دهد، اما فقط تا زمانی که heartbeat.every تنظیم نشده باشد. agents.defaults.heartbeat.every یا agents.entries.*.heartbeat.every مختص هر عامل را تنظیم کنید؛ برای غیرفعال‌سازی از 0m استفاده کنید.
• بدنه پرامپت (قابل پیکربندی از طریق agents.defaults.heartbeat.prompt): Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• مهلت زمانی: نوبت‌های Heartbeat فاقد مقدار تنظیم‌شده، در صورت تنظیم بودن agents.defaults.timeoutSeconds، از آن استفاده می‌کنند. در غیر این صورت، از تناوب Heartbeat با سقف 600 ثانیه استفاده می‌کنند. برای کارهای طولانی‌تر Heartbeat، agents.defaults.heartbeat.timeoutSeconds یا agents.entries.*.heartbeat.timeoutSeconds مختص هر عامل را تنظیم کنید.
• پرامپت Heartbeat عیناً به‌عنوان پیام کاربر ارسال می‌شود. وقتی Heartbeatها برای عامل پیش‌فرض فعال باشند، پرامپت سیستم شامل بخش «Heartbeatها» می‌شود و اجرا در داخل علامت‌گذاری می‌شود.
• وقتی Heartbeatها با 0m غیرفعال شوند، کار cron پایشگر باقی می‌ماند اما غیرفعال می‌شود و یادداشت آن برای زمانی که تناوب را دوباره فعال کنید حفظ می‌شود.
• وقتی خود cron غیرفعال باشد، حتی اگر تناوب Heartbeat فعال بماند، Heartbeatهای زمان‌بندی‌شده اجرا نمی‌شوند.
• ساعات فعال (heartbeat.activeHours) در منطقه زمانی پیکربندی‌شده بررسی می‌شوند. خارج از این بازه، Heartbeatها تا تیک بعدی درون بازه نادیده گرفته می‌شوند.
• Heartbeatها هنگامی که کار cron فعال یا در صف است، یا زمانی که مسیرهای زیرعامل مبتنی بر کلید نشست یا فرمان‌های تودرتوی آن عامل مشغول‌اند، خودکار به تعویق می‌افتند. عامل‌های هم‌سطح یکدیگر را متوقف نمی‌کنند.

هدف پرامپت Heartbeat

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

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

Heartbeat می‌تواند به وظایف پس‌زمینه تکمیل‌شده واکنش نشان دهد، اما خود اجرای Heartbeat رکورد وظیفه ایجاد نمی‌کند.

اگر می‌خواهید Heartbeat کار بسیار مشخصی انجام دهد (برای مثال «آمار Gmail PubSub را بررسی کن» یا «سلامت Gateway را تأیید کن»)، agents.defaults.heartbeat.prompt (یا agents.entries.*.heartbeat.prompt) را روی یک بدنه سفارشی تنظیم کنید (عیناً ارسال می‌شود).

قرارداد پاسخ

• اگر هیچ موردی نیازمند توجه نیست، با HEARTBEAT_OK پاسخ دهید.
• اجرای Heartbeat می‌تواند به‌جای آن، برای نداشتن به‌روزرسانی قابل مشاهده، heartbeat_respond را با notify: false فراخوانی کند، یا برای هشدار، notify: true را همراه notificationText فراخوانی کند. در صورت وجود، پاسخ ساختاریافته ابزار بر متن جایگزین اولویت دارد.
• یک نتیجه معنادار heartbeat_respond با notify: false بی‌صدا می‌ماند، اما به‌عنوان زمینه داخلی محدود برای نوبت بعدی کاربر در همان نشست به خاطر سپرده می‌شود. تأییدهای no_change و اعلان‌های قابل مشاهده به این شکل ذخیره نمی‌شوند.
• در طول اجرای Heartbeat، اگر HEARTBEAT_OK در ابتدا یا انتهای پاسخ ظاهر شود، OpenClaw آن را تأیید دریافت در نظر می‌گیرد. توکن حذف می‌شود و اگر محتوای باقی‌مانده حداکثر 300 نویسه باشد، پاسخ کنار گذاشته می‌شود.
• اگر HEARTBEAT_OK در میانه پاسخ ظاهر شود، رفتار ویژه‌ای با آن نمی‌شود.
• برای هشدارها، HEARTBEAT_OK را درج نکنید؛ فقط متن هشدار را برگردانید.

خارج از Heartbeatها، HEARTBEAT_OK اضافی در ابتدا/انتهای پیام حذف و ثبت می‌شود؛ پیامی که فقط شامل HEARTBEAT_OK باشد کنار گذاشته می‌شود.

پیکربندی

{  agents: {    defaults: {      heartbeat: {        every: "30m", // پیش‌فرض: 30m (مقدار 0m غیرفعال می‌کند)        model: "anthropic/claude-opus-4-6",        lightContext: false, // پیش‌فرض: false؛ مقدار true فایل‌های راه‌اندازی فضای کاری را برای اجرای Heartbeat رد می‌کند        isolatedSession: false, // پیش‌فرض: false؛ مقدار true هر Heartbeat را در نشستی تازه اجرا می‌کند (بدون تاریخچه مکالمه)        target: "last", // پیش‌فرض: none | گزینه‌ها: last | none | <channel id> (هسته یا Plugin، برای مثال "imessage")        to: "+15551234567", // بازنویسی اختیاری مختص کانال        accountId: "ops-bot", // شناسه اختیاری کانال چندحسابی        prompt: "در صورت ارائه، زمینه یادداشت پایشگر Heartbeat را دنبال کن. وظایف تکرارشونده کارهای cron هستند؛ زمان‌بندی آن‌ها را با ابزارهای cron یا CLI مربوط به openclaw cron ایجاد یا تغییر بده، نه با یادداشت Heartbeat. وظایف قدیمی را از گفت‌وگوهای قبلی استنباط یا تکرار نکن. اگر هیچ موردی نیازمند توجه نیست، پاسخ بده HEARTBEAT_OK.",      },    },  },}

دامنه و اولویت

• agents.defaults.heartbeat رفتار سراسری Heartbeat را تنظیم می‌کند.
• agents.entries.*.heartbeat روی آن ادغام می‌شود؛ اگر هر عاملی دارای بلوک heartbeat باشد، فقط همان عامل‌ها Heartbeat را اجرا می‌کنند.
• channels.defaults.heartbeatVisibility مقادیر پیش‌فرض قابلیت مشاهده را برای همه کانال‌ها تنظیم می‌کند.
• channels.<channel>.heartbeatVisibility مقادیر پیش‌فرض کانال را بازنویسی می‌کند.
• channels.<channel>.accounts.<id>.heartbeatVisibility (کانال‌های چندحسابی) تنظیمات مختص کانال را بازنویسی می‌کند.

Heartbeatهای مختص عامل

اگر هر ورودی agents.entries.* شامل بلوک heartbeat باشد، فقط همان عامل‌ها Heartbeat را اجرا می‌کنند. بلوک مختص عامل روی agents.defaults.heartbeat ادغام می‌شود (بنابراین می‌توانید مقادیر پیش‌فرض مشترک را یک‌بار تنظیم و برای هر عامل بازنویسی کنید).

مثال: دو عامل که فقط عامل دوم Heartbeat را اجرا می‌کند.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // ارسال صریح به آخرین مخاطب (مقدار پیش‌فرض "none" است)      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "در صورت ارائه، زمینه یادداشت پایشگر Heartbeat را دنبال کن. وظایف تکرارشونده کارهای cron هستند؛ زمان‌بندی آن‌ها را با ابزارهای cron یا CLI مربوط به openclaw cron ایجاد یا تغییر بده، نه با یادداشت Heartbeat. وظایف قدیمی را از گفت‌وگوهای قبلی استنباط یا تکرار نکن. اگر هیچ موردی نیازمند توجه نیست، پاسخ بده HEARTBEAT_OK.",        },      },    ],  },}

نمونه ساعات فعال

Heartbeatها را به ساعات کاری در منطقه زمانی مشخص محدود کنید:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // ارسال صریح به آخرین مخاطب (مقدار پیش‌فرض "none" است)        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // اختیاری؛ در صورت تنظیم از userTimezone و در غیر این صورت از منطقه زمانی میزبان استفاده می‌کند        },      },    },  },}

خارج از این بازه (پیش از ساعت 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", // اختیاری: هدایت به موضوع/رشته‌ای مشخص          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: رویدادهای نشانگر را برای سطوح وضعیت رابط کاربری منتشر می‌کند.

اگر هر سه false باشند، 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

الگوهای رایج

یادداشت موقت پایشگر (اختیاری)

هر کار Cron پایشگر Heartbeat یک سند یادداشت موقت خصوصی دارد که در پایگاه دادهٔ وضعیت مشترک ذخیره می‌شود. آن را مانند «چک‌لیست Heartbeat» خود در نظر بگیرید: کوچک، پایدار و مناسب برای بررسی هر 30 دقیقه. وقتی یادداشت موقت وجود داشته باشد، محتوای آن به پرامپت Heartbeat افزوده می‌شود.

آن را با CLI مربوط به Cron مدیریت کنید (شناسهٔ کار از openclaw cron list --all می‌آید):

openclaw cron scratch <jobId>                 # یادداشت موقت فعلی را چاپ می‌کندopenclaw cron scratch <jobId> --set "..."     # آن را با متن دقیق جایگزین می‌کندopenclaw cron scratch <jobId> --file notes.md # آن را از یک فایل جایگزین می‌کند (- برای stdin)openclaw cron scratch <jobId> --unset         # آن را حذف می‌کند

نوشتن‌ها با سازوکار مقایسه‌و‌جایگزینی محافظت می‌شوند: --expected-revision <n> را ارسال کنید تا به‌جای بازنویسی یک ویرایش هم‌زمان، عملیات ناموفق شود. یادداشت موقت به 256 KiB محدود است و هرگز در خروجی cron list/cron runs ظاهر نمی‌شود.

عامل نیز می‌تواند یادداشت موقت خودش را به‌روزرسانی کند: در طول یک نوبت Heartbeat، heartbeat_respond یک رشتهٔ اختیاری scratch می‌پذیرد که یادداشت موقت پایشگر را برای Heartbeatهای آینده به‌طور کامل جایگزین می‌کند.

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

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

نمونهٔ یادداشت موقت:

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

زمان‌بندی بررسی‌های تکرارشونده با Cron

یادداشت موقت Heartbeat زمینهٔ پرامپت است، نه زمان‌بند. هر بررسی تکرارشونده را به‌صورت یک کار Cron ایجاد کنید تا تناوب، وضعیت فعال/غیرفعال و تاریخچهٔ اجرای خودش را داشته باشد. وقتی بررسی باید از زمینهٔ عادی مکالمه استفاده کند، کارهای Cron همچنان می‌توانند نشست اصلی را هدف قرار دهند.

یادداشت موقت قدیمی ممکن است شامل یک بلوک ساختاریافتهٔ tasks: باشد. پس از ارتقا، openclaw doctor --fix را یک‌بار اجرا کنید: Doctor هر ورودی معتبر را به یک کار Cron با زمان‌بندی مستقل تبدیل می‌کند، فاصلهٔ زمانی و زمان اجرای قبلی آن را حفظ می‌کند و بلوک بازنشسته را حذف می‌کند، در حالی که نثر پیرامون یادداشت موقت را نگه می‌دارد. نوبت‌های Heartbeat در زمان اجرا، متن tasks: را به‌عنوان زمان‌بندی تجزیه نمی‌کنند.

کارهای Heartbeat ایجادشده توسط Doctor، ساعت‌های فعال، دورهٔ انتظار، محافظ‌های سیلاب و مشغول بودن Heartbeat را حفظ می‌کنند. کارهایی که هم‌زمان سررسید می‌شوند می‌توانند در یک نوبت Heartbeat ادغام شوند. یک رخداد خارج از ساعت‌های فعال نادیده گرفته می‌شود و در رخداد Cron بعدی آن دوباره تلاش می‌شود.

آیا عامل می‌تواند یادداشت موقت خود را به‌روزرسانی کند؟

بله. در طول یک نوبت Heartbeat، عامل می‌تواند مقدار scratch را به heartbeat_respond ارسال کند تا نثر پایشگر برای Heartbeatهای آینده به‌طور کامل جایگزین شود. همچنین می‌توانید در یک گفت‌وگوی عادی از آن بخواهید openclaw cron scratch <jobId> --set ... را اجرا کند، یا خودتان یادداشت موقت را با همان فرمان ویرایش کنید. زمان‌بندی‌های تکرارشونده را با Cron مدیریت کنید، نه با نوشتن نحو زمان‌بند در یادداشت موقت.

بیدارسازی دستی (در صورت تقاضا)

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

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ها نوبت‌های کامل عامل را اجرا می‌کنند. بازه‌های کوتاه‌تر توکن بیشتری مصرف می‌کنند. برای کاهش هزینه:

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

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

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

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

مرتبط

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