Chapter 11: Final Technical Guide to OpenCLAW | Technical Audiobook Course

In this section, we'll explore how messages travel from ingress points through to their delivery on channels. Understanding this flow is crucial for managing and troubleshooting message routing effectively. Let's explore the life cycle of a message as it flows through the system from when it first arrives inbound to when outbound replies are sent. Understanding this pipeline helps clarify how messages are processed efficiently and reliably. This diagram shows the main stages a message passes through. First, routing and session key determination happen. If a session is busy, the message queues. Then the agent processes the run, possibly calling tools and streaming output. Finally, outbound replies are sent with channel aware chunking and limits. An inbound message follows a predictable path. The gateway first routes it and identifies the session key. It then checks for duplicates or rapid repeats to avoid redundant work. If a run is active, the message queues until execution. The agent run may call tools and stream responses. Finally, the gateway manages chunking and sends outbound messages. Open Claw uses a deduplication cache key by channel, account, peer, session, and message ID to block duplicate runs from redeliver events. Debouncing rules suppress rapid repeats like quick edits or resends. Operators can tune these settings to handle noisy clients or accidental double deliveries. Routing and bindings assign each message to an agent and session. Messages can be conversation content or explicit commands. The session key controls transcript placement and queue order. History buffer sizes and session policies affect how much context the agent receives, balancing memory use and coherence. To prevent collisions and overlapping replies, Open Claw uses a lane-aware FIFO queue. Each lane, often a session or workspace, has a concurrency limit. The main lane defaults to four concurrent runs, sub-agents to eight, and others to one. Queue modes and API controls allow flexible message handling. Checking queue depth and concurrency helps diagnose slow or stuck responses. Retries happen independently for each HTTP request, like message sends or media uploads. This means partial workflows can succeed or fail in parts. Different providers handle errors uniquely, so adapter-specific tuning of retry attempts, backoff, and error handling is important. Avoid broad retries on non-idempotent requests to prevent issues. Open Claw supports two streaming methods to channels, each suited to different use cases. Understanding these helps optimize message delivery and user experience. Block streaming sends fully completed assistant blocks as individual channel messages. This works well when content is naturally divided into steps or paragraphs, allowing clear segmented delivery. Preview streaming sends a temporary editable message that is updated progressively, mimicking typing or editing behavior. This creates a more dynamic and natural user experience. Open Claw does not stream raw token deltas, but uses a block chunker with configurable size bounds and heuristics to avoid splitting code or semantic units. It coalesces small pieces and can insert pacing delays to simulate human delivery. Channel size and rate limits influence chunking behavior. Tuning these parameters helps balance message size and frequency when debugging message delivery. Check the duplication hits to catch duplicates. Inspect queue depths and concurrency. Review retry logs for HTTP calls and analyze streaming and chunking decisions in the run trace. Upcoming chapters will detail how to configure these settings and provider specific overrides. In this section, we'll explore how OpenClaw manages incoming messages to avoid duplicate processing, handle rapid message bursts, and maintain proper session context. Understanding these mechanisms helps ensure efficient and accurate agent responses. Incoming messages can arrive multiple times, in quick bursts, or with historical context. OpenClaw uses a combination of a short-lived dedupe cache, debounce windows per channel, and clear session mappings to prevent repeated agent runs and noisy processing while preserving important text for commands. OpenClaw keeps a short-lived dedupe cache key by channel, account, peer, session, and message ID to block duplicate agent runs from redelivered messages. This cache is temporary, allowing legitimate replays later, like deliberate message replays or gap recovery. Debouncing groups rapid, consecutive text-only messages from the same sender within a channel and conversation. These messages are buffered for a configurable debounce window, then combined into a single body for one agent run, improving efficiency and context. Only text-only messages are subject to debouncing, allowing them to be grouped and processed together for better context and reduced duplicate runs. Messages containing media or attachments bypass the debounce window and trigger immediate processing to ensure timely handling of rich content. Explicit control commands are processed immediately without debouncing to ensure urgent directives are handled promptly. Some channels may allow coalescing of direct messages from the same sender, but this is channel specific. The debounce window can be set globally and overridden per channel. This flexibility lets operators balance responsiveness and batching based on channel characteristics. Here is an example JSON configuration setting the default debounce to 2000 milliseconds with longer debounce for WhatsApp and shorter for Slack and Discord. Adjust these values carefully to optimize latency and batching. Setting debounce too high causes slow replies and a sluggish gateway. Too low reduces batching benefits and may allow duplicate runs if upstream providers resend messages rapidly. Finding the right balance is key. Sessions are maintained by the gateway with distinct keys per group conversation and channel type. Direct chats usually map to a main session key per peer ensuring that group context doesn't leak and transcripts remain consistent. Open Claw distinguishes three inbound message forms to handle raw input and context properly. This separation helps the agent parse commands accurately while maintaining full conversational context. The body is the full prompt the agent receives including any history or contextual scaffolding the gateway adds to provide conversational context. Command body contains the raw user input text intended for command parsing and directive detection ensuring parsers see exactly what the user sent. Raw body is a legacy term equivalent to command body, used interchangeably in the system. When a channel provides message history, set command body to the original message text for accurate parsing, and set body to the combined prompt including history, so the agent has full context. The gateway keeps a short pending buffer of messages that didn't trigger runs, like those merged during debouts. These buffers aren't part of the committed session transcript and don't duplicate stored entries. Their size can be configured globally and per channel. Here's a quick checklist for channel integrators to ensure proper inbound handling and session management in OpenClaw. Stable message IDs are essential for deduplication to work correctly and prevent duplicate agent runs. For channels that send message history, keep the original text in command body and the combined prompt in body to maintain parsing accuracy and context. Adjust debouts timings per channel to balance response latency and batching benefits, avoiding values that are too high or too low. Make sure media attachments are flagged correctly, so they skip the text debounce window and get processed immediately as intended. In this section, we'll explore how OpenClaw manages inbound messages using a command queue. We'll cover lane-based concurrency, session serialization, and different queue modes that control message processing. Inbound messages that trigger automatic replies don't go directly to the model. Instead, OpenClaw uses an in-process FIFO queue that is aware of lanes. This prevents reply collisions within the same session and lets operators manage concurrency and overflow. Let's look closer at how the queue works. It uses lanes to organize work, caps to limit concurrency, and maps sessions to lanes to ensure serialized processing per session. Each lane serializes runs in FIFO order and has a configurable concurrency cap. If no cap is set, it defaults to one. Built-in lanes have higher caps like four for main and eight for sub-agent with a global maximum enforced by agents.default.max.concurrent. When work is enqueued by session key, the queue uses a lane named session key. This ensures only one active run per session executes at a time, preserving per session serialization while allowing other lanes to run in parallel. The queue runs entirely in process using TypeScript and promises. There are no external background workers by default. Adding lanes lets you run background tasks without blocking reply lanes. Queue modes determine how inbound messages are combined or sequenced before processing. Choosing the right mode affects reply behavior and concurrency. The collect mode, which is the default, gathers input over a debounce window and produces a single reply. This mode is safe when you want one response per inbound message. Steer mode lets the agent adjust a single reply based on the latest input similar to collect but focused on steering the response dynamically. Follow-up mode enqueues messages as non-debounced follow-up runs, allowing immediate processing without waiting to batch inputs. Steer backlog processes backlog items but can generate duplicate follow-ups under load, so it's not recommended when you want exactly one response per inbound. Interrupt mode aborts any currently running reply and immediately starts a new one. Useful for urgent or changing inputs. For workflows needing one response per inbound message, collect or steer modes are recommended. Avoid steer backlog if you want to prevent duplicate or unexpected follow-ups. Here is a canonical JSON configuration block for the messages.q settings. This can be placed directly in your config file to control queue behavior. This JSON sets the queue mode to collect with a 1,000 millisecond debounce window. It limits queued messages per session to 20 and uses summarize as the overflow policy. The Discord channel uses collect mode specifically. Let's break down the key fields in the queue configuration and what each controls. The mode field sets the default queue behavior. If not specified, it defaults to collect. You can override this per session if needed. Debounce ms defines the quiet wait window in milliseconds to batch rapid successive inbound messages into a single processing run. The cap limits how many messages can be queued per session before overflow handling kicks in. The drop field defines how to handle messages when the cap is exceeded, controlling overflow behavior. The old policy drops the oldest queued messages first when overflow occurs. The new policy drops incoming messages that exceed the cap, preserving the existing queue. Summarize collapses overflowed messages into a single summarized run, helping preserve intent under heavy load. The by channel field lets you set default queue modes for specific channels like Discord, overriding the global mode. You can set per session queue mode overrides using the {slash} queue command. Use {slash} queue default or {slash} queue reset to clear overrides. This is handy for debugging or temporary changes without editing config files. Imagine a busy chat where many messages arrive quickly for one session and the cap of 20 is reached. With drop set to summarize, Openclaw collapses the overflow into a single summary run, preserving context and enabling a coherent reply instead of multiple partial or lost messages. Here are some tips to troubleshoot queue-related issues. If command seems stuck, enable verbose logs and look for lines like queued for x ms. These indicate queue depth and how long items are waiting. If you see duplicated follow-ups under load, check if the session mode is steer backlog. Switching to collect or steer can fix this. Increase the cap for sessions with legitimate high message volume or add separate lanes for background tasks to avoid blocking main reply lanes. For temporary experiments, use the {slash} queue command to toggle modes per session without needing to reload or edit configs. Finally, here are some operational tips to optimize queue behavior. Adjust debounce ms to balance latency and combined context. A higher value reduces duplicate replies, but increases perceived response delay. Set agents.default.max concurrent to enforce a global concurrency limit across all lanes. Add lanes only if you need parallelism for non-conflicting tasks. More lanes increase concurrency and CPU usage, so use them judiciously. In this section, we'll explore how retry policies work on a per request basis in Openclaw and how different providers influence retry behavior. Understanding these nuances is key to building reliable integrations. Openclaw treats each network send as a single HTTP operation for retries, such as sending a message or uploading media. Importantly, retries happen per request, not across multi-step flows. This means if part of a flow succeeds before a failure, naive retries can cause duplicates or inconsistent states unless the flow is designed carefully. The default retry settings in Open Claw are conservative to avoid excessive retries. They include three attempts, an exponential backoff capped at 30 seconds, and a small jitter to prevent synchronized retries. Some providers also require minimum delays between requests for optimal behavior. The system tries up to three times before giving up, balancing reliability and avoiding excessive retries. The maximum delay between retries is capped at 30,000 milliseconds or 30 seconds to prevent long waits. A jitter of 0.1 adds randomness to retry timing, reducing the chance of many clients retrying simultaneously. Some providers like Telegram and Discord perform best with minimum delays between requests. Around 400 milliseconds for Telegram and 500 milliseconds for Discord. Retry settings can be tuned per channel in the gateway configuration. This allows customizing retry behavior to fit each provider's needs. Here is a sample JSON snippet showing retry settings for Telegram and Discord channels, specifying attempts, minimum delay, maximum delay, and jitter. Different providers have unique retry behaviors that integrations must handle. Understanding these helps you tune retries properly and avoid issues. Discord triggers retries only on rate limit responses indicated by HTTP 429. If Discord provides a retry underscore after value, Open Claw respects it. Otherwise, it falls back to exponential back off. Telegram retries on transient errors like HTTP 429, timeouts, or connection resets. It also respects the retry underscore after field. However, some errors like markdown parse failures are not retried. Instead, the client should fall back to plain text. It's important to mark errors that should not be retried, such as syntax errors, permanent authentication failures, and domain-specific parse errors. This prevents wasting retry attempts on failures that won't succeed. To prevent duplicate side effects in multi-step flows, make each step item potent or checkpoint progress on the server. This ensures retries don't cause inconsistent states. One strategy is to make uploads deterministic and store return resource IDs. Later steps can check if the upload succeeded and reuse the ID instead of retrying blindly. Another approach is to split composite flows into atomic steps that record completion, such as via a marker file or database record before proceeding to the next step. Where supported by providers, use the duplication tokens or idempotency keys to ensure operations that create state are not repeated during retries. Finally, test retry behavior in staging or with low-traffic accounts. Simulate rate limits and transient failures to verify retry underscore after handling, minimum delays, and non-retrievable error detection. Adjust min delay amps and attempts to balance reliability and duplicate risk. In this section, we'll explore how streaming and chunking work in Open claw, focusing on block streaming, coalescing of message chunks, and pacing to create natural conversational flows. This diagram shows how model output events are processed. The chunker collects token deltas and emits blocks either when a text end is reached or at the message end, depending on configuration. These blocks are then sent as channel messages. Open claw separates streaming into two layers, block streaming, which sends complete message blocks as channel messages, and preview streaming, which updates a single temporary message with patches. Token deltas are first combined into blocks before streaming. Control over block streaming behavior is managed through agent configuration settings. These determine how and when blocks are emitted during streaming. Individual channels can override the default block streaming settings using their own per channel block streaming configurations, allowing tailored streaming behavior. This setting enables block streaming by default for agents, turning on block emission unless overridden. This option controls when a chunker flushes blocks, either after each text segment ends or only at the end of the full message. These parameters configure the chunker's behavior, setting minimum and maximum chunk sizes and preferred breakpoints for splitting text. The embedded block chunker applies specific rules to convert model token deltas into well-formed blocks for streaming. A minimum character threshold ensures the chunker avoids emitting very small fragments by waiting until enough text accumulates. The chunker tries to split text at natural boundaries in this order, preferring paragraph breaks first, then new lines, sentences, white space, and finally force breaks. A maximum character limit caps chunk size if no natural break is found. The chunker splits forcibly and ensures markdown fences remain balanced by closing and reopening them as needed. Coalescing combines consecutive blocks into fewer messages by waiting a configurable idle time after the last delta, reducing fragmentation while respecting min and max chunk sizes. The human delay setting inserts a randomized pause between emitted blocks to create a more natural conversational flow, useful when multiple bubbles are sent. Let's review how these configuration options map to practical streaming modes and how to adjust them for different use cases. To stream blocks as the chunker determines natural breaks, enable block streaming by default and set the break to text end, allowing paragraph level streaming. To emit only one final message after all content is ready, set the break to message end so the chunker buffers everything until completion. Block streaming is disabled by default unless explicitly enabled globally or overridden by specific channel settings. Here's a recommended setup for assistants that produce longer, more conversational replies with natural streaming. Raising max chars lets the chunker emit longer message bubbles, but keep it within your channel size limits to avoid truncation. Increasing min chars reduces the number of very short message fragments, making streaming smoother and less fragmented. Setting the break at text end lets natural paragraphs stream as they complete, improving readability and flow. Adding a human delay between 250 and 750 milliseconds creates a more conversational rhythm by spacing out message bubbles. Now let's cover common issues and how to troubleshoot them when using block streaming. Broken code fences usually mean max chars is too low. Increasing it helps keep fence code blocks whole within a single chunk. To reduce tiny fragmented bubbles, raise min chars or increase the idle ms coalescing delay to join more deltas together. When messages are too large for a channel, reduce max chars or turn off block streaming for that channel to avoid delivery issues. If you want incremental preview updates, but only get final blocks, verify that the channel client supports and uses preview streaming, which is separate from block streaming. Remember that channel size and rate limits interact with all chunking parameters. Always validate limits and test long replies after tuning chunk sizes, idle time, and pacing.