How to Connect OpenClaw to Signal

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.

Steps

1. 1

   Decide whether to link an existing Signal account or register a bot number

   Before you touch config, decide if this OpenClaw instance should run on a separate bot number or your existing Signal account. The gateway connects to a Signal device (the signal-cli account), and if you run it on your personal account it ignores your own messages for loop protection, so use a dedicated bot number if you want to text the bot directly.

   textCopy

   *   Use a **separate Signal number** for the bot (recommended).
   *   **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.

2. 2

   Install signal-cli on the OpenClaw host

   Install signal-cli on the same host where the OpenClaw gateway runs so it can talk to Signal over HTTP JSON-RPC and SSE. The native Linux build avoids JVM cold starts, but if you use the JVM tarball you must install JRE 25+ first and keep signal-cli updated because old releases can break when Signal changes server APIs.

   bashCopy

   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

3. 3

   Link an existing Signal account with QR (Path A)

   If you want to reuse an existing Signal account, link it as a new device via signal-cli. 164 account number in OpenClaw so replies route correctly.

   bashCopy

   signal-cli link -n "OpenClaw"

4. 4

   Register a dedicated Signal bot number with SMS (Path B)

   For a clean bot identity, register a dedicated phone number with signal-cli using SMS (and captcha if required). Be aware that registering a number with signal-cli can de-authenticate the main Signal app for that number, so prefer a fresh bot number; run the captcha and verification commands from the same external IP and quickly, because captcha tokens expire.

   bashCopy

   signal-cli -a +<BOT_PHONE_NUMBER> register
   
   signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
   signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

5. 5

   Configure the Signal channel in OpenClaw

   Wire Signal into OpenClaw by adding a signal channel block to your gateway configuration. 164 format, point cliPath at the signal-cli binary, and use dmPolicy "pairing" plus an allowFrom list so only approved numbers can DM the agent until you explicitly open it up.

   jsonCopy

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

6. 6

   Restart the OpenClaw gateway and verify the Signal channel

   After editing the config, restart the gateway so it picks up the Signal settings, then run the built-in diagnostics. The doctor and channels status probe confirm that the gateway can reach signal-cli and that the Signal channel is healthy before you start pairing users.

   bashCopy

   # If you run the gateway as a user systemd service:
   systemctl --user restart openclaw-gateway.service
   
   # Then verify:
   openclaw doctor
   openclaw channels status --probe

7. 7

   Pair your Signal DM sender with the bot

   With the channel live, you need to pair each DM sender so OpenClaw accepts their messages under the default pairing policy. Send a first DM to the bot number, then approve the pairing code on the server; this prevents random numbers from driving your agent while still making it easy to onboard trusted contacts.

   bashCopy

   openclaw pairing approve signal <PAIRING_CODE>

8. 8

   Optionally run signal-cli as an external daemon

   If you prefer to manage signal-cli yourself (for example in its own service or container), run it as a daemon and point OpenClaw at the HTTP endpoint. Setting httpUrl and autoStart false tells OpenClaw to skip auto-spawning signal-cli and rely on your external process instead.

   jsonCopy

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

Configuration

Troubleshooting

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

openclaw pairing list signal

openclaw doctor --fix

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

Frequently asked questions