Signal (signal-cli)

Status: integracja z zewnetrznym CLI. Gateway komunikuje sie z signal-cli przez HTTP JSON-RPC + SSE.

Wymagania wstepne

  • OpenClaw zainstalowany na serwerze (przeplyw Linux ponizej przetestowany na Ubuntu 24).
  • signal-cli dostepny na hoscie, na ktorym dziala gateway.
  • Numer telefonu zdolny do odebrania jednego SMS weryfikacyjnego (dla sciezki rejestracji SMS).
  • Dostep do przegladarki dla captcha Signal (signalcaptchas.org) podczas rejestracji.

Szybka konfiguracja (dla poczatkujacych)

  1. Uzyj oddzielnego numeru Signal dla bota (zalecane).
  2. Zainstaluj signal-cli (Java wymagana jesli uzywasz buildu JVM).
  3. Wybierz jedna sciezke konfiguracji:
    • Sciezka A (link QR): signal-cli link -n "OpenClaw" i zeskanuj w Signal.
    • Sciezka B (rejestracja SMS): zarejestruj dedykowany numer z captcha + weryfikacja SMS.
  4. Skonfiguruj OpenClaw i zrestartuj gateway.
  5. Wyslij pierwszy DM i zatwierdz parowanie (openclaw pairing approve signal <CODE>).

Minimalna konfiguracja:

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

Referencja pol:

PoleOpis
accountNumer telefonu bota w formacie E.164 (+15551234567)
cliPathSciezka do signal-cli (signal-cli jesli w PATH)
dmPolicyPolityka dostepu DM (pairing zalecana)
allowFromNumery telefonow lub wartosci uuid:<id> dozwolone do DM

Czym jest

  • Kanal Signal przez signal-cli (nie wbudowany libsignal).
  • Deterministyczny routing: odpowiedzi zawsze wracaja do Signal.
  • DM wspoldziela glowna sesje agenta; grupy sa izolowane (agent:<agentId>:signal:group:<groupId>).

Zapisy konfiguracji

Domyslnie Signal pozwala na zapisy aktualizacji konfiguracji wyzwalane przez /config set|unset (wymaga commands.config: true).

Wylacz:

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

Model numeru (wazne)

  • Gateway laczy sie z urzadzeniem Signal (kontem signal-cli).
  • Jesli uruchomisz bota na osobistym koncie Signal, bedzie ignorowal twoje wlasne wiadomosci (ochrona przed petla).
  • Aby “pisac do bota i otrzymywac odpowiedzi”, uzyj oddzielnego numeru bota.

Sciezka konfiguracji A: polacz istniejace konto Signal (QR)

  1. Zainstaluj signal-cli (build JVM lub natywny).
  2. Polacz konto bota:
    • signal-cli link -n "OpenClaw" nastepnie zeskanuj QR w Signal.
  3. Skonfiguruj Signal i uruchom gateway.

Przyklad:

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

Obsluga wielu kont: uzyj channels.signal.accounts z konfiguracja per konto i opcjonalnym name. Zobacz gateway/configuration dla wspolnego wzorca.

Sciezka konfiguracji B: zarejestruj dedykowany numer bota (SMS, Linux)

Uzyj tego, gdy chcesz dedykowany numer bota zamiast laczenia istniejacego konta aplikacji Signal.

  1. Uzyskaj numer zdolny do odbioru SMS (lub weryfikacji glosowej dla stacjonarnych).
    • Uzyj dedykowanego numeru bota, aby unikac konfliktow konta/sesji.
  2. Zainstaluj signal-cli na hoscie gateway:
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

Jesli uzywasz buildu JVM (signal-cli-${VERSION}.tar.gz), zainstaluj najpierw JRE 25+. Utrzymuj signal-cli aktualnym; upstream zaznacza, ze stare wydania moga sie psuc gdy zmieniaja sie API serwera Signal.

  1. Zarejestruj i zweryfikuj numer:
signal-cli -a +<BOT_PHONE_NUMBER> register

Jesli wymagana jest captcha:

  1. Otworz https://signalcaptchas.org/registration/generate.html.
  2. Wykonaj captche, skopiuj link docelowy signalcaptcha://... z “Open Signal”.
  3. Uruchom z tego samego zewnetrznego IP co sesja przegladarki gdy to mozliwe.
  4. Uruchom rejestracje ponownie natychmiast (tokeny captcha szybko wygasaja):
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
  1. Skonfiguruj OpenClaw, zrestartuj gateway, zweryfikuj kanal:
# Jesli uruchamiasz gateway jako usluge systemd uzytkownika:
systemctl --user restart openclaw-gateway

# Nastepnie zweryfikuj:
openclaw doctor
openclaw channels status --probe
  1. Sparuj nadawce DM:
    • Wyslij dowolna wiadomosc na numer bota.
    • Zatwierdz kod na serwerze: openclaw pairing approve signal <PAIRING_CODE>.
    • Zapisz numer bota jako kontakt na telefonie, aby unikac “Nieznany kontakt”.

Wazne: rejestracja konta numerowego za pomoca signal-cli moze wylogowac glowna sesje aplikacji Signal dla tego numeru. Preferuj dedykowany numer bota lub uzyj trybu linkowania QR, jesli chcesz zachowac istniejaca konfiguracje aplikacji telefonicznej.

Referencje upstream:

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

Tryb zewnetrznego demona (httpUrl)

Jesli chcesz zarzadzac signal-cli samodzielnie (wolne starty JVM na zimno, inicjalizacja kontenera lub wspoldzielone CPU), uruchom demona oddzielnie i wskazz OpenClaw na niego:

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

Pomija to automatyczne uruchamianie i oczekiwanie na start wewnatrz OpenClaw. Dla wolnych startow przy automatycznym uruchamianiu ustaw channels.signal.startupTimeoutMs.

Kontrola dostepu (DM + grupy)

DM:

  • Domyslnie: channels.signal.dmPolicy = "pairing".
  • Nieznani nadawcy otrzymuja kod parowania; wiadomosci sa ignorowane do momentu zatwierdzenia (kody wygasaja po 1 godzinie).
  • Zatwierdzanie przez:
    • openclaw pairing list signal
    • openclaw pairing approve signal <CODE>
  • Parowanie to domyslna wymiana tokenow dla DM Signal. Szczegoly: Parowanie
  • Nadawcy z samym UUID (z sourceUuid) sa przechowywani jako uuid:<id> w channels.signal.allowFrom.

Grupy:

  • channels.signal.groupPolicy = open | allowlist | disabled.
  • channels.signal.groupAllowFrom kontroluje, kto moze wyzwalac w grupach gdy allowlist jest ustawione.
  • channels.signal.groups["<group-id>" | "*"] moze nadpisac zachowanie grupy z requireMention, tools i toolsBySender.
  • Uzyj channels.signal.accounts.<id>.groups dla nadpisan per konto w konfiguracjach wielokontowych.
  • Uwaga runtime: jesli channels.signal calkowicie brakuje, runtime stosuje zastepczym groupPolicy="allowlist" dla sprawdzen grupowych (nawet jesli channels.defaults.groupPolicy jest ustawione).

Jak dziala (zachowanie)

  • signal-cli dziala jako demon; gateway odczytuje zdarzenia przez SSE.
  • Wiadomosci przychodzace sa normalizowane do wspolnej koperty kanalu.
  • Odpowiedzi zawsze routuja z powrotem do tego samego numeru lub grupy.

Media + limity

  • Tekst wychodzacy jest dzielony na kawalki do channels.signal.textChunkLimit (domyslnie 4000).
  • Opcjonalne dzielenie po nowej linii: ustaw channels.signal.chunkMode="newline" aby dzielic na pustych liniach (granice akapitow) przed dzieleniem wedlug dlugosci.
  • Zalaczniki obslugiwane (base64 pobierane z signal-cli).
  • Domyslny limit mediow: channels.signal.mediaMaxMb (domyslnie 8).
  • Uzyj channels.signal.ignoreAttachments aby pominac pobieranie mediow.
  • Kontekst historii grupy uzywa channels.signal.historyLimit (lub channels.signal.accounts.*.historyLimit), stosujac zastepczym messages.groupChat.historyLimit. Ustaw 0 aby wylaczyc (domyslnie 50).

Pisanie + potwierdzenia odczytu

  • Wskazniki pisania: OpenClaw wysyla sygnaly pisania przez signal-cli sendTyping i odswieza je podczas dzialania odpowiedzi.
  • Potwierdzenia odczytu: gdy channels.signal.sendReadReceipts jest true, OpenClaw przekazuje potwierdzenia odczytu dla dozwolonych DM.
  • Signal-cli nie udostepnia potwierdzen odczytu dla grup.

Reakcje (narzedzie wiadomosci)

  • Uzyj message action=react z channel=signal.
  • Cele: E.164 nadawcy lub UUID (uzyj uuid:<id> z wyjscia parowania; sam UUID tez dziala).
  • messageId to znacznik czasu Signal dla wiadomosci, na ktora reagujesz.
  • Reakcje grupowe wymagaja targetAuthor lub targetAuthorUuid.

Przyklady:

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

Konfiguracja:

  • channels.signal.actions.reactions: wlaczenie/wylaczenie akcji reakcji (domyslnie true).
  • channels.signal.reactionLevel: off | ack | minimal | extensive.
    • off/ack wylacza reakcje agenta (narzedzie wiadomosci react zwroci blad).
    • minimal/extensive wlacza reakcje agenta i ustawia poziom wskazowek.
  • Nadpisania per konto: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Cele dostarczania (CLI/cron)

  • DM: signal:+15551234567 (lub zwykly E.164).
  • DM UUID: uuid:<id> (lub sam UUID).
  • Grupy: signal:group:<groupId>.
  • Nazwy uzytkownikow: username:<name> (jesli obslugiwane przez twoje konto Signal).

Rozwiazywanie problemow

Najpierw uruchom te polecenia:

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

Nastepnie potwierdz stan parowania DM jesli potrzeba:

openclaw pairing list signal

Czeste bledy:

  • Demon osiagalny, ale brak odpowiedzi: zweryfikuj ustawienia konta/demona (httpUrl, account) i tryb odbioru.
  • DM ignorowane: nadawca oczekuje na zatwierdzenie parowania.
  • Wiadomosci grupowe ignorowane: bramkowanie nadawcow/wzmianek grupy blokuje dostarczenie.
  • Bledy walidacji konfiguracji po edycji: uruchom openclaw doctor --fix.
  • Signal brakuje w diagnostyce: potwierdz channels.signal.enabled: true.

Dodatkowe sprawdzenia:

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

Przeplyw diagnostyczny: /channels/troubleshooting.

Uwagi bezpieczenstwa

  • signal-cli przechowuje klucze konta lokalnie (zwykle ~/.local/share/signal-cli/data/).
  • Zrob kopie zapasowa stanu konta Signal przed migracja serwera lub przebudowa.
  • Zachowaj channels.signal.dmPolicy: "pairing", chyba ze jawnie chcesz szerszego dostepu DM.
  • Weryfikacja SMS jest potrzebna tylko dla przeplywow rejestracji lub odzyskiwania, ale utrata kontroli nad numerem/kontem moze skomplikowac ponowna rejestracje.

Referencja konfiguracji (Signal)

Pelna konfiguracja: Konfiguracja

Opcje dostawcy:

  • channels.signal.enabled: wlaczenie/wylaczenie startu kanalu.
  • channels.signal.account: E.164 dla konta bota.
  • channels.signal.cliPath: sciezka do signal-cli.
  • channels.signal.httpUrl: pelny URL demona (nadpisuje host/port).
  • channels.signal.httpHost, channels.signal.httpPort: powiazanie demona (domyslnie 127.0.0.1:8080).
  • channels.signal.autoStart: automatyczne uruchamianie demona (domyslnie true jesli httpUrl nie ustawiony).
  • channels.signal.startupTimeoutMs: timeout oczekiwania na start w ms (max 120000).
  • channels.signal.receiveMode: on-start | manual.
  • channels.signal.ignoreAttachments: pominecie pobierania zalacznikow.
  • channels.signal.ignoreStories: ignorowanie stories z demona.
  • channels.signal.sendReadReceipts: przekazywanie potwierdzen odczytu.
  • channels.signal.dmPolicy: pairing | allowlist | open | disabled (domyslnie: pairing).
  • channels.signal.allowFrom: lista dozwolonych DM (E.164 lub uuid:<id>). open wymaga "*". Signal nie ma nazw uzytkownikow; uzyj ID telefonicznych/UUID.
  • channels.signal.groupPolicy: open | allowlist | disabled (domyslnie: allowlist).
  • channels.signal.groupAllowFrom: lista dozwolonych nadawcow grupowych.
  • channels.signal.groups: nadpisania per grupe z kluczem ID grupy Signal (lub "*"). Obslugiwane pola: requireMention, tools, toolsBySender.
  • channels.signal.accounts.<id>.groups: wersja per konto channels.signal.groups dla konfiguracji wielokontowych.
  • channels.signal.historyLimit: max wiadomosci grupowych dolaczanych jako kontekst (0 wylacza).
  • channels.signal.dmHistoryLimit: limit historii DM w turach uzytkownika. Nadpisania per uzytkownika: channels.signal.dms["<phone_or_uuid>"].historyLimit.
  • channels.signal.textChunkLimit: rozmiar kawalka wychodzacego (znaki).
  • channels.signal.chunkMode: length (domyslnie) lub newline aby dzielic na pustych liniach (granice akapitow) przed dzieleniem wedlug dlugosci.
  • channels.signal.mediaMaxMb: limit mediow przychodzacych/wychodzacych (MB).

Powiazane opcje globalne:

  • agents.list[].groupChat.mentionPatterns (Signal nie obsluguje natywnych wzmianek).
  • messages.groupChat.mentionPatterns (globalny zastepczym).
  • messages.responsePrefix.
arrow_back
Poprzedni
Nostr
Następny
Synology Chat
arrow_forward