Signal

Status: external CLI integration. Gateway talks to

over HTTP JSON-RPC + SSE.

Prerequisites

• OpenClaw installed on your server (Linux flow below tested on Ubuntu 24).
• text

  Copy

  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 (
  text

  Copy

  signalcaptchas.org
  ) during registration.

Quick setup (beginner)

1. Use a separate Signal number for the bot (recommended).
2. Install
   text

   Copy

   signal-cli
   (Java required if you use the JVM build).
3. Choose one setup path:
   • Path A (QR link):
     text

     Copy

     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 (
   text

   Copy

   openclaw pairing approve signal <CODE>
   ).

Minimal config:

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

Field reference:

What it is

• Signal channel via
  text

  Copy

  signal-cli
  (not embedded libsignal).
• Deterministic routing: replies always go back to Signal.
• DMs share the agent's main session; groups are isolated (
  text

  Copy

  agent:<agentId>:signal:group:<groupId>
  ).

Config writes

By default, Signal is allowed to write config updates triggered by

(requires ).

Disable with:

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

The number model (important)

• The gateway connects to a Signal device (the
  text

  Copy

  signal-cli
  account).
• 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 path A: link existing Signal account (QR)

1. Install
   text

   Copy

   signal-cli
   (JVM or native build).
2. Link a bot account:
   • text

     Copy

     signal-cli link -n "OpenClaw"
     then scan the QR in Signal.
3. Configure Signal and start the gateway.

Example:

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

Multi-account support: use

with per-account config and optional . See

text

Copy

gateway/configuration

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
   text

   Copy

   signal-cli
   on the gateway host:

bash
Copy
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 (

), install JRE 25+ first. Keep updated; upstream notes that old releases can break as Signal server APIs change.

3. Register and verify the number:

bash
Copy
signal-cli -a +<BOT_PHONE_NUMBER> register

If captcha is required:

1. Open
   text

   Copy

   https://signalcaptchas.org/registration/generate.html
   .
2. Complete captcha, copy the
   text

   Copy

   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
Copy
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
Copy
# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service

# 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:
     text

     Copy

     openclaw pairing approve signal <PAIRING_CODE>
     .
   • Save the bot number as a contact on your phone to avoid "Unknown contact".

Upstream references:

• text

  Copy

  signal-cli
  README:
  text

  Copy

  https://github.com/AsamK/signal-cli
• Captcha flow:
  text

  Copy

  https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Linking flow:
  text

  Copy

  https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

External daemon mode (httpUrl)

If you want to manage

yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point OpenClaw at it:

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

This skips auto-spawn and the startup wait inside OpenClaw. For slow starts when auto-spawning, set

.

Access control (DMs + groups)

DMs:

• Default:
  text

  Copy

  channels.signal.dmPolicy = "pairing"
  .
• Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
• Approve via:
  • text

    Copy

    openclaw pairing list signal
  • text

    Copy

    openclaw pairing approve signal <CODE>
• Pairing is the default token exchange for Signal DMs. Details: Pairing
• UUID-only senders (from
  text

  Copy

  sourceUuid
  ) are stored as
  text

  Copy

  uuid:<id>
  in
  text

  Copy

  channels.signal.allowFrom
  .

Groups:

• text

  Copy

  channels.signal.groupPolicy = open | allowlist | disabled
  .
• text

  Copy

  channels.signal.groupAllowFrom
  controls which groups or senders can trigger group replies when
  text

  Copy

  allowlist
  is set; entries can be Signal group IDs (raw,
  text

  Copy

  group:<id>
  , or
  text

  Copy

  signal:group:<id>
  ), sender phone numbers,
  text

  Copy

  uuid:<id>
  values, or
  text

  Copy

  *
  .
• text

  Copy

  channels.signal.groups["<group-id>" | "*"]
  can override group behavior with
  text

  Copy

  requireMention
  ,
  text

  Copy

  tools
  , and
  text

  Copy

  toolsBySender
  .
• Use
  text

  Copy

  channels.signal.accounts.<id>.groups
  for per-account overrides in multi-account setups.
• Allowlisting a Signal group through
  text

  Copy

  groupAllowFrom
  does not disable mention gating by itself. A specifically configured
  text

  Copy

  channels.signal.groups["<group-id>"]
  entry processes every group message unless
  text

  Copy

  requireMention=true
  is set.
• Runtime note: if
  text

  Copy

  channels.signal
  is completely missing, runtime falls back to
  text

  Copy

  groupPolicy="allowlist"
  for group checks (even if
  text

  Copy

  channels.defaults.groupPolicy
  is set).

How it works (behavior)

• text

  Copy

  signal-cli
  runs as a daemon; the gateway reads events via SSE.
• Inbound messages are normalized into the shared channel envelope.
• Replies always route back to the same number or group.

Media + limits

• Outbound text is chunked to
  text

  Copy

  channels.signal.textChunkLimit
  (default 4000).
• Optional newline chunking: set
  text

  Copy

  channels.signal.chunkMode="newline"
  to split on blank lines (paragraph boundaries) before length chunking.
• Attachments supported (base64 fetched from
  text

  Copy

  signal-cli
  ).
• Voice-note attachments use the
  text

  Copy

  signal-cli
  filename as a MIME fallback when
  text

  Copy

  contentType
  is missing, so audio transcription can still classify AAC voice memos.
• Default media cap:
  text

  Copy

  channels.signal.mediaMaxMb
  (default 8).
• Use
  text

  Copy

  channels.signal.ignoreAttachments
  to skip downloading media.
• Group history context uses
  text

  Copy

  channels.signal.historyLimit
  (or
  text

  Copy

  channels.signal.accounts.*.historyLimit
  ), falling back to
  text

  Copy

  messages.groupChat.historyLimit
  . Set
  text

  Copy

  0
  to disable (default 50).

Typing + read receipts

• Typing indicators: OpenClaw sends typing signals via
  text

  Copy

  signal-cli sendTyping
  and refreshes them while a reply is running.
• Read receipts: when
  text

  Copy

  channels.signal.sendReadReceipts
  is true, OpenClaw forwards read receipts for allowed DMs.
• Signal-cli does not expose read receipts for groups.

Reactions (message tool)

• Use
  text

  Copy

  message action=react
  with
  text

  Copy

  channel=signal
  .
• Targets: sender E.164 or UUID (use
  text

  Copy

  uuid:<id>
  from pairing output; bare UUID works too).
• text

  Copy

  messageId
  is the Signal timestamp for the message you’re reacting to.
• Group reactions require
  text

  Copy

  targetAuthor
  or
  text

  Copy

  targetAuthorUuid
  .

Examples:

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

Config:

• text

  Copy

  channels.signal.actions.reactions
  : enable/disable reaction actions (default true).
• text

  Copy

  channels.signal.reactionLevel
  :
  text

  Copy

  off | ack | minimal | extensive
  .
  • text

    Copy

    off
    /
    text

    Copy

    ack
    disables agent reactions (message tool
    text

    Copy

    react
    will error).
  • text

    Copy

    minimal
    /
    text

    Copy

    extensive
    enables agent reactions and sets the guidance level.
• Per-account overrides:
  text

  Copy

  channels.signal.accounts.<id>.actions.reactions
  ,
  text

  Copy

  channels.signal.accounts.<id>.reactionLevel
  .

Delivery targets (CLI/cron)

• DMs:
  text

  Copy

  signal:+15551234567
  (or plain E.164).
• UUID DMs:
  text

  Copy

  uuid:<id>
  (or bare UUID).
• Groups:
  text

  Copy

  signal:group:<groupId>
  .
• Usernames:
  text

  Copy

  username:<name>
  (if supported by your Signal account).

Troubleshooting

Run this ladder first:

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

Then confirm DM pairing state if needed:

bash
Copy
openclaw pairing list signal

Common failures:

• Daemon reachable but no replies: verify account/daemon settings (
  text

  Copy

  httpUrl
  ,
  text

  Copy

  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
  text

  Copy

  openclaw doctor --fix
  .
• Signal missing from diagnostics: confirm
  text

  Copy

  channels.signal.enabled: true
  .

Extra checks:

bash
Copy
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.

Security notes

• text

  Copy

  signal-cli
  stores account keys locally (typically
  text

  Copy

  ~/.local/share/signal-cli/data/
  ).
• Back up Signal account state before server migration or rebuild.
• Keep
  text

  Copy

  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

Provider options:

• text

  Copy

  channels.signal.enabled
  : enable/disable channel startup.
• text

  Copy

  channels.signal.account
  : E.164 for the bot account.
• text

  Copy

  channels.signal.cliPath
  : path to
  text

  Copy

  signal-cli
  .
• text

  Copy

  channels.signal.httpUrl
  : full daemon URL (overrides host/port).
• text

  Copy

  channels.signal.httpHost
  ,
  text

  Copy

  channels.signal.httpPort
  : daemon bind (default 127.0.0.1:8080).
• text

  Copy

  channels.signal.autoStart
  : auto-spawn daemon (default true if
  text

  Copy

  httpUrl
  unset).
• text

  Copy

  channels.signal.startupTimeoutMs
  : startup wait timeout in ms (cap 120000).
• text

  Copy

  channels.signal.receiveMode
  :
  text

  Copy

  on-start | manual
  .
• text

  Copy

  channels.signal.ignoreAttachments
  : skip attachment downloads.
• text

  Copy

  channels.signal.ignoreStories
  : ignore stories from the daemon.
• text

  Copy

  channels.signal.sendReadReceipts
  : forward read receipts.
• text

  Copy

  channels.signal.dmPolicy
  :
  text

  Copy

  pairing | allowlist | open | disabled
  (default: pairing).
• text

  Copy

  channels.signal.allowFrom
  : DM allowlist (E.164 or
  text

  Copy

  uuid:<id>
  ).
  text

  Copy

  open
  requires
  text

  Copy

  "*"
  . Signal has no usernames; use phone/UUID ids.
• text

  Copy

  channels.signal.groupPolicy
  :
  text

  Copy

  open | allowlist | disabled
  (default: allowlist).
• text

  Copy

  channels.signal.groupAllowFrom
  : group allowlist; accepts Signal group IDs (raw,
  text

  Copy

  group:<id>
  , or
  text

  Copy

  signal:group:<id>
  ), sender E.164 numbers, or
  text

  Copy

  uuid:<id>
  values.
• text

  Copy

  channels.signal.groups
  : per-group overrides keyed by Signal group id (or
  text

  Copy

  "*"
  ). Supported fields:
  text

  Copy

  requireMention
  ,
  text

  Copy

  tools
  ,
  text

  Copy

  toolsBySender
  .
• text

  Copy

  channels.signal.accounts.<id>.groups
  : per-account version of
  text

  Copy

  channels.signal.groups
  for multi-account setups.
• text

  Copy

  channels.signal.historyLimit
  : max group messages to include as context (0 disables).
• text

  Copy

  channels.signal.dmHistoryLimit
  : DM history limit in user turns. Per-user overrides:
  text

  Copy

  channels.signal.dms["<phone_or_uuid>"].historyLimit
  .
• text

  Copy

  channels.signal.textChunkLimit
  : outbound chunk size (chars).
• text

  Copy

  channels.signal.chunkMode
  :
  text

  Copy

  length
  (default) or
  text

  Copy

  newline
  to split on blank lines (paragraph boundaries) before length chunking.
• text

  Copy

  channels.signal.mediaMaxMb
  : inbound/outbound media cap (MB).

Related global options:

• text

  Copy

  agents.list[].groupChat.mentionPatterns
  (Signal does not support native mentions).
• text

  Copy

  messages.groupChat.mentionPatterns
  (global fallback).
• text

  Copy

  messages.responsePrefix
  .

Related

• Channels Overview — all supported channels
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening