Heartbeat

Heartbeat, modelin sizi ileti yağmuruna tutmadan ilgilenilmesi gereken her şeyi ortaya çıkarabilmesi için ana oturumda düzenli aralıklarla ajan turları çalıştırır.

Heartbeat, zamanlanmış bir ana oturum turudur; arka plan görevi kayıtları oluşturmaz. Görev kayıtları, bağımsız çalışmalar içindir (ACP çalıştırmaları, alt ajanlar, yalıtılmış Cron işleri).

Sorun giderme: Zamanlanmış Görevler

Hızlı başlangıç (başlangıç düzeyi)

Örnek yapılandırma:

{  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      },    },  },}

Varsayılanlar

• Aralık: 30m. Anthropic sağlayıcı varsayılanlarının uygulanması, çözümlenen kimlik doğrulama modu OAuth/token olduğunda (Claude CLI'ın yeniden kullanımı dâhil) bunu 1h değerine yükseltir; ancak yalnızca heartbeat.every ayarlanmamışsa. agents.defaults.heartbeat.every veya ajan başına agents.list[].heartbeat.every değerini ayarlayın; devre dışı bırakmak için 0m kullanın.
• İstem gövdesi (agents.defaults.heartbeat.prompt aracılığıyla yapılandırılabilir): 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.
• Zaman aşımı: Heartbeat turlarında zaman aşımı ayarlanmamışsa, mevcut olduğunda agents.defaults.timeoutSeconds kullanılır. Aksi hâlde, en fazla 600 saniye olmak üzere Heartbeat sıklığı kullanılır. Daha uzun Heartbeat çalışmaları için agents.defaults.heartbeat.timeoutSeconds veya ajan başına agents.list[].heartbeat.timeoutSeconds değerini ayarlayın.
• Heartbeat istemi, kullanıcı iletisi olarak aynen gönderilir. Sistem istemi yalnızca varsayılan ajan için Heartbeat'ler etkin olduğunda (ve includeSystemPromptSection, false olmadığında) bir "Heartbeat'ler" bölümü içerir ve çalıştırma dâhili olarak işaretlenir.
• Heartbeat'ler 0m ile devre dışı bırakıldığında, normal çalıştırmalar da modelin yalnızca Heartbeat'e yönelik talimatları görmemesi için başlangıç bağlamına HEARTBEAT.md dosyasını dâhil etmez.
• Etkin saatler (heartbeat.activeHours), yapılandırılmış saat diliminde denetlenir. Bu aralığın dışında Heartbeat'ler, aralık içindeki bir sonraki işarete kadar atlanır.
• Cron çalışması etkin olduğunda veya kuyruğa alındığında Heartbeat'ler otomatik olarak ertelenir. Bir ajanı kendi oturum anahtarına bağlı alt ajanı veya iç içe komut hatları meşgulken de ertelemek için heartbeat.skipWhenBusy: true ayarını kullanın; başka bir ajanın devam eden alt ajan çalışması olması artık kardeş ajanları duraklatmaz.

Heartbeat isteminin amacı

Varsayılan istem kasıtlı olarak geniş kapsamlıdır:

• Arka plan görevleri: "Bekleyen görevleri göz önünde bulundur", ajanı takip edilecek işleri (gelen kutusu, takvim, anımsatıcılar, kuyruğa alınmış çalışmalar) incelemeye ve acil olanları ortaya çıkarmaya yönlendirir.
• Kullanıcıyla durum kontrolü: "Gündüzleri zaman zaman kullanıcınızın durumunu kontrol edin", ara sıra kısa bir "ihtiyacınız olan bir şey var mı?" iletisine yönlendirir; ancak yapılandırılmış yerel saat diliminizi kullanarak gece saatlerinde ileti yağmurunu önler (bkz. Saat Dilimi).

Heartbeat, tamamlanan arka plan görevlerine tepki verebilir ancak Heartbeat çalıştırmasının kendisi görev kaydı oluşturmaz.

Heartbeat'in çok özel bir işlem yapmasını istiyorsanız (ör. "Gmail PubSub istatistiklerini kontrol et" veya "Gateway durumunu doğrula"), agents.defaults.heartbeat.prompt (veya agents.list[].heartbeat.prompt) değerini özel bir gövdeye ayarlayın (aynen gönderilir).

Yanıt sözleşmesi

• İlgilenilmesi gereken bir şey yoksa HEARTBEAT_OK ile yanıt verin.
• Heartbeat çalıştırmaları bunun yerine görünür güncelleme olmaması için notify: false ile veya uyarı için notify: true ve notificationText ile heartbeat_respond çağrısı yapabilir. Yapılandırılmış araç yanıtı mevcut olduğunda metin yedeğine göre önceliklidir.
• Heartbeat çalıştırmaları sırasında OpenClaw, yanıtın başında veya sonunda görünen HEARTBEAT_OK değerini onay olarak kabul eder. Token kaldırılır ve kalan içerik ≤ ackMaxChars ise (varsayılan: 300) yanıt bırakılır.
• HEARTBEAT_OK bir yanıtın ortasında görünürse özel olarak işlenmez.
• Uyarılarda HEARTBEAT_OK değerini eklemeyin; yalnızca uyarı metnini döndürün.

Heartbeat'lerin dışında, bir iletinin başında/sonunda bulunan gereksiz HEARTBEAT_OK kaldırılır ve günlüğe kaydedilir; yalnızca HEARTBEAT_OK içeren bir ileti bırakılır.

Yapılandırma

{  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      },    },  },}

Kapsam ve öncelik

• agents.defaults.heartbeat, genel Heartbeat davranışını ayarlar.
• agents.list[].heartbeat bunun üzerine birleştirilir; herhangi bir ajanda heartbeat bloğu varsa Heartbeat'leri yalnızca bu ajanlar çalıştırır.
• channels.defaults.heartbeat, tüm kanallar için görünürlük varsayılanlarını ayarlar.
• channels.<channel>.heartbeat, kanal varsayılanlarını geçersiz kılar.
• channels.<channel>.accounts.<id>.heartbeat (çok hesaplı kanallar), kanal başına ayarları geçersiz kılar.

Ajan başına Heartbeat'ler

Herhangi bir agents.list[] girdisi heartbeat bloğu içeriyorsa Heartbeat'leri yalnızca bu ajanlar çalıştırır. Ajan başına blok, agents.defaults.heartbeat üzerine birleştirilir (böylece paylaşılan varsayılanları bir kez ayarlayıp ajan başına geçersiz kılabilirsiniz).

Örnek: iki ajan vardır ve yalnızca ikinci ajan Heartbeat'leri çalıştırır.

{  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.",        },      },    ],  },}

Etkin saatler örneği

Heartbeat'leri belirli bir saat dilimindeki çalışma saatleriyle sınırlandırın:

{  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        },      },    },  },}

Bu aralığın dışında (Doğu saatine göre sabah 9'dan önce veya akşam 10'dan sonra) Heartbeat'ler atlanır. Aralık içindeki bir sonraki zamanlanmış işaret normal biçimde çalışır.

7/24 yapılandırma

Heartbeat'lerin tüm gün çalışmasını istiyorsanız şu kalıplardan birini kullanın:

• activeHours değerini tamamen atlayın (zaman aralığı kısıtlaması yoktur; varsayılan davranış budur).
• Tam günlük bir aralık ayarlayın: activeHours: { start: "00:00", end: "24:00" }.

Çok hesaplı örnek

Telegram gibi çok hesaplı kanallarda belirli bir hesabı hedeflemek için accountId kullanın:

{  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" },      },    },  },}

Alan notları

Teslimat davranışı

Görünürlük denetimleri

Varsayılan olarak uyarı içeriği teslim edilirken HEARTBEAT_OK onayları bastırılır. Bunu kanal veya hesap bazında ayarlayabilirsiniz:

channels:  defaults:    heartbeat:      showOk: false # HEARTBEAT_OK değerini gizle (varsayılan)      showAlerts: true # Uyarı mesajlarını göster (varsayılan)      useIndicator: true # Gösterge olaylarını yayınla (varsayılan)  telegram:    heartbeat:      showOk: true # Telegram'da OK onaylarını göster  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Bu hesap için uyarı teslimatını bastır

Öncelik: hesap bazında → kanal bazında → kanal varsayılanları → yerleşik varsayılanlar.

Her işaretin yaptığı

• showOk: model yalnızca OK içeren bir yanıt döndürdüğünde HEARTBEAT_OK onayı gönderir.
• showAlerts: model OK olmayan bir yanıt döndürdüğünde uyarı içeriğini gönderir.
• useIndicator: kullanıcı arayüzü durum yüzeyleri için gösterge olayları yayınlar.

Üçü de yanlışsa OpenClaw, Heartbeat çalışmasını tamamen atlar (model çağrısı yapılmaz).

Kanal bazında ve hesap bazında örnekler

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # tüm Slack hesapları    accounts:      ops:        heartbeat:          showAlerts: false # uyarıları yalnızca ops hesabı için bastır  telegram:    heartbeat:      showOk: true

Yaygın kalıplar

HEARTBEAT.md (isteğe bağlı)

Çalışma alanında bir HEARTBEAT.md dosyası varsa varsayılan istem, ajana bunu okumasını söyler. Bunu "Heartbeat kontrol listeniz" olarak düşünün: küçük, kararlı ve her 30 dakikada bir değerlendirilmesi güvenli.

Normal çalışmalarda HEARTBEAT.md, yalnızca varsayılan ajan için Heartbeat rehberliği etkinleştirildiğinde eklenir. Heartbeat sıklığını 0m ile devre dışı bırakmak veya includeSystemPromptSection: false ayarlamak, dosyayı normal önyükleme bağlamından çıkarır.

Yerel Codex çalışma düzeneğinde HEARTBEAT.md içeriği, diğer önyükleme dosyaları gibi tura eklenmez. Dosya varsa ve boşluk dışı içerik barındırıyorsa bir Heartbeat iş birliği modu notu Codex'i dosyaya yönlendirir ve devam etmeden önce dosyayı okumasını söyler.

HEARTBEAT.md mevcut ancak fiilen boşsa (yalnızca boş satırlar, Markdown/HTML yorumları, # Başlık gibi Markdown başlıkları, kod çiti işaretçileri veya boş kontrol listesi taslakları içeriyorsa), OpenClaw API çağrılarını azaltmak için Heartbeat çalışmasını atlar. Bu atlama reason=empty-heartbeat-file olarak bildirilir. Dosya yoksa Heartbeat yine çalışır ve model ne yapılacağına karar verir.

İstem şişmesini önlemek için dosyayı küçük tutun (kısa kontrol listesi veya hatırlatıcılar).

Örnek HEARTBEAT.md:

# Heartbeat kontrol listesi - Hızlı tarama: gelen kutularında acil bir şey var mı?- Gündüzse ve bekleyen başka bir şey yoksa kısa bir durum kontrolü yap.- Bir görev engellenmişse _neyin eksik olduğunu_ yaz ve bir dahaki sefere Peter'a sor.

tasks: blokları

HEARTBEAT.md, Heartbeat'in kendi içinde aralığa dayalı kontroller için küçük, yapılandırılmış bir tasks: bloğunu da destekler.

Örnek:

tasks: - name: inbox-triage  interval: 30m  prompt: "Acil okunmamış e-postaları denetle ve zaman açısından hassas olanları işaretle."- name: calendar-scan  interval: 2h  prompt: "Hazırlık veya takip gerektiren yaklaşan toplantıları denetle." # Ek talimatlar - Uyarıları kısa tut.- Zamanı gelen tüm görevlerden sonra ilgilenilmesi gereken bir şey yoksa HEARTBEAT_OK ile yanıt ver.

Görev modu, tek bir Heartbeat dosyasında birkaç periyodik kontrol bulundurmak ancak her zaman adımında hepsinin maliyetini ödememek istediğinizde kullanışlıdır.

Ajan HEARTBEAT.md dosyasını güncelleyebilir mi?

Evet, isterseniz güncelleyebilir.

HEARTBEAT.md, ajan çalışma alanındaki sıradan bir dosyadır; bu nedenle ajana (normal bir sohbette) şuna benzer bir şey söyleyebilirsiniz:

• "Günlük takvim kontrolü eklemek için HEARTBEAT.md dosyasını güncelle."
• "HEARTBEAT.md dosyasını daha kısa ve gelen kutusu takiplerine odaklı olacak şekilde yeniden yaz."

Bunun proaktif olarak gerçekleşmesini istiyorsanız Heartbeat isteminize şu şekilde açık bir satır da ekleyebilirsiniz: "Kontrol listesi güncelliğini yitirirse HEARTBEAT.md dosyasını daha iyi bir listeyle güncelle."

Manuel uyandırma (istek üzerine)

Bir sistem olayını kuyruğa almak ve isteğe bağlı olarak anında Heartbeat tetiklemek için openclaw system event kullanın:

openclaw system event --text "Acil takipleri denetle" --mode now

--session-key verilmezse ve birden fazla ajanda heartbeat yapılandırılmışsa --mode now, bu ajanların Heartbeat çalışmalarının her birini hemen çalıştırır.

Aynı CLI grubundaki ilgili Heartbeat denetimleri:

openclaw system heartbeat last     # son Heartbeat olayını gösteropenclaw system heartbeat enable   # Heartbeat çalışmalarını etkinleştiropenclaw system heartbeat disable  # Heartbeat çalışmalarını devre dışı bırak

Akıl yürütme teslimatı (isteğe bağlı)

Varsayılan olarak, heartbeat'ler yalnızca nihai "yanıt" yükünü iletir.

Şeffaflık istiyorsanız şunu etkinleştirin:

• agents.defaults.heartbeat.includeReasoning: true

Etkinleştirildiğinde heartbeat'ler, ayrıca Thinking ön ekiyle ayrı bir mesaj iletir (/reasoning on ile aynı biçimde). Bu, agent birden fazla oturumu/codex'i yönetirken neden size bildirim göndermeye karar verdiğini görmek istediğinizde yararlı olabilir; ancak istediğinizden daha fazla dahili ayrıntıyı da açığa çıkarabilir. Grup sohbetlerinde bunu kapalı tutmayı tercih edin.

Maliyet farkındalığı

Heartbeat'ler tam agent turları çalıştırır. Daha kısa aralıklar daha fazla token tüketir. Maliyeti azaltmak için:

• Tam konuşma geçmişini göndermekten kaçınmak için isolatedSession: true kullanın (çalıştırma başına yaklaşık 100 bin tokendan yaklaşık 2-5 bin tokena düşürür).
• Başlangıç dosyalarını yalnızca HEARTBEAT.md ile sınırlamak için lightContext: true kullanın.
• Daha ucuz bir model ayarlayın (örneğin ollama/llama3.2:1b).
• HEARTBEAT.md dosyasını küçük tutun.
• Yalnızca dahili durum güncellemeleri istiyorsanız target: "none" kullanın.

Heartbeat sonrasında bağlam taşması

Heartbeat'ler, çalışma tamamlandıktan sonra paylaşılan oturumun mevcut çalışma zamanı modelini korur. Bu nedenle bir oturumu daha küçük bir yerel modele (örneğin 32k pencereli bir Ollama modeline) geçiren heartbeat, sonraki ana oturum turunda bu modeli etkin bırakabilir. Sonraki tur bağlam taşması bildirirse ve oturumun son çalışma zamanı modeli yapılandırılmış heartbeat.model ile eşleşiyorsa OpenClaw'ın kurtarma mesajı, olası neden olarak heartbeat modelinin sızmasını belirtir ve bir düzeltme önerir.

Bunu önlemek için heartbeat'leri yeni bir oturumda çalıştırmak üzere isolatedSession: true kullanın (en küçük istem için isteğe bağlı olarak lightContext: true ile birlikte) veya paylaşılan oturum için yeterince büyük bir bağlam penceresine sahip heartbeat modeli seçin.

İlgili

• Otomasyon - tüm otomasyon mekanizmalarına genel bakış
• Arka Plan Görevleri - ayrılmış çalışmaların nasıl izlendiği
• Saat Dilimi - saat diliminin heartbeat zamanlamasını nasıl etkilediği
• Sorun Giderme - otomasyon sorunlarını ayıklama