메시지

이 페이지에서는 OpenClaw가 인바운드 메시지, 세션, 큐잉, 스트리밍, 추론 가시성을 어떻게 처리하는지 통합적으로 설명합니다.

메시지 흐름 (개괄)

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

주요 설정 항목:

messages.* — 접두사, 큐잉, 그룹 동작.
agents.defaults.* — 블록 스트리밍 및 청킹 기본값.
채널 오버라이드 (channels.whatsapp.*, channels.telegram.* 등) — 제한값 및 스트리밍 토글.

전체 스키마는 설정을 참고하세요.

인바운드 중복 제거

채널은 재연결 후 같은 메시지를 다시 전달할 수 있습니다. OpenClaw는 채널/계정/상대방/세션/메시지 ID를 키로 하는 짧은 수명의 캐시를 유지하여 중복 전달이 다른 에이전트 실행을 트리거하지 않도록 합니다.

인바운드 디바운싱

같은 발신자의 빠른 연속 메시지를 messages.inbound를 통해 단일 에이전트 턴으로 배치할 수 있습니다. 디바운싱은 채널 + 대화 단위로 적용되며 응답 스레딩/ID에는 가장 최근 메시지를 사용합니다.

설정 (전역 기본값 + 채널별 오버라이드):

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

참고:

디바운스는 텍스트만 있는 메시지에 적용됩니다. 미디어/첨부파일은 즉시 플러시됩니다.
컨트롤 명령어는 독립적으로 유지되도록 디바운싱을 우회합니다.

세션과 디바이스

세션은 클라이언트가 아닌 게이트웨이가 소유합니다.

1:1 채팅은 에이전트 메인 세션 키로 통합됩니다.
그룹/채널은 자체 세션 키를 갖습니다.
세션 스토어와 트랜스크립트는 게이트웨이 호스트에 저장됩니다.

여러 디바이스/채널이 같은 세션에 매핑될 수 있지만, 히스토리가 모든 클라이언트에 완전히 동기화되지는 않습니다. 권장: 컨텍스트 불일치를 피하기 위해 긴 대화에는 하나의 기본 디바이스를 사용하세요. Control UI와 TUI는 항상 게이트웨이 기반 세션 트랜스크립트를 표시하므로 진실의 원천입니다.

자세한 내용: 세션 관리.

인바운드 본문과 히스토리 컨텍스트

OpenClaw는 프롬프트 본문과 명령어 본문을 분리합니다:

Body: 에이전트에 전송되는 프롬프트 텍스트. 채널 엔벨로프와 선택적 히스토리 래퍼를 포함할 수 있습니다.
CommandBody: 디렉티브/명령어 파싱을 위한 원시 사용자 텍스트.
RawBody: CommandBody의 레거시 별칭 (호환성 유지).

채널이 히스토리를 제공할 때는 공유 래퍼를 사용합니다:

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

비직접 채팅 (그룹/채널/방)에서는 현재 메시지 본문 앞에 발신자 레이블(히스토리 항목과 동일한 스타일)이 붙습니다. 이를 통해 실시간과 큐/히스토리 메시지가 에이전트 프롬프트에서 일관성을 유지합니다.

히스토리 버퍼는 보류 전용입니다: 실행을 트리거하지 않은 그룹 메시지(예: 멘션 게이트 메시지)를 포함하고, 세션 트랜스크립트에 이미 있는 메시지는 제외합니다.

디렉티브 제거는 현재 메시지 섹션에만 적용되므로 히스토리는 그대로 유지됩니다. 히스토리를 래핑하는 채널은 CommandBody (또는 RawBody)를 원본 메시지 텍스트로 설정하고 Body는 결합된 프롬프트로 유지해야 합니다. 히스토리 버퍼는 messages.groupChat.historyLimit (전역 기본값)과 channels.slack.historyLimit 또는 channels.telegram.accounts.<id>.historyLimit 같은 채널별 오버라이드로 설정 가능합니다 (비활성화하려면 0 설정).

큐잉과 후속 처리

실행이 이미 활성 중이면 인바운드 메시지를 큐에 넣거나, 현재 실행에 조종하거나, 후속 턴을 위해 수집할 수 있습니다.

messages.queue (및 messages.queue.byChannel)로 설정합니다.
모드: interrupt, steer, followup, collect, 그리고 백로그 변형.

자세한 내용: 큐잉.

스트리밍, 청킹, 배칭

블록 스트리밍은 모델이 텍스트 블록을 생성하는 대로 부분 응답을 전송합니다. 청킹은 채널 텍스트 제한을 준수하고 펜스된 코드가 분할되지 않도록 합니다.

주요 설정:

agents.defaults.blockStreamingDefault (on|off, 기본값 off)
agents.defaults.blockStreamingBreak (text_end|message_end)
agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
agents.defaults.blockStreamingCoalesce (유휴 기반 배칭)
agents.defaults.humanDelay (블록 응답 간 사람 같은 일시 정지)
채널 오버라이드: *.blockStreaming 및 *.blockStreamingCoalesce (Telegram이 아닌 채널은 명시적 *.blockStreaming: true 필요)

자세한 내용: 스트리밍 + 청킹.

추론 가시성과 토큰

OpenClaw는 모델 추론을 노출하거나 숨길 수 있습니다:

/reasoning on|off|stream으로 가시성을 제어합니다.
추론 내용은 모델이 생성할 때 여전히 토큰 사용량에 포함됩니다.
Telegram은 임시 버블로의 추론 스트리밍을 지원합니다.

자세한 내용: 사고 + 추론 디렉티브 및 토큰 사용량.

접두사, 스레딩, 응답

아웃바운드 메시지 포매팅은 messages에서 중앙 관리됩니다:

messages.responsePrefix, channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix (아웃바운드 접두사 캐스케이드), 그리고 channels.whatsapp.messagePrefix (WhatsApp 인바운드 접두사)
replyToMode와 채널별 기본값을 통한 응답 스레딩

자세한 내용: 설정 및 채널 문서.