Messages

Trang này giải thích cách OpenClaw xử lý message đến, session, queueing, streaming và hiển thị reasoning.

Luồng message (tổng quan)

Message đến
  -> routing/bindings -> session key
  -> queue (nếu đang có run đang chạy)
  -> agent run (streaming + tools)
  -> reply gửi đi (giới hạn channel + chunking)

Các cài đặt chính nằm trong config:

  • messages.* cho prefix, queueing và hành vi nhóm.
  • agents.defaults.* cho block streaming và chunking mặc định.
  • Channel overrides (channels.whatsapp.*, channels.telegram.*, v.v.) cho giới hạn và bật/tắt streaming.

Xem Configuration để biết schema đầy đủ.

Inbound dedupe

Các Channel có thể gửi lại cùng một message sau khi reconnect. OpenClaw giữ một cache ngắn hạn với key là channel/account/peer/session/message id để các lần gửi trùng lặp không kích hoạt agent run mới.

Inbound debouncing

Các message liên tiếp nhanh từ cùng một người gửi có thể được gộp thành một lượt agent duy nhất thông qua messages.inbound. Debouncing được áp dụng theo từng channel + conversation và sử dụng message gần nhất cho reply threading/IDs.

Config (mặc định toàn cục + override theo channel):

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

Lưu ý:

  • Debounce chỉ áp dụng cho message chỉ có text; media/attachments sẽ được xử lý ngay lập tức.
  • Các lệnh control bỏ qua debouncing nên chúng vẫn độc lập.

Sessions và devices

Sessions thuộc về gateway, không phải clients.

  • Chat trực tiếp sẽ gộp vào session key chính của agent.
  • Groups/channels có session keys riêng của chúng.
  • Session store và transcripts nằm trên gateway host.

Nhiều devices/channels có thể map vào cùng một session, nhưng lịch sử không được đồng bộ đầy đủ về mọi client. Mình khuyên các bạn nên dùng một device chính cho các cuộc hội thoại dài để tránh context bị phân tán. Control UI và TUI luôn hiển thị session transcript từ gateway, nên chúng là nguồn chính xác nhất.

Chi tiết: Session management.

Inbound bodies và history context

OpenClaw tách prompt body khỏi command body:

  • Body: prompt text gửi đến agent. Có thể bao gồm channel envelopes và optional history wrappers.
  • CommandBody: raw user text để parse directive/command.
  • RawBody: alias cũ của CommandBody (giữ lại để tương thích).

Khi một channel cung cấp history, nó dùng wrapper chung:

  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]

Với non-direct chats (groups/channels/rooms), current message body được thêm prefix với sender label (cùng style dùng cho history entries). Điều này giữ cho message real-time và queued/history nhất quán trong agent prompt.

History buffers là pending-only: chúng bao gồm các message nhóm không kích hoạt run (ví dụ: message bị mention-gated) và loại trừ các message đã có trong session transcript.

Directive stripping chỉ áp dụng cho phần current message nên history vẫn nguyên vẹn. Các Channel wrap history nên set CommandBody (hoặc RawBody) thành original message text và giữ Body là combined prompt. History buffers có thể config qua messages.groupChat.historyLimit (mặc định toàn cục) và per-channel overrides như channels.slack.historyLimit hoặc channels.telegram.accounts.<id>.historyLimit (set 0 để tắt).

Queueing và followups

Nếu đã có run đang chạy, các message đến có thể được queued, steered vào run hiện tại, hoặc collected cho lượt followup.

  • Config qua messages.queue (và messages.queue.byChannel).
  • Modes: interrupt, steer, followup, collect, cộng thêm các biến thể backlog.

Chi tiết: Queueing.

Streaming, chunking và batching

Block streaming gửi các reply từng phần khi model tạo ra text blocks. Chunking tuân thủ giới hạn text của channel và tránh cắt fenced code.

Các cài đặt chính:

  • agents.defaults.blockStreamingDefault (on|off, mặc định off)
  • agents.defaults.blockStreamingBreak (text_end|message_end)
  • agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
  • agents.defaults.blockStreamingCoalesce (idle-based batching)
  • agents.defaults.humanDelay (độ trễ giống người giữa các block replies)
  • Channel overrides: *.blockStreaming và *.blockStreamingCoalesce (các channel không phải Telegram cần set rõ *.blockStreaming: true)

Chi tiết: Streaming + chunking.

Reasoning visibility và tokens

OpenClaw có thể hiển thị hoặc ẩn model reasoning:

  • /reasoning on|off|stream điều khiển hiển thị.
  • Reasoning content vẫn tính vào token usage khi được model tạo ra.
  • Telegram hỗ trợ reasoning stream vào draft bubble.

Chi tiết: Thinking + reasoning directives và Token use.

Prefixes, threading và replies

Định dạng outbound message được tập trung trong messages:

  • messages.responsePrefix (outbound prefix) và channels.whatsapp.messagePrefix (WhatsApp inbound prefix)
  • Reply threading qua replyToMode và per-channel defaults

Chi tiết: Configuration và channel docs.