// dokumentacja openclaw

Integracja OpenClaw z Signal — konfiguracja signal-cli

Wprowadzenie

Kanał Signal w OpenClaw działa jako zewnętrzna integracja CLI — Gateway komunikuje się z signal-cli przez HTTP JSON-RPC i SSE (Server-Sent Events). Dzięki temu agent AI może prowadzić szyfrowane rozmowy przez Signal, obsługując zarówno wiadomości prywatne, jak i grupy.

Wymagania

  • OpenClaw zainstalowany na serwerze Linux (testowano na Ubuntu 24)
  • signal-cli dostępne na hoście Gateway
  • Numer telefonu zdolny do odbioru SMS weryfikacyjnego
  • Dostęp do przeglądarki w celu rozwiązania captcha Signal

Instalacja signal-cli

Dla natywnych buildów Linux:

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/

Buildy JVM wymagają Java Runtime Environment 25 lub nowszego.

Metody konfiguracji

Ścieżka A — łączenie istniejącego konta (QR)

Jeśli masz już konto Signal, możesz je połączyć:

signal-cli link -n "OpenClaw"

Zeskanuj kod QR w aplikacji Signal, aby sparować urządzenie.

Ścieżka B — rejestracja nowego numeru (SMS)

  1. Uruchom: signal-cli -a +<NUMER_BOTA> register
  2. Jeśli wymagana jest captcha — wejdź na signalcaptchas.org/registration/generate.html, rozwiąż weryfikację
  3. Uruchom z tokenem captcha: signal-cli -a +<NUMER_BOTA> register --captcha '<URL>'
  4. Zweryfikuj kod: signal-cli -a +<NUMER_BOTA> verify <KOD>
  5. Zrestartuj Gateway i przetestuj połączenie

Minimalna konfiguracja

Podstawowa konfiguracja wymaga następujących pól JSON:

{
  channels: {
    signal: {
      account: "+48123456789",
      cliPath: "/usr/local/bin/signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+48987654321"]
    }
  }
}

Pole account to numer bota w formacie E.164, cliPath wskazuje ścieżkę do signal-cli.

Kontrola dostępu

Polityka DM

Domyślny tryb to pairing. Nieznani nadawcy otrzymują kody parowania wygasające po godzinie. Zatwierdzenie: openclaw pairing approve signal KOD.

Polityka grup

  • open — otwarte dla wszystkich
  • allowlist — wymagane dopasowanie nadawcy
  • disabled — grupy zablokowane

Nadpisania per-grupa obsługują requireMention, tools i toolsBySender. Nadawcy identyfikowani wyłącznie przez UUID są zapisywani jako uuid:<id> na listach dozwolonych.

Tryb zewnętrznego demona

Gdy zarządzasz signal-cli osobno, użyj konfiguracji:

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

To wyłącza automatyczne uruchamianie demona. Dla wolnych startów na zimno skonfiguruj startupTimeoutMs.

Obsługa wiadomości

  • Dzielenie tekstu — limit 4000 znaków domyślnie (textChunkLimit), opcjonalny tryb newline preferujący podział na akapitach
  • Media — załączniki pobierane przez base64 z signal-cli, limit 8 MB (mediaMaxMb). Pomiń pobieranie ustawieniem ignoreAttachments
  • Kontekst historii — grupy korzystają z historyLimit (domyślnie 50 wiadomości)

Reakcje i potwierdzenia

Narzędzie wiadomości obsługuje reakcje emoji. W DM-ach: message action=react channel=signal target=+<numer>. W grupach wymagane jest podanie targetAuthor. Konfiguracja reactionLevel kontroluje częstotliwość: off, ack, minimal, extensive.

Wskaźniki pisania i potwierdzenia odczytu

Wskaźniki pisania odświeżają się podczas generowania odpowiedzi przez sendTyping. Potwierdzenia odczytu przekazywane są dla dozwolonych DM, gdy sendReadReceipts jest ustawione na true. Signal-cli nie udostępnia potwierdzeń odczytu w grupach.

Bezpieczeństwo

Klucze konta przechowywane są lokalnie w ~/.local/share/signal-cli/data/. Wykonaj kopię zapasową przed migracją lub przebudową systemu. Utrzymuj politykę pairing w DM, chyba że świadomie rozszerzasz dostęp. Utrata konta komplikuje ponowną rejestrację.

Rozwiązywanie problemów

Diagnostyka początkowa:

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

Sprawdź status parowania: openclaw pairing list signal. Najczęstsze problemy to nieosiągalny demon, oczekujące zatwierdzenia parowania blokujące wiadomości, bramkowanie nadawców w grupach oraz błędy walidacji.

Wróc do dokumentacji