Mainstream messaging

Signal

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

Voraussetzungen

OpenClaw ist auf Ihrem Server installiert (der Linux-Ablauf unten wurde unter Ubuntu 24 getestet).
signal-cli ist auf dem Host verfügbar, auf dem der Gateway läuft.
Eine Telefonnummer, die eine Verifizierungs-SMS empfangen kann (für den SMS-Registrierungspfad).
Browserzugriff für das Signal-Captcha (signalcaptchas.org) während der Registrierung.

Schnelle Einrichtung (Einsteiger)

Verwenden Sie eine separate Signal-Nummer für den Bot (empfohlen).
Installieren Sie signal-cli (Java ist erforderlich, wenn Sie den JVM-Build verwenden).
Wählen Sie einen Einrichtungspfad:
- Pfad A (QR-Verknüpfung): signal-cli link -n "OpenClaw" und mit Signal scannen.
- Pfad B (SMS-Registrierung): Registrieren Sie eine dedizierte Nummer mit Captcha + SMS-Verifizierung.
Konfigurieren Sie OpenClaw und starten Sie den Gateway neu.
Senden Sie eine erste DM und genehmigen Sie die Kopplung (openclaw pairing approve signal <CODE>).

Minimale Konfiguration:

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

Feldreferenz:

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

Was es ist

Signal-Kanal über signal-cli (keine eingebettete libsignal).
Deterministisches Routing: Antworten gehen immer zurück zu Signal.
DMs teilen sich die Hauptsitzung des Agenten; Gruppen sind isoliert (agent:<agentId>:signal:group:<groupId>).

Konfigurationsschreibvorgänge

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

Deaktivieren mit:

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

Das Nummernmodell (wichtig)

Der Gateway verbindet sich mit einem Signal-Gerät (dem signal-cli-Konto).
Wenn Sie den Bot auf Ihrem persönlichen Signal-Konto ausführen, ignoriert er Ihre eigenen Nachrichten (Schleifenschutz).
Für „Ich schreibe dem Bot und er antwortet“ verwenden Sie eine separate Bot-Nummer.

Einrichtungspfad A: Vorhandenes Signal-Konto verknüpfen (QR)

Installieren Sie signal-cli (JVM- oder nativer Build).
Verknüpfen Sie ein Bot-Konto:
- signal-cli link -n "OpenClaw" und scannen Sie dann den QR-Code in Signal.
Konfigurieren Sie Signal und starten Sie den Gateway.

Beispiel:

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

Unterstützung für mehrere Konten: Verwenden Sie channels.signal.accounts mit kontospezifischer Konfiguration und optionalem name. Siehe gateway/configuration für das gemeinsame Muster.

Einrichtungspfad B: Dedizierte Bot-Nummer registrieren (SMS, Linux)

Verwenden Sie dies, wenn Sie eine dedizierte Bot-Nummer möchten, statt ein vorhandenes Signal-App-Konto zu verknüpfen.

Besorgen Sie eine Nummer, die SMS empfangen kann (oder Sprachverifizierung für Festnetzanschlüsse).
- Verwenden Sie eine dedizierte Bot-Nummer, um Konto-/Sitzungskonflikte zu vermeiden.
Installieren Sie 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 Sie den JVM-Build (signal-cli-${VERSION}.tar.gz) verwenden, installieren Sie zuerst JRE 25+. Halten Sie signal-cli aktuell; upstream weist darauf hin, dass alte Releases brechen können, wenn sich Signal-Server-APIs ändern.

Registrieren und verifizieren Sie die Nummer:

signal-cli -a +&lt;BOT_PHONE_NUMBER&gt; register

Wenn ein Captcha erforderlich ist:

Öffnen Sie https://signalcaptchas.org/registration/generate.html.
Schließen Sie das Captcha ab und kopieren Sie das Linkziel signalcaptcha://... aus „Open Signal“.
Führen Sie den Befehl möglichst von derselben externen IP-Adresse aus wie die Browser-Sitzung.
Führen Sie die Registrierung sofort erneut aus (Captcha-Token laufen schnell ab):

signal-cli -a +&lt;BOT_PHONE_NUMBER&gt; register --captcha '&lt;SIGNALCAPTCHA_URL&gt;'
signal-cli -a +&lt;BOT_PHONE_NUMBER&gt; verify &lt;VERIFICATION_CODE&gt;

Konfigurieren Sie OpenClaw, starten Sie den Gateway neu und prüfen Sie den Kanal:

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

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

Koppeln Sie Ihren DM-Absender:
- Senden Sie eine beliebige Nachricht an die Bot-Nummer.
- Genehmigen Sie den Code auf dem Server: openclaw pairing approve signal <PAIRING_CODE>.
- Speichern Sie die Bot-Nummer als Kontakt auf Ihrem Telefon, um „Unbekannter Kontakt“ zu vermeiden.

Upstream-Referenzen:

signal-cli README: https://github.com/AsamK/signal-cli
Captcha-Ablauf: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
Verknüpfungsablauf: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

Externer Daemon-Modus (httpUrl)

Wenn Sie signal-cli selbst verwalten möchten (langsame JVM-Kaltstarts, Container-Initialisierung oder gemeinsam genutzte CPUs), führen Sie den Daemon separat aus und richten Sie OpenClaw darauf aus:

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

Dies überspringt das automatische Starten und die Startwartezeit innerhalb von OpenClaw. Legen Sie bei langsamen Starts mit automatischem Start channels.signal.startupTimeoutMs fest.

Zugriffskontrolle (DMs + Gruppen)

DMs:

Standard: channels.signal.dmPolicy = "pairing".
Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie genehmigt sind (Codes laufen nach 1 Stunde ab).
Genehmigen über:
- openclaw pairing list signal
- openclaw pairing approve signal <CODE>
Kopplung ist der standardmäßige Token-Austausch für Signal-DMs. Details: Kopplung
UUID-only-Absender (aus sourceUuid) werden als uuid:<id> in channels.signal.allowFrom gespeichert.

Gruppen:

channels.signal.groupPolicy = open | allowlist | disabled.
channels.signal.groupAllowFrom steuert, welche Gruppen oder Absender Gruppenantworten auslösen können, wenn allowlist festgelegt ist; Einträge können Signal-Gruppen-IDs (roh, group:<id> oder signal:group:<id>), Telefonnummern von Absendern, uuid:<id>-Werte oder * sein.
channels.signal.groups["<group-id>" | "*"] kann das Gruppenverhalten mit requireMention, tools und toolsBySender überschreiben.
Verwenden Sie channels.signal.accounts.<id>.groups für kontospezifische Überschreibungen in Multi-Konto-Einrichtungen.
Das Zulassen einer Signal-Gruppe über groupAllowFrom deaktiviert die Erwähnungsprüfung nicht von selbst. Ein speziell konfigurierter Eintrag channels.signal.groups["<group-id>"] verarbeitet jede Gruppennachricht, sofern requireMention=true nicht gesetzt ist.
Laufzeithinweis: Wenn channels.signal vollständig fehlt, fällt die Laufzeit für Gruppenprüfungen auf groupPolicy="allowlist" zurück (selbst wenn channels.defaults.groupPolicy gesetzt ist).

Funktionsweise (Verhalten)

signal-cli läuft als Daemon; der Gateway liest Ereignisse über SSE.
Eingehende Nachrichten werden in den gemeinsamen Kanalumschlag normalisiert.
Antworten werden immer zurück an dieselbe Nummer oder Gruppe geleitet.

Medien + Limits

Ausgehender Text wird auf channels.signal.textChunkLimit aufgeteilt (Standard 4000).
Optionale Zeilenumbruch-Aufteilung: Setzen Sie channels.signal.chunkMode="newline", um vor der Längenaufteilung an Leerzeilen (Absatzgrenzen) zu trennen.
Anhänge werden unterstützt (base64 wird von signal-cli abgerufen).
Sprachnachrichten-Anhänge verwenden den signal-cli-Dateinamen als MIME-Fallback, wenn contentType fehlt, sodass die Audiotranskription AAC-Sprachnotizen weiterhin klassifizieren kann.
Standard-Medienlimit: channels.signal.mediaMaxMb (Standard 8).
Verwenden Sie channels.signal.ignoreAttachments, um das Herunterladen von Medien zu überspringen.
Der Gruppenverlaufskontext verwendet channels.signal.historyLimit (oder channels.signal.accounts.*.historyLimit) und fällt auf messages.groupChat.historyLimit zurück. Setzen Sie 0, um ihn zu deaktivieren (Standard 50).

Tippen + Lesebestätigungen

Tippindikatoren: OpenClaw sendet Tippsignale über signal-cli sendTyping und aktualisiert sie, während eine Antwort läuft.
Lesebestätigungen: Wenn channels.signal.sendReadReceipts true ist, leitet OpenClaw Lesebestätigungen für zugelassene DMs weiter.
Signal-cli stellt keine Lesebestätigungen für Gruppen bereit.

Reaktionen (Nachrichten-Tool)

Verwenden Sie message action=react mit channel=signal.
Ziele: Absender im E.164-Format oder UUID (verwenden Sie uuid:<id> aus der Kopplungsausgabe; eine bloße UUID funktioniert ebenfalls).
messageId ist der Signal-Zeitstempel der Nachricht, auf die Sie reagieren.
Gruppenreaktionen erfordern targetAuthor oder targetAuthorUuid.

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=✅

Konfiguration:

channels.signal.actions.reactions: Reaktionsaktionen aktivieren/deaktivieren (Standard true).
channels.signal.reactionLevel: off | ack | minimal | extensive.
- off/ack deaktiviert Agentenreaktionen (das Nachrichten-Tool react gibt einen Fehler zurück).
- minimal/extensive aktiviert Agentenreaktionen und legt die Anleitungsstufe fest.
Kontospezifische Überschreibungen: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Zustellungsziele (CLI/Cron)

DMs: signal:+15551234567 (oder schlicht E.164).
UUID-DMs: uuid:<id> (oder bloße UUID).
Gruppen: signal:group:<groupId>.
Benutzernamen: username:<name> (wenn von Ihrem Signal-Konto unterstützt).

Fehlerbehebung

Führen Sie zuerst diese Stufen aus:

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

Bestätigen Sie dann bei Bedarf den DM-Kopplungsstatus:

openclaw pairing list signal

Häufige Fehler:

Daemon erreichbar, aber keine Antworten: Prüfen Sie Konto-/Daemon-Einstellungen (httpUrl, account) und Empfangsmodus.
DMs werden ignoriert: Der Absender wartet auf Kopplungsgenehmigung.
Gruppennachrichten werden ignoriert: Gruppenabsender-/Erwähnungsprüfung blockiert die Zustellung.
Konfigurationsvalidierungsfehler nach Änderungen: Führen Sie openclaw doctor --fix aus.
Signal fehlt in der Diagnose: Bestätigen Sie channels.signal.enabled: true.

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

Zum Triage-Ablauf: /channels/troubleshooting.

Sicherheitshinweise

signal-cli speichert Kontoschlüssel lokal (typischerweise ~/.local/share/signal-cli/data/).
Sichern Sie den Signal-Kontostatus vor einer Servermigration oder einem Neuaufbau.
Behalten Sie channels.signal.dmPolicy: "pairing" bei, sofern Sie nicht ausdrücklich breiteren DM-Zugriff wünschen.
SMS-Verifizierung ist nur für Registrierungs- oder Wiederherstellungsabläufe erforderlich, aber der Verlust der Kontrolle über die Nummer/das Konto kann eine erneute Registrierung erschweren.

Konfigurationsreferenz (Signal)

Vollständige Konfiguration: Konfiguration

Provider-Optionen:

channels.signal.enabled: Kanalstart aktivieren/deaktivieren.
channels.signal.account: E.164 für das Bot-Konto.
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: Daemon automatisch starten (standardmäßig true, wenn httpUrl nicht gesetzt ist).
channels.signal.startupTimeoutMs: Zeitlimit für das Warten beim Start in ms (Obergrenze 120000).
channels.signal.receiveMode: on-start | manual.
channels.signal.ignoreAttachments: Herunterladen von Anhängen überspringen.
channels.signal.ignoreStories: Stories vom Daemon ignorieren.
channels.signal.sendReadReceipts: Lesebestätigungen weiterleiten.
channels.signal.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
channels.signal.allowFrom: DM-Allowlist (E.164 oder uuid:<id>). open erfordert "*". Signal hat keine Benutzernamen; verwenden Sie Telefon-/UUID-IDs.
channels.signal.groupPolicy: open | allowlist | disabled (Standard: allowlist).
channels.signal.groupAllowFrom: Gruppen-Allowlist; akzeptiert Signal-Gruppen-IDs (roh, group:<id> oder signal:group:<id>), E.164-Nummern von Absendern oder uuid:<id>-Werte.
channels.signal.groups: gruppenspezifische Überschreibungen, die nach Signal-Gruppen-ID (oder "*") indiziert sind. Unterstützte Felder: requireMention, tools, toolsBySender.
channels.signal.accounts.<id>.groups: kontospezifische Version von channels.signal.groups für Setups mit mehreren Konten.
channels.signal.historyLimit: maximale Anzahl von Gruppennachrichten, die als Kontext einbezogen werden (0 deaktiviert dies).
channels.signal.dmHistoryLimit: DM-Verlaufslimit in Benutzer-Turns. Benutzerspezifische Überschreibungen: channels.signal.dms["<phone_or_uuid>"].historyLimit.
channels.signal.textChunkLimit: ausgehende Chunk-Größe (Zeichen).
channels.signal.chunkMode: length (Standard) oder newline, um vor der Längenaufteilung an Leerzeilen (Absatzgrenzen) zu trennen.
channels.signal.mediaMaxMb: Obergrenze für eingehende/ausgehende Medien (MB).

Zugehörige globale Optionen:

agents.list[].groupChat.mentionPatterns (Signal unterstützt keine nativen Erwähnungen).
messages.groupChat.mentionPatterns (globaler Fallback).
messages.responsePrefix.

Zugehörig

Kanalübersicht — alle unterstützten Kanäle
Kopplung — DM-Authentifizierung und Kopplungsablauf
Gruppen — Verhalten von Gruppenchats und Erwähnungsprüfung
Kanalrouting — Sitzungsrouting für Nachrichten
Sicherheit — Zugriffsmodell und Härtung

# Voraussetzungen

# Schnelle Einrichtung (Einsteiger)

# Was es ist

# Konfigurationsschreibvorgänge

# Das Nummernmodell (wichtig)

# Einrichtungspfad A: Vorhandenes Signal-Konto verknüpfen (QR)

# Einrichtungspfad B: Dedizierte Bot-Nummer registrieren (SMS, Linux)

# Externer Daemon-Modus (httpUrl)

# Zugriffskontrolle (DMs + Gruppen)

# Funktionsweise (Verhalten)

# Medien + Limits

# Tippen + Lesebestätigungen

# Reaktionen (Nachrichten-Tool)

# Zustellungsziele (CLI/Cron)

# Fehlerbehebung

# Sicherheitshinweise

# Konfigurationsreferenz (Signal)

# Zugehörig