docs(signal): improve setup, verification, and troubleshooting guidance

2026-03-07 22:44:16 +00:00 · 2026-02-13 20:38:48 +01:00
parent f02247b6c5
commit e0c04c62c9
1 changed files with 103 additions and 7 deletions
--- 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 <CODE>`).

 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:<id>` 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 +<BOT_PHONE_NUMBER> 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 +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
+signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
+```
+
+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 <PAIRING_CODE>`.
+   - 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)