diff --git a/docs/channels/signal.md b/docs/channels/signal.md index df4d630cc55..60bb5f7ce92 100644 --- a/docs/channels/signal.md +++ b/docs/channels/signal.md @@ -1,5 +1,5 @@ --- -summary: "Signal support via signal-cli (JSON-RPC + SSE), setup, and number model" +summary: "Signal support via signal-cli (JSON-RPC + SSE), setup paths, and number model" read_when: - Setting up Signal support - Debugging Signal send/receive @@ -10,13 +10,22 @@ title: "Signal" Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE. +## Prerequisites + +- OpenClaw installed on your server (Linux flow below tested on Ubuntu 24). +- `signal-cli` available on the host where the gateway runs. +- A phone number that can receive one verification SMS (for SMS registration path). +- Browser access for Signal captcha (`signalcaptchas.org`) during registration. + ## Quick setup (beginner) 1. Use a **separate Signal number** for the bot (recommended). -2. Install `signal-cli` (Java required). -3. Link the bot device and start the daemon: - - `signal-cli link -n "OpenClaw"` -4. Configure OpenClaw and start the gateway. +2. Install `signal-cli` (Java required if you use the JVM build). +3. Choose one setup path: + - **Path A (QR link):** `signal-cli link -n "OpenClaw"` and scan with Signal. + - **Path B (SMS register):** register a dedicated number with captcha + SMS verification. +4. Configure OpenClaw and restart the gateway. +5. Send a first DM and approve pairing (`openclaw pairing approve signal `). Minimal config: @@ -34,6 +43,15 @@ Minimal config: } ``` +Field reference: + +| Field | Description | +| ----------- | ------------------------------------------------- | +| `account` | Bot phone number in E.164 format (`+15551234567`) | +| `cliPath` | Path to `signal-cli` (`signal-cli` if on `PATH`) | +| `dmPolicy` | DM access policy (`pairing` recommended) | +| `allowFrom` | Phone numbers or `uuid:` values allowed to DM | + ## What it is - Signal channel via `signal-cli` (not embedded libsignal). @@ -58,9 +76,9 @@ Disable with: - If you run the bot on **your personal Signal account**, it will ignore your own messages (loop protection). - For "I text the bot and it replies," use a **separate bot number**. -## Setup (fast path) +## Setup path A: link existing Signal account (QR) -1. Install `signal-cli` (Java required). +1. Install `signal-cli` (JVM or native build). 2. Link a bot account: - `signal-cli link -n "OpenClaw"` then scan the QR in Signal. 3. Configure Signal and start the gateway. @@ -83,6 +101,67 @@ Example: Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. +## Setup path B: register dedicated bot number (SMS, Linux) + +Use this when you want a dedicated bot number instead of linking an existing Signal app account. + +1. Get a number that can receive SMS (or voice verification for landlines). + - Use a dedicated bot number to avoid account/session conflicts. +2. Install `signal-cli` on the gateway host: + +```bash +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 +``` + +If you use the JVM build (`signal-cli-${VERSION}.tar.gz`), install JRE 25+ first. +Keep `signal-cli` updated; upstream notes that old releases can break as Signal server APIs change. + +3. Register and verify the number: + +```bash +signal-cli -a + register +``` + +If captcha is required: + +1. Open `https://signalcaptchas.org/registration/generate.html`. +2. Complete captcha, copy the `signalcaptcha://...` link target from "Open Signal". +3. Run from the same external IP as the browser session when possible. +4. Run registration again immediately (captcha tokens expire quickly): + +```bash +signal-cli -a + register --captcha '' +signal-cli -a + verify +``` + +4. Configure OpenClaw, restart gateway, verify channel: + +```bash +# If you run the gateway as a user systemd service: +systemctl --user restart openclaw-gateway + +# Then verify: +openclaw doctor +openclaw channels status --probe +``` + +5. Pair your DM sender: + - Send any message to the bot number. + - Approve code on the server: `openclaw pairing approve signal `. + - Save the bot number as a contact on your phone to avoid "Unknown contact". + +Important: registering a phone number account with `signal-cli` can de-authenticate the main Signal app session for that number. Prefer a dedicated bot number, or use QR link mode if you need to keep your existing phone app setup. + +Upstream references: + +- `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)` + ## External daemon mode (httpUrl) If you want to manage `signal-cli` yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point OpenClaw at it: @@ -191,9 +270,26 @@ Common failures: - Daemon reachable but no replies: verify account/daemon settings (`httpUrl`, `account`) and receive mode. - DMs ignored: sender is pending pairing approval. - Group messages ignored: group sender/mention gating blocks delivery. +- Config validation errors after edits: run `openclaw doctor --fix`. +- Signal missing from diagnostics: confirm `channels.signal.enabled: true`. + +Extra checks: + +```bash +openclaw pairing list signal +pgrep -af signal-cli +grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 +``` For triage flow: [/channels/troubleshooting](/channels/troubleshooting). +## Security notes + +- `signal-cli` stores account keys locally (typically `~/.local/share/signal-cli/data/`). +- Back up Signal account state before server migration or rebuild. +- Keep `channels.signal.dmPolicy: "pairing"` unless you explicitly want broader DM access. +- SMS verification is only needed for registration or recovery flows, but losing control of the number/account can complicate re-registration. + ## Configuration reference (Signal) Full configuration: [Configuration](/gateway/configuration)