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 `Thinking` message too      },    },  },}

ค่าเริ่มต้น

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

จุดประสงค์ของพรอมต์ Heartbeat

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

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

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

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

ข้อตกลงการตอบกลับ

• หากไม่มีสิ่งใดต้องได้รับความสนใจ ให้ตอบกลับด้วย HEARTBEAT_OK
• การทำงานของ Heartbeat อาจเรียก heartbeat_respond โดยใช้ notify: false เพื่อไม่แสดงการอัปเดต หรือใช้ notify: true พร้อม notificationText สำหรับการแจ้งเตือนแทน หากมีการตอบกลับจากเครื่องมือแบบมีโครงสร้าง การตอบกลับนั้นจะมีลำดับความสำคัญเหนือข้อความสำรอง
• ระหว่างการทำงานของ Heartbeat OpenClaw จะถือว่า HEARTBEAT_OK เป็นการตอบรับเมื่อปรากฏที่ จุดเริ่มต้นหรือจุดสิ้นสุด ของคำตอบ โทเค็นดังกล่าวจะถูกตัดออก และคำตอบจะถูกละทิ้งหากเนื้อหาที่เหลือมีความยาว ≤ 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 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.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        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:00 น. หรือหลัง 22:00 น. ตามเวลาตะวันออก) Heartbeat จะถูกข้าม รอบตามกำหนดเวลาถัดไปที่อยู่ภายในช่วงจะทำงานตามปกติ

การตั้งค่าให้ทำงานตลอด 24 ชั่วโมงทุกวัน

หากคุณต้องการให้ 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 # ซ่อน HEARTBEAT_OK (ค่าเริ่มต้น)      showAlerts: true # แสดงข้อความแจ้งเตือน (ค่าเริ่มต้น)      useIndicator: true # ปล่อยอีเวนต์ตัวบ่งชี้ (ค่าเริ่มต้น)  telegram:    heartbeat:      showOk: true # แสดงการตอบรับ OK บน Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # ระงับการส่งการแจ้งเตือนสำหรับบัญชีนี้

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

หน้าที่ของแต่ละแฟล็ก

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

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

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

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # บัญชี Slack ทั้งหมด    accounts:      ops:        heartbeat:          showAlerts: false # ระงับการแจ้งเตือนเฉพาะบัญชี ops  telegram:    heartbeat:      showOk: true

รูปแบบที่ใช้บ่อย

HEARTBEAT.md (ตัวเลือกเสริม)

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

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

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

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

รักษาไฟล์ให้มีขนาดเล็ก (รายการตรวจสอบหรือข้อความเตือนสั้น ๆ) เพื่อหลีกเลี่ยงไม่ให้พรอมต์มีขนาดใหญ่เกินไป

ตัวอย่าง HEARTBEAT.md:

# รายการตรวจสอบ Heartbeat - ตรวจอย่างรวดเร็ว: มีเรื่องเร่งด่วนในกล่องข้อความหรือไม่?- หากเป็นช่วงกลางวัน ให้ตรวจสอบสถานะเล็กน้อยถ้าไม่มีเรื่องอื่นรอดำเนินการ- หากงานติดขัด ให้จดว่า_ขาดอะไร_ และถาม Peter ในครั้งถัดไป

บล็อก tasks:

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

ตัวอย่าง:

tasks: - name: inbox-triage  interval: 30m  prompt: "ตรวจหาอีเมลที่ยังไม่ได้อ่านและเร่งด่วน แล้วทำเครื่องหมายรายการที่ไวต่อเวลา"- name: calendar-scan  interval: 2h  prompt: "ตรวจหาการประชุมที่กำลังจะมาถึงซึ่งต้องเตรียมตัวหรือติดตามผล" # คำสั่งเพิ่มเติม - เขียนการแจ้งเตือนให้สั้น- หากไม่มีสิ่งใดต้องดำเนินการหลังตรวจงานที่ถึงกำหนดทั้งหมดแล้ว ให้ตอบ HEARTBEAT_OK

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

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

ได้ หากคุณขอให้ดำเนินการ

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

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

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

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

ใช้ openclaw system event เพื่อเพิ่มอีเวนต์ระบบเข้าคิวและเลือกเรียก Heartbeat ทันที:

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

หากไม่ได้ระบุ --session-key และมีเอเจนต์หลายตัวที่กำหนดค่า heartbeat ไว้ --mode now จะเรียก Heartbeat ของเอเจนต์เหล่านั้นทั้งหมดทันที

การควบคุม Heartbeat ที่เกี่ยวข้องในกลุ่ม CLI เดียวกัน:

openclaw system heartbeat last     # แสดงอีเวนต์ Heartbeat ล่าสุดopenclaw system heartbeat enable   # เปิดใช้งาน Heartbeatopenclaw system heartbeat disable  # ปิดใช้งาน Heartbeat

การส่งกระบวนการให้เหตุผล (ตัวเลือกเสริม)

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

การคำนึงถึงค่าใช้จ่าย

Heartbeat จะเรียกใช้รอบการทำงานของตัวแทนแบบเต็ม ช่วงเวลาที่สั้นลงจะใช้โทเค็นมากขึ้น วิธีลดค่าใช้จ่าย:

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

บริบทล้นหลังจาก Heartbeat

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

เพื่อหลีกเลี่ยงปัญหานี้ ให้ใช้ isolatedSession: true เพื่อเรียกใช้ Heartbeat ในเซสชันใหม่ (อาจใช้ร่วมกับ lightContext: true เพื่อให้พรอมต์มีขนาดเล็กที่สุด) หรือเลือกโมเดล Heartbeat ที่มีหน้าต่างบริบทใหญ่เพียงพอสำหรับเซสชันที่ใช้ร่วมกัน

เนื้อหาที่เกี่ยวข้อง

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