OpenClaw Channel-Routing: Mehrere Kanäle und Agenten sauber zuordnen

Ein OpenClaw-Gateway nimmt Nachrichten aus Telegram, WhatsApp, Discord und Slack gleichzeitig an. Welcher Agent eine Nachricht bearbeitet, legst du über bindings fest. Laut Kanalrouting-Dokumentation von OpenClaw geht die Antwort danach deterministisch an den Kanal zurück, aus dem die Nachricht kam. Das Modell sucht sich den Rückweg nicht selbst aus.

Fehler passieren trotzdem. Ein zu breites Binding fängt Nachrichten ab, die für einen anderen Agenten gedacht waren. Oder ein Agent, der Telegram- und WhatsApp-DMs bedient, nimmt Wissen aus dem einen Gespräch ins andere mit, weil unter der Standardeinstellung alle Direktnachrichten in derselben Hauptsession landen. Dieses Tutorial richtet enge Zuordnungen ein und prüft anschließend jede Etappe einzeln, vom Eingang bis zur sichtbaren Antwort.

Was du vor dem Ändern brauchst

Mindestens zwei Agenten und die gewünschten Kanäle sollten bereits laufen. Für die Konfiguration zählen technische Bezeichner, keine Anzeigenamen: die Agent-IDs, der interne Kanalname wie telegram oder slack, bei mehreren Konten die jeweilige accountId und für enge Zuordnungen die Peer-ID des Testchats.

Leg pro Route einen unkritischen Testchat an. Sichere die aktive Gateway-Konfiguration, bevor du Bindings änderst. Tokens gehören weder in Testprotokolle noch in Screenshots.

Fehlt die Grundkonfiguration noch, beginne mit dem Guide zum OpenClaw-Gateway mit JSON5. Telegram und WhatsApp verbindest du mit dem Tutorial Telegram und WhatsApp verbinden. Die Grundlagen für Slack mit App, Mentions und Kanälen erklärt der Beitrag Slack mit OpenClaw verbinden.

Rückweg und Kontext sind zwei Paar Schuhe

channel bezeichnet das Kanal-Plugin, accountId eine Konto-Instanz innerhalb dieses Kanals, sofern er mehrere Konten unterstützt. agentId wählt laut OpenClaw-Doku einen isolierten Arbeitsbereich mit eigenem Sitzungsspeicher. Am häufigsten unterschätzt wird aber der Session-Schlüssel, denn er entscheidet, welche Nachrichten einen gemeinsamen Verlauf haben.

Eine Telegram-Nachricht kann also korrekt nach Telegram beantwortet werden und trotzdem Kontext aus einer WhatsApp-DM von gestern mitbringen. Unter dem Standardwert session.dmScope: "main" ist genau das vorgesehen: Direktnachrichten aus allen Kanälen laufen in der Hauptsession des Agenten zusammen, erkennbar an einem Schlüssel wie agent:main:main.

Das übersieht man leicht.

Gruppen und Kanäle bleiben dagegen laut Dokumentation pro Kanal getrennt. webchat ist der interne Kanal der WebChat-Oberfläche und kein konfigurierbarer ausgehender Kanal.

Schritt 1: Bindings möglichst eng festlegen

Das folgende JSON5-Beispiel zeigt drei unterschiedlich breite Zuordnungen. Die IDs sind Platzhalter für dein Setup:

{
  bindings: [
    {
      agentId: "support",
      match: {
        channel: "telegram",
        accountId: "support-bot",
        peer: {
          kind: "group",
          id: "-100123",
        },
      },
    },
    {
      agentId: "operations",
      match: {
        channel: "slack",
        accountId: "work",
      },
    },
    {
      agentId: "private",
      match: {
        channel: "whatsapp",
      },
    },
  ],
}

Das Telegram-Binding greift nur für eine einzige Gruppe, und auch nur über das Konto support-bot. Dafür müssen laut Doku alle angegebenen Felder des match-Blocks passen. Das Slack-Binding erfasst das komplette Konto work. Am breitesten ist die WhatsApp-Regel: Sie übernimmt jede zugelassene WhatsApp-Nachricht, für die keine genauere Zuordnung existiert.

Welche Regel gewinnt, beschreibt die Kanalrouting-Dokumentation als feste Rangfolge. Ein exakter Peer schlägt Thread-Vererbung und Peer-Platzhalter, danach folgen Discord-Guild mit Rollen, Discord-Guild und Slack-Team, dann das Konto, dann der gesamte Kanal und zuletzt der Standard-Agent. Verlass dich bei überlappenden Regeln also nicht auf ihre Position in der Datei, sondern prüf, welches Binding den konkreten Eingang am genauesten beschreibt.

Ich würde jedes neue Setup mit Peer- oder Konto-Bindings beginnen und kanalweite Regeln erst dann ergänzen, wenn wirklich jede zugelassene Nachricht dieses Kanals zum selben Agenten gehören soll.

Schritt 2: DM-Kontext bewusst festlegen

Sollen Direktnachrichten aus verschiedenen Kanälen keinen gemeinsamen Verlauf haben, setze den Geltungsbereich explizit:

{
  session: {
    dmScope: "per-channel-peer",
  },
}

Neben dem Standard main dokumentiert OpenClaw drei Alternativen: per-peer, per-channel-peer und per-account-channel-peer. Alle drei halten DMs in getrennten Sessions. Die Namen zeigen, was jeweils getrennt wird: der Absender, zusätzlich der Kanal, zusätzlich das Konto. Bei mehreren Konten im selben Kanal ist per-account-channel-peer damit die feinste Variante. Soll eine Person kanalübergreifend bewusst denselben Kontext behalten, bleibt main die richtige Wahl.

Einzelne Bindings können den globalen Wert über bindings[].session.dmScope überschreiben. Setz das sparsam ein, denn jede Ausnahme ist später eine zusätzliche Hypothese bei der Fehlersuche.

Schritt 3: Standardkonto für ausgehende Pfade bestimmen

Die accountId in einem Binding bezieht sich nur auf den Eingang. Welches Konto ein ausgehender Pfad ohne explizite accountId nutzt, regelt laut Doku separat channels.<channel>.defaultAccount:

{
  channels: {
    telegram: {
      defaultAccount: "support-bot",
    },
  },
}

Fehlt dieser Wert und sind zwei oder mehr Konten konfiguriert, kann das Fallback-Routing eine normalisierte Konto-ID wählen. Ein korrektes eingehendes Binding ändert daran nichts.

Schritt 4: Konfiguration validieren und laden

Prüfe die Konfiguration, bevor das Gateway sie lädt:

openclaw config validate

Laut CLI-Referenz prüft der Befehl die aktive Konfiguration gegen das Schema, ohne das Gateway zu starten. Falsch verschachtelte Blöcke oder ungültige Werte korrigierst du vor dem Laden. Danach startest oder lädst du das Gateway auf dem Weg neu, den deine Installation vorsieht, etwa als interaktiven Prozess oder als Systemdienst. Meldet der neue Prozess Konfigurationsfehler, schick noch keine Testnachrichten.

Schritt 5: Kanalverbindungen und Sessions getrennt prüfen

Zuerst die Erreichbarkeit:

openclaw channels status --probe

Der Befehl zeigt den Zustand der Kanäle, über die Zuordnung von Agenten sagt er nichts. Umgekehrt ist auch eine Session-Liste kein Verbindungstest. Laut CLI-Referenz kann sich ein Kanal neu verbinden, ohne dass eine Session-Zeile entsteht, bis die erste Nachricht verarbeitet wird.

Schick deshalb pro Route genau eine erkennbare Testnachricht und liste danach die kürzlich aktiven Sessions aller Agenten auf:

openclaw sessions --all-agents --active 10 --json

Am Schlüssel lässt sich beides ablesen, Agent und Kontext. Laut Doku haben Gruppen-Sessions die Form agent:<agentId>:<channel>:group:<id>. Für die Telegram-Gruppe aus dem Beispiel sollte also agent:support:telegram:group:-100123 auftauchen. Mit per-channel-peer müssen DMs desselben Absenders aus Telegram und WhatsApp getrennte Schlüssel ergeben. Unter main ist eine gemeinsame Hauptsession das erwartete Ergebnis.

Für die laufende Diagnose hilft zusätzlich:

openclaw logs --follow

Nachrichtentexte und personenbezogene IDs haben im Protokoll nichts zu suchen, wenn gekürzte oder pseudonymisierte Angaben reichen.

Schritt 6: Jede Route einzeln abnehmen

Erweitere das Setup erst, wenn jede vorhandene Route den erwarteten Ausgang zeigt:

Routing und Berechtigung sind getrennte Prüfungen. bindings wählen den Agenten, während Allowlisten, Gruppenfreigaben und Mention-Regeln entscheiden, ob eine Nachricht überhaupt verarbeitet wird. Eine passende Route setzt diese Kontrollen nicht außer Kraft.

Was Routing nicht leistet

Eine Prompt-Anweisung wie „Antworte über Telegram“ verändert weder das Binding noch zuverlässig das Ziel. Für einen bewussten Versand in einen anderen Kanal brauchst du ein dafür vorgesehenes Messaging-Werkzeug und ein eindeutiges Ziel. Laut Kanalrouting-Doku müssen Provider-Präfixe wie telegram:123 zum gewählten Kanal passen. Eine WhatsApp-Zustellung an ein Telegram-Ziel schlägt fehl, bevor das Plugin das Ziel überhaupt normalisiert.

Auch Broadcast-Gruppen sind kein allgemeines Multi-Agent-Routing. Die Dokumentation führt sie als experimentell und beschränkt sie auf WhatsApp über den Webkanal. Andere Kanäle ignorieren die broadcast-Konfiguration. Dort führt eine eingehende Nachricht mehrere Agenten aus, jeden in einer eigenen Session und mit eigener Antwort. broadcast hat Vorrang vor gewöhnlichen Bindings, prüft aber weiter Zulassung und Gruppenaktivierung. Die Funktion bestimmt nur, welche Agenten laufen, nicht, ob eine Nachricht verarbeitet werden darf.

Fehlersuche und Rücknahme

Reagiert der falsche Agent, such zuerst nach einem spezifischeren Peer- oder Konto-Binding. Prüf dann, ob wirklich jedes Feld im erwarteten match-Block zum Eingang passt.

Bringt der richtige Agent Kontext aus einem anderen Kanal mit, liegt die Ursache in session.dmScope oder in einem Override unter bindings[].session.dmScope.

Geht die Antwort über das falsche Konto raus, betrachte das eingehende accountId und das ausgehende defaultAccount getrennt. Beide können unabhängig voneinander falsch sein.

Bleibt ein Kanal komplett stumm, beginne mit openclaw channels status --probe und den Logs. Eine leere Session-Liste ersetzt diese Verbindungsprüfung nicht.

Lässt sich der Weg einer Nachricht nicht eindeutig erklären, nimm das neue Binding wieder heraus oder spiel die gesicherte Konfiguration zurück, validiere sie und lade das Gateway neu. Weiter testest du erst, wenn der alte Zustand wieder läuft, und dann mit einem engeren Match.

Wann eine Route wirklich funktioniert

Eine sichtbare Antwort reicht für die Abnahme nicht. Schick eine eindeutig erkennbare Testnachricht und prüf anschließend anhand von Session-Key und Logs, welcher Agent über welches Konto geantwortet hat und ob die Antwort im ursprünglichen Gespräch angekommen ist.

Das Binding bestimmt den Agenten, dmScope den DM-Kontext und defaultAccount das ausgehende Fallback-Konto. Wer diese Stellschrauben getrennt testet, entdeckt spätestens beim zweiten Konto oder bei der nächsten Gruppe, ob eine Route nur technisch reagiert oder auch betrieblich korrekt eingerichtet ist.