Heartbeat

Heartbeat, ana oturumda periyodik ajan dönüşleri çalıştırır; böylece model, sizi spamlemeden dikkat gerektiren her şeyi öne çıkarabilir.

Heartbeat, zamanlanmış bir ana oturum dönüşüdür; arka plan görevi kayıtları oluşturmaz. Görev kayıtları, ayrık işler 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ıç seviyesi)

Ö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 subagent or nested lanes are busy
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

# Varsayılanlar

• Aralık: 30m (veya Claude CLI yeniden kullanımı dahil Anthropic OAuth/token kimlik doğrulaması algılanan kimlik doğrulama modu olduğunda 1h). agents.defaults.heartbeat.every ya da ajan başına agents.list[].heartbeat.every ayarlayın; devre dışı bırakmak için 0m kullanın.
• İstem gövdesi (agents.defaults.heartbeat.prompt üzerinden 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.
• Heartbeat istemi, kullanıcı mesajı olarak aynen gönderilir. Sistem istemi yalnızca varsayılan ajan için Heartbeat'ler etkin olduğunda bir "Heartbeat" bölümü içerir ve çalıştırma dahili olarak işaretlenir.
• Heartbeat'ler 0m ile devre dışı bırakıldığında, normal çalıştırmalar bootstrap bağlamından HEARTBEAT.md dosyasını da çıkarır; böylece model yalnızca Heartbeat'e yönelik yönergeleri görmez.
• Etkin saatler (heartbeat.activeHours) yapılandırılmış saat diliminde denetlenir. Pencerenin dışında Heartbeat'ler, pencerenin içindeki bir sonraki tik işaretine kadar atlanır.
• Cron işi etkinken veya kuyruğa alınmışken Heartbeat'ler otomatik olarak ertelenir. Ek yoğun hatlarda (alt ajan veya iç içe komut işi) da ertelemek için heartbeat.skipWhenBusy: true ayarlayın; bu, yerel Ollama ve diğer kısıtlı tek çalışma zamanı barındırıcıları için kullanışlıdır.

# Heartbeat istemi ne içindir

Varsayılan istem bilinçli olarak geniş tutulmuştur:

• Arka plan görevleri: "Consider outstanding tasks", ajanı takipleri (gelen kutusu, takvim, hatırlatıcılar, kuyruğa alınmış işler) gözden geçirmeye ve acil olan her şeyi öne çıkarmaya yönlendirir.
• İnsan kontrolü: "Checkup sometimes on your human during day time", ara sıra hafif bir "bir şeye ihtiyacın var mı?" mesajını teşvik eder, ancak yapılandırılmış yerel saat diliminizi kullanarak gece spamini önler (Saat Dilimi bölümüne bakın).

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

Bir Heartbeat'in çok belirli bir şey yapmasını istiyorsanız (ör. "Gmail PubSub istatistiklerini kontrol et" veya "Gateway sağlığını 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

• Dikkat gerektiren bir şey yoksa HEARTBEAT_OK ile yanıt verin.
• Araç kullanabilen Heartbeat çalıştırmaları bunun yerine görünür güncelleme olmaması için notify: false ile veya uyarı için notify: true artı notificationText ile heartbeat_respond çağırabilir. Mevcut olduğunda yapılandırılmış araç yanıtı, metin yedeğine göre önceliklidir.
• Heartbeat çalıştırmaları sırasında OpenClaw, HEARTBEAT_OK yanıtın başında veya sonunda göründüğünde bunu bir onay olarak değerlendirir. Token çıkarılır ve kalan içerik ≤ ackMaxChars ise yanıt atılır (varsayılan: 300).
• HEARTBEAT_OK bir yanıtın ortasında görünürse özel olarak değerlendirilmez.
• Uyarılar için HEARTBEAT_OK eklemeyin; yalnızca uyarı metnini döndürün.

Heartbeat'lerin dışında, bir mesajın başında/sonunda bulunan başıboş HEARTBEAT_OK çıkarılır ve günlüğe yazılır; yalnızca HEARTBEAT_OK olan bir mesaj atı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 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 subagent/nested lanes
        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        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
      },
    },
  },
}

# Kapsam ve öncelik

• agents.defaults.heartbeat, genel Heartbeat davranışını ayarlar.
• agents.list[].heartbeat bunun üstüne birleştirilir; herhangi bir ajanda heartbeat bloğu varsa yalnızca bu ajanlar Heartbeat ç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 bazlı ayarları geçersiz kılar.

# Ajan başına Heartbeat'ler

Herhangi bir agents.list[] girdisi bir heartbeat bloğu içeriyorsa, Heartbeat'leri yalnızca o 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, 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ırlayı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 pencerenin dışında (Doğu saatine göre sabah 9'dan önce veya akşam 10'dan sonra), Heartbeat'ler atlanır. Pencere içindeki bir sonraki zamanlanmış tik normal şekilde çalışır.

# 24/7 kurulum

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

• activeHours alanını tamamen atlayın (zaman penceresi kısıtlaması yoktur; varsayılan davranış budur).
• Tam günlük bir pencere 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ı

everystring

Heartbeat aralığı (süre dizesi; varsayılan birim = dakika).

modelstring

Heartbeat çalıştırmaları için isteğe bağlı model geçersiz kılması (provider/model).

includeReasoningboolean

Etkinleştirildiğinde, mevcut olduğunda ayrı Reasoning: mesajını da teslim eder (/reasoning on ile aynı biçimde).

lightContextboolean

True olduğunda, Heartbeat çalıştırmaları hafif bootstrap bağlamı kullanır ve çalışma alanı bootstrap dosyalarından yalnızca HEARTBEAT.md dosyasını tutar.

isolatedSessionboolean

True olduğunda, her Heartbeat önceki konuşma geçmişi olmayan yeni bir oturumda çalışır. Cron sessionTarget: "isolated" ile aynı yalıtım kalıbını kullanır. Heartbeat başına token maliyetini önemli ölçüde azaltır. Maksimum tasarruf için lightContext: true ile birleştirin. Teslim yönlendirmesi yine ana oturum bağlamını kullanır.

skipWhenBusyboolean

True olduğunda, Heartbeat çalıştırmaları ekstra yoğun hatlarda ertelenir: alt ajan veya iç içe komut işi. Cron hatları, bu bayrak olmadan bile Heartbeat'leri her zaman erteler; böylece yerel model ana makineleri cron ve Heartbeat istemlerini aynı anda çalıştırmaz.

sessionstring

Heartbeat çalıştırmaları için isteğe bağlı oturum anahtarı.

• main (varsayılan): ajanın ana oturumu.
• Açık oturum anahtarı (openclaw sessions --json veya oturumlar CLI üzerinden kopyalayın).
• Oturum anahtarı biçimleri: bkz. Oturumlar ve Gruplar.

targetstring

• last: son kullanılan harici kanala teslim et.
• açık kanal: yapılandırılmış herhangi bir kanal veya plugin kimliği; örneğin discord, matrix, telegram veya whatsapp.
• none (varsayılan): Heartbeat'i çalıştır ama harici olarak teslim etme.

directPolicy"allow" | "block"

Doğrudan/DM teslim davranışını denetler. allow: doğrudan/DM Heartbeat teslimine izin ver. block: doğrudan/DM teslimini bastır (reason=dm-blocked).

tostring

İsteğe bağlı alıcı geçersiz kılması (kanala özgü kimlik; ör. WhatsApp için E.164 veya Telegram sohbet kimliği). Telegram konuları/iş parçacıkları için <chatId>:topic:<messageThreadId> kullanın.

accountIdstring

Çok hesaplı kanallar için isteğe bağlı hesap kimliği. target: "last" olduğunda, hesap kimliği hesapları destekliyorsa çözümlenen son kanala uygulanır; aksi halde yok sayılır. Hesap kimliği çözümlenen kanal için yapılandırılmış bir hesapla eşleşmezse teslimat atlanır.

promptstring

Varsayılan istem gövdesini geçersiz kılar (birleştirilmez).

ackMaxCharsnumber

Teslimden önce HEARTBEAT_OK sonrasında izin verilen maksimum karakter sayısı.

suppressToolErrorWarningsboolean

True olduğunda, Heartbeat çalıştırmaları sırasında araç hatası uyarı yüklerini bastırır.

activeHoursobject

Heartbeat çalıştırmalarını bir zaman aralığıyla sınırlar. start (HH:MM, dahil; gün başlangıcı için 00:00 kullanın), end (HH:MM hariç; gün sonu için 24:00 kullanılabilir) ve isteğe bağlı timezone içeren nesne.

• Atlanırsa veya "user" olursa: ayarlanmışsa agents.defaults.userTimezone değerini kullanır, aksi halde ana sistem saat dilimine geri döner.
• "local": her zaman ana sistem saat dilimini kullanır.
• Herhangi bir IANA tanımlayıcısı (örn. America/New_York): doğrudan kullanılır; geçersizse yukarıdaki "user" davranışına geri döner.
• Etkin bir pencere için start ve end eşit olmamalıdır; eşit değerler sıfır genişlikte kabul edilir (her zaman pencerenin dışında).
• Etkin pencerenin dışında, Heartbeat’ler pencere içindeki bir sonraki tike kadar atlanır.

# Teslim davranışı

# Görünürlük kontrolleri

Varsayılan olarak, uyarı içeriği teslim edilirken HEARTBEAT_OK onayları bastırılır. Bunu kanal başına veya hesap başına ayarlayabilirsiniz:

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

Öncelik: hesap başına → kanal başına → kanal varsayılanları → yerleşik varsayılanlar.

# Her bayrağın yaptığı şey

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

Üçü de false ise OpenClaw Heartbeat çalıştırmasını tamamen atlar (model çağrısı yok).

# Kanal başına ve hesap başına örnekler

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

# Yaygın kalıplar

Amaç	Yapılandırma
Varsayılan davranış (sessiz OK’ler, uyarılar açık)	(yapılandırma gerekmez)
Tamamen sessiz (ileti yok, gösterge yok)	channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }
Yalnızca gösterge (ileti yok)	channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }
OK’ler yalnızca tek kanalda	channels.telegram.heartbeat: { showOk: true }

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

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

Normal çalıştırmalarda, HEARTBEAT.md yalnızca varsayılan ajan için Heartbeat rehberliği etkinleştirildiğinde enjekte edilir. Heartbeat temposunu 0m ile devre dışı bırakmak veya includeSystemPromptSection: false ayarlamak, onu normal önyükleme bağlamından çıkarır.

HEARTBEAT.md varsa ancak fiilen boşsa (yalnızca boş satırlar ve # Heading gibi markdown başlıkları), OpenClaw API çağrılarını azaltmak için Heartbeat çalıştırmasını atlar. Bu atlama reason=empty-heartbeat-file olarak raporlanır. Dosya yoksa Heartbeat yine çalışır ve model ne yapılacağına karar verir.

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

Örnek 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: blokları

HEARTBEAT.md, Heartbeat’in içinde aralık tabanlı kontroller için küçük ve yapılandırılmış bir tasks: bloğunu da destekler.

Örnek:

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.

Görev modu, her tikte hepsine ödeme yapmadan tek bir Heartbeat dosyasında birkaç periyodik kontrol tutmak istediğinizde kullanışlıdır.

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

Evet — isterseniz.

HEARTBEAT.md, ajan çalışma alanındaki normal bir dosyadır; bu yüzden ajana (normal bir sohbette) şöyle bir şey söyleyebilirsiniz:

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

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

# Elle uyandırma (isteğe bağlı)

Şununla bir sistem olayını kuyruğa alabilir ve anında Heartbeat tetikleyebilirsiniz:

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

Birden fazla ajanda heartbeat yapılandırılmışsa, elle uyandırma bu ajan Heartbeat’lerinin her birini hemen çalıştırır.

Bir sonraki zamanlanmış tiki beklemek için --mode next-heartbeat kullanın.

# Reasoning teslimi (isteğe bağlı)

Varsayılan olarak Heartbeat’ler yalnızca son “yanıt” yükünü teslim eder.

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

• agents.defaults.heartbeat.includeReasoning: true

Etkinleştirildiğinde Heartbeat’ler ayrıca Reasoning: ön ekli ayrı bir ileti de teslim eder (/reasoning on ile aynı biçimde). Bu, ajan birden çok oturumu/codex’i yönetirken ve size neden ping atmaya karar verdiğini görmek istediğinizde yararlı olabilir; ancak istediğinizden fazla dahili ayrıntıyı da sızdırabilir. Grup sohbetlerinde kapalı tutmayı tercih edin.

# Maliyet farkındalığı

Heartbeat’ler tam ajan turları çalıştırır. Daha kısa aralıklar daha fazla token harcar. Maliyeti azaltmak için:

• Tam konuşma geçmişi göndermekten kaçınmak için isolatedSession: true kullanın (çalıştırma başına ~100K token’dan ~2-5K token’a).
• Önyükleme dosyalarını yalnızca HEARTBEAT.md ile sınırlamak için lightContext: true kullanın.
• Daha ucuz bir model ayarlayın (örn. 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ı

Bir Heartbeat daha önce mevcut bir oturumu daha küçük bir yerel modelde bıraktıysa, örneğin 32k pencereli bir Ollama modeli, ve bir sonraki ana oturum turu bağlam taşması bildirirse, oturum çalışma zamanı modelini yapılandırılmış birincil modele geri sıfırlayın. OpenClaw’ın sıfırlama iletisi, son çalışma zamanı modeli yapılandırılmış heartbeat.model ile eşleştiğinde bunu belirtir.

Güncel Heartbeat’ler, çalıştırma tamamlandıktan sonra paylaşılan oturumun mevcut çalışma zamanı modelini korur. Heartbeat’leri yeni bir oturumda çalıştırmak için yine isolatedSession: true kullanabilir, en küçük istem için bunu lightContext: true ile birleştirebilir veya paylaşılan oturum için yeterince büyük bağlam penceresine sahip bir Heartbeat modeli seçebilirsiniz.

# İlgili

• Otomasyon ve Görevler — tüm otomasyon mekanizmalarına genel bakış
• Arka Plan Görevleri — ayrılmış işin nasıl izlendiği
• Saat Dilimi — saat diliminin Heartbeat zamanlamasını nasıl etkilediği
• Sorun Giderme — otomasyon sorunlarını ayıklama