Heartbeat hay cron? Xem Tự động hóa để biết hướng dẫn về thời điểm sử dụng từng loại.
Bắt đầu nhanh (người mới)
1
Chọn nhịp chạy
Giữ Heartbeat được bật (mặc định là
30m, hoặc 1h khi xác thực OAuth/token của Anthropic được cấu hình, bao gồm cả việc tái sử dụng Claude CLI) hoặc đặt nhịp chạy riêng.2
Thêm HEARTBEAT.md (không bắt buộc)
Tạo một danh sách kiểm tra
HEARTBEAT.md ngắn hoặc khối tasks: trong không gian làm việc của tác nhân.3
Quyết định nơi gửi thông báo Heartbeat
target: "none" là giá trị mặc định; đặt target: "last" để định tuyến đến liên hệ gần nhất.4
Tinh chỉnh không bắt buộc
- Bật gửi nội dung suy luận của Heartbeat để đảm bảo tính minh bạch.
- Sử dụng ngữ cảnh khởi tạo gọn nhẹ nếu các lượt chạy Heartbeat chỉ cần
HEARTBEAT.md. - Bật phiên cô lập để tránh gửi toàn bộ lịch sử hội thoại trong mỗi Heartbeat.
- Giới hạn Heartbeat trong giờ hoạt động (giờ địa phươ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 giá trị này lên1hkhi 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ỉ khiheartbeat.everychưa được đặt. Đặtagents.defaults.heartbeat.everyhoặcagents.list[].heartbeat.everytheo từng tác nhân; dùng0mđể tắt. - Nội dung lời nhắc (có thể cấu hình qua
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. - Thời gian chờ: các lượt Heartbeat chưa đặt giá trị sẽ dùng
agents.defaults.timeoutSecondskhi giá trị này được đặt. Nếu không, chúng dùng nhịp Heartbeat, tối đa 600 giây. Đặtagents.defaults.heartbeat.timeoutSecondshoặcagents.list[].heartbeat.timeoutSecondstheo từng tác nhân cho công việc Heartbeat dài hơn. - Lời nhắc Heartbeat được gửi nguyên văn dưới dạng thông báo 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 tác nhân mặc định (và
includeSystemPromptSectionkhông phải làfalse), đồng thời lượt chạy được gắn cờ nội bộ. - Khi Heartbeat bị tắt bằng
0m, các lượt chạy thông thường cũng loạiHEARTBEAT.mdkhỏ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 khung giờ đó, Heartbeat bị bỏ qua cho đến nhịp tiếp theo nằm trong khung giờ. - Heartbeat tự động trì hoãn khi công việc cron đang hoạt động hoặc đang xếp hàng. Đặt
heartbeat.skipWhenBusy: trueđể cũng trì hoãn một tác nhân khi tác nhân phụ theo khóa phiên hoặc luồng lệnh lồng nhau của chính nó đang chạy; các tác nhân ngang hàng không còn tạm dừng chỉ vì một tác nhân khác đang có công việc tác nhân phụ đang chạy.
Mục đích của lời nhắc Heartbeat
Lời nhắc mặc định được thiết kế rộng:- Tác vụ nền: “Xem xét các tác vụ chưa hoàn thành” nhắc tác nhân 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 đang xếp hàng) và nêu ra mọi nội dung khẩn cấp.
- Hỏi thăm người dùng: “Thỉnh thoảng hỏi thăm người dùng vào ban ngày” khuyến khích thỉnh thoảng gửi một thông báo ngắn như “bạn có cần gì không?”, nhưng tránh gửi quá nhiều 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ờ).
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).
Hợp đồng phản hồi
- Nếu không có gì cần chú ý, hãy phản hồi bằng
HEARTBEAT_OK. - Thay vào đó, lượt chạy Heartbeat có thể gọi
heartbeat_respondvớinotify: falsekhi không có cập nhật hiển thị, hoặcnotify: truecùngnotificationTextđể 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. - Kết quả
heartbeat_respondcó ý nghĩa vớinotify: falsevẫn không hiển thị nhưng được ghi nhớ dưới dạng ngữ cảnh nội bộ có giới hạn cho lượt người dùng tiếp theo trong phiên đó. Các xác nhậnno_changevà thông báo hiển thị không được lưu theo cách này. - Trong lượt chạy Heartbeat, OpenClaw coi
HEARTBEAT_OKlà xác nhận khi nó xuất hiện ở đầu hoặc cuối phản hồi. Token bị loại bỏ và phản hồi bị bỏ nếu nội dung còn lại ≤ackMaxChars(mặc định: 300). - Nếu
HEARTBEAT_OKxuất hiện ở giữa phản hồi, nó không được xử lý đặc biệt. - Đối với cảnh báo, không bao gồm
HEARTBEAT_OK; chỉ trả về văn bản cảnh báo.
HEARTBEAT_OK không đúng chỗ ở đầu/cuối thông báo sẽ bị loại bỏ và ghi nhật ký; thông báo chỉ chứa HEARTBEAT_OK sẽ bị bỏ.
Cấu hình
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ỳ tác nhân nào có khốiheartbeat, chỉ những tác nhân đó 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>.heartbeatghi đè giá trị mặc định của kênh.channels.<channel>.accounts.<id>.heartbeat(kênh nhiều tài khoản) ghi đè cài đặt theo từng kênh.
Heartbeat theo từng tác nhân
Nếu bất kỳ mụcagents.list[] nào chứa khối heartbeat, chỉ những tác nhân đó chạy Heartbeat. Khối theo từng tác nhân được hợp nhất lên trên agents.defaults.heartbeat (vì vậy có thể đặt các giá trị mặc định dùng chung một lần và ghi đè theo từng tác nhân).
Ví dụ: hai tác nhân, chỉ tác nhân thứ hai chạy Heartbeat.
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ể:Thiết lập 24/7
Nếu 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 có giới hạn khung giờ; đây là hành vi mặc định). - Đặt khung giờ cả ngày:
activeHours: { start: "00:00", end: "24:00" }.
Ví dụ về nhiều tài khoản
Sử dụngaccountId để nhắm đến một tài khoản cụ thể trên các kênh nhiều tài khoản như Telegram:
Ghi chú về trường
Khoảng thời gian Heartbeat (chuỗi thời lượng; đơn vị mặc định = phút).
Ghi đè mô hình không bắt buộc cho các lượt chạy Heartbeat (
provider/model).Khi bật, cũng gửi thông báo
Thinking riêng khi có (cùng cấu trúc với /reasoning on).Khi là true, các lượt chạy Heartbeat sử dụng ngữ cảnh khởi tạo gọn nhẹ và chỉ giữ
HEARTBEAT.md từ các tệp khởi tạo của không gian làm việc.Khi là true, mỗi Heartbeat chạy trong một phiên mới không có lịch sử hội thoại trước đó. Sử dụng cùng mẫu cô lập như cron
sessionTarget: "isolated". Giảm đáng kể chi phí token cho mỗi Heartbeat. Kết hợp với lightContext: true để tiết kiệm tối đa. Việc định tuyến gửi vẫn sử dụng ngữ cảnh phiên chính.Khi là true, các lượt chạy Heartbeat trì hoãn trên các luồng bận bổ sung của tác nhân đó: tác nhân phụ theo khóa phiên hoặc công việc lệnh lồng nhau của chính nó. Các luồng cron luôn trì hoãn Heartbeat ngay cả khi không có cờ này, để các máy chủ mô hình cục bộ không chạy đồng thời lời nhắc cron và Heartbeat.
last: gửi đến kênh bên ngoài được sử dụng gần nhất.- kênh cụ thể: bất kỳ kênh hoặc id plugin nào đã được cấu hình, ví dụ
discord,matrix,telegramhoặcwhatsapp. none(mặc định): chạy heartbeat nhưng không gửi ra bên ngoài.
Kiểm soát hành vi gửi trực tiếp/DM.
allow: cho phép gửi heartbeat trực tiếp/qua DM. block: chặn gửi trực tiếp/qua DM (reason=dm-blocked).Tùy chọn ghi đè người nhận (id dành riêng cho kênh, ví dụ E.164 cho WhatsApp hoặc id cuộc trò chuyện Telegram). Đối với chủ đề/luồng Telegram, hãy dùng
<chatId>:topic:<messageThreadId>.Id tài khoản tùy chọn cho các kênh nhiều tài khoản. Khi
target: "last", id tài khoản áp dụng cho kênh gần nhất đã phân giải nếu kênh đó hỗ trợ tài khoản; nếu không, id này bị bỏ qua. Nếu id tài khoản không khớp với tài khoản đã cấu hình cho kênh được phân giải, việc gửi sẽ bị bỏ qua.Ghi đè nội dung prompt mặc định (không hợp nhất).
Xác định có chèn phần system prompt
## Heartbeats của agent mặc định hay không. Đặt false để duy trì hành vi runtime của heartbeat (nhịp chạy, gửi, HEARTBEAT.md) nhưng loại bỏ hướng dẫn heartbeat khỏi system prompt của agent.Số ký tự tối đa được phép sau
HEARTBEAT_OK trước khi gửi.Khi là true, chặn các payload cảnh báo lỗi công cụ trong khi chạy heartbeat.
Số giây tối đa cho phép đối với một lượt agent heartbeat trước khi bị hủy. Để trống để dùng
agents.defaults.timeoutSeconds khi giá trị này được đặt; nếu không, dùng nhịp heartbeat với giới hạn tối đa 600 giây.Giới hạn các lần chạy heartbeat trong một khoảng thời gian. Đối tượng gồm
start (HH:MM, tính cả thời điểm này; dùng 00:00 cho đầu ngày), end (HH:MM, không tính thời điểm này; cho phép 24:00 cho cuối ngày) và timezone tùy chọn.- Nếu bỏ qua hoặc là
"user": dùngagents.defaults.userTimezonecủa bạn nếu đã đặt; nếu không, dùng múi giờ của hệ thống máy chủ. "local": luôn dùng múi giờ của hệ thống máy chủ.- Bất kỳ mã định danh IANA nào (ví dụ
America/New_York): được dùng trực tiếp; nếu không hợp lệ, quay về hành vi"user"nêu trên. startvàendkhông được bằng nhau đối với một khoảng hoạt động; các giá trị bằng nhau được coi là khoảng có độ rộng bằng 0 (luôn nằm ngoài khoảng).- Ngoài khoảng hoạt động, heartbeat bị bỏ qua cho đến nhịp tiếp theo nằm trong khoảng.
Hành vi gửi
Định tuyến phiên và đích
Định tuyến phiên và đích
- Theo mặc định, heartbeat chạy trong phiên chính của agent (
agent:<id>:<mainKey>), hoặcglobalkhisession.scope = "global". Đặtsessionđể ghi đè sang một phiên kênh cụ thể (Discord/WhatsApp/v.v.). sessionchỉ ảnh hưởng đến ngữ cảnh chạy; việc gửi được kiểm soát bởitargetvàto.- Để gửi đến một kênh/người nhận cụ thể, hãy đặt
target+to. Vớitarget: "last", việc gửi dùng kênh bên ngoài gần nhất của phiên đó. - Theo mặc định, việc gửi heartbeat cho phép các đích trực tiếp/DM. Đặt
directPolicy: "block"để chặn gửi đến đích trực tiếp nhưng vẫn chạy lượt heartbeat. - Nếu hàng đợi chính, lane phiên đích, lane cron hoặc một tác vụ cron đang hoạt động bị bận, heartbeat sẽ bị bỏ qua và được thử lại sau.
- Nếu
skipWhenBusy: true, các lane subagent được định danh theo phiên và lane lồng nhau của agent này cũng trì hoãn việc chạy heartbeat. Các lane đang bận của agent khác không trì hoãn agent này. - Nếu
targetkhông phân giải được đích bên ngoài nào, lượt chạy vẫn diễn ra nhưng không có tin nhắn đi nào được gửi.
Khả năng hiển thị và hành vi bỏ qua
Khả năng hiển thị và hành vi bỏ qua
- Nếu
showOk,showAlertsvàuseIndicatorđều bị tắt, lượt chạy sẽ bị bỏ qua ngay từ đầu dưới dạngreason=alerts-disabled. - Nếu chỉ tắt việc gửi cảnh báo, OpenClaw vẫn có thể chạy heartbeat, cập nhật dấu thời gian của các tác vụ đến hạn, khôi phục dấu thời gian phiên chuyển sang trạng thái nhàn rỗi và chặn payload cảnh báo gửi ra ngoài.
- Nếu đích heartbeat được phân giải hỗ trợ trạng thái đang nhập, OpenClaw sẽ hiển thị trạng thái này trong khi lượt heartbeat đang hoạt động. Tính năng này dùng cùng đích mà heartbeat sẽ gửi đầu ra trò chuyện tới và bị vô hiệu hóa bởi
typingMode: "never".
Vòng đời phiên và kiểm toán
Vòng đời phiên và kiểm toán
- Các phản hồi chỉ dành cho heartbeat không duy trì phiên hoạt động. Siêu dữ liệu heartbeat có thể cập nhật hàng của phiên, nhưng thời điểm hết hạn do không hoạt động dùng
lastInteractionAttừ tin nhắn thực gần nhất của người dùng/kênh, còn thời điểm hết hạn hằng ngày dùngsessionStartedAt. - Lịch sử trong Control UI và WebChat ẩn các prompt heartbeat và xác nhận chỉ chứa OK. Bản ghi phiên cơ sở vẫn có thể chứa các lượt đó để kiểm toán/phát lại.
- Các tác vụ nền tách rời có thể đưa một sự kiện hệ thống vào hàng đợi và đánh thức heartbeat khi phiên chính cần nhanh chóng nhận biết điều gì đó. Việc đánh thức này không biến lượt chạy heartbeat thành tác vụ nền.
Kiểm soát khả năng hiển thị
Theo mặc định, các xác nhậnHEARTBEAT_OK bị chặn trong khi nội dung cảnh báo vẫn được gửi. Bạn có thể điều chỉnh theo từng kênh hoặc từng tài khoản:
Chức năng của từng cờ
showOk: gửi xác nhậnHEARTBEAT_OKkhi mô hình trả về phản hồi chỉ chứa 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 những bề mặt trạng thái UI.
Ví dụ theo kênh và theo tài khoản
Mẫu phổ biến
HEARTBEAT.md (tùy chọn)
Nếu tệpHEARTBEAT.md tồn tại trong workspace, prompt mặc định sẽ yêu cầu agent đọc tệp đó. Hãy xem đâ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 sau 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 agent mặc định. Việc vô hiệu hóa nhịp heartbeat bằng 0m hoặc đặt includeSystemPromptSection: false sẽ loại bỏ nó khỏi ngữ cảnh bootstrap thông thường.
Trên harness Codex gốc, nội dung HEARTBEAT.md không được chèn vào lượt chạy như các tệp bootstrap 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ẽ hướng Codex đến tệp và yêu cầu Codex đọ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 chạy heartbeat để tiết kiệm lệnh gọi API. Việc bỏ qua đó được báo cáo dưới dạng reason=empty-heartbeat-file. Nếu tệp không tồn tại, 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 ngắn hoặc lời nhắc) để tránh prompt phình to.
Ví dụ HEARTBEAT.md:
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ụ:
Hành vi
Hành vi
- OpenClaw phân tích khối
tasks:và kiểm tra từng tác vụ theointervalriêng của tác vụ đó. - Chỉ các tác vụ đến hạn mới được đưa vào prompt heartbeat cho nhịp đó.
- Nếu không có tác vụ nào đến hạn, heartbeat sẽ bị bỏ qua hoàn toàn (
reason=no-tasks-due) để tránh lãng phí một lệnh gọi mô hình. - Nội dung không phải tác vụ trong
HEARTBEAT.mdđược giữ nguyên và nối thêm làm ngữ cảnh bổ sung sau danh sách tác vụ đến hạn. - Dấu thời gian chạy gần nhất của tác vụ được lưu trong trạng thái phiên (
heartbeatTaskState), vì vậy các khoảng thời gian vẫn được duy trì sau những lần khởi động lại thông thường. - Dấu thời gian của tác vụ chỉ được cập nhật sau khi lượt chạy heartbeat hoàn tất quy trình phản hồi thông thường. Các lượt chạy
empty-heartbeat-file/no-tasks-duebị bỏ qua không đánh dấu tác vụ là đã hoàn thành.
Agent 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 workspace của agent, vì vậy bạn có thể nói với agent (trong cuộc trò chuyện thông thường) những câu 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.”
Đánh thức thủ công (theo yêu cầu)
Dùngopenclaw system event để đưa 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:
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:
Gửi nội dung suy luận (tùy chọn)
Theo mặc định, Heartbeat chỉ gửi tải trọng “câu trả lời” cuối cùng. Nếu muốn có tính minh bạch, hãy bật:agents.defaults.heartbeat.includeReasoning: true
Thinking (cùng định dạng với /reasoning on). Điều này có thể hữu ích khi tác tử đang quản lý nhiều phiên/codex và bạn muốn biết lý do tác tử quyết định nhắn cho bạn — nhưng cũng có thể làm lộ nhiều chi tiết nội bộ hơn mong muốn. Nên giữ tùy chọn này ở trạng thái tắt trong các cuộc trò chuyện nhóm.
Lưu ý về chi phí
Heartbeat chạy các lượt tác tử đầy đủ. Khoảng thời gian ngắn hơn tiêu tốn nhiều token hơn. Để giảm chi phí:- Sử dụng
isolatedSession: trueđể tránh gửi toàn bộ lịch sử hội thoại (từ khoảng 100K token xuống còn khoảng 2-5K mỗi lần chạy). - Sử dụng
lightContext: trueđể giới hạn các tệp khởi động chỉ cònHEARTBEAT.md. - Đặt
modeltiết kiệm hơn (ví dụ:ollama/llama3.2:1b). - Giữ
HEARTBEAT.mdở mức nhỏ. - Sử 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
Heartbeat duy trì mô hình thời gian chạy hiện có của phiên dùng chung sau khi lượt chạy hoàn tất, 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ổ 32k) có thể để 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ớiheartbeat.model đã cấu hình, thông báo khôi phục của OpenClaw sẽ nêu việc mô hình Heartbeat ảnh hưởng sang phiên chính là nguyên nhân có khả năng xảy ra và đề xuất cách khắc phục.
Để tránh điều này: sử 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ó prompt 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 chạy tách biệt
- 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