Heartbeat

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

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

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

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

ตัวอย่าง config:

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

ค่าเริ่มต้น

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

prompt ของ Heartbeat มีไว้เพื่ออะไร

prompt เริ่มต้นตั้งใจให้กว้าง:

• งานเบื้องหลัง: "Consider outstanding tasks" กระตุ้นให้เอเจนต์ตรวจสอบงานติดตามผล (กล่องขาเข้า, ปฏิทิน, การเตือน, งานที่อยู่ในคิว) และแจ้งสิ่งเร่งด่วน
• การเช็กอินกับมนุษย์: "Checkup sometimes on your human during day time" กระตุ้นให้ส่งข้อความเบา ๆ เป็นครั้งคราวว่า "มีอะไรที่คุณต้องการไหม?" แต่หลีกเลี่ยงสแปมตอนกลางคืนโดยใช้ timezone ท้องถิ่นที่คุณกำหนดค่าไว้ (ดู Timezone)

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 ที่หลงมาที่จุดเริ่มต้น/ท้ายสุดของข้อความจะถูกตัดออกและบันทึก log; ข้อความที่มีเพียง HEARTBEAT_OK จะถูกทิ้ง

Config

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

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

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

Heartbeat ราย agent

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

ตัวอย่าง: agent สองตัว โดยมีเฉพาะ agent ตัวที่สองที่รัน 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 จะถูกข้าม tick ถัดไปที่ถูกกำหนดเวลาไว้ภายในช่วงเวลาจะรันตามปกติ

การตั้งค่าแบบ 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" },      },    },  },}

หมายเหตุของฟิลด์

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

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

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

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: ส่ง acknowledgment HEARTBEAT_OK เมื่อโมเดลส่งคืนการตอบกลับแบบ OK เท่านั้น
• showAlerts: ส่งเนื้อหา alert เมื่อโมเดลส่งคืนการตอบกลับที่ไม่ใช่ 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, prompt เริ่มต้นจะบอกให้เอเจนต์อ่านไฟล์นั้น ให้คิดว่าเป็น "เช็กลิสต์ Heartbeat" ของคุณ: เล็ก เสถียร และปลอดภัยที่จะพิจารณาทุก 30 นาที

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

ใน Codex harness แบบ native เนื้อหา HEARTBEAT.md จะไม่ถูก inject เข้าไปใน turn หากไฟล์มีอยู่และมีเนื้อหาที่ไม่ใช่ whitespace คำสั่งโหมด collaboration ของ Heartbeat จะชี้ Codex ไปที่ไฟล์และบอกให้อ่านก่อนดำเนินการต่อ

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

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

ตัวอย่าง 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: แบบมีโครงสร้างขนาดเล็กสำหรับการตรวจตาม interval ภายใน 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 ของเอเจนต์ ดังนั้นคุณสามารถบอกเอเจนต์ (ในแชตปกติ) ได้ประมาณนี้:

• "อัปเดต HEARTBEAT.md เพื่อเพิ่มการตรวจปฏิทินรายวัน"
• "เขียน HEARTBEAT.md ใหม่ให้สั้นลงและเน้นการติดตามผล inbox"

หากคุณต้องการให้สิ่งนี้เกิดขึ้นเชิงรุก คุณยังสามารถใส่บรรทัดชัดเจนใน prompt ของ Heartbeat เช่น: "หากเช็กลิสต์เริ่มล้าสมัย ให้อัปเดต HEARTBEAT.md ด้วยรายการที่ดีกว่า"

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

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

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

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

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

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

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

ความตระหนักเรื่องค่าใช้จ่าย

Heartbeat รัน turn ของเอเจนต์แบบเต็ม interval ที่สั้นกว่าจะใช้ token มากขึ้น เพื่อลดค่าใช้จ่าย:

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

Context overflow หลัง Heartbeat

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

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

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

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