Heartbeat

Heartbeat chạy các lượt agent định kỳ trong phiên chính để mô hình có thể nêu ra mọi nội dung cần chú ý mà không gửi tin nhắn dồn dập cho bạn.

Heartbeat là một lượt phiên chính theo lịch - nó không tạo bản ghi tác vụ nền. Bản ghi tác vụ dành cho công việc tách biệt (các lượt chạy ACP, subagent, tác vụ cron cô lập).

Khắc phục sự cố: Tác vụ theo lịch

Bắt đầu nhanh (người mới)

Cấu hình ví dụ:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // gửi rõ ràng đến liên hệ gần nhất (mặc định là "none")        directPolicy: "allow", // mặc định: cho phép đích trực tiếp/DM; đặt "block" để chặn        lightContext: true, // không bắt buộc: chỉ chèn HEARTBEAT.md từ các tệp khởi tạo        isolatedSession: true, // không bắt buộc: phiên mới cho mỗi lượt chạy (không có lịch sử hội thoại)        skipWhenBusy: true, // không bắt buộc: cũng trì hoãn khi subagent hoặc các luồng lồng nhau của agent này đang bận        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // không bắt buộc: cũng gửi thông báo `Thinking` riêng      },    },  },}

Giá trị mặc định

• Khoảng thời gian: 30m. Việc áp dụng giá trị mặc định của nhà cung cấp Anthropic sẽ tăng khoảng này lên 1h khi chế độ xác thực đã phân giải là OAuth/token (bao gồm cả việc tái sử dụng Claude CLI), nhưng chỉ khi chưa đặt heartbeat.every. Đặt agents.defaults.heartbeat.every hoặc agents.list[].heartbeat.every theo từng agent; dùng 0m để tắt.
• Nội dung lời nhắc (có thể cấu hình qua agents.defaults.heartbeat.prompt): Đọc HEARTBEAT.md nếu tệp tồn tại (ngữ cảnh không gian làm việc). Tuân thủ nghiêm ngặt. Không suy diễn hoặc lặp lại các tác vụ cũ từ những cuộc trò chuyện trước. Nếu không có gì cần chú ý, hãy trả lời HEARTBEAT_OK.
• Thời gian chờ: các lượt Heartbeat chưa đặt thời gian chờ sẽ sử dụng agents.defaults.timeoutSeconds nếu có. Nếu không, chúng sử dụng tần suất Heartbeat với giới hạn tối đa 600 giây. Đặt agents.defaults.heartbeat.timeoutSeconds hoặc agents.list[].heartbeat.timeoutSeconds theo từng agent cho công việc Heartbeat kéo dài hơn.
• Lời nhắc Heartbeat được gửi nguyên văn dưới dạng tin nhắn của người dùng. Lời nhắc hệ thống chỉ bao gồm phần "Heartbeats" khi Heartbeat được bật cho agent mặc định (và includeSystemPromptSection không phải là false), đồng thời lượt chạy được đánh dấu nội bộ.
• Khi Heartbeat bị tắt bằng 0m, các lượt chạy thông thường cũng bỏ HEARTBEAT.md khỏi ngữ cảnh khởi tạo để mô hình không thấy các hướng dẫn chỉ dành cho Heartbeat.
• Giờ hoạt động (heartbeat.activeHours) được kiểm tra theo múi giờ đã cấu hình. Ngoài khoảng thời gian này, Heartbeat sẽ bị bỏ qua cho đến nhịp tiếp theo nằm trong khoảng.
• Heartbeat tự động trì hoãn khi công việc cron đang hoạt động hoặc nằm trong hàng đợi. Đặt heartbeat.skipWhenBusy: true để cũng trì hoãn một agent khi subagent gắn với khóa phiên hoặc các luồng lệnh lồng nhau của chính agent đó đang chạy; các agent ngang hàng không còn tạm dừng chỉ vì một agent khác đang có công việc subagent.

Mục đích của lời nhắc Heartbeat

Lời nhắc mặc định được thiết kế có chủ ý với phạm vi rộng:

• Tác vụ nền: "Xem xét các tác vụ còn tồn đọng" thúc đẩy agent xem lại các việc cần theo dõi (hộp thư đến, lịch, lời nhắc, công việc trong hàng đợi) và nêu ra mọi nội dung khẩn cấp.
• Hỏi thăm con người: "Thỉnh thoảng hỏi thăm người dùng của bạn vào ban ngày" thúc đẩy một thông báo ngắn gọn kiểu "bạn có cần gì không?" vào những lúc thích hợp, nhưng tránh gửi dồn dập vào ban đêm bằng cách sử dụng múi giờ địa phương đã cấu hình (xem Múi giờ).

Heartbeat có thể phản ứng với các tác vụ nền đã hoàn tất, nhưng bản thân một lượt chạy Heartbeat không tạo bản ghi tác vụ.

Nếu bạn muốn Heartbeat thực hiện một việc thật cụ thể (ví dụ: "kiểm tra số liệu thống kê Gmail PubSub" hoặc "xác minh tình trạng Gateway"), hãy đặt agents.defaults.heartbeat.prompt (hoặc agents.list[].heartbeat.prompt) thành nội dung tùy chỉnh (được gửi nguyên văn).

Giao ước phản hồi

• Nếu không có gì cần chú ý, hãy trả lời bằng HEARTBEAT_OK.
• Thay vào đó, các lượt chạy Heartbeat có thể gọi heartbeat_respond với notify: false để không hiển thị cập nhật, hoặc notify: true cùng notificationText để gửi cảnh báo. Khi có, phản hồi công cụ có cấu trúc được ưu tiên hơn văn bản dự phòng.
• Trong các lượt chạy Heartbeat, OpenClaw coi HEARTBEAT_OK là xác nhận khi nó xuất hiện ở đầu hoặc cuối câu trả lời. Token này bị loại bỏ và câu trả lời bị loại bỏ nếu nội dung còn lại có độ dài ≤ ackMaxChars (mặc định: 300).
• Nếu HEARTBEAT_OK xuất hiện ở giữa câu trả lời, nó không được xử lý đặc biệt.
• Đối với cảnh báo, không đưa HEARTBEAT_OK vào; chỉ trả về văn bản cảnh báo.

Ngoài các lượt Heartbeat, HEARTBEAT_OK xuất hiện ngoài ý muốn ở đầu/cuối tin nhắn sẽ bị loại bỏ và ghi nhật ký; tin nhắn chỉ chứa HEARTBEAT_OK sẽ bị loại bỏ.

Cấu hình

{  agents: {    defaults: {      heartbeat: {        every: "30m", // mặc định: 30m (0m để tắt)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // mặc định: false (gửi thông báo Thinking riêng khi có)        lightContext: false, // mặc định: false; true chỉ giữ HEARTBEAT.md trong các tệp khởi tạo của không gian làm việc        isolatedSession: false, // mặc định: false; true chạy mỗi Heartbeat trong một phiên mới (không có lịch sử hội thoại)        skipWhenBusy: false, // mặc định: false; true cũng chờ các luồng subagent/lồng nhau của agent này        target: "last", // mặc định: none | tùy chọn: last | none | <id kênh> (lõi hoặc plugin, ví dụ "imessage")        to: "+15551234567", // ghi đè theo kênh, không bắt buộc        accountId: "ops-bot", // id kênh đa tài khoản, không bắt buộc        prompt: "Đọc HEARTBEAT.md nếu tệp tồn tại (ngữ cảnh không gian làm việc). Tuân thủ nghiêm ngặt. Không suy diễn hoặc lặp lại các tác vụ cũ từ những cuộc trò chuyện trước. Nếu không có gì cần chú ý, hãy trả lời HEARTBEAT_OK.",        includeSystemPromptSection: true, // mặc định: true; false bỏ phần lời nhắc hệ thống ## Heartbeats đối với agent mặc định        ackMaxChars: 300, // số ký tự tối đa được phép sau HEARTBEAT_OK      },    },  },}

Phạm vi và thứ tự ưu tiên

• agents.defaults.heartbeat đặt hành vi Heartbeat toàn cục.
• agents.list[].heartbeat được hợp nhất lên trên; nếu bất kỳ agent nào có khối heartbeat, chỉ những agent đó chạy Heartbeat.
• channels.defaults.heartbeat đặt giá trị mặc định về khả năng hiển thị cho tất cả các kênh.
• channels.<channel>.heartbeat ghi đè giá trị mặc định của kênh.
• channels.<channel>.accounts.<id>.heartbeat (các kênh đa tài khoản) ghi đè thiết lập theo từng kênh.

Heartbeat theo từng agent

Nếu bất kỳ mục agents.list[] nào có khối heartbeat, chỉ những agent đó chạy Heartbeat. Khối theo từng agent được hợp nhất lên trên agents.defaults.heartbeat (vì vậy bạn có thể đặt giá trị mặc định dùng chung một lần rồi ghi đè theo từng agent).

Ví dụ: hai agent, chỉ agent thứ hai chạy Heartbeat.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // gửi rõ ràng đến liên hệ gần nhất (mặc định là "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Đọc HEARTBEAT.md nếu tệp tồn tại (ngữ cảnh không gian làm việc). Tuân thủ nghiêm ngặt. Không suy diễn hoặc lặp lại các tác vụ cũ từ những cuộc trò chuyện trước. Nếu không có gì cần chú ý, hãy trả lời HEARTBEAT_OK.",        },      },    ],  },}

Ví dụ về giờ hoạt động

Giới hạn Heartbeat trong giờ làm việc ở một múi giờ cụ thể:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // gửi rõ ràng đến liên hệ gần nhất (mặc định là "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // không bắt buộc; dùng userTimezone nếu đã đặt, nếu không thì dùng múi giờ máy chủ        },      },    },  },}

Ngoài khoảng thời gian này (trước 9 giờ sáng hoặc sau 10 giờ tối theo giờ miền Đông), Heartbeat sẽ bị bỏ qua. Nhịp theo lịch tiếp theo nằm trong khoảng sẽ chạy bình thường.

Thiết lập 24/7

Nếu bạn muốn Heartbeat chạy cả ngày, hãy sử dụng một trong các mẫu sau:

• Bỏ hoàn toàn activeHours (không giới hạn theo khoảng thời gian; đây là hành vi mặc định).
• Đặt khoảng thời gian cả ngày: activeHours: { start: "00:00", end: "24:00" }.

Ví dụ đa tài khoản

Sử dụng accountId để nhắm đến một tài khoản cụ thể trên các kênh đa tài khoản như Telegram:

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // không bắt buộc: định tuyến đến một chủ đề/luồng cụ thể          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

Ghi chú về trường

Hành vi gửi

Điều khiển khả năng hiển thị

Theo mặc định, các xác nhận HEARTBEAT_OK bị ẩn trong khi nội dung cảnh báo được gửi. Bạn có thể điều chỉnh theo từng kênh hoặc từng tài khoản:

channels:  defaults:    heartbeat:      showOk: false # Ẩn HEARTBEAT_OK (mặc định)      showAlerts: true # Hiển thị thông báo cảnh báo (mặc định)      useIndicator: true # Phát sự kiện chỉ báo (mặc định)  telegram:    heartbeat:      showOk: true # Hiển thị xác nhận OK trên Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Chặn gửi cảnh báo cho tài khoản này

Thứ tự ưu tiên: theo tài khoản → theo kênh → giá trị mặc định của kênh → giá trị mặc định tích hợp sẵn.

Chức năng của từng cờ

• showOk: gửi xác nhận HEARTBEAT_OK khi mô hình trả về phản hồi chỉ có OK.
• showAlerts: gửi nội dung cảnh báo khi mô hình trả về phản hồi không phải OK.
• useIndicator: phát các sự kiện chỉ báo cho các bề mặt trạng thái giao diện người dùng.

Nếu cả ba đều là false, OpenClaw bỏ qua hoàn toàn lượt Heartbeat (không gọi mô hình).

Ví dụ theo kênh và theo tài khoản

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # tất cả tài khoản Slack    accounts:      ops:        heartbeat:          showAlerts: false # chỉ chặn cảnh báo cho tài khoản ops  telegram:    heartbeat:      showOk: true

Các mẫu phổ biến

HEARTBEAT.md (tùy chọn)

Nếu có tệp HEARTBEAT.md trong không gian làm việc, lời nhắc mặc định sẽ yêu cầu tác tử đọc tệp đó. Hãy coi đây là "danh sách kiểm tra Heartbeat" của bạn: ngắn gọn, ổn định và an toàn để xem xét mỗi 30 phút.

Trong các lượt chạy thông thường, HEARTBEAT.md chỉ được chèn khi hướng dẫn Heartbeat được bật cho tác tử mặc định. Việc tắt nhịp Heartbeat bằng 0m hoặc đặt includeSystemPromptSection: false sẽ loại bỏ tệp này khỏi ngữ cảnh khởi tạo thông thường.

Trên bộ khung Codex gốc, nội dung HEARTBEAT.md không được chèn vào lượt như các tệp khởi tạo khác. Nếu tệp tồn tại và có nội dung không chỉ gồm khoảng trắng, một ghi chú về chế độ cộng tác Heartbeat sẽ trỏ Codex đến tệp và yêu cầu đọc tệp trước khi tiếp tục.

Nếu HEARTBEAT.md tồn tại nhưng thực tế trống (chỉ có dòng trống, chú thích Markdown/HTML, tiêu đề Markdown như # Heading, dấu phân cách khối mã hoặc mục danh sách kiểm tra trống), OpenClaw sẽ bỏ qua lượt Heartbeat để tiết kiệm lượt gọi API. Việc bỏ qua này được báo cáo là reason=empty-heartbeat-file. Nếu thiếu tệp, Heartbeat vẫn chạy và mô hình quyết định việc cần làm.

Hãy giữ tệp thật ngắn (danh sách kiểm tra hoặc lời nhắc ngắn) để tránh làm lời nhắc phình to.

Ví dụ về HEARTBEAT.md:

# Danh sách kiểm tra Heartbeat - Xem nhanh: có gì khẩn cấp trong hộp thư đến không?- Nếu đang là ban ngày và không có gì khác đang chờ xử lý, hãy kiểm tra tình hình ở mức nhẹ.- Nếu một tác vụ bị chặn, hãy ghi lại _đang thiếu điều gì_ và hỏi Peter vào lần tới.

Các khối tasks:

HEARTBEAT.md cũng hỗ trợ một khối tasks: có cấu trúc nhỏ cho các lượt kiểm tra theo khoảng thời gian ngay trong Heartbeat.

Ví dụ:

tasks: - name: inbox-triage  interval: 30m  prompt: "Kiểm tra email khẩn cấp chưa đọc và đánh dấu mọi nội dung nhạy cảm về thời gian."- name: calendar-scan  interval: 2h  prompt: "Kiểm tra các cuộc họp sắp tới cần chuẩn bị hoặc theo dõi." # Hướng dẫn bổ sung - Giữ cảnh báo ngắn gọn.- Nếu không có gì cần chú ý sau khi hoàn tất tất cả tác vụ đến hạn, hãy trả lời HEARTBEAT_OK.

Chế độ tác vụ hữu ích khi bạn muốn một tệp Heartbeat chứa nhiều lượt kiểm tra định kỳ mà không phải trả chi phí cho tất cả chúng ở mỗi nhịp.

Tác tử có thể cập nhật HEARTBEAT.md không?

Có - nếu bạn yêu cầu.

HEARTBEAT.md chỉ là một tệp thông thường trong không gian làm việc của tác tử, vì vậy bạn có thể nói với tác tử (trong một cuộc trò chuyện thông thường) nội dung như:

• "Cập nhật HEARTBEAT.md để thêm lượt kiểm tra lịch hằng ngày."
• "Viết lại HEARTBEAT.md để ngắn gọn hơn và tập trung vào việc theo dõi hộp thư đến."

Nếu muốn việc này diễn ra chủ động, bạn cũng có thể thêm một dòng rõ ràng vào lời nhắc Heartbeat, chẳng hạn: "Nếu danh sách kiểm tra trở nên lỗi thời, hãy cập nhật HEARTBEAT.md bằng một danh sách tốt hơn."

Đánh thức thủ công (theo yêu cầu)

Dùng openclaw system event để xếp một sự kiện hệ thống vào hàng đợi và tùy chọn kích hoạt Heartbeat ngay lập tức:

openclaw system event --text "Kiểm tra các việc khẩn cấp cần theo dõi" --mode now

Nếu không cung cấp --session-key và nhiều tác tử đã cấu hình heartbeat, --mode now sẽ chạy ngay Heartbeat của từng tác tử đó.

Các điều khiển Heartbeat liên quan trong cùng nhóm CLI:

openclaw system heartbeat last     # hiển thị sự kiện Heartbeat gần nhấtopenclaw system heartbeat enable   # bật Heartbeatopenclaw system heartbeat disable  # tắt Heartbeat

Gửi nội dung suy luận (tùy chọn)

Theo mặc định, Heartbeat chỉ gửi phần tải trọng "câu trả lời" cuối cùng.

Nếu bạn muốn tính minh bạch, hãy bật:

• agents.defaults.heartbeat.includeReasoning: true

Khi được bật, Heartbeat cũng sẽ gửi một thông báo riêng có tiền tố Thinking (cùng định dạng với /reasoning on). Điều này có thể hữu ích khi tác nhân đang quản lý nhiều phiên/codex và bạn muốn biết lý do tác nhân quyết định nhắn cho bạn — nhưng nó cũng có thể làm lộ nhiều chi tiết nội bộ hơn mong muốn. Nên tắt tính năng này trong các cuộc trò chuyện nhóm.

Lưu ý về chi phí

Heartbeat chạy toàn bộ lượt của tác nhân. Khoảng thời gian ngắn hơn sẽ tiêu tốn nhiều token hơn. Để giảm chi phí:

• Dùng isolatedSession: true để tránh gửi toàn bộ lịch sử hội thoại (giảm từ khoảng 100 nghìn token xuống khoảng 2–5 nghìn token mỗi lần chạy).
• Dùng lightContext: true để giới hạn các tệp khởi tạo chỉ còn HEARTBEAT.md.
• Đặt model có chi phí thấp hơn (ví dụ: ollama/llama3.2:1b).
• Giữ HEARTBEAT.md ngắn gọn.
• Dùng target: "none" nếu bạn chỉ muốn cập nhật trạng thái nội bộ.

Tràn ngữ cảnh sau Heartbeat

Sau khi lượt chạy hoàn tất, Heartbeat giữ nguyên mô hình thời gian chạy hiện có của phiên dùng chung. Vì vậy, một Heartbeat đã chuyển phiên sang mô hình cục bộ nhỏ hơn (ví dụ: mô hình Ollama có cửa sổ ngữ cảnh 32k) có thể khiến mô hình đó tiếp tục được dùng cho lượt tiếp theo của phiên chính. Nếu lượt tiếp theo báo tràn ngữ cảnh và mô hình thời gian chạy gần nhất của phiên khớp với heartbeat.model đã cấu hình, thông báo khôi phục của OpenClaw sẽ chỉ ra rằng việc mô hình Heartbeat ảnh hưởng sang phiên chính có thể là nguyên nhân và đề xuất cách khắc phục.

Để tránh điều này: dùng isolatedSession: true để chạy Heartbeat trong một phiên mới (có thể kết hợp với lightContext: true để có lời nhắc nhỏ nhất), hoặc chọn mô hình Heartbeat có cửa sổ ngữ cảnh đủ lớn cho phiên dùng chung.

Liên quan

• Tự động hóa - tổng quan nhanh về tất cả cơ chế tự động hóa
• Tác vụ nền - cách theo dõi công việc tách rời
• Múi giờ - cách múi giờ ảnh hưởng đến lịch Heartbeat
• Khắc phục sự cố - gỡ lỗi các vấn đề tự động hóa