Heartbeat

Heartbeat เรียกใช้ รอบการทำงานของเอเจนต์เป็นระยะ ในเซสชันหลัก เพื่อให้โมเดลสามารถแจ้งสิ่งที่ต้องให้ความสนใจได้โดยไม่ส่งข้อความรบกวนคุณมากเกินไป

Heartbeat คือรอบการทำงานตามกำหนดเวลาในเซสชันหลัก — มัน ไม่ สร้างระเบียน งานเบื้องหลัง ระเบียนงานมีไว้สำหรับงานที่แยกออกไป (การรัน ACP, เอเจนต์ย่อย, งาน cron แบบแยกโดดเดี่ยว)

การแก้ไขปัญหา: งานตามกำหนดเวลา

เริ่มต้นอย่างรวดเร็ว (ผู้เริ่มต้น)

ตัวอย่างการกำหนดค่า:

{  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 `Reasoning:` message too      },    },  },}

ค่าเริ่มต้น

• ช่วงเวลา: 30m (หรือ 1h เมื่อโหมดการยืนยันตัวตนที่ตรวจพบคือ Anthropic OAuth/token รวมถึงการใช้ Claude CLI ซ้ำ) ตั้งค่า agents.defaults.heartbeat.every หรือ agents.list[].heartbeat.every; ใช้ 0m เพื่อปิดใช้งาน
• เนื้อหาพรอมป์ (กำหนดค่าได้ผ่าน agents.defaults.heartbeat.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.
• พรอมป์ Heartbeat จะถูกส่ง ตรงตามตัวอักษร เป็นข้อความของผู้ใช้ พรอมป์ระบบจะมีส่วน "Heartbeat" เฉพาะเมื่อเปิดใช้ Heartbeat สำหรับเอเจนต์เริ่มต้น และการรันถูกทำเครื่องหมายไว้ภายใน
• เมื่อปิดใช้ Heartbeat ด้วย 0m การรันปกติจะไม่รวม HEARTBEAT.md จากบริบทเริ่มต้นด้วย เพื่อไม่ให้โมเดลเห็นคำสั่งที่มีไว้สำหรับ Heartbeat เท่านั้น
• ชั่วโมงที่ใช้งานอยู่ (heartbeat.activeHours) จะถูกตรวจสอบตามเขตเวลาที่กำหนดค่าไว้อยู่ นอกช่วงเวลาดังกล่าว Heartbeat จะถูกข้ามจนกว่าจะถึง tick ถัดไปภายในช่วงเวลา
• Heartbeat จะเลื่อนออกโดยอัตโนมัติระหว่างที่งาน cron กำลังทำงานหรืออยู่ในคิว ตั้งค่า heartbeat.skipWhenBusy: true เพื่อเลื่อนเอเจนต์ด้วยเมื่อเอเจนต์นั้นมีเอเจนต์ย่อยที่ผูกกับคีย์เซสชันของตนเองหรือเลนคำสั่งซ้อนที่กำลังยุ่งอยู่; เอเจนต์พี่น้องจะไม่หยุดชั่วคราวอีกต่อไปเพียงเพราะเอเจนต์อื่นมีงานเอเจนต์ย่อยที่กำลังดำเนินอยู่

พรอมป์ Heartbeat มีไว้เพื่ออะไร

พรอมป์เริ่มต้นถูกตั้งใจให้ครอบคลุมกว้าง:

• งานเบื้องหลัง: "พิจารณางานที่ยังค้างอยู่" กระตุ้นให้เอเจนต์ตรวจสอบรายการติดตามผล (กล่องข้อความ ปฏิทิน ตัวเตือน งานที่อยู่ในคิว) และแจ้งสิ่งที่เร่งด่วน
• การเช็กอินกับมนุษย์: "เช็กกับมนุษย์ของคุณเป็นครั้งคราวในช่วงกลางวัน" กระตุ้นข้อความเบา ๆ เป็นครั้งคราวว่า "มีอะไรที่คุณต้องการไหม?" แต่หลีกเลี่ยงสแปมในเวลากลางคืนโดยใช้เขตเวลาท้องถิ่นที่คุณกำหนดค่าไว้ (ดู เขตเวลา)

Heartbeat สามารถตอบสนองต่องาน งานเบื้องหลัง ที่เสร็จสมบูรณ์ได้ แต่การรัน Heartbeat เองจะไม่สร้างระเบียนงาน

หากคุณต้องการให้ Heartbeat ทำบางอย่างที่เฉพาะเจาะจงมาก (เช่น "ตรวจสอบสถิติ Gmail PubSub" หรือ "ตรวจสอบสุขภาพของ gateway") ให้ตั้งค่า agents.defaults.heartbeat.prompt (หรือ agents.list[].heartbeat.prompt) เป็นเนื้อหาที่กำหนดเอง (ส่งตรงตามตัวอักษร)

สัญญาการตอบกลับ

• หากไม่มีสิ่งใดต้องให้ความสนใจ ให้ตอบด้วย HEARTBEAT_OK
• การรัน Heartbeat ที่ใช้เครื่องมือได้อาจเรียก heartbeat_respond พร้อม notify: false เพื่อไม่ให้มีการอัปเดตที่มองเห็นได้ หรือ notify: true พร้อม notificationText สำหรับการแจ้งเตือน เมื่อมีอยู่ การตอบกลับแบบมีโครงสร้างจากเครื่องมือจะมีความสำคัญเหนือ fallback แบบข้อความ
• ระหว่างการรัน Heartbeat, OpenClaw จะถือว่า HEARTBEAT_OK เป็น ack เมื่อปรากฏที่ จุดเริ่มต้นหรือจุดสิ้นสุด ของคำตอบ โทเค็นจะถูกตัดออก และคำตอบจะถูกทิ้งหากเนื้อหาที่เหลือมีความยาว ≤ ackMaxChars (ค่าเริ่มต้น: 300)
• หาก HEARTBEAT_OK ปรากฏอยู่ ตรงกลาง ของคำตอบ จะไม่ถูกปฏิบัติเป็นกรณีพิเศษ
• สำหรับการแจ้งเตือน อย่า ใส่ HEARTBEAT_OK; ส่งคืนเฉพาะข้อความแจ้งเตือนเท่านั้น

นอกเหนือจาก Heartbeat, HEARTBEAT_OK ที่หลุดมาอยู่ต้น/ท้ายข้อความจะถูกตัดออกและบันทึกไว้; ข้อความที่มีเพียง HEARTBEAT_OK จะถูกทิ้ง

การกำหนดค่า

{  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 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.",        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

ขอบเขตและลำดับความสำคัญ

• agents.defaults.heartbeat ตั้งค่าพฤติกรรม Heartbeat ส่วนกลาง
• agents.list[].heartbeat จะรวมทับเพิ่มเติม หากเอเจนต์ใดมีบล็อก heartbeat เฉพาะเอเจนต์เหล่านั้นเท่านั้น ที่จะเรียกใช้ Heartbeat
• channels.defaults.heartbeat ตั้งค่าเริ่มต้นด้านการมองเห็นสำหรับทุกช่องทาง
• channels.<channel>.heartbeat แทนที่ค่าเริ่มต้นของช่องทาง
• channels.<channel>.accounts.<id>.heartbeat (ช่องทางแบบหลายบัญชี) แทนที่การตั้งค่าต่อช่องทาง

Heartbeat ต่อเอเจนต์

หากรายการ agents.list[] ใดมีบล็อก heartbeat เฉพาะเอเจนต์เหล่านั้นเท่านั้น ที่จะเรียกใช้ Heartbeat บล็อกต่อเอเจนต์จะรวมทับเพิ่มเติมจาก agents.defaults.heartbeat (ดังนั้นคุณจึงตั้งค่าเริ่มต้นที่ใช้ร่วมกันครั้งเดียว แล้วแทนที่เป็นรายเอเจนต์ได้)

ตัวอย่าง: เอเจนต์สองตัว มีเพียงเอเจนต์ตัวที่สองเท่านั้นที่เรียกใช้ Heartbeat

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

ตัวอย่างชั่วโมงที่ใช้งาน

จำกัด Heartbeat ให้อยู่ในช่วงเวลาทำการในเขตเวลาที่ระบุ:

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

นอกช่วงเวลานี้ (ก่อน 9 โมงเช้าหรือหลัง 4 ทุ่มตามเวลาตะวันออก) Heartbeat จะถูกข้าม รอบการทำงานที่กำหนดไว้ถัดไปภายในช่วงเวลานี้จะทำงานตามปกติ

การตั้งค่าแบบ 24/7

หากคุณต้องการให้ Heartbeat ทำงานทั้งวัน ให้ใช้รูปแบบใดรูปแบบหนึ่งต่อไปนี้:

• ละ activeHours ทั้งหมด (ไม่มีข้อจำกัดช่วงเวลา; นี่คือพฤติกรรมเริ่มต้น)
• ตั้งค่าหน้าต่างเต็มวัน: activeHours: { start: "00:00", end: "24:00" }.

ตัวอย่างหลายบัญชี

ใช้ accountId เพื่อกำหนดเป้าหมายบัญชีเฉพาะในช่องทางแบบหลายบัญชี เช่น Telegram:

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

หมายเหตุภาคสนาม

พฤติกรรมการส่งมอบ

การควบคุมการมองเห็น

โดยค่าเริ่มต้น การตอบรับ HEARTBEAT_OK จะถูกระงับขณะที่เนื้อหาการแจ้งเตือนถูกส่งมอบ คุณสามารถปรับค่านี้ต่อช่องทางหรือต่อบัญชีได้:

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

ลำดับความสำคัญ: ต่อบัญชี → ต่อช่องทาง → ค่าเริ่มต้นของช่องทาง → ค่าเริ่มต้นในตัว

แต่ละ flag ทำอะไร

• showOk: ส่งการตอบรับ HEARTBEAT_OK เมื่อโมเดลส่งคืนการตอบกลับที่เป็น OK เท่านั้น
• showAlerts: ส่งเนื้อหาการแจ้งเตือนเมื่อโมเดลส่งคืนการตอบกลับที่ไม่ใช่ OK
• useIndicator: emit เหตุการณ์ indicator สำหรับพื้นผิวสถานะ UI

หากทั้ง สามอย่าง เป็น false OpenClaw จะข้ามการรัน heartbeat ทั้งหมด (ไม่มีการเรียกโมเดล)

ตัวอย่างต่อช่องทางเทียบกับต่อบัญชี

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

รูปแบบที่พบบ่อย

HEARTBEAT.md (ไม่บังคับ)

หากมีไฟล์ HEARTBEAT.md อยู่ใน workspace พรอมต์เริ่มต้นจะบอกให้เอเจนต์อ่านไฟล์นั้น ให้คิดว่าไฟล์นี้เป็น "เช็กลิสต์ heartbeat" ของคุณ: เล็ก เสถียร และปลอดภัยที่จะรวมทุก 30 นาที

ในการรันปกติ HEARTBEAT.md จะถูก inject เฉพาะเมื่อเปิดใช้งานคำแนะนำ heartbeat สำหรับเอเจนต์เริ่มต้นเท่านั้น การปิดใช้งานจังหวะ heartbeat ด้วย 0m หรือการตั้งค่า includeSystemPromptSection: false จะละไว้จากบริบท bootstrap ปกติ

หาก HEARTBEAT.md มีอยู่แต่แทบจะว่างเปล่า (มีเฉพาะบรรทัดว่างและหัวข้อ markdown เช่น # Heading) OpenClaw จะข้ามการรัน heartbeat เพื่อประหยัดการเรียก API การข้ามนั้นจะถูกรายงานเป็น reason=empty-heartbeat-file หากไฟล์หายไป heartbeat ยังคงรัน และโมเดลจะตัดสินใจว่าจะทำอะไร

ทำให้เล็กมาก (เช็กลิสต์สั้น ๆ หรือการเตือนความจำ) เพื่อหลีกเลี่ยงพรอมต์บวม

ตัวอย่าง 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:

HEARTBEAT.md ยังรองรับบล็อก tasks: แบบมีโครงสร้างขนาดเล็กสำหรับการตรวจสอบตามช่วงเวลาภายใน heartbeat เอง

ตัวอย่าง:

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.

โหมดงานมีประโยชน์เมื่อคุณต้องการให้ไฟล์ heartbeat เดียวเก็บการตรวจสอบเป็นระยะหลายรายการ โดยไม่ต้องจ่ายสำหรับทั้งหมดในทุก tick

เอเจนต์สามารถอัปเดต HEARTBEAT.md ได้ไหม?

ได้ — หากคุณขอให้ทำ

HEARTBEAT.md เป็นเพียงไฟล์ปกติใน workspace ของเอเจนต์ ดังนั้นคุณสามารถบอกเอเจนต์ (ในแชทปกติ) ได้ เช่น:

• "Update HEARTBEAT.md to add a daily calendar check."
• "Rewrite HEARTBEAT.md so it's shorter and focused on inbox follow-ups."

หากคุณต้องการให้สิ่งนี้เกิดขึ้นเชิงรุก คุณสามารถใส่บรรทัดที่ชัดเจนในพรอมต์ heartbeat ของคุณได้ด้วย เช่น: "If the checklist becomes stale, update HEARTBEAT.md with a better one."

การปลุกด้วยตนเอง (ตามต้องการ)

คุณสามารถ enqueue เหตุการณ์ระบบและทริกเกอร์ heartbeat ทันทีด้วย:

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

หากมีเอเจนต์หลายตัวที่กำหนดค่า heartbeat ไว้ การปลุกด้วยตนเองจะรัน heartbeat ของเอเจนต์เหล่านั้นแต่ละตัวทันที

ใช้ --mode next-heartbeat เพื่อรอ tick ที่กำหนดเวลาไว้ถัดไป

การส่งมอบ reasoning (ไม่บังคับ)

โดยค่าเริ่มต้น heartbeat จะส่งมอบเฉพาะเพย์โหลด "คำตอบ" สุดท้ายเท่านั้น

หากคุณต้องการความโปร่งใส ให้เปิดใช้งาน:

• agents.defaults.heartbeat.includeReasoning: true

เมื่อเปิดใช้งาน heartbeat จะส่งมอบข้อความแยกต่างหากที่ขึ้นต้นด้วย Reasoning: ด้วย (รูปแบบเดียวกับ /reasoning on) สิ่งนี้มีประโยชน์เมื่อเอเจนต์จัดการหลายเซสชัน/codexes และคุณต้องการเห็นว่าทำไมเอเจนต์จึงตัดสินใจ ping คุณ — แต่อาจรั่วไหลรายละเอียดภายในมากกว่าที่คุณต้องการได้เช่นกัน แนะนำให้ปิดไว้ในแชทกลุ่ม

การตระหนักถึงต้นทุน

heartbeat รันรอบเอเจนต์เต็มรูปแบบ ช่วงเวลาที่สั้นลงใช้ token มากขึ้น เพื่อลดต้นทุน:

• ใช้ isolatedSession: true เพื่อหลีกเลี่ยงการส่งประวัติการสนทนาทั้งหมด (~100K token ลดลงเหลือ ~2-5K ต่อการรัน)
• ใช้ lightContext: true เพื่อจำกัดไฟล์ bootstrap ให้เหลือเพียง HEARTBEAT.md
• ตั้งค่า model ที่ถูกกว่า (เช่น ollama/llama3.2:1b)
• ทำให้ HEARTBEAT.md เล็ก
• ใช้ target: "none" หากคุณต้องการเฉพาะการอัปเดตสถานะภายใน

บริบทล้นหลัง heartbeat

หาก heartbeat ก่อนหน้านี้ทิ้งเซสชันเดิมไว้บนโมเดล local ที่เล็กกว่า เช่น โมเดล Ollama ที่มีหน้าต่าง 32k และรอบเซสชันหลักถัดไปรายงานว่าบริบทล้น ให้รีเซ็ตโมเดล runtime ของเซสชันกลับไปเป็นโมเดลหลักที่กำหนดค่าไว้ ข้อความรีเซ็ตของ OpenClaw จะระบุเรื่องนี้เมื่อโมเดล runtime ล่าสุดตรงกับ heartbeat.model ที่กำหนดค่าไว้

heartbeat ปัจจุบันจะรักษาโมเดล runtime เดิมของเซสชันที่แชร์ไว้หลังจากการรันเสร็จสมบูรณ์ คุณยังสามารถใช้ isolatedSession: true เพื่อรัน heartbeat ในเซสชันใหม่ รวมกับ lightContext: true เพื่อให้พรอมต์เล็กที่สุด หรือเลือกโมเดล heartbeat ที่มีหน้าต่างบริบทใหญ่พอสำหรับเซสชันที่แชร์

ที่เกี่ยวข้อง

• Automation — กลไก Automation ทั้งหมดในภาพรวม
• งานเบื้องหลัง — วิธีติดตามงานที่แยกออก
• เขตเวลา — วิธีที่เขตเวลามีผลต่อการกำหนดเวลา heartbeat
• การแก้ไขปัญหา — การดีบักปัญหา Automation