Skip to main content

​
Signal (signal-cli)

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

​
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 "Clawdbot"
  4. Configure Clawdbot and start the gateway.
Minimal config: 
{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"]
    }
  }
}

​
What it is

  • Signal channel via signal-cli (not embedded libsignal).
  • Deterministic routing: replies always go back to Signal.
  • DMs share the agent’s main session; groups are isolated (agent:<agentId>: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: 
{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"]
    }
  }
}
Multi-account support: use channels.signal.accounts with per-account config and optional name. See gateway/configuration for the shared pattern.

​
Access control (DMs + groups)

DMs:
  • Default: channels.signal.dmPolicy = "pairing".
  • Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
  • Approve via:
    • clawdbot pairing list signal
    • clawdbot pairing approve signal <CODE>
  • Pairing is the default token exchange for Signal DMs. Details: Pairing
  • UUID-only senders (from sourceUuid) are stored as uuid:<id> in channels.signal.allowFrom.
Groups:
  • channels.signal.groupPolicy = open | allowlist | disabled.
  • channels.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 channel envelope.
  • Replies always route back to the same number or group.

​
Media + limits

  • Outbound text is chunked to channels.signal.textChunkLimit (default 4000).
  • Attachments supported (base64 fetched from signal-cli).
  • Default media cap: channels.signal.mediaMaxMb (default 8).
  • Use channels.signal.ignoreAttachments to skip downloading media.
  • Group history context uses channels.signal.historyLimit (or channels.signal.accounts.*.historyLimit), falling back to messages.groupChat.historyLimit. Set 0 to disable (default 50).

​
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:
  • channels.signal.enabled: enable/disable channel startup.
  • channels.signal.account: E.164 for the bot account.
  • channels.signal.cliPath: path to signal-cli.
  • channels.signal.httpUrl: full daemon URL (overrides host/port).
  • channels.signal.httpHost, channels.signal.httpPort: daemon bind (default 127.0.0.1:8080).
  • channels.signal.autoStart: auto-spawn daemon (default true if httpUrl unset).
  • channels.signal.receiveMode: on-start | manual.
  • channels.signal.ignoreAttachments: skip attachment downloads.
  • channels.signal.ignoreStories: ignore stories from the daemon.
  • channels.signal.sendReadReceipts: forward read receipts.
  • channels.signal.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
  • channels.signal.allowFrom: DM allowlist (E.164 or uuid:<id>). open requires "*".
  • channels.signal.groupPolicy: open | allowlist | disabled (default: allowlist).
  • channels.signal.groupAllowFrom: group sender allowlist.
  • channels.signal.historyLimit: max group messages to include as context (0 disables).
  • channels.signal.textChunkLimit: outbound chunk size (chars).
  • channels.signal.mediaMaxMb: inbound/outbound media cap (MB).
Related global options:
  • agents.list[].groupChat.mentionPatterns (Signal does not support native mentions).
  • messages.groupChat.mentionPatterns (global fallback).
  • messages.responsePrefix.