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

Ein OpenClaw-Gateway kann Nachrichten aus Telegram, WhatsApp, Discord oder Slack gleichzeitig annehmen. Welche Arbeitsumgebung eine Nachricht verarbeitet, legst du mit bindings fest. Die normale Antwort geht anschließend deterministisch in das Gespräch zurück, aus dem die Nachricht kam. Das Modell sucht den Rückkanal nicht selbst aus.

Das verhindert allerdings keine Fehler durch zu breite Bindings, verwechselte Konten oder unerwartet gemeinsam genutzte Sessions. Dieses Tutorial richtet deshalb eindeutige Zuordnungen ein und prüft danach Kanal, Konto, Agent, Session und tatsächliches Antwortziel getrennt.

Was du vor dem Ändern brauchst

Für den Ablauf sollten bereits mindestens zwei Agenten und die gewünschten Kanäle eingerichtet sein. Notiere dir:

• die vorhandenen Agent-IDs,
• den internen Kanalnamen wie telegram, slack oder whatsapp,
• bei mehreren Konten die jeweilige accountId,
• für eine enge Zuordnung die Peer-ID des Testchats,
• einen unkritischen Testchat pro Route.

Agent-IDs und accountId sind technische Bezeichner. Anzeigenamen aus Telegram oder Slack reichen als Ersatz nicht aus. Kopiere außerdem die aktive Gateway-Konfiguration an einen geschützten Ort, bevor du Bindings änderst. Tokens und andere Zugangsdaten gehören weder in Testprotokolle noch in Screenshots.

Wenn du die Grundkonfiguration noch nicht eingerichtet hast, beginne mit dem Guide zum OpenClaw-Gateway mit JSON5. Telegram und WhatsApp richtest du vor dem Routing mit dem Tutorial Telegram und WhatsApp verbinden ein. Für Slack beschreibt der Beitrag Slack mit OpenClaw verbinden die benötigte App-, Mention- und Kanalbasis.

Channel, Account, Agent und Session

Vier Angaben bestimmen unterschiedliche Teile des Ablaufs:

• channel bezeichnet das Kanal-Plugin, beispielsweise telegram, whatsapp, discord oder slack.
• accountId bezeichnet eine konkrete Konto-Instanz innerhalb eines Kanals, sofern dieser mehrere Konten unterstützt.
• agentId bestimmt die isolierte Arbeitsumgebung, die die Nachricht verarbeitet.
• Die Session hält den Gesprächskontext und steuert, welche Nachrichten denselben Verlauf teilen.

Der Rückweg und der Session-Kontext sind nicht dasselbe. Eine Telegram-Nachricht kann korrekt nach Telegram beantwortet werden und trotzdem Kontext mit einer vorherigen WhatsApp-DM teilen. Unter dem Standardwert session.dmScope: "main" laufen Direktnachrichten verschiedener Kanäle in der Hauptsession desselben Agenten zusammen.

webchat ist der interne Kanal der WebChat-Oberfläche. Er ist kein frei konfigurierbarer ausgehender Messaging-Kanal.

Schritt 1: Bindings möglichst eng festlegen

Das folgende JSON5-Beispiel zeigt drei unterschiedlich breite Zuordnungen. Ersetze Agenten-, Konto- und Peer-IDs durch Werte aus deinem Setup:

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

Das Telegram-Binding gilt nur für die angegebene Direktnachricht über das Konto support-bot. Das Slack-Binding erfasst das gesamte Konto work. Das WhatsApp-Binding erfasst jede zugelassene WhatsApp-Nachricht, für die keine spezifischere Zuordnung greift.

Mehrere Felder innerhalb eines match-Blocks werden gemeinsam ausgewertet: Channel, Konto und Peer müssen alle passen. Es genügt nicht, dass nur eines der Felder übereinstimmt.

Für die Auswahl des Agenten sind spezifische Peer-Zuordnungen stärker als reine Konto- oder Channel-Zuordnungen. Danach folgen Konto-, Channel- und schließlich Standard-Agent-Regeln. Verlasse dich bei überlappenden Regeln daher nicht auf eine vermeintliche Reihenfolge in der Datei. Prüfe, welches Binding den konkreten Eingang am genauesten beschreibt.

Beginne mit Peer- oder Konto-Bindings. Ein kanalweites Binding ist nur sinnvoll, wenn wirklich jede zugelassene Nachricht dieses Kanals zum selben Agenten gehören soll.

Schritt 2: DM-Kontext bewusst festlegen

Wenn Direktnachrichten aus verschiedenen Kanälen keinen gemeinsamen Verlauf verwenden sollen, setze den Session-Geltungsbereich explizit:

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

OpenClaw dokumentiert vier DM-Scopes:

• main: Alle DMs des Agenten teilen dessen Hauptsession. Das ist der Standard.
• per-peer: Jeder Absender erhält eine eigene DM-Session.
• per-channel-peer: Kanal und Absender werden getrennt berücksichtigt.
• per-account-channel-peer: Zusätzlich wird die Konto-Instanz getrennt berücksichtigt.

Für mehrere Konten desselben Kanals liefert per-account-channel-peer die feinste dokumentierte Trennung. Wenn dieselbe Person kanalübergreifend bewusst einen gemeinsamen Kontext erhalten soll, kann main dagegen beabsichtigt sein.

Ein Binding kann den globalen DM-Scope für die von ihm erfassten Peers über bindings[].session.dmScope überschreiben. Nutze solche Ausnahmen sparsam, weil eine Mischung aus globalem und bindingspezifischem Scope die Diagnose erschwert.

Schritt 3: Standardkonto für ausgehende Pfade bestimmen

accountId in einem Binding beschreibt das Konto des eingehenden Matchs. Davon getrennt bestimmt channels.<channel>.defaultAccount, welches Konto ein ausgehender Pfad ohne ausdrücklich angegebene accountId verwendet.

Bei mehreren Konten eines unterstützten Kanals solltest du den Standard festlegen:

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

Ohne expliziten Standard kann das Fallback-Routing anhand der normalisierten Konto-ID-Reihenfolge ein nicht beabsichtigtes Konto auswählen. Ein korrektes eingehendes Binding ersetzt diese ausgehende Voreinstellung nicht.

Schritt 4: Konfiguration validieren und laden

Prüfe die aktive Konfiguration vor dem Neustart oder Reload des Gateways:

openclaw config validate

Der Schritt ist erfolgreich, wenn die Validierung ohne Konfigurationsfehler endet. Eine unbekannte Agent-ID, ein falsch geschachtelter Block oder ein ungültiger Wert muss vor dem Laden korrigiert werden.

Lade beziehungsweise starte das Gateway danach über den Betriebsweg neu, den du für deine Installation verwendest. Das kann ein interaktiv gestarteter Prozess oder ein Dienst des Betriebssystems sein. Fahre nicht mit Testnachrichten fort, solange der neue Gateway-Prozess Konfigurationsfehler meldet.

Schritt 5: Kanalverbindungen und Sessions getrennt prüfen

Prüfe, ob die konfigurierten Kanäle erreichbar sind:

openclaw channels status --probe

Dieser Aufruf prüft den Kanalzustand. Er belegt noch nicht, dass die Nachricht beim gewünschten Agenten oder in der vorgesehenen Session gelandet ist.

Sende anschließend genau eine erkennbare Testnachricht pro Route. Liste danach die kürzlich aktiven Sessions aller Agenten auf:

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

Prüfe in der Ausgabe mindestens die Agent-Zuordnung und den verwendeten Session-Kontext. Bei per-channel-peer müssen DMs desselben Absenders aus Telegram und WhatsApp getrennte Sessions ergeben. Bei main ist eine gemeinsame Hauptsession dagegen das erwartete Verhalten.

Für den Annahmepfad kannst du zusätzlich die Kanal-Logs heranziehen:

openclaw channels logs --channel telegram

Bei einer laufenden Diagnose hilft außerdem:

openclaw logs --follow

Achte auf Kanal, Konto, Agent und Session. Protokolliere keine Tokens, Nachrichtentexte oder personenbezogenen IDs, wenn für den Test gekürzte oder pseudonymisierte Angaben genügen.

Schritt 6: Jede Route einzeln abnehmen

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

Routing und Berechtigung sind getrennte Prüfungen. bindings wählen den Agenten. Kanalrichtlinien, Allowlisten, Gruppenfreigaben und Mention-Regeln bestimmen, ob die Nachricht überhaupt verarbeitet werden darf. Eine passende Route hebt diese Zugriffskontrollen nicht auf.

Warum eine Prompt-Anweisung keine Route ersetzt

Eine normale Antwort folgt dem vom Gateway bestimmten Rückweg. Die Anweisung „Antworte über Telegram“ ändert weder das eingehende Binding noch zuverlässig den Zielkanal.

Für einen bewussten kanalübergreifenden Versand brauchst du ein dafür vorgesehenes Messaging-Werkzeug und ein eindeutiges Ziel. Provider-Präfixe müssen zum ausgewählten Kanal passen; eine WhatsApp-Zustellung an ein Telegram-Ziel soll nicht als Abkürzung für kanalübergreifendes Routing dienen.

Broadcast ist kein allgemeines Multi-Agent-Routing

Broadcast-Gruppen sind experimentell und laut aktueller Dokumentation auf WhatsApp über den Webkanal begrenzt. Sie führen mehrere Agenten für dieselbe eingehende Nachricht aus. Jeder Agent arbeitet in einer isolierten Session und veröffentlicht eine eigene Antwort.

Broadcast wird nach den Zulassungs- und Gruppenaktivierungsregeln ausgewertet. Die Funktion ändert, welche Agenten ausgeführt werden, aber nicht, ob die Nachricht verarbeitet werden darf. Für Telegram, Slack oder Discord ist sie keine allgemeine Alternative zu bindings.

Fehlersuche und Rücknahme

Wenn der falsche Agent reagiert, suche nach einem spezifischeren Peer- oder Konto-Binding. Prüfe anschließend, ob alle Felder des erwarteten match-Blocks tatsächlich zum Eingang passen.

Wenn der richtige Agent antwortet, aber Kontext aus einem anderen Kanal auftaucht, kontrolliere session.dmScope sowie mögliche Overrides unter bindings[].session.dmScope.

Wenn die Antwort über das falsche Konto versendet wird, trenne das eingehende accountId vom ausgehenden defaultAccount und prüfe beide Werte.

Bleibt ein Kanal vollständig still, beginne mit openclaw channels status --probe und den Kanal-Logs. Eine leere Session-Liste ist kein Ersatz für diese Verbindungsprüfung.

Kannst du den Annahmepfad nicht eindeutig erklären, nimm das neue Binding wieder aus der aktiven Konfiguration oder stelle die zuvor gesicherte Version wieder her. Validiere die zurückgesetzte Konfiguration und lade das Gateway erneut. Setze den Test fort, sobald der ursprüngliche Zustand wieder erreichbar ist, und verwende dann einen engeren Match.

Kernpunkte

Eine Route ist abgenommen, wenn du für eine Testnachricht Eingangskanal, beteiligtes Konto, ausgewählten Agenten, verwendete Session und tatsächliches Antwortziel belegen kannst. Das Binding bestimmt den Agenten, dmScope den DM-Kontext und defaultAccount das ausgehende Fallback-Konto. Kanalstatus, Session-Liste und Logs prüfen jeweils einen anderen Teil dieses Ablaufs.

Beim zusätzlichen Konto oder einem neuen Gruppenraum verhindert diese Trennung, dass ein technisch erfolgreicher Lauf als korrekt gilt, obwohl Agent, Session oder Antwortziel nicht zur vorgesehenen Route passen.