Signal mit OpenClaw verbinden: signal-cli, Pairing, Gruppen und Troubleshooting

OpenClaw bindet Signal über das separate Plugin @openclaw/signal und signal-cli an. Das Gateway enthält keine eigene libsignal-Implementierung. Beim nativen Daemon läuft die Verbindung über JSON-RPC und Server-Sent Events; der Container bbernhard/signal-cli-rest-api verwendet REST und WebSocket.

Für die Fehlersuche zählt die Reihenfolge. Prüfe zuerst, ob das Signal-Konto funktioniert und der Transport erreichbar ist. Danach folgt der OpenClaw-Kanal, anschließend das DM-Pairing. Gruppen kommen ganz zuletzt. Der Ablauf ähnelt dem Discord-Setup, doch Signal trennt Geräteverknüpfung und OpenClaw-Zugriff besonders deutlich.

Bevor du startest

Du brauchst eine laufende OpenClaw-Installation mit erreichbarem Gateway, Kommandozeilenzugriff auf dessen Host und eine Signal-Nummer für signal-cli. Für den Antworttest ist eine zweite Signal-Identität nötig. Beim Container müssen Kontozustand und Schlüssel auf einem persistenten Datenträger liegen; außerdem braucht der Gateway eine erreichbare HTTP-Adresse.

Eine eigene Bot-Nummer ist der sauberste Weg. Verwendest du dein persönliches Signal-Konto, ignoriert OpenClaw Nachrichten dieses Kontos wegen des Loop-Schutzes. Ein Selbsttest vom Bot-Konto an denselben Bot kann deshalb nicht funktionieren.

1. Signal-Plugin installieren

Installiere den Kanal:

openclaw plugins install @openclaw/signal

Der Befehl registriert und aktiviert das Plugin. Starte danach den geführten Kanal-Setup:

openclaw channels add

Wähle Signal aus. Der Wizard prüft, ob signal-cli im PATH liegt, und fragt Bot-Nummer sowie Signal-Endpunkt ab. Auf unterstützten Systemen kann er auch den passenden Installationsweg anbieten.

Dieser Schritt ist abgeschlossen, wenn der Wizard ohne Plugin- oder Konfigurationsfehler endet.

Die Live-Dokumentation nennt zusätzliche Signal-Flags wie --signal-number, --http-host und --http-port. Prüfe vor einer automatisierten Installation, ob deine lokale CLI sie tatsächlich anbietet:

openclaw channels add --help

In der für diesen Text geprüften Installation fehlten die Signal-spezifischen Flags in der Kurzhilfe, obwohl die Live-Dokumentation sie aufführte. Vergleiche deshalb auch die installierte Version:

openclaw --version

Solange Dokumentation und lokale Hilfe voneinander abweichen, ist der interaktive Wizard der sicherere Weg.

2. Signal-Konto verlinken oder registrieren

Signal-Geräteverknüpfung und OpenClaw-Pairing sind zwei verschiedene Vorgänge. Zuerst erhält signal-cli Zugriff auf ein Signal-Konto. Später entscheidest du, wer dem OpenClaw-Kanal Direktnachrichten schicken darf.

Vorhandenes Konto per QR-Code verlinken

Starte den Link-Vorgang:

signal-cli link -n "OpenClaw"

Scanne den QR-Code in der Signal-App über die Verwaltung verknüpfter Geräte. Der Link steht, wenn signal-cli dort als Gerät erscheint und der Befehl ohne Fehler endet. Für den Nachrichtentest verwendest du anschließend ein anderes Signal-Konto.

Eigene Bot-Nummer registrieren

Eine getrennte Nummer eignet sich besser für dauerhaften Betrieb. Sie muss den vorgesehenen Registrierungs- und Verifikationsprozess durchlaufen; gegebenenfalls ist ein Signal-Captcha nötig.

Die genaue Syntax hängt von der installierten signal-cli-Version ab:

signal-cli --help

Folge anschließend dem Registrierungsabschnitt der aktuellen OpenClaw-Signal-Dokumentation. Eine Nummer, die bereits in der normalen Signal-App verwendet wird, kann durch eine neue Registrierung bestehende Sitzungen verlieren. Nimm dafür keine wichtige private Nummer ohne vorherige Prüfung.

3. Transport festlegen

OpenClaw dokumentiert zwei Betriebswege.

Verwalteter nativer Betrieb

Der native signal-cli-Daemon verwendet JSON-RPC über HTTP. Ereignisse kommen über Server-Sent Events; der Healthcheck liegt unter /api/v1/check, der Ereignisstrom unter /api/v1/events.

Beim Transport managed-native verwaltet OpenClaw den Prozesslebenszyklus. Richte diesen Weg über openclaw channels add ein und übernimm keine Transportfelder aus alten Beispielen.

Externer Container

Der Container bbernhard/signal-cli-rest-api verwendet REST und WebSocket. Ein laufender Container heißt noch nicht, dass Nachrichten ankommen. Ein laufender Prozess ist noch kein erreichbarer Dienst. Am wichtigsten ist der Kontozustand: Bleibt er nicht persistent, verliert der Container die Verlinkung bei jedem Neustart, und alles Weitere ist hinfällig. Erst wenn das Konto zuverlässig verlinkt oder registriert ist, entscheiden ein erreichbarer Gateway-Endpunkt und der Modus MODE=json-rpc darüber, ob der dokumentierte Empfang tatsächlich funktioniert.

Ein universelles Compose-Manifest wäre hier irreführend. Läuft der Container im selben Docker-Netz wie der Gateway, wohin ist der Datenträger mit dem Kontozustand gemountet, und unter welcher Adresse ist der Gateway von dort aus überhaupt erreichbar? Die Antworten hängen vom jeweiligen Deployment ab. Trage den tatsächlich erreichbaren Endpunkt über den OpenClaw-Wizard ein.

Konfigurationsfelder wie apiMode oder channels.signal.streaming.chunkMode gehören nicht in dieses Setup. Sie sind im geprüften Laufzeitschema ungültig.

4. Gateway und Transport prüfen

Starte den Gateway nach der Einrichtung neu:

openclaw gateway restart

Führe danach den dokumentierten Gateway-Probe aus:

openclaw gateway call channels.status --params '{"probe":true}'

Signal muss im Ergebnis erscheinen und sein Transport als erreichbar beziehungsweise funktionsfähig gemeldet werden. Ein laufender Gateway-Prozess allein reicht nicht.

Für den gezielten Signal-Test bietet die installierte CLI außerdem:

openclaw channels status --channel signal --probe

Scheitert dieser Probe, behebe zuerst Plugin, Kontoverknüpfung oder Transport. Pairing und Gruppenregeln können einen unerreichbaren Kanal nicht reparieren.

5. Direktnachrichten pairen

Bei dmPolicy: "pairing" verarbeitet OpenClaw Nachrichten unbekannter Absender erst nach einer Freigabe. Sende vom zweiten Signal-Konto eine DM an die Bot-Nummer und prüfe die offenen Anfragen:

openclaw pairing list signal

Genehmige den angezeigten Code:

openclaw pairing approve signal <PAIRING_CODE>

Sende danach eine neue Nachricht. Der DM-Test ist bestanden, wenn der Bot diese Nachricht beantwortet; die Nachricht vor der Freigabe wird nicht nachträglich verarbeitet.

Pairing-Codes verfallen nach einer Stunde. Pro Kanal-Konto können höchstens drei Anfragen gleichzeitig offen sein. Wenn kein neuer Code erscheint, prüfe deshalb die bestehende Liste. Alternativ findest du Anfragen in der Control UI unter Settings → Channels → DM access requests.

Eine DM-Freigabe erteilt keinen Gruppenzugriff.

6. Gruppen getrennt testen

Eine funktionierende DM zeigt, dass Konto und Transport stehen und der Kanal grundsätzlich Nachrichten verarbeitet. Gruppen besitzen eigene Freigabe- und Mention-Regeln.

Signal-Gruppenwerte hängen vom Setup und von der installierten Kanalversion ab. Verwende deshalb keine aus Anzeigenamen abgeleiteten oder aus fremden Beispielen kopierten IDs. Prüfe die verfügbaren Einstellungen in der Kanalreferenz deiner OpenClaw-Version.

Teste danach einen klar begrenzten Fall: Sende eine eindeutige Erwähnung des Bots, führe den Signal-Probe erneut aus und beobachte parallel die Logs. Ändere höchstens eine Gruppen- oder Mention-Regel, bevor du denselben Test wiederholst.

Der Gruppentest ist bestanden, wenn die eingehende Nachricht im Signal-Kanal erscheint und nur unter der vorgesehenen Zugriffsregel eine Antwort auslöst.

Diagnose nach Fehlerbild

Beginne immer mit derselben Leiter:

openclaw status
openclaw gateway status
openclaw doctor
openclaw channels status --channel signal --probe
openclaw pairing list signal

Öffne für den Live-Test in einem zweiten Terminal die Logs:

openclaw logs --follow

Beende die Ansicht mit Ctrl-C.

Signal fehlt im Kanalstatus

Prüfe Plugininstallation und Wizard-Abschluss. Starte den Gateway neu und wiederhole den Probe.

Kanal-Probe schlägt fehl

Beim nativen Betrieb muss der Wizard signal-cli finden und den verwalteten Dienst starten können. Beim Container prüfst du Endpunkt, Netzwerk, Kontoverknüpfung und MODE=json-rpc.

Probe funktioniert, aber die DM bleibt unbeantwortet

Prüfe openclaw pairing list signal. Genehmige eine offene Anfrage und sende danach eine neue Nachricht. Ohne Anfrage kontrollierst du DM-Richtlinie und freigegebene Absenderwerte.

DMs funktionieren, Gruppen bleiben still

Der Transport ist dann gesund. Konzentriere dich auf Gruppenfreigabe, Absenderfreigabe und Mention-Regel. Das DM-Pairing gilt dort nicht automatisch.

Signal verschwindet nach einem Update

openclaw doctor --fix ist kein pauschaler Signal-Reparaturbefehl. Nutze ihn nur, wenn openclaw status --all eine beschädigte Plugin-Abhängigkeitsstruktur meldet:

openclaw status --all
openclaw doctor --fix
openclaw gateway restart
openclaw status --all

Ohne diesen Befund bleibst du bei der normalen Diagnose und veränderst nicht vorsorglich weitere Komponenten.

Recovery ohne Neuinstallation

Fällt der Kanal nach einer Änderung aus, setze zuerst die letzte Signal-Konfigurationsänderung zurück, starte danach den Gateway neu und prüfe ausschließlich den Signal-Kanal, bevor du an anderen Stellen weitersuchst:

openclaw gateway restart
openclaw channels status --channel signal --probe

Ist der Transport wieder gesund, teste eine bereits freigegebene DM. Gruppenregeln aktivierst du danach schrittweise. Beim Container kontrollierst du zuvor Konto, persistenten Zustand, Netzwerk und MODE=json-rpc.

Eine erneute Plugininstallation ist erst sinnvoll, wenn Status oder Logs einen Pluginfehler zeigen. Eine neue Signal-Registrierung kann bestehende Sitzungen beeinflussen und gehört ans Ende der Diagnose.

Signal-Zustand schützen

Der von signal-cli oder dem Container gespeicherte Kontozustand enthält sensible Schlüssel. Sein Speicherort hängt von Betriebssystem, Installation und Container-Mount ab.

Sichere genau den Zustand deines gewählten Betriebswegs. Veröffentliche keine Logs mit Telefonnummern, UUIDs oder Pairing-Codes. Vor einer Servermigration brauchst du ein geprüftes Backup oder einen geplanten neuen Link- beziehungsweise Registrierungsprozess.

Wenn derselbe Agent weitere Messenger verwendet, hilft OpenClaw Channel-Routing dabei, Zugriffsregeln getrennt zu halten.

Der sichere Ablauf

Installiere das Plugin, führe den Wizard aus und verlinke oder registriere das Signal-Konto. Bestehe danach den Kanal-Probe. Erst jetzt pairt ein zweites Signal-Konto seine DM; Gruppen folgen als eigener Test.

Diese Reihenfolge trennt Transportfehler von Zugriffsproblemen und Gruppenfehlern, statt sie bei einem Symptom zu vermischen. Bleibt Signal stumm, weißt du dadurch, auf welcher Ebene du suchen musst. Kein Rätselraten. Genau das macht die Anleitung belastbar: Sie verspricht keinen magischen Reparaturbefehl, sondern einen kontrollierten Weg vom Konto bis zur Gruppenregel.