Streaming Modes

+15 Mana ✨
OpenClaw Streaming Configuration(DOCUMENTATION)OpenClaw Channel Reference(DOCUMENTATION)

Introduction

When your OpenClaw agent generates a response, the text does not arrive all at once. It streams token by token from the language model. OpenClaw offers two streaming modes that control how these tokens are delivered to the user: partial streaming and block streaming. The choice affects user experience, platform compatibility, and how responses appear in different chat clients.

Key Concepts

  • Partial Streaming: Tokens are appended to a single message that updates in real-time, like watching someone type. The message grows as tokens arrive.
  • Block Streaming: Each logical section of the response is sent as a separate, complete message. The user receives multiple discrete messages rather than one growing message.
  • Per-Channel Configuration: Each communication channel can be configured with its own streaming mode based on platform capabilities.
  • Token Buffering: Tokens are buffered briefly before being sent to reduce network overhead and provide smoother visual updates.
  • Streaming Fallback: Platforms that do not support message editing automatically fall back to block streaming.

Real World Context

A team uses OpenClaw across Discord, WhatsApp, and a custom WebChat widget. Discord supports message editing, so partial streaming works great — users see the response being typed in real-time. WhatsApp does not support editing sent messages, so block streaming is used instead. The WebChat widget supports Server-Sent Events, enabling smooth partial streaming. Each channel is configured independently to provide the best experience for its platform.

Deep Dive

Streaming mode is configured per channel in your OpenClaw configuration:

json
{
  "channels": {
    "discord": {
      "enabled": true,
      "streaming": {
        "mode": "partial",
        "bufferMs": 100
      }
    },
    "whatsapp": {
      "enabled": true,
      "streaming": {
        "mode": "block",
        "blockDelimiter": "paragraph"
      }
    },
    "webchat": {
      "enabled": true,
      "streaming": {
        "mode": "partial",
        "bufferMs": 50
      }
    }
  }
}

This configuration sets Discord and WebChat to partial streaming (with different buffer intervals) and WhatsApp to block streaming. The bufferMs field controls how long tokens are collected before sending an update. A lower value provides faster visual updates but generates more network traffic.

Partial Streaming

In partial streaming mode, the agent sends an initial empty or minimal message, then continuously edits it as new tokens arrive:

markdown
Partial streaming flow:
1. Agent sends initial message: "..."
2. After 100ms buffer: edit message to "I will analyze"
3. After 100ms buffer: edit message to "I will analyze the auth module"
4. After 100ms buffer: edit message to "I will analyze the auth module and suggest"
5. ... continues until response is complete
6. Final edit: complete response

This creates a smooth typing effect where users can read the response as it forms. It requires the platform to support message editing via API.

Platforms that support partial streaming include Discord, Slack, WebChat (via SSE), and Telegram (via editMessageText).

Block Streaming

In block streaming mode, the response is split into logical blocks, and each block is sent as a separate message:

markdown
Block streaming flow:
1. Agent generates full first paragraph
2. Sends paragraph 1 as message 1
3. Agent generates second paragraph
4. Sends paragraph 2 as message 2
5. ... continues for each block

The blockDelimiter field controls how the response is split. Options include:

markdown
Block delimiters:
- "paragraph": Split on double newlines (default)
- "sentence": Split on sentence boundaries
- "heading": Split on markdown headings
- "fixed": Split at a fixed character count

Block streaming is the only option for platforms like WhatsApp, iMessage, and SMS that do not support editing sent messages.

Common Pitfalls

  • Using partial streaming on platforms that do not support editing: This causes either errors or duplicate messages. Always check platform capabilities before choosing a mode.
  • Setting bufferMs too low: A buffer of 10ms generates excessive API calls to the chat platform, which can trigger rate limits. The 50-100ms range works well.
  • Not configuring streaming per channel: Using the same mode for all channels means some platforms get a suboptimal experience.

Best Practices

  • Match the mode to the platform: Use partial streaming where editing is supported, and block streaming elsewhere.
  • Use paragraph delimiters for block streaming: Paragraph-based splitting produces the most natural reading experience in block mode.
  • Test streaming on each platform: The visual experience varies significantly across platforms. Test with real messages to verify the configuration feels right.

Summary

  • Partial streaming edits a single message in real-time as tokens arrive, creating a typing effect
  • Block streaming sends multiple discrete messages, each containing a logical section of the response
  • Streaming mode is configured per channel based on platform capabilities
  • Token buffering (50-100ms) reduces network overhead while maintaining responsive visual updates
  • Platforms without message editing support automatically fall back to block streaming
✓ Completed