​

Kalp Atışı (Gateway)

Heartbeat mi Cron mu? Hangisinin ne zaman kullanılacağına dair rehber için Cron vs Heartbeat bölümüne bakın.

​

Hızlı başlangıç (yeni başlayanlar)

1. Heartbeat’leri etkin bırakın (varsayılan 30m; Anthropic OAuth/setup-token için 1h) veya kendi sıklığınızı ayarlayın.
2. Ajan çalışma alanında küçük bir HEARTBEAT.md kontrol listesi oluşturun (isteğe bağlı ama önerilir).
3. Heartbeat mesajlarının nereye gideceğine karar verin (varsayılan target: "last").
4. İsteğe bağlı: şeffaflık için heartbeat muhakeme iletimini etkinleştirin.
5. İsteğe bağlı: heartbeat’leri yalnızca aktif saatlerle sınırlayın (yerel saat).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

Varsayılanlar

• Aralık: 30m (Anthropic OAuth/setup-token algılanan kimlik doğrulama modu olduğunda 1h). Küresel olarak agents.defaults.heartbeat.every veya ajan bazında 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.
• Aktif saatler (heartbeat.activeHours) yapılandırılan saat diliminde kontrol edilir. Pencere dışında heartbeat’ler, pencere içindeki bir sonraki tetiklemeye kadar atlanır.

​

Heartbeat isteminin amacı

• Arka plan görevleri: “Consider outstanding tasks” ifadesi, ajanın takipleri (gelen kutusu, takvim, hatırlatıcılar, kuyruktaki işler) gözden geçirmesini ve acil olanları öne çıkarmasını teşvik eder.
• İnsanla kısa yoklama: “Checkup sometimes on your human during day time” ifadesi, ara sıra hafif bir “Bir şeye ihtiyacın var mı?” mesajını teşvik eder; ancak yapılandırılmış yerel saat dilimini kullanarak gece spam’ini önler (bkz. /concepts/timezone).

​

Yanıt sözleşmesi

• Dikkat gerektiren bir şey yoksa HEARTBEAT_OK ile yanıtlayın.
• Heartbeat çalıştırmaları sırasında OpenClaw, yanıtın başında veya sonunda göründüğünde HEARTBEAT_OK’ü bir onay (ack) olarak kabul eder. Belirteç çıkarılır ve kalan içerik ≤ ackMaxChars (varsayılan: 300) ise yanıt düşürülür.
• HEARTBEAT_OK 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", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // 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 küresel heartbeat davranışını ayarlar.
• agents.list[].heartbeat bunun üzerine birleştirilir; herhangi bir ajanda heartbeat bloğu varsa yalnızca o 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 (çoklu hesap kanalları) kanal başına ayarları geçersiz kılar.

​

Per-agent heartbeats

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    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.",
        },
      },
    ],
  },
}

​

Aktif saatler örneği

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

Çoklu hesap örneği

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          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ılma (provider/model).
• includeReasoning: etkinleştirildiğinde, ayrı Reasoning: mesajını da mevcut olduğunda iletir (şekli /reasoning on ile aynıdır).
• session: heartbeat çalıştırmaları için isteğe bağlı oturum anahtarı.
  • main (default): agent main session.
  • Açık oturum anahtarı (openclaw sessions --json’den veya sessions CLI üzerinden kopyalayın).
  • Oturum anahtarı biçimleri: Sessions ve Groups bölümlerine bakın.
• target:
  • last (varsayılan): son kullanılan harici kanala iletir.
  • açık kanal: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: heartbeat’i çalıştırır ancak harici olarak iletmez.
• to: isteğe bağlı alıcı geçersiz kılma (kanala özgü kimlik; ör. WhatsApp için E.164 veya Telegram sohbet kimliği).
• accountId: çoklu hesap 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şmezse iletim atlanır.
• prompt: varsayılan istem gövdesini geçersiz kılar (birleştirilmez).
• ackMaxChars: iletimden önce HEARTBEAT_OK sonrasında izin verilen azami karakter sayısı.
• activeHours: heartbeat çalıştırmalarını bir zaman penceresiyle sınırlar. start (HH:MM, dahil), end (HH:MM, hariç; gün sonu için 24:00 kabul edilir) ve isteğe bağlı timezone içeren nesne.
  • Atlanırsa veya "user" ise: ayarlıysa 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.
  • Aktif pencere dışında heartbeat’ler, pencere içindeki bir sonraki tetiklemeye kadar atlanır.

​

İletim davranışı

• Heartbeat’ler varsayılan olarak ajanın ana oturumunda çalışır (agent:<id>:<mainKey>), veya session.scope = "global" olduğunda global. 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; iletim target ve to tarafından kontrol edilir.
• Belirli bir kanal/alıcıya iletmek için target + to ayarlayın. target: "last" ile, iletim o oturum için son harici kanalı kullanır.
• Ana kuyruk meşgulse heartbeat atlanır ve daha sonra yeniden denenir.
• target harici bir hedefe çözümlenmezse, çalıştırma yine gerçekleşir ancak giden mesaj gönderilmez.
• Yalnızca heartbeat yanıtları oturumu canlı tutmaz; son updatedAt geri yüklenir, böylece boşta kalma süresi normal davranır.

​

Görünürlük denetimleri

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

​

Her bayrağın yaptığı

• showOk: model yalnızca OK içeren bir 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ı üretir.

​

Kanal başına vs 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

​

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

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

​

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

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

​

Manuel uyandırma (istek üzerine)

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

​

Reasoning delivery (optional)

• agents.defaults.heartbeat.includeReasoning: true

​

Maliyet farkındalığı