OpenClaw Nachrichten-Flow: Messaging-Logik optimieren

Kennst du das Problem? Du baust einen Bot und plötzlich schickt ein User fünf Nachrichten hintereinander ab, oder die API liefert dieselbe Nachricht aufgrund eines Reconnects doppelt aus. Das Handling von Nachrichtenflüssen kann schnell im Chaos enden, besonders wenn verschiedene Channels und asynchrone Agent-Runs zusammenkommen.

OpenClaw löst diese Probleme durch eine strukturierte Verarbeitung. Hier erfährst du, wie das System mit Inbound-Nachrichten, Sessions, Queueing und Streaming umgeht, damit deine Agenten-Interaktionen stabil und vorhersehbar bleiben.

Nachrichtenfluss (High-Level)

Der Weg einer Nachricht durch das System folgt einer klaren Logik:

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

Die wichtigsten Stellschrauben findest du in der Konfiguration:

• messages.* für Präfixe, Queueing und das Verhalten in Gruppen.
• agents.defaults.* für Block-Streaming und Chunking-Standardwerte.
• Channel-Overrides (channels.whatsapp.*, channels.telegram.*, etc.) für Limits und Streaming-Optionen.

Schau dir die Configuration für das vollständige Schema an.

Inbound-Deduplizierung

Channels senden dieselbe Nachricht manchmal mehrfach, zum Beispiel nach einem Reconnect. OpenClaw nutzt einen kurzlebigen Cache, der auf Channel, Account, Peer, Session und Message-ID basiert. So verhindern wir, dass doppelte Zustellungen einen weiteren Agent-Run auslösen.

Inbound-Debouncing

Wenn ein derselbe Absender schnell hintereinander Nachrichten schickt, können diese über messages.inbound zu einem einzigen Agent-Turn zusammengefasst werden. Das Debouncing funktioniert pro Channel und Konversation. Für das Threading der Antwort wird die aktuellste Nachricht verwendet.

Konfiguration (globaler Standard + Overrides pro Channel):

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

Wichtige Details:

• Debouncing gilt nur für Textnachrichten; Medien und Anhänge werden sofort verarbeitet.
• Control-Commands umgehen das Debouncing, damit sie eigenständig bleiben.

Sessions und Geräte

Sessions gehören dem Gateway, nicht den Clients.

• Direkte Chats werden im Haupt-Session-Key des Agenten zusammengefasst.
• Gruppen und Channels erhalten eigene Session-Keys.
• Der Session-Store und die Transkripte liegen auf dem Gateway-Host.

Mehrere Geräte oder Channels können auf dieselbe Session verweisen, aber die Historie wird nicht vollständig an jeden Client zurücksynchronisiert. Wir empfehlen, ein primäres Gerät für lange Konversationen zu nutzen, um Kontext-Abweichungen zu vermeiden. Das Control UI und das TUI zeigen immer das vom Gateway gesicherte Transkript und sind somit die “Source of Truth”.

Details findest du unter Session management.

Inbound-Bodies und Historien-Kontext

OpenClaw unterscheidet zwischen dem Prompt-Body und dem Command-Body:

• Body: Der Prompt-Text, der an den Agenten geht. Er kann Channel-Informationen und optionale Historien-Wrapper enthalten.
• CommandBody: Der rohe User-Text für das Parsing von Direktiven und Befehlen.
• RawBody: Ein Legacy-Alias für CommandBody (aus Kompatibilitätsgründen beibehalten).

Wenn ein Channel eine Historie liefert, nutzt er einen gemeinsamen Wrapper:

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

In Nicht-Direkt-Chats (Gruppen, Channels, Räume) wird dem aktuellen Message-Body das Label des Absenders vorangestellt. Das sorgt für Konsistenz zwischen Echtzeit-Nachrichten und Nachrichten aus der Queue oder Historie im Agent-Prompt.

Historien-Buffer sind Pending-only: Sie enthalten Gruppennachrichten, die keinen Run ausgelöst haben (z. B. Nachrichten ohne Erwähnung), und schließen Nachrichten aus, die bereits im Session-Transkript stehen.

Das Entfernen von Direktiven (Directive Stripping) erfolgt nur im Bereich der aktuellen Nachricht, damit die Historie intakt bleibt. Channels, die Historie einbetten, sollten CommandBody (oder RawBody) auf den Originaltext setzen und Body für den kombinierten Prompt nutzen. Die Buffer sind über messages.groupChat.historyLimit und Channel-Overrides wie channels.slack.historyLimit konfigurierbar (Wert 0 deaktiviert die Funktion).

Queueing und Follow-ups

Falls bereits ein Run aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den aktuellen Run gesteuert oder für einen Follow-up-Turn gesammelt werden.

• Konfiguration über messages.queue (und messages.queue.byChannel).
• Modi: interrupt, steer, followup, collect, sowie Backlog-Varianten.

Details unter Queueing.

Streaming, Chunking und Batching

Block-Streaming sendet Teilantworten, während das Modell Textblöcke generiert. Das Chunking achtet auf Textlimits der Channels und vermeidet es, Code-Blöcke zu zerschneiden.

Wichtige Einstellungen:

• agents.defaults.blockStreamingDefault (on|off, Standard ist off)
• agents.defaults.blockStreamingBreak (text_end|message_end)
• agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
• agents.defaults.blockStreamingCoalesce (Idle-basiertes Batching)
• agents.defaults.humanDelay (menschlich wirkende Pause zwischen Antworten)
• Channel-Overrides: *.blockStreaming und *.blockStreamingCoalesce (Nicht-Telegram-Channels benötigen explizit *.blockStreaming: true)

Details unter Streaming + chunking.

Reasoning-Sichtbarkeit und Tokens

OpenClaw kann das Reasoning des Modells ein- oder ausblenden:

• /reasoning on|off|stream steuert die Sichtbarkeit.
• Reasoning-Inhalte zählen zum Token-Verbrauch, wenn das Modell sie generiert.
• Telegram unterstützt das Streaming von Reasoning direkt in die “Draft-Bubble”.

Details unter Thinking + reasoning directives und Token use.

Präfixe, Threading und Antworten

Die Formatierung ausgehender Nachrichten ist zentral in messages geregelt:

• messages.responsePrefix, channels.<channel>.responsePrefix und channels.<channel>.accounts.<id>.responsePrefix bilden die Kaskade für Outbound-Präfixe. Dazu kommt channels.whatsapp.messagePrefix für Inbound-Präfixe bei WhatsApp.
• Reply-Threading wird über replyToMode und Channel-Standards gesteuert.

Details in der Configuration und den Channel-Docs.

Verwandte Themen

• Streaming — Echtzeit-Zustellung von Nachrichten
• Retry — Verhalten bei Wiederholungsversuchen
• Queue — Warteschlange für die Nachrichtenverarbeitung
• Channels — Integrationen für Messaging-Plattformen

Nächste Schritte

• Schau dir das Session management an, um zu verstehen, wie Daten gespeichert werden.
• Optimiere dein Streaming für eine bessere User Experience.

AI Setup Assistant