Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw xử lý tin nhắn đến thông qua một pipeline gồm phân giải phiên, xếp hàng, streaming, thực thi công cụ và khả năng hiển thị reasoning. Trang này ánh xạ đường đi từ tin nhắn đến đến phản hồi.

​
Luồng tin nhắn (cấp cao)

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)
Các nút điều chỉnh chính nằm trong cấu hình:
  • messages.* cho tiền tố, xếp hàng và hành vi nhóm.
  • agents.defaults.* cho mặc định block streaming và chunking.
  • Ghi đè kênh (channels.whatsapp.*, channels.telegram.*, v.v.) cho giới hạn và nút bật/tắt streaming.
Xem Cấu hình để biết schema đầy đủ.

​
Chống trùng lặp tin nhắn đến

Các kênh có thể gửi lại cùng một tin nhắn sau khi kết nối lại. OpenClaw giữ một bộ nhớ đệm ngắn hạn được định danh theo kênh/tài khoản/đối tượng ngang hàng/phiên/id tin nhắn để các lần gửi trùng lặp không kích hoạt thêm một lần chạy agent khác.

​
Debounce tin nhắn đến

Các tin nhắn liên tiếp nhanh từ cùng một người gửi có thể được gom thành một lượt agent duy nhất qua messages.inbound. Debounce được giới hạn theo từng kênh + cuộc hội thoại và dùng tin nhắn gần nhất cho threading/id phản hồi. Cấu hình (mặc định toàn cục + ghi đè theo kênh): 
{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}
Ghi chú:
  • Debounce áp dụng cho tin nhắn chỉ có văn bản; phương tiện/tệp đính kèm được flush ngay lập tức.
  • Lệnh điều khiển bỏ qua debounce để chúng vẫn đứng riêng — ngoại trừ khi một kênh chủ động chọn gom DM từ cùng người gửi (ví dụ BlueBubbles coalesceSameSenderDms), trong đó lệnh DM chờ trong cửa sổ debounce để một payload gửi tách có thể nhập vào cùng lượt agent.

​
Phiên và thiết bị

Phiên thuộc quyền sở hữu của gateway, không phải của client.
  • Trò chuyện trực tiếp được gộp vào khóa phiên chính của agent.
  • Nhóm/kênh có khóa phiên riêng.
  • Kho phiên và bản ghi hội thoại nằm trên máy chủ gateway.
Nhiều thiết bị/kênh có thể ánh xạ tới cùng một phiên, nhưng lịch sử không được đồng bộ đầy đủ trở lại mọi client. Khuyến nghị: dùng một thiết bị chính cho các cuộc hội thoại dài để tránh ngữ cảnh phân kỳ. Control UI và TUI luôn hiển thị bản ghi hội thoại phiên do gateway hỗ trợ, vì vậy chúng là nguồn sự thật. Chi tiết: Quản lý phiên.

​
Siêu dữ liệu kết quả công cụ

content của kết quả công cụ là kết quả mà model nhìn thấy. details của kết quả công cụ là siêu dữ liệu runtime cho hiển thị UI, chẩn đoán, gửi phương tiện và Plugin. OpenClaw giữ ranh giới đó rõ ràng:
  • toolResult.details bị loại bỏ trước khi phát lại provider và đầu vào compaction.
  • Bản ghi hội thoại phiên được lưu bền vững chỉ giữ details có giới hạn; siêu dữ liệu quá lớn được thay bằng một tóm tắt gọn có đánh dấu persistedDetailsTruncated: true.
  • Plugin và công cụ nên đặt văn bản mà model phải đọc trong content, không chỉ trong details.

​
Nội dung đến và ngữ cảnh lịch sử

OpenClaw tách nội dung prompt khỏi nội dung lệnh:
  • BodyForAgent: văn bản chính hướng tới model cho tin nhắn hiện tại. Plugin kênh nên giữ phần này tập trung vào văn bản mang prompt hiện tại của người gửi.
  • Body: fallback prompt kế thừa. Phần này có thể bao gồm phong bì kênh và wrapper lịch sử tùy chọn, nhưng các kênh hiện tại không nên dựa vào nó làm đầu vào model chính khi có BodyForAgent.
  • CommandBody: văn bản người dùng thô để phân tích chỉ thị/lệnh.
  • RawBody: bí danh kế thừa cho CommandBody (giữ để tương thích).
Khi một kênh cung cấp lịch sử, nó dùng một wrapper dùng chung:
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
Với trò chuyện không trực tiếp (nhóm/kênh/phòng), nội dung tin nhắn hiện tại được thêm tiền tố bằng nhãn người gửi (cùng kiểu dùng cho các mục lịch sử). Điều này giữ cho tin nhắn thời gian thực và tin nhắn được xếp hàng/lịch sử nhất quán trong prompt của agent. Bộ đệm lịch sử là chỉ pending: chúng bao gồm các tin nhắn nhóm không kích hoạt một lần chạy (ví dụ, tin nhắn bị chặn bởi cổng mention) và loại trừ tin nhắn đã có trong bản ghi hội thoại phiên. Việc loại bỏ chỉ thị chỉ áp dụng cho phần tin nhắn hiện tại để lịch sử vẫn nguyên vẹn. Các kênh bọc lịch sử nên đặt CommandBody (hoặc RawBody) thành văn bản tin nhắn gốc và giữ Body là prompt kết hợp. Lịch sử có cấu trúc, phản hồi, tin nhắn được chuyển tiếp và siêu dữ liệu kênh được render dưới dạng các khối ngữ cảnh không đáng tin cậy vai trò người dùng trong quá trình lắp ráp prompt. Bộ đệm lịch sử có thể cấu hình qua messages.groupChat.historyLimit (mặc định toàn cục) và ghi đè theo kênh như channels.slack.historyLimit hoặc channels.telegram.accounts.<id>.historyLimit (đặt 0 để tắt).

​
Xếp hàng và followup

Nếu một lần chạy đang hoạt động, tin nhắn đến có thể được xếp hàng, điều hướng vào lần chạy hiện tại, hoặc được thu thập cho một lượt followup.
  • Cấu hình qua messages.queue (và messages.queue.byChannel).
  • Chế độ mặc định là steer, với debounce followup 500ms khi steering rơi về gửi followup đã xếp hàng.
  • Chế độ: steer, followup, collect, steer-backlog, interrupt, và chế độ kế thừa từng cái một queue.
Chi tiết: Hàng đợi lệnh và Hàng đợi steering.

​
Quyền sở hữu lần chạy của kênh

Plugin kênh có thể giữ thứ tự, debounce đầu vào và áp dụng backpressure transport trước khi một tin nhắn đi vào hàng đợi phiên. Chúng không nên áp đặt một timeout riêng quanh chính lượt agent. Sau khi một tin nhắn được định tuyến tới một phiên, công việc chạy lâu được quản lý bởi vòng đời phiên, công cụ và runtime để mọi kênh báo cáo và phục hồi nhất quán từ các lượt chậm.

​
Streaming, chunking và batching

Block streaming gửi phản hồi từng phần khi model tạo ra các khối văn bản. Chunking tôn trọng giới hạn văn bản của kênh và tránh tách code fence. Thiết lập chính:
  • agents.defaults.blockStreamingDefault (on|off, mặc định tắt)
  • agents.defaults.blockStreamingBreak (text_end|message_end)
  • agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
  • agents.defaults.blockStreamingCoalesce (batching dựa trên idle)
  • agents.defaults.humanDelay (khoảng dừng giống con người giữa các phản hồi khối)
  • Ghi đè kênh: *.blockStreaming và *.blockStreamingCoalesce (các kênh không phải Telegram yêu cầu *.blockStreaming: true rõ ràng)
Chi tiết: Streaming + chunking.

​
Khả năng hiển thị reasoning và token

OpenClaw có thể hiển thị hoặc ẩn reasoning của model:
  • /reasoning on|off|stream điều khiển khả năng hiển thị.
  • Nội dung reasoning vẫn được tính vào mức sử dụng token khi được model tạo ra.
  • Telegram hỗ trợ stream reasoning vào một bong bóng nháp tạm thời, bong bóng này bị xóa sau khi gửi cuối cùng; dùng /reasoning on để có đầu ra reasoning được giữ lại.
Chi tiết: Chỉ thị thinking + reasoning và Mức sử dụng token.

​
Tiền tố, threading và phản hồi

Định dạng tin nhắn gửi đi được tập trung trong messages:
  • messages.responsePrefix, channels.<channel>.responsePrefix, và channels.<channel>.accounts.<id>.responsePrefix (chuỗi cascade tiền tố gửi đi), cộng với channels.whatsapp.messagePrefix (tiền tố tin nhắn đến WhatsApp)
  • Threading phản hồi qua replyToMode và mặc định theo kênh
Chi tiết: Cấu hình và tài liệu kênh.

​
Phản hồi im lặng

Token im lặng chính xác NO_REPLY / no_reply có nghĩa là “không gửi phản hồi hiển thị cho người dùng”. Khi một lượt cũng có phương tiện công cụ đang pending, chẳng hạn âm thanh TTS đã tạo, OpenClaw loại bỏ văn bản im lặng nhưng vẫn gửi tệp đính kèm phương tiện. OpenClaw phân giải hành vi đó theo loại cuộc hội thoại:
  • Cuộc hội thoại trực tiếp mặc định không cho phép im lặng và viết lại một phản hồi im lặng đơn thuần thành một fallback ngắn có thể nhìn thấy.
  • Nhóm/kênh mặc định cho phép im lặng.
  • Điều phối nội bộ mặc định cho phép im lặng.
OpenClaw cũng dùng phản hồi im lặng cho các lỗi runner nội bộ xảy ra trước bất kỳ phản hồi assistant nào trong trò chuyện không trực tiếp, để nhóm/kênh không thấy nội dung lỗi gateway rập khuôn. Trò chuyện trực tiếp mặc định hiển thị nội dung lỗi ngắn gọn; chi tiết runner thô chỉ được hiển thị khi /verbose là on hoặc full. Mặc định nằm dưới agents.defaults.silentReply và agents.defaults.silentReplyRewrite; surfaces.<id>.silentReply và surfaces.<id>.silentReplyRewrite có thể ghi đè chúng theo từng surface. Khi phiên cha có một hoặc nhiều lần chạy subagent được spawn đang pending, phản hồi im lặng đơn thuần bị bỏ trên mọi surface thay vì được viết lại, để cha giữ im lặng cho đến khi sự kiện hoàn tất của child gửi phản hồi thật.

​
Liên quan