Messages

Messages 문서는 OpenClaw 공식 문서(concepts/messages)를 한국어로 정리한 가이드입니다. Message flow, sessions, queueing, and reasoning visibility 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Message flow, sessions, queueing, and reasoning visibility

한국어 가이드 범위: concepts/messages 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Inbound dedupe
Inbound debouncing
Sessions and devices
Prompt bodies and history context
Tool result metadata
Queueing and followups
Channel run ownership
Streaming, chunking, and batching
Reasoning visibility and tokens
Prefixes, threading, and replies
Silent replies
관련 문서

상세 내용

본문

Inbound messages move through routing, dedupe/debounce, an agent run, and outbound delivery:

주요 항목:

messages.* for prefixes, queueing, inbound debounce, and group behavior.
agents.defaults.* for block streaming, chunking, and silent-reply defaults.
Channel overrides (channels.telegram.*, channels.whatsapp.*, etc.) for per-channel caps and streaming toggles.

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

Inbound dedupe

Channels can redeliver the same message after a reconnect. OpenClaw keeps an in-memory cache keyed by agent scope, channel route (channel + peer + account + thread), and message id, so a redelivered message does not trigger a second agent run. The cache entry expires after 20 minutes or once 5000 entries are tracked, whichever comes first.

Inbound debouncing

Rapid consecutive text messages from the same sender can be batched into one agent turn via messages.inbound. Debouncing is scoped per channel + conversation and uses the most recent message for reply threading/IDs.

주요 항목:

Debounce applies to text-only messages; media/attachments flush immediately.
Control commands (stop/abort/status, etc.) bypass debouncing so they dispatch immediately.
Disabled by default: messages.inbound.debounceMs has no built-in default, so debouncing only activates once you set it (globally or per channel).
iMessage follows the same generic debounce policy. imsg 0.13.1 and newer coalesces Apple URL-preview split-sends before OpenClaw receives them, so no iMessage-specific debounce setting is needed.

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

Sessions and devices

Sessions are owned by the gateway, not by clients.

주요 항목:

Direct chats collapse into the agent's main session key.
Groups/channels get their own session keys.
The session store and transcripts live on the gateway host.

Prompt bodies and history context

Channel plugins populate several text fields on the inbound context, from most to least preferred:

주요 항목:

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

Field	Purpose
`BodyForAgent`	Model-facing text for the current turn. Falls back to `CommandBody` / `RawBody` / `Body` when unset.
`BodyForCommands`	Clean text used for directive/command parsing. Falls back to `CommandBody` / `RawBody` / `Body` when unset.
`CommandBody`	Legacy intermediate body; prefer `BodyForCommands`.
`RawBody`	Deprecated alias for `CommandBody`.
`Body`	Legacy prompt body; may include channel envelopes and history wrappers.

Tool result metadata

Tool result content is the model-visible result; details is runtime metadata for UI rendering, diagnostics, media delivery, and plugins.

주요 항목:

toolResult.details is stripped before provider replay and before compaction input.
Persisted session transcripts keep only bounded details; oversized metadata is replaced with a compact summary marked persistedDetailsTruncated: true.
Plugins and tools should put text the model must read in content, not only in details.

Queueing and followups

When a run is already active, inbound messages steer into it by default. messages.queue controls the mode:

Mode	Behavior
`steer` (default)	Inject the new prompt into the active run.
`followup`	Run the message after the active run finishes.
`collect`	Batch compatible messages into one later turn.
`interrupt`	Abort the active run, then start the newest prompt.

Channel run ownership

Channel plugins may preserve ordering, debounce input, and apply transport backpressure before a message enters the session queue. They should not impose a separate timeout around the agent turn itself. Once a message is routed to a session, the session, tool, and runtime lifecycle govern long-running work so all channels report and recover from slow turns consistently.

Streaming, chunking, and batching

Block streaming sends partial replies as the model produces text blocks; chunking respects channel text limits and avoids splitting fenced code.

주요 항목:

agents.defaults.blockStreamingDefault (on|off, default off)
agents.defaults.blockStreamingBreak (text_end|message_end)
agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
agents.defaults.blockStreamingCoalesce (idle-based batching)
agents.defaults.humanDelay (human-like pause between block replies)
Channel overrides: *.streaming.block.enabled and *.streaming.block.coalesce on bundled channels; stale flat keys are migrated by openclaw doctor --fix. Block streaming is off unless explicitly enabled, on every channel including Telegram. QQ Bot is the exception: it has no streaming.block keys and streams block replies unless channels.qqbot.streaming.mode is "off".

Reasoning visibility and tokens

Details: Thinking + reasoning directives and Token use.

주요 항목:

/reasoning on|off|stream controls visibility.
Reasoning content still counts toward token usage when the model produces it.
Telegram supports streaming reasoning into a transient draft bubble that is deleted after final delivery; use /reasoning on for persistent reasoning output.

Prefixes, threading, and replies

Details: Configuration and channel docs.

주요 항목:

Outbound prefixes live at channels.<channel>.responsePrefix and channels.<channel>.accounts.<id>.responsePrefix. Account values win. Doctor copies the global fallback into configured channel blocks when those canonical fields are unset; messages.responsePrefix remains as a fallback for implicit and custom channels.
Reply threading via replyToMode and per-channel defaults.

Silent replies

The silent token NO_REPLY (case-insensitive, so no_reply also matches) means "do not deliver a user-visible reply." When a turn also has pending tool media, such as generated TTS audio, OpenClaw strips the silent text but still delivers the media attachment.

주요 항목:

Direct conversations never receive NO_REPLY prompt guidance. If a direct run accidentally returns a bare silent token, OpenClaw suppresses it instead of rewriting or delivering it.
Groups/channels allow silence by default. In message_tool visible-reply mode, silence means the model does not call message(action=send).
Internal orchestration allows silence by default.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/messages
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

Messages

핵심 요약

Message flow, sessions, queueing, and reasoning visibility

한국어 가이드 범위: concepts/messages 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Inbound dedupe
Inbound debouncing
Sessions and devices
Prompt bodies and history context
Tool result metadata
Queueing and followups
Channel run ownership
Streaming, chunking, and batching
Reasoning visibility and tokens
Prefixes, threading, and replies
Silent replies
관련 문서

상세 내용

본문

Inbound messages move through routing, dedupe/debounce, an agent run, and outbound delivery:

주요 항목:

messages.* for prefixes, queueing, inbound debounce, and group behavior.
agents.defaults.* for block streaming, chunking, and silent-reply defaults.
Channel overrides (channels.telegram.*, channels.whatsapp.*, etc.) for per-channel caps and streaming toggles.

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

Inbound dedupe

Inbound debouncing

주요 항목:

Debounce applies to text-only messages; media/attachments flush immediately.
Control commands (stop/abort/status, etc.) bypass debouncing so they dispatch immediately.
Disabled by default: messages.inbound.debounceMs has no built-in default, so debouncing only activates once you set it (globally or per channel).
iMessage follows the same generic debounce policy. imsg 0.13.1 and newer coalesces Apple URL-preview split-sends before OpenClaw receives them, so no iMessage-specific debounce setting is needed.

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

Sessions and devices

Sessions are owned by the gateway, not by clients.

주요 항목:

Direct chats collapse into the agent's main session key.
Groups/channels get their own session keys.
The session store and transcripts live on the gateway host.

Prompt bodies and history context

Channel plugins populate several text fields on the inbound context, from most to least preferred:

주요 항목:

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

Field	Purpose
`BodyForAgent`	Model-facing text for the current turn. Falls back to `CommandBody` / `RawBody` / `Body` when unset.
`BodyForCommands`	Clean text used for directive/command parsing. Falls back to `CommandBody` / `RawBody` / `Body` when unset.
`CommandBody`	Legacy intermediate body; prefer `BodyForCommands`.
`RawBody`	Deprecated alias for `CommandBody`.
`Body`	Legacy prompt body; may include channel envelopes and history wrappers.

Tool result metadata

Tool result content is the model-visible result; details is runtime metadata for UI rendering, diagnostics, media delivery, and plugins.

주요 항목:

toolResult.details is stripped before provider replay and before compaction input.
Persisted session transcripts keep only bounded details; oversized metadata is replaced with a compact summary marked persistedDetailsTruncated: true.
Plugins and tools should put text the model must read in content, not only in details.

Queueing and followups

When a run is already active, inbound messages steer into it by default. messages.queue controls the mode:

Mode	Behavior
`steer` (default)	Inject the new prompt into the active run.
`followup`	Run the message after the active run finishes.
`collect`	Batch compatible messages into one later turn.
`interrupt`	Abort the active run, then start the newest prompt.

Channel run ownership

Streaming, chunking, and batching

Block streaming sends partial replies as the model produces text blocks; chunking respects channel text limits and avoids splitting fenced code.

주요 항목:

agents.defaults.blockStreamingDefault (on|off, default off)
agents.defaults.blockStreamingBreak (text_end|message_end)
agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
agents.defaults.blockStreamingCoalesce (idle-based batching)
agents.defaults.humanDelay (human-like pause between block replies)
Channel overrides: *.streaming.block.enabled and *.streaming.block.coalesce on bundled channels; stale flat keys are migrated by openclaw doctor --fix. Block streaming is off unless explicitly enabled, on every channel including Telegram. QQ Bot is the exception: it has no streaming.block keys and streams block replies unless channels.qqbot.streaming.mode is "off".

Reasoning visibility and tokens

Details: Thinking + reasoning directives and Token use.

주요 항목:

/reasoning on|off|stream controls visibility.
Reasoning content still counts toward token usage when the model produces it.
Telegram supports streaming reasoning into a transient draft bubble that is deleted after final delivery; use /reasoning on for persistent reasoning output.

Prefixes, threading, and replies

Details: Configuration and channel docs.

주요 항목:

Outbound prefixes live at channels.<channel>.responsePrefix and channels.<channel>.accounts.<id>.responsePrefix. Account values win. Doctor copies the global fallback into configured channel blocks when those canonical fields are unset; messages.responsePrefix remains as a fallback for implicit and custom channels.
Reply threading via replyToMode and per-channel defaults.

Silent replies

주요 항목:

Direct conversations never receive NO_REPLY prompt guidance. If a direct run accidentally returns a bare silent token, OpenClaw suppresses it instead of rewriting or delivering it.
Groups/channels allow silence by default. In message_tool visible-reply mode, silence means the model does not call message(action=send).
Internal orchestration allows silence by default.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/messages
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

Messages

핵심 요약

문서 구성

상세 내용

본문

Inbound dedupe

Inbound debouncing

Sessions and devices

Prompt bodies and history context

Tool result metadata

Queueing and followups

Channel run ownership

Streaming, chunking, and batching

Reasoning visibility and tokens

Prefixes, threading, and replies

Silent replies

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Messages

핵심 요약

문서 구성

상세 내용

본문

Inbound dedupe

Inbound debouncing

Sessions and devices

Prompt bodies and history context

Tool result metadata

Queueing and followups

Channel run ownership

Streaming, chunking, and batching

Reasoning visibility and tokens

Prefixes, threading, and replies

Silent replies

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드