Connect Signal to Your AI Agent

Why Signal Is Different

Telegram and Discord hand out bot tokens, so connecting them is a paste-one-value affair we can do from the dashboard. Signal has no bot API. The only way in is signal-cli, a command-line Signal client that registers as a device on a phone number, and your agent then talks to it over local HTTP. That is why Signal needs a terminal session instead of a button.

Everything below happens inside your own instance, and everything it writes lands on your persistent volume, so it survives restarts and upgrades.

Decide This First: Which Number?

This choice changes the setup, so make it before you start.

• Your own number, as a linked device. Fastest path: you scan a QR code exactly like linking Signal Desktop, and your phone stays the primary device. The trade-off is that the agent rides your personal account, so it sees the conversations that account receives.
• A separate number for the bot. Cleaner if you want to message the agent and get replies back the way you would with any other bot. It needs a spare number that can receive an SMS, and registration involves a captcha.

A dedicated number is the better long-term answer for a bot you intend to talk to. Registering an existing number with signal-cli can sign that number out of the Signal app on your phone, so do not register a number you actively use.

Open the Web Terminal

Go to openclawlaunch.com/dashboard, find your instance, and open its terminal. Every command below runs there.

OpenClaw: Install the Signal Plugin

OpenClaw ships an official Signal channel plugin, and it manages the signal-cli process for you. Install it:

openclaw plugins install @openclaw/signal

Then run the guided setup. The wizard checks whether signal-cli is present and offers to download it if not, installing it under your OpenClaw config directory so it persists:

openclaw channels add --channel signal --signal-number +15551234567

Link the account by QR (see the QR section below), or register a dedicated number:

# Link an existing account as a device
signal-cli link -n "OpenClaw"

# Or register a dedicated bot number
signal-cli -a +15551234567 register --captcha 'signalcaptcha://...'
signal-cli -a +15551234567 verify 123456

The captcha token comes from https://signalcaptchas.org/registration/generate.html and expires quickly, so register immediately after generating it.

Minimal configuration:

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

Keep dmPolicy on pairing so strangers cannot talk to your agent. With managed-native, OpenClaw starts and supervises the daemon itself, so there is nothing else to keep alive.

Verify and approve your first sender:

openclaw channels status --probe
openclaw pairing approve signal <CODE>

Hermes: Install signal-cli

Hermes talks to a signal-cli daemon over local HTTP. Install the native build onto your persistent volume so it survives a container rebuild:

mkdir -p /opt/data/signal-cli/bin /opt/data/signal-cli/data
cd /tmp
curl -L -O https://github.com/AsamK/signal-cli/releases/download/v0.14.6/signal-cli-0.14.6-Linux-native.tar.gz
tar xzf signal-cli-0.14.6-Linux-native.tar.gz -C /opt/data/signal-cli/bin
chmod 755 /opt/data/signal-cli/bin/signal-cli
/opt/data/signal-cli/bin/signal-cli --version

Show the Linking QR Code in the Terminal

This is the part people get stuck on. signal-cli link prints a sgnl://linkdevice?... URI as plain text, and the Signal app on your phone will only scan a QR code — there is no field to paste a link into. So render the URI as a QR yourself:

# One-time: install a QR renderer onto the persistent volume
cd /opt/data/signal-cli && npm install qrcode-terminal

# Start linking and render the QR
/opt/data/signal-cli/bin/signal-cli --config /opt/data/signal-cli/data \
  link -n "Hermes" | while read -r uri; do
    node -e "require('/opt/data/signal-cli/node_modules/qrcode-terminal').generate(process.argv[1],{small:true})" "$uri"
  done

The QR comes out around 43 columns wide, which fits the Web Terminal at its default size. On your phone, open Signal, go to Settings, then Linked Devices, tap Link New Device, and scan it. Leave the command running until linking completes.

Hermes: Keep the Daemon Running

The daemon has to be running for Signal to work, and a bare background process does not come back after a restart. Use a gateway startup hook, which lives on your persistent volume and fires every time the gateway starts.

Create /opt/data/hooks/signal-daemon/HOOK.yaml:

name: signal-daemon
description: Start the signal-cli daemon when the gateway starts
events:
  - gateway:startup

And /opt/data/hooks/signal-daemon/handler.py:

import os
import socket
import subprocess

CLI = "/opt/data/signal-cli/bin/signal-cli"
CONFIG = "/opt/data/signal-cli/data"
ACCOUNT = os.environ.get("SIGNAL_ACCOUNT", "")


def _already_running() -> bool:
    with socket.socket() as s:
        s.settimeout(1)
        return s.connect_ex(("127.0.0.1", 8080)) == 0


def handle(event_type: str, context: dict):
    if not ACCOUNT or _already_running():
        return
    subprocess.Popen(
        [CLI, "--config", CONFIG, "-a", ACCOUNT,
         "daemon", "--http", "127.0.0.1:8080"],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        start_new_session=True,
    )

Hermes: Point the Agent at Signal

Add these to /opt/data/.env:

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+15551234567
SIGNAL_ALLOWED_USERS=+15557654321

SIGNAL_ALLOWED_USERS is the allowlist of numbers permitted to talk to the agent. Leave it out and unknown senders get a pairing code instead, which you approve with hermes pairing approve signal CODE. Group messages are ignored unless you set SIGNAL_GROUP_ALLOWED_USERS.

Restart the gateway so the hook and the new settings load, then confirm:

curl http://127.0.0.1:8080/api/v1/check

A JSON response with a signal-cli version means the daemon is up. Send your agent a Signal message and it should reply.

Troubleshooting

• Nothing happens after scanning. The linking URI is short-lived. Cancel the command, run it again for a fresh QR, and scan promptly.
• The QR looks garbled or wrapped. Widen the terminal or zoom out — the code needs its full width to scan.
• The agent ignores your messages. If you linked your own account rather than using a separate number, the agent skips messages you send yourself to avoid talking in circles. A dedicated bot number solves this.
• It worked, then stopped after a restart. The startup hook is missing or errored. Confirm both hook files exist and that SIGNAL_ACCOUNT is set.
• Sends fail after a long quiet period. Signal changes its server APIs over time and old signal-cli builds stop working. Reinstall a current release.

Want Us to Set It Up?

If you would rather not do this yourself, contact support from your dashboard and we will set Signal up on your instance. You will still need to scan the QR from your phone, or receive the SMS code if you are using a dedicated number, because only you can authorise a device on your account.