OpenClaw mit Signal verbinden: Schnelle Einrichtung

Signal (signal-cli)

Status: externe CLI-Integration. Das Gateway kommuniziert mit signal-cli über HTTP JSON-RPC + SSE.

Voraussetzungen

• OpenClaw auf deinem Server installiert (der Linux-Flow unten wurde auf Ubuntu 24 getestet).
• signal-cli auf dem Host verfügbar, auf dem das Gateway läuft.
• Eine Telefonnummer, die eine Verifizierungs-SMS empfangen kann (für den SMS-Registrierungsweg).
• Browser-Zugriff für Signal-Captcha (signalcaptchas.org) während der Registrierung.

Schnelle Einrichtung (Anfänger)

1. Verwende eine separate Signal-Nummer für den Bot (empfohlen).
2. Installiere signal-cli (Java erforderlich, wenn du den JVM-Build nutzt).
3. Wähle einen Einrichtungsweg:
   • Weg A (QR-Link): signal-cli link -n "OpenClaw" und mit Signal scannen.
   • Weg B (SMS-Registrierung): registriere eine eigene Nummer mit Captcha + SMS-Verifizierung.
4. Konfiguriere OpenClaw und starte das Gateway neu.
5. Sende eine erste DM und bestätige das Pairing (openclaw pairing approve signal <CODE>).

Minimale Konfiguration:

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

Feld-Referenz:

Feld	Beschreibung
account	Bot-Telefonnummer im E.164 Format (+15551234567)
cliPath	Pfad zu signal-cli (signal-cli, falls im PATH)
dmPolicy	DM-Zugriffsrichtlinie (pairing empfohlen)
allowFrom	Telefonnummern oder uuid:<id> Werte, die DMs senden dürfen

Was es ist

• Signal-Channel via signal-cli (keine eingebettete libsignal) mit deterministischem Routing, damit Antworten immer zuverlässig zurück an Signal gehen.
• DMs teilen sich die Haupt-Session des Agents; Gruppen sind isoliert (agent:<agentId>:signal:group:<groupId>).

Konfigurations-Schreibzugriff

Standardmäßig darf Signal Konfigurations-Updates schreiben, die durch /config set|unset ausgelöst werden (erfordert commands.config: true).

Deaktiviere es so:

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

Support für mehrere Accounts: Nutze channels.signal.accounts mit Konfiguration pro Account und optionalem name. Siehe gateway/configuration für das geteilte Pattern.

Setup-Pfad B: Eigene Bot-Nummer registrieren (SMS, Linux)

Nutze diesen Weg, wenn du eine eigene Bot-Nummer willst, statt einen bestehenden Account der Signal-App zu verknüpfen.

1. Besorge dir eine Nummer, die SMS empfangen kann (oder Sprachverifizierung für Festnetznummern).
   • Nutze eine eigene Bot-Nummer, um Konflikte mit Accounts oder Sessions zu vermeiden.
2. Installiere signal-cli auf dem Gateway-Host:

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version

Wenn du den JVM-Build nutzt (signal-cli-${VERSION}.tar.gz), installiere zuerst JRE 25+. Halte signal-cli aktuell; die Entwickler weisen darauf hin, dass alte Versionen nicht mehr funktionieren, wenn sich die Signal-Server-APIs ändern.

3. Registriere und verifiziere die Nummer:

signal-cli -a +<BOT_PHONE_NUMBER> register

Falls ein Captcha erforderlich ist:

1. Öffne https://signalcaptchas.org/registration/generate.html.
2. Löse das Captcha und kopiere den signalcaptcha://... Link von “Open Signal”.
3. Führe den Befehl möglichst von der gleichen externen IP aus wie die Browser-Session.
4. Starte die Registrierung sofort neu (Captcha-Token laufen schnell ab):

signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

4. Konfiguriere OpenClaw, starte das Gateway neu und prüfe den Channel:

# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway

# Then verify:
openclaw doctor
openclaw channels status --probe

5. Kopple deinen DM-Sender:
   • Sende eine Nachricht an die Bot-Nummer.
   • Bestätige den Code auf dem Server: openclaw pairing approve signal <PAIRING_CODE>.
   • Speichere die Bot-Nummer als Kontakt auf deinem Handy, um “Unbekannter Kontakt” zu vermeiden.

Wichtig: Die Registrierung einer Telefonnummer mit signal-cli kann die Session der Haupt-App für diese Nummer beenden. Nutze lieber eine eigene Bot-Nummer oder den QR-Link-Modus, wenn du dein bestehendes Handy-Setup behalten willst.

Upstream-Referenzen:

• signal-cli README: https://github.com/AsamK/signal-cli
• Captcha-Flow: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Linking-Flow: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

Externer Daemon-Modus (httpUrl)

Wenn du signal-cli selbst verwalten willst (wegen langsamer JVM-Kaltstarts, Container-Init oder geteilter CPUs), starte den Daemon separat und verbinde OpenClaw damit:

{
  channels: {
    signal: {
      httpUrl: "http://127.0.0.1:8080",
      autoStart: false,
    },
  },
}

Das überspringt das automatische Starten und die Wartezeit innerhalb von OpenClaw. Für langsame Starts beim automatischen Starten kannst du channels.signal.startupTimeoutMs setzen.

Zugriffskontrolle (DMs + Gruppen)

DMs:

• Standardmäßig ist channels.signal.dmPolicy = "pairing" eingestellt.
• Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden ignoriert, bis du sie freigibst (Codes laufen nach 1 Stunde ab).
• Die Freigabe erfolgt über:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Pairing ist der Standard-Token-Austausch für Signal DMs. Details findest du hier: Pairing
• Absender, die nur eine UUID besitzen (aus sourceUuid), werden als uuid:<id> in channels.signal.allowFrom hinterlegt.

Gruppen:

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom steuert, wer in Gruppen Trigger auslösen darf, wenn allowlist aktiv ist.
• Mit channels.signal.groups["<group-id>" | "*"] kannst du das Gruppenverhalten überschreiben, etwa durch requireMention, tools oder toolsBySender.
• Nutze channels.signal.accounts.<id>.groups für spezifische Einstellungen pro Account in Setups mit mehreren Accounts.
• Hinweis zur Runtime: Falls channels.signal komplett fehlt, nutzt die Runtime automatisch groupPolicy="allowlist" für Gruppen-Checks (selbst wenn channels.defaults.groupPolicy gesetzt ist).

Funktionsweise (Verhalten)

• signal-cli läuft als Daemon, während das Gateway Events via SSE ausliest.
• Eingehende Nachrichten werden in den geteilten Channel-Envelope normalisiert und Antworten fließen immer an die ursprüngliche Nummer oder Gruppe zurück.

Medien + Limits

• Ausgehender Text wird auf channels.signal.textChunkLimit aufgeteilt (Standard: 4000).
• Optionales Splitting nach Zeilenumbrüchen: Setze channels.signal.chunkMode="newline", um Text an Leerzeilen (Absatzgrenzen) zu trennen, bevor das Limit greift.
• Attachments werden unterstützt (base64-Abruf über signal-cli).
• Standard-Limit für Medien: channels.signal.mediaMaxMb (Standard: 8).
• Nutze channels.signal.ignoreAttachments, um den Download von Medien zu überspringen.
• Der Kontext für den Gruppenverlauf nutzt channels.signal.historyLimit (oder channels.signal.accounts.*.historyLimit) und greift sonst auf messages.groupChat.historyLimit zurück. Setze den Wert auf 0, um die Funktion zu deaktivieren (Standard: 50).

Tipp-Indikatoren + Lesebestätigungen

• Tipp-Indikatoren: OpenClaw sendet Signale über signal-cli sendTyping und aktualisiert diese laufend, während eine Antwort generiert wird.
• Lesebestätigungen: Bei aktiviertem channels.signal.sendReadReceipts leitet OpenClaw Bestätigungen für erlaubte DMs weiter; für Gruppen bietet signal-cli diese Funktion aktuell nicht an.

Reaktionen (message tool)

Manchmal sagt ein Emoji mehr als tausend Worte. Mit dem message tool kannst du ganz einfach auf Nachrichten reagieren.

• Verwende message action=react mit channel=signal.
• Targets: E.164-Nummer oder UUID des Absenders (nutze uuid:<id> aus dem Pairing-Output; die reine UUID funktioniert ebenfalls).
• messageId ist der Signal-Zeitstempel der Nachricht, auf die du reagieren möchtest.
• Für Reaktionen in Gruppen sind targetAuthor oder targetAuthorUuid erforderlich.

Beispiele:

message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅

Config:

• channels.signal.actions.reactions: Aktiviert oder deaktiviert Reaktionen (Standard ist true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack deaktiviert Reaktionen des Agents (das react Tool gibt einen Fehler aus).
  • minimal/extensive aktiviert Reaktionen des Agents und legt das Level für die Guidance fest.
• Overrides pro Account: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Zustellungsziele (CLI/cron)

Wenn du Nachrichten über das CLI oder per cron-Job verschickst, kannst du diese Ziele verwenden:

• DMs: signal:+15551234567 (oder die reine E.164-Nummer).
• UUID DMs: uuid:<id> (oder die reine UUID).
• Gruppen: signal:group:<groupId>.
• Usernames: username:<name> (sofern dein Signal-Account dies unterstützt).

Fehlerbehebung

Geh zuerst diese Liste durch:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Prüfe danach bei Bedarf den DM-Pairing-Status:

openclaw pairing list signal

Häufige Fehler:

• Daemon erreichbar, aber keine Antworten: Überprüfe die Account- und Daemon-Einstellungen (httpUrl, account) sowie den Empfangsmodus.
• DMs werden ignoriert: Der Absender wartet auf die Pairing-Freigabe.
• Gruppennachrichten werden ignoriert: Group-Sender- oder Mention-Gating blockiert die Zustellung.
• Validierungsfehler in der Konfiguration nach Bearbeitung: Führe openclaw doctor --fix aus.
• Signal fehlt in der Diagnose: Bestätige, dass channels.signal.enabled: true gesetzt ist.

Zusätzliche Prüfungen:

openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

Für den Triage-Flow: /channels/troubleshooting.

Sicherheitshinweise

• signal-cli speichert Account-Keys lokal (normalerweise unter ~/.local/share/signal-cli/data/).
• Erstelle ein Backup deines Signal-Account-Status, bevor du den Server migrierst oder neu aufsetzt.
• Behalte channels.signal.dmPolicy: "pairing" bei, außer du möchtest explizit einen breiteren DM-Zugriff erlauben.
• Die SMS-Verifizierung ist nur für die Registrierung oder Recovery-Prozesse nötig. Beachte jedoch, dass der Verlust der Nummer oder des Accounts die erneute Registrierung erschweren kann.

Konfigurationsreferenz (Signal)

Vollständige Konfiguration: Konfiguration

Provider-Optionen:

• channels.signal.enabled: Aktiviert oder deaktiviert den Start des Kanals.
• channels.signal.account: E.164-Format für den Bot-Account.
• channels.signal.cliPath: Pfad zu signal-cli.
• channels.signal.httpUrl: Vollständige Daemon-URL (überschreibt Host/Port).
• channels.signal.httpHost, channels.signal.httpPort: Daemon-Bindung (Standard: 127.0.0.1:8080).
• channels.signal.autoStart: Startet den Daemon automatisch (Standard: true, falls httpUrl nicht gesetzt ist).
• channels.signal.startupTimeoutMs: Zeitlimit für den Startvorgang in ms (maximal 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: Überspringt den Download von Anhängen.
• channels.signal.ignoreStories: Ignoriert Stories vom Daemon.
• channels.signal.sendReadReceipts: Leitet Lesebestätigungen weiter.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
• channels.signal.allowFrom: Allowlist für DMs (E.164 oder uuid:<id>). open erfordert "*". Signal nutzt keine Benutzernamen; du musst Telefonnummern oder UUID-IDs verwenden.
• channels.signal.groupPolicy: open | allowlist | disabled (Standard: allowlist).
• channels.signal.groupAllowFrom: Allowlist für Absender in Gruppen.
• channels.signal.groups: Overrides pro Gruppe, indiziert nach der Signal-Gruppen-ID (oder "*"). Unterstützte Felder: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: Account-spezifische Version von channels.signal.groups für Setups mit mehreren Accounts.
• channels.signal.historyLimit: Maximale Anzahl an Gruppennachrichten, die als Kontext einbezogen werden (0 deaktiviert dies).
• channels.signal.dmHistoryLimit: Limit für den DM-Verlauf in Benutzer-Turns. Overrides pro Benutzer: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: Größe ausgehender Chunks (Zeichen).
• channels.signal.chunkMode: length (Standard) oder newline, um bei Leerzeilen (Absatzgrenzen) zu trennen, bevor das Chunking nach Länge erfolgt.
• channels.signal.mediaMaxMb: Limit für eingehende und ausgehende Medien (MB).

Zugehörige globale Optionen:

• agents.list[].groupChat.mentionPatterns (Signal unterstützt keine nativen Mentions).
• messages.groupChat.mentionPatterns (globaler Fallback).
• messages.responsePrefix.

Verwandte Themen

• Channels Overview — alle unterstützten Kanäle
• Pairing — DM-Authentifizierung und Pairing-Flow
• Groups — Verhalten in Gruppenchats und Mention-Gating
• Channel Routing — Session-Routing für Nachrichten
• Security — Zugriffsmodell und Hardening

{
  channels: { signal: { configWrites: false } },
}