​

Heartbeat (Gateway)

Heartbeat mi Cron mu? Hangisinin ne zaman kullanılacağına dair yönlendirme için bkz. Automation & Tasks.

​

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

1. Heartbeat’i etkin bırakın (varsayılan 30m, veya Anthropic OAuth/token auth için 1h; buna Claude CLI yeniden kullanımı da dahildir) ya da kendi sıklığınızı ayarlayın.
2. Aracı çalışma alanında küçük bir HEARTBEAT.md kontrol listesi veya tasks: bloğu oluşturun (isteğe bağlı ama önerilir).
3. Heartbeat mesajlarının nereye gideceğine karar verin (varsayılan target: "none" değeridir; son kişiye yönlendirmek için target: "last" ayarlayın).
4. İsteğe bağlı: şeffaflık için heartbeat reasoning teslimini etkinleştirin.
5. İsteğe bağlı: heartbeat çalıştırmaları yalnızca HEARTBEAT.md gerektiriyorsa hafif bootstrap bağlamını kullanın.
6. İsteğe bağlı: her heartbeat’te tam konuşma geçmişini göndermemek için izole oturumları etkinleştirin.
7. İsteğe bağlı: heartbeat’leri etkin saatlerle sınırlandırın (yerel saat).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // son kişiye açık teslim (varsayılan "none")
        directPolicy: "allow", // varsayılan: doğrudan/DM hedeflerine izin ver; bastırmak için "block" ayarla
        lightContext: true, // isteğe bağlı: bootstrap dosyalarından yalnızca HEARTBEAT.md enjekte et
        isolatedSession: true, // isteğe bağlı: her çalıştırmada yeni oturum (konuşma geçmişi yok)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // isteğe bağlı: ayrı bir `Reasoning:` mesajı da gönder
      },
    },
  },
}

​

Varsayılanlar

• Aralık: 30m (veya algılanan auth modu Anthropic OAuth/token auth ise 1h; buna Claude CLI yeniden kullanımı da dahildir). agents.defaults.heartbeat.every veya aracı başına agents.list[].heartbeat.every ayarlayın; devre dışı bırakmak için 0m kullanın.
• İstem gövdesi (agents.defaults.heartbeat.prompt ile 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 bir “Heartbeat” bölümü içerir ve çalıştırma dahili olarak işaretlenir.
• Etkin saatler (heartbeat.activeHours) yapılandırılmış saat diliminde denetlenir. Pencerenin dışında heartbeat’ler, pencerenin içindeki bir sonraki tik anına kadar atlanır.

​

Heartbeat istemi ne için kullanılır

• Arka plan görevleri: “Consider outstanding tasks”, aracıyı takip işleri (gelen kutusu, takvim, hatırlatıcılar, kuyruktaki işler) gözden geçirmeye ve acil olanları ortaya çıkarmaya yönlendirir.
• İnsani check-in: “Checkup sometimes on your human during day time”, arada sırada hafif bir “bir şeye ihtiyacın var mı?” mesajını teşvik eder, ancak yapılandırılmış yerel saat diliminizi kullanarak gece spam’inden kaçınır (bkz. /concepts/timezone).

​

Yanıt sözleşmesi

• Dikkat gerektiren bir şey yoksa HEARTBEAT_OK ile yanıt verin.
• Heartbeat çalıştırmaları sırasında OpenClaw, HEARTBEAT_OK ifadesi yanıtın başında veya sonunda göründüğünde bunu bir onay olarak kabul eder. Kalan içerik ≤ ackMaxChars (varsayılan: 300) ise token çıkarılır ve yanıt düşürülür.
• HEARTBEAT_OK bir yanıtın ortasında görünürse özel olarak ele alınmaz.
• Uyarılar için HEARTBEAT_OK eklemeyin; yalnızca uyarı metnini döndürün.

​

Yapılandırma

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // varsayılan: 30m (0m devre dışı bırakır)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // varsayılan: false (varsa ayrı `Reasoning:` mesajı teslim eder)
        lightContext: false, // varsayılan: false; true yalnızca çalışma alanı bootstrap dosyalarından HEARTBEAT.md dosyasını tutar
        isolatedSession: false, // varsayılan: false; true her heartbeat'i yeni bir oturumda çalıştırır (konuşma geçmişi yok)
        target: "last", // varsayılan: none | seçenekler: last | none | <channel id> (çekirdek veya plugin, ör. "bluebubbles")
        to: "+15551234567", // isteğe bağlı kanala özgü geçersiz kılma
        accountId: "ops-bot", // isteğe bağlı çok hesaplı kanal kimliği
        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, // HEARTBEAT_OK sonrasında izin verilen maksimum karakter
      },
    },
  },
}

​

Kapsam ve öncelik

• agents.defaults.heartbeat, genel heartbeat davranışını ayarlar.
• agents.list[].heartbeat bunun üzerine birleştirilir; herhangi bir aracının heartbeat bloğu varsa heartbeat’leri yalnızca o aracılar ç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.

​

Aracı başına heartbeat’ler

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // son kişiye açık teslim (varsayılan "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // son kişiye açık teslim (varsayılan "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // isteğe bağlı; ayarlanmışsa userTimezone kullanır, aksi halde ana makine saat dilimi
        },
      },
    },
  },
}

​

7/24 kurulum

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

​

Çok hesaplı örnek

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // isteğe bağlı: belirli bir topic/thread'e yönlendir
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Alan notları

• every: heartbeat aralığı (süre dizesi; varsayılan birim = dakika).
• model: heartbeat çalıştırmaları için isteğe bağlı model geçersiz kılması (provider/model).
• includeReasoning: etkinleştirildiğinde, varsa ayrı Reasoning: mesajını da teslim eder (/reasoning on ile aynı biçim).
• lightContext: 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.
• isolatedSession: true olduğunda her heartbeat, önceki konuşma geçmişi olmadan yeni bir oturumda çalışır. Cron sessionTarget: "isolated" ile aynı izolasyon desenini kullanır. Heartbeat başına token maliyetini dramatik biçimde azaltır. Maksimum tasarruf için lightContext: true ile birleştirin. Teslim yönlendirmesi yine de ana oturum bağlamını kullanır.
• session: heartbeat çalıştırmaları için isteğe bağlı oturum anahtarı.
  • main (varsayılan): aracı ana oturumu.
  • Açık oturum anahtarı (openclaw sessions --json veya sessions CLI çıktısından kopyalayın).
  • Oturum anahtarı biçimleri için bkz. Sessions ve Groups.
• target:
  • last: son kullanılan dış kanala teslim eder.
  • açık kanal: örneğin discord, matrix, telegram veya whatsapp gibi yapılandırılmış herhangi bir kanal veya plugin kimliği.
  • none (varsayılan): heartbeat’i çalıştırır ama harici olarak teslim etmez.
• directPolicy: doğrudan/DM teslim davranışını denetler:
  • allow (varsayılan): doğrudan/DM heartbeat teslimine izin verir.
  • block: doğrudan/DM teslimini bastırır (reason=dm-blocked).
• to: isteğe bağlı alıcı geçersiz kılması (kanala özgü kimlik; ör. WhatsApp için E.164 veya Telegram chat kimliği). Telegram topic/thread’leri için <chatId>:topic:<messageThreadId> kullanın.
• accountId: çok hesaplı kanallar için isteğe bağlı hesap kimliği. target: "last" olduğunda hesap kimliği, 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şmiyorsa teslim atlanır.
• prompt: varsayılan istem gövdesini geçersiz kılar (birleştirilmez).
• ackMaxChars: teslimden önce HEARTBEAT_OK sonrasında izin verilen maksimum karakter.
• suppressToolErrorWarnings: true olduğunda heartbeat çalıştırmaları sırasında araç hata uyarısı payload’larını bastırır.
• activeHours: heartbeat çalıştırmalarını bir zaman penceresiyle 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ır veya "user" ise: ayarlanmışsa agents.defaults.userTimezone kullanılır, aksi halde ana makine sistem saat dilimine geri düşer.
  • "local": her zaman ana makine sistem saat dilimini kullanır.
  • Herhangi bir IANA tanımlayıcısı (ör. America/New_York): doğrudan kullanılır; geçersizse yukarıdaki "user" davranışına geri düşer.
  • Etkin pencere için start ve end eşit olmamalıdır; eşit değerler sıfır genişlikli (her zaman pencere dışında) olarak değerlendirilir.
  • Etkin pencerenin dışında heartbeat’ler, pencerenin içindeki bir sonraki tik zamanına kadar atlanır.

​

Teslim davranışı

• Heartbeat’ler varsayılan olarak aracının ana oturumunda çalışır (agent:<id>:<mainKey>), veya session.scope = "global" ise global içinde. Bunu belirli bir kanal oturumuna (Discord/WhatsApp/vb.) geçersiz kılmak için session ayarlayın.
• session yalnızca çalıştırma bağlamını etkiler; teslim target ve to tarafından denetlenir.
• Belirli bir kanal/alıcıya teslim etmek için target + to ayarlayın. target: "last" ile teslim, o oturum için son dış kanalı kullanır.
• Heartbeat teslimleri varsayılan olarak doğrudan/DM hedeflerine izin verir. Heartbeat turunu yine çalıştırırken doğrudan hedefe gönderimleri bastırmak için directPolicy: "block" ayarlayın.
• Ana kuyruk meşgulse heartbeat atlanır ve daha sonra yeniden denenir.
• target hiçbir dış hedefe çözülmezse çalıştırma yine gerçekleşir ama giden mesaj gönderilmez.
• showOk, showAlerts ve useIndicator öğelerinin tümü devre dışıysa çalıştırma başlangıçta reason=alerts-disabled ile atlanır.
• Yalnızca uyarı teslimi devre dışıysa OpenClaw yine de heartbeat’i çalıştırabilir, vadesi gelen görev zaman damgalarını güncelleyebilir, oturum boşta kalma zaman damgasını geri yükleyebilir ve dışa giden uyarı payload’ını bastırabilir.
• Yalnızca heartbeat yanıtları oturumu canlı tutmaz; son updatedAt geri yüklenir, böylece boşta sona erme normal davranır.
• Ayrılmış background tasks, ana oturumun bir şeyi hızlıca fark etmesi gerektiğinde bir sistem olayı kuyruğa ekleyip heartbeat’i uyandırabilir. Bu uyandırma, heartbeat çalıştırmasını bir arka plan görevi yapmaz.

​

Görünürlük denetimleri

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

​

Her bayrak ne yapar

• 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.

​

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

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

​

Yaygın desenler

​

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

# Heartbeat checklist

- Hızlı tarama: gelen kutularında acil bir şey var mı?
- Gündüz vaktiyse, bekleyen başka bir şey yoksa hafif bir check-in yap.
- Bir görev engellenmişse, _neyin eksik olduğunu_ yaz ve Peter'a bir dahaki sefere sor.

​

tasks: blokları

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

- Uyarıları kısa tut.
- Vadesi gelen tüm görevlerden sonra dikkat gerektiren bir şey yoksa HEARTBEAT_OK ile yanıt ver.

• OpenClaw tasks: bloğunu ayrıştırır ve her görevi kendi interval değerine göre denetler.
• O tik için yalnızca vadesi gelen görevler heartbeat istemine eklenir.
• Vadesi gelen görev yoksa boşa model çağrısı yapmamak için heartbeat tamamen atlanır (reason=no-tasks-due).
• HEARTBEAT.md içindeki görev dışı içerik korunur ve vadesi gelen görev listesinden sonra ek bağlam olarak eklenir.
• Görev son çalıştırma zaman damgaları oturum durumunda (heartbeatTaskState) saklanır; böylece aralıklar normal yeniden başlatmalarda korunur.
• Görev zaman damgaları yalnızca heartbeat çalıştırması normal yanıt yolunu tamamladıktan sonra ilerletilir. Atlanan empty-heartbeat-file / no-tasks-due çalıştırmaları görevleri tamamlanmış olarak işaretlemez.

​

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

• “Günlük bir 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.”

​

El ile uyandırma (isteğe bağlı)

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

​

Reasoning teslimi (isteğe bağlı)

• agents.defaults.heartbeat.includeReasoning: true

​

Maliyet farkındalığı

• Tam konuşma geçmişini göndermemek için isolatedSession: true kullanın (~100K token’dan çalıştırma başına ~2-5K’ya düşer).
• Bootstrap dosyalarını yalnızca HEARTBEAT.md ile sınırlamak için lightContext: true kullanın.
• Daha ucuz bir model ayarlayın (ör. ollama/llama3.2:1b).
• HEARTBEAT.md dosyasını küçük tutun.
• Yalnızca dahili durum güncellemeleri istiyorsanız target: "none" kullanın.

​

İlgili

• Automation & Tasks — tüm otomasyon mekanizmalarına bir bakış
• Background Tasks — ayrılmış işlerin nasıl izlendiği
• Timezone — saat diliminin heartbeat zamanlamasını nasıl etkilediği
• Troubleshooting — otomasyon sorunlarını hata ayıklama