​

Kiểm tra định kỳ (Gateway)

Kiểm tra định kỳ hay Cron? Xem Cron vs Kiểm tra định kỳ để biết khi nào nên sử dụng từng loại.

​

Bắt đầu nhanh (dành cho người mới)

1. Giữ kiểm tra định kỳ được bật (mặc định là 30m, hoặc 1h cho Anthropic OAuth/setup-token) hoặc đặt tần suất riêng.
2. Tạo một danh sách kiểm tra nhỏ HEARTBEAT.md trong không gian làm việc của tác vụ (không bắt buộc nhưng nên làm).
3. Quyết định nơi thông điệp kiểm tra định kỳ sẽ được gửi (target: "none" là mặc định; đặt target: "last" để gửi đến liên hệ cuối cùng).
4. Tùy chọn: bật tính năng gửi lý do kiểm tra định kỳ để minh bạch.
5. Tùy chọn: sử dụng ngữ cảnh khởi động nhẹ nếu kiểm tra định kỳ chỉ cần HEARTBEAT.md.
6. Tùy chọn: bật các phiên cách ly để tránh gửi toàn bộ lịch sử hội thoại mỗi lần kiểm tra định kỳ.
7. Tùy chọn: giới hạn kiểm tra định kỳ trong giờ hoạt động (giờ địa phương).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // gửi rõ ràng đến liên hệ cuối cùng (mặc định là "none")
        directPolicy: "allow", // mặc định: cho phép gửi trực tiếp/DM; đặt "block" để chặn
        lightContext: true, // tùy chọn: chỉ chèn HEARTBEAT.md từ các tệp khởi động
        isolatedSession: true, // tùy chọn: phiên mới mỗi lần chạy (không có lịch sử hội thoại)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // tùy chọn: gửi thêm thông điệp `Reasoning:`
      },
    },
  },
}

​

Mặc định

• Khoảng thời gian: 30m (hoặc 1h khi phát hiện chế độ xác thực Anthropic OAuth/setup-token). Đặt agents.defaults.heartbeat.every hoặc cho từng tác vụ agents.list[].heartbeat.every; sử dụng 0m để tắt.
• Nội dung nhắc nhở (có thể cấu hình qua agents.defaults.heartbeat.prompt): Đọc HEARTBEAT.md nếu có (ngữ cảnh không gian làm việc). Thực hiện nghiêm ngặt. Không suy diễn hoặc lặp lại các tác vụ cũ từ các cuộc trò chuyện trước. Nếu không có gì cần chú ý, trả lời HEARTBEAT_OK.
• Lời nhắc kiểm tra định kỳ được gửi nguyên văn như thông điệp của người dùng. Lời nhắc hệ thống bao gồm phần “Kiểm tra định kỳ” và lượt chạy được đánh dấu nội bộ.
• Giờ hoạt động (heartbeat.activeHours) được kiểm tra theo múi giờ đã cấu hình. Ngoài khung giờ này, kiểm tra định kỳ bị bỏ qua cho đến lần chạy tiếp theo trong khung giờ.

​

Mục đích của lời nhắc kiểm tra định kỳ

• Tác vụ nền: “Xem xét các tác vụ còn lại” nhắc nhở tác vụ xem xét các công việc tiếp theo (hộp thư đến, lịch, nhắc nhở, công việc xếp hàng) và hiển thị bất kỳ điều gì khẩn cấp.
• Kiểm tra con người: “Thỉnh thoảng kiểm tra con người của bạn trong giờ làm việc” nhắc nhở một thông điệp nhẹ nhàng “có cần gì không?”, nhưng tránh gửi vào ban đêm bằng cách sử dụng múi giờ địa phương đã cấu hình (xem /concepts/timezone).

​

Hợp đồng phản hồi

• Nếu không có gì cần chú ý, trả lời với HEARTBEAT_OK.
• Trong các lần chạy kiểm tra định kỳ, OpenClaw coi HEARTBEAT_OK là một xác nhận khi nó xuất hiện ở đầu hoặc cuối của phản hồi. Token này bị loại bỏ và phản hồi bị loại bỏ nếu nội dung còn lại ≤ ackMaxChars (mặc định: 300).
• Nếu HEARTBEAT_OK xuấ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.

​

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 điệp Reasoning: riêng khi có)
        lightContext: false, // mặc định: false; true chỉ giữ lại HEARTBEAT.md từ các tệp khởi động không gian làm việc
        isolatedSession: false, // mặc định: false; true chạy mỗi lần kiểm tra định kỳ trong một phiên mới (không có lịch sử hội thoại)
        target: "last", // mặc định: none | tùy chọn: last | none | <channel id> (core hoặc plugin, ví dụ: "bluebubbles")
        to: "+15551234567", // tùy chọn ghi đè kênh cụ thể
        accountId: "ops-bot", // tùy chọn id kênh đa tài khoản
        prompt: "Đọc HEARTBEAT.md nếu có (ngữ cảnh không gian làm việc). Thực hiện nghiêm ngặt. Không suy diễn hoặc lặp lại các tác vụ cũ từ các cuộc trò chuyện trước. Nếu không có gì cần chú ý, trả lời HEARTBEAT_OK.",
        ackMaxChars: 300, // số ký tự tối đa cho phép sau HEARTBEAT_OK
      },
    },
  },
}

​

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

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

​

Kiểm tra định kỳ theo tác vụ

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

​

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

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

​

Cài đặt 24/7

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

​

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

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // tùy chọn: gửi đến một chủ đề/cuộc trò chuyện cụ thể
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Ghi chú trường

• every: khoảng thời gian kiểm tra định kỳ (chuỗi thời lượng; đơn vị mặc định = phút).
• model: ghi đè mô hình tùy chọn cho các lần chạy kiểm tra định kỳ (provider/model).
• includeReasoning: khi bật, cũng gửi thông điệp Reasoning: riêng khi có (cùng hình dạng với /reasoning on).
• lightContext: khi true, các lần chạy kiểm tra định kỳ sử dụng ngữ cảnh khởi động nhẹ và chỉ giữ lại HEARTBEAT.md từ các tệp khởi động không gian làm việc.
• isolatedSession: khi true, mỗi lần kiểm tra định kỳ 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ột mẫu cách ly như cron sessionTarget: "isolated". Giảm đáng kể chi phí token cho mỗi lần kiểm tra định kỳ. Kết hợp với lightContext: true để tiết kiệm tối đa. Định tuyến gửi vẫn sử dụng ngữ cảnh phiên chính.
• session: khóa phiên tùy chọn cho các lần chạy kiểm tra định kỳ.
  • main (mặc định): phiên chính của tác vụ.
  • Khóa phiên rõ ràng (sao chép từ openclaw sessions --json hoặc sessions CLI).
  • Định dạng khóa phiên: xem Sessions và Groups.
• target:
  • last: gửi đến kênh bên ngoài được sử dụng cuối cùng.
  • kênh rõ ràng: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none (mặc định): chạy kiểm tra định kỳ nhưng không gửi ra bên ngoài.
• directPolicy: kiểm soát hành vi gửi trực tiếp/DM:
  • allow (mặc định): cho phép gửi trực tiếp/DM kiểm tra định kỳ.
  • block: chặn gửi trực tiếp/DM (reason=dm-blocked).
• to: ghi đè người nhận tùy chọn (id kênh cụ thể, ví dụ E.164 cho WhatsApp hoặc id cuộc trò chuyện Telegram). Đối với chủ đề/cuộc trò chuyện Telegram, sử dụng <chatId>:topic:<messageThreadId>.
• accountId: id tài khoản tùy chọn cho các kênh đa tài khoản. Khi target: "last", id tài khoản áp dụng cho kênh cuối cùng đã giải quyết nếu nó hỗ trợ tài khoản; nếu không thì 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 đã giải quyết, việc gửi bị bỏ qua.
• prompt: ghi đè nội dung nhắc nhở mặc định (không hợp nhất).
• ackMaxChars: số ký tự tối đa cho phép sau HEARTBEAT_OK trước khi gửi.
• suppressToolErrorWarnings: khi true, chặn các cảnh báo lỗi công cụ trong các lần chạy kiểm tra định kỳ.
• activeHours: giới hạn các lần chạy kiểm tra định kỳ trong một khung giờ. Đối tượng với start (HH:MM, bao gồm; sử dụng 00:00 cho đầu ngày), end (HH:MM không bao gồm; 24:00 cho phép cho cuối ngày), và timezone tùy chọn.
  • Bỏ qua hoặc "user": sử dụng agents.defaults.userTimezone của bạn nếu đã đặt, nếu không thì sử dụng múi giờ hệ thống máy chủ.
  • "local": luôn sử dụng múi giờ hệ thống máy chủ.
  • Bất kỳ định danh IANA nào (ví dụ America/New_York): sử dụng trực tiếp; nếu không hợp lệ, sử dụng hành vi "user" ở trên.
  • start và end không được bằng nhau cho một khung giờ hoạt động; các giá trị bằng nhau được coi là không có độ rộng (luôn ngoài khung giờ).
  • Ngoài khung giờ hoạt động, các lần kiểm tra định kỳ bị bỏ qua cho đến lần chạy tiếp theo trong khung giờ.

​

Hành vi gửi

• Kiểm tra định kỳ chạy trong phiên chính của tác vụ theo mặc định (agent:<id>:<mainKey>), hoặc global khi session.scope = "global". Đặt session để ghi đè sang một phiên kênh cụ thể (Discord/WhatsApp/v.v.).
• session chỉ ảnh hưởng đến ngữ cảnh chạy; việc gửi được kiểm soát bởi target và to.
• Để gửi đến một kênh/người nhận cụ thể, đặt target + to. Với target: "last", việc gửi sử dụng kênh bên ngoài cuối cùng cho phiên đó.
• Việc gửi kiểm tra định kỳ cho phép các mục tiêu trực tiếp/DM theo mặc định. Đặt directPolicy: "block" để chặn gửi đến mục tiêu trực tiếp trong khi vẫn chạy lượt kiểm tra định kỳ.
• Nếu hàng đợi chính bận, kiểm tra định kỳ bị bỏ qua và thử lại sau.
• Nếu target không giải quyết được đến đích bên ngoài, lượt chạy vẫn diễn ra nhưng không có thông điệp gửi ra ngoài.
• Các phản hồi chỉ kiểm tra định kỳ không giữ phiên hoạt động; updatedAt cuối cùng được khôi phục để hết hạn không hoạt động hoạt động bình thường.

​

Kiểm soát khả năng hiển thị

channels:
  defaults:
    heartbeat:
      showOk: false # Ẩn HEARTBEAT_OK (mặc định)
      showAlerts: true # Hiển thị thông điệp cảnh báo (mặc định)
      useIndicator: true # Phát ra 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

​

Tác dụ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ỉ OK.
• showAlerts: gửi nội dung cảnh báo khi mô hình trả về phản hồi không OK.
• useIndicator: phát ra sự kiện chỉ báo cho các bề mặt trạng thái giao diện người dùng.

​

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

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

​

Mẫu phổ biến

​

HEARTBEAT.md (không bắt buộc)

# Danh sách kiểm tra định kỳ

- Quét nhanh: có gì khẩn cấp trong hộp thư đến không?
- Nếu là ban ngày, thực hiện kiểm tra nhẹ nhàng nếu không có gì khác đang chờ.
- Nếu một tác vụ bị chặn, ghi lại _những gì còn thiếu_ và hỏi Peter lần sau.

​

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

• “Cập nhật HEARTBEAT.md để thêm kiểm tra lịch hàng ngày.”
• “Viết lại HEARTBEAT.md để nó ngắn hơn và tập trung vào các công việc tiếp theo trong hộp thư đến.”

​

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

openclaw system event --text "Kiểm tra các công việc khẩn cấp" --mode now

​

Gửi lý do (tùy chọn)

• agents.defaults.heartbeat.includeReasoning: true

​

Nhận thức về chi phí

• Sử dụng isolatedSession: true để tránh gửi toàn bộ lịch sử hội thoại (~100K token giảm xuống còn ~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òn HEARTBEAT.md.
• Đặt một mô hình rẻ hơn (ví dụ: ollama/llama3.2:1b).
• Giữ HEARTBEAT.md nhỏ.
• Sử dụng target: "none" nếu bạn chỉ muốn cập nhật trạng thái nội bộ.