clawdbot/docs/signal.md

summary, read_when

summary	read_when
Signal support via signal-cli (JSON-RPC + SSE), setup, and number model	Setting up Signal support Debugging Signal send/receive

Signal (signal-cli)

Updated: 2026-01-06

Status: external CLI integration. Gateway talks to signal-cli over HTTP JSON-RPC + SSE.

What it is

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

The number model (important)

• The gateway connects to a Signal device (the 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 (fast path)

1. Install signal-cli (Java required).
2. Link a bot account:
   • signal-cli link -n "Clawdbot" then scan the QR in Signal.
3. Configure Signal and start the gateway.

Example:

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

Access control (DMs + groups)

DMs:

• Default: signal.dmPolicy = "pairing".
• Unknown senders receive a pairing code; messages are ignored until approved.
• Approve via:
  • clawdbot pairing list --provider signal
  • clawdbot pairing approve --provider signal <CODE>
• Pairing is the default token exchange for Signal DMs. Details: Pairing

Groups:

• signal.groupPolicy = open | allowlist | disabled.
• signal.groupAllowFrom controls who can trigger in groups when allowlist is set.

How it works (behavior)

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

Media + limits

• Attachments supported (base64 fetched from signal-cli).
• Default cap: signal.mediaMaxMb.
• Use signal.ignoreAttachments to skip downloading media.

Delivery targets (CLI/cron)

• DMs: signal:+15551234567 (or plain E.164).
• Groups: signal:group:<groupId>.
• Usernames: username:<name> (if supported by your Signal account).

Configuration reference (Signal)

Full configuration: Configuration

Provider options:

• signal.enabled: enable/disable provider startup.
• signal.account: E.164 for the bot account.
• signal.cliPath: path to signal-cli.
• signal.httpUrl: full daemon URL (overrides host/port).
• signal.httpHost, signal.httpPort: daemon bind (default 127.0.0.1:8080).
• signal.autoStart: auto-spawn daemon (default true if httpUrl unset).
• signal.receiveMode: on-start | manual.
• signal.ignoreAttachments: skip attachment downloads.
• signal.ignoreStories: ignore stories from the daemon.
• signal.sendReadReceipts: forward read receipts.
• signal.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• signal.allowFrom: DM allowlist (E.164). open requires "*".
• signal.groupPolicy: open | allowlist | disabled (default: open).
• signal.groupAllowFrom: group sender allowlist.
• signal.textChunkLimit: outbound chunk size (chars).
• signal.mediaMaxMb: inbound/outbound media cap (MB).

Related global options:

• routing.groupChat.mentionPatterns (Signal does not support native mentions).
• messages.responsePrefix.