OpenClaw 메시지 흐름 최적화: 5분 만에 설정하기

메시지 기반의 AI 에이전트를 개발하다 보면 가장 골치 아픈 게 바로 메시지 흐름을 관리하는 일이에요. 사용자가 메시지를 연달아 보내거나, 여러 플랫폼에서 동시에 메시지가 쏟아질 때 컨텍스트를 유지하고 중복 처리를 하는 작업은 생각보다 복잡하거든요.

OpenClaw는 이러한 인바운드 메시지 처리부터 세션 관리, 큐잉, 그리고 스트리밍까지의 복잡한 과정을 깔끔하게 연결해 줍니다. 개발자가 비즈니스 로직에만 집중할 수 있도록 OpenClaw가 메시지를 어떻게 다루는지 자세히 알아볼게요.

메시지 흐름 (상위 수준)

OpenClaw가 인바운드 메시지를 처리하는 전체적인 흐름은 다음과 같아요.

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

주요 설정 옵션은 configuration에서 관리할 수 있어요.

messages.*: 접두사(prefixes), 큐잉, 그룹 동작 관련 설정
agents.defaults.*: 블록 스트리밍 및 청킹(chunking) 기본값 설정
Channel overrides (channels.whatsapp.*, channels.telegram.* 등): 전송 제한 및 스트리밍 활성화 여부 설정

전체 스키마에 대한 내용은 Configuration 문서를 참고해 주세요.

인바운드 중복 제거

메시지 채널은 연결이 재설정된 후 동일한 메시지를 다시 보낼 때가 있어요. OpenClaw는 channel, account, peer, session, message id를 키로 사용하는 단기 캐시를 유지합니다. 덕분에 중복된 메시지가 들어와도 에이전트가 중복으로 실행되지 않아요.

인바운드 디바운싱 (Debouncing)

동일한 발신자가 짧은 간격으로 여러 메시지를 보낼 경우, messages.inbound 설정을 통해 이를 하나의 에이전트 턴(turn)으로 묶을 수 있어요. 디바운싱은 채널과 대화별로 적용되며, 답장 스레딩이나 ID 생성에는 가장 최근 메시지를 사용합니다.

설정 예시 (글로벌 기본값 및 채널별 오버라이드):

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

참고 사항:

디바운싱은 텍스트 전용 메시지에만 적용됩니다. 미디어나 첨부 파일은 즉시 처리돼요.
제어 명령(Control commands)은 디바운싱을 거치지 않고 즉시 독립적으로 실행됩니다.

세션 및 디바이스

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

다이렉트 채팅은 에이전트의 메인 세션 키로 통합됩니다.
그룹이나 채널은 각각 고유한 세션 키를 가집니다.
세션 저장소와 트랜스크립트(transcripts)는 Gateway 호스트에 저장됩니다.

여러 디바이스나 채널이 동일한 세션에 매핑될 수 있지만, 히스토리가 모든 클라이언트에 완전히 동기화되지는 않아요. 컨텍스트가 어긋나는 것을 방지하려면 긴 대화에는 하나의 주 디바이스를 사용하는 것을 추천합니다. Control UI와 TUI는 항상 Gateway 기반의 세션 트랜스크립트를 보여주므로, 이들이 데이터의 기준점(source of truth)이 됩니다.

자세한 내용은 Session management를 확인하세요.

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

OpenClaw는 prompt body와 command body를 구분해서 처리해요.

Body: 에이전트에게 전달되는 프롬프트 텍스트입니다. 채널 정보와 선택적인 히스토리 래퍼가 포함될 수 있어요.
CommandBody: 지시어나 명령 파싱을 위한 순수 사용자 텍스트입니다.
RawBody: CommandBody의 이전 별칭입니다 (호환성을 위해 유지됨).

채널에서 히스토리를 제공할 때는 공통 래퍼를 사용합니다.

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

다이렉트 채팅이 아닌 경우(그룹, 채널, 룸 등)에는 현재 메시지 본문 앞에 발신자 라벨이 붙습니다. 이는 히스토리 항목에 사용되는 스타일과 동일해요. 덕분에 실시간 메시지와 큐에 쌓였던 히스토리 메시지가 에이전트 프롬프트 내에서 일관된 형식을 유지하게 됩니다.

히스토리 버퍼는 대기 중인(pending-only) 메시지만 포함합니다. 예를 들어 멘션이 있어야만 반응하는 그룹에서 멘션 없이 지나간 메시지들은 포함되지만, 이미 세션 트랜스크립트에 기록된 메시지는 제외됩니다.

지시어 제거(Directive stripping)는 현재 메시지 섹션에만 적용되어 히스토리는 온전하게 보존됩니다. 히스토리를 래핑하는 채널은 CommandBody(또는 RawBody)를 원래 메시지 텍스트로 설정하고, Body를 결합된 프롬프트로 유지해야 합니다. 히스토리 버퍼는 messages.groupChat.historyLimit(글로벌 기본값)이나 channels.slack.historyLimit, channels.telegram.accounts.<id>.historyLimit 같은 채널별 설정을 통해 조절할 수 있습니다 (0으로 설정하면 비활성화됩니다).

큐잉 및 후속 작업

에이전트가 이미 실행 중일 때 새로운 메시지가 들어오면, 이를 큐에 넣거나 현재 실행 중인 작업에 반영하거나 다음 턴을 위해 모아둘 수 있어요.

messages.queue (및 messages.queue.byChannel)를 통해 설정합니다.
모드 종류: interrupt, steer, followup, collect 및 백로그 변형 모드.

자세한 내용은 Queueing 문서를 참고하세요.

스트리밍, 청킹 및 배칭

블록 스트리밍을 사용하면 모델이 텍스트 블록을 생성하는 대로 부분 답장을 보낼 수 있어요. 청킹(Chunking) 기능은 채널의 텍스트 제한을 준수하면서 코드 블록이 중간에 잘리지 않도록 관리해 줍니다.

주요 설정:

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 설정 필요)

자세한 내용은 Streaming + chunking 문서를 확인해 보세요.

추론 가시성 및 토큰

OpenClaw는 모델의 추론(reasoning) 과정을 보여주거나 숨길 수 있는 기능을 제공합니다.

/reasoning on|off|stream 명령으로 가시성을 제어합니다.
추론 내용은 화면에 보이지 않더라도 모델이 생성한 것이라면 토큰 사용량에 포함됩니다.
Telegram은 드래프트 버블(draft bubble)을 통한 추론 스트리밍을 지원합니다.

자세한 내용은 Thinking + reasoning directives 및 Token use 문서를 참고하세요.

접두사, 스레딩 및 답장

아웃바운드 메시지 형식은 messages 설정에서 중앙 집중식으로 관리됩니다.

messages.responsePrefix, channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix 순으로 적용되는 접두사 계층 구조를 가집니다. WhatsApp 인바운드 접두사는 channels.whatsapp.messagePrefix를 사용합니다.
replyToMode 및 채널별 기본값을 통해 답장 스레딩을 설정할 수 있습니다.

자세한 내용은 Configuration 및 채널별 문서를 확인해 주세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.