openclaw-skill/openclaw-knowhow-skill/output/openclaw-docs_data/pages/Signal_signal_cli_8ec2f0265a.json

{
  "title": "Signal (signal-cli)",
  "content": "Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.\n\n## Quick setup (beginner)\n\n1. Use a **separate Signal number** for the bot (recommended).\n2. Install `signal-cli` (Java required).\n3. Link the bot device and start the daemon:\n   * `signal-cli link -n \"OpenClaw\"`\n4. Configure OpenClaw and start the gateway.\n\n* Signal channel via `signal-cli` (not embedded libsignal).\n* Deterministic routing: replies always go back to Signal.\n* DMs share the agent's main session; groups are isolated (`agent:<agentId>:signal:group:<groupId>`).\n\nBy default, Signal is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).\n\n## The number model (important)\n\n* The gateway connects to a **Signal device** (the `signal-cli` account).\n* If you run the bot on **your personal Signal account**, it will ignore your own messages (loop protection).\n* For \"I text the bot and it replies,\" use a **separate bot number**.\n\n1. Install `signal-cli` (Java required).\n2. Link a bot account:\n   * `signal-cli link -n \"OpenClaw\"` then scan the QR in Signal.\n3. Configure Signal and start the gateway.\n\nMulti-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.\n\n## External daemon mode (httpUrl)\n\nIf you want to manage `signal-cli` yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point OpenClaw at it:\n\nThis skips auto-spawn and the startup wait inside OpenClaw. For slow starts when auto-spawning, set `channels.signal.startupTimeoutMs`.\n\n## Access control (DMs + groups)\n\n* Default: `channels.signal.dmPolicy = \"pairing\"`.\n* Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).\n* Approve via:\n  * `openclaw pairing list signal`\n  * `openclaw pairing approve signal <CODE>`\n* Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)\n* UUID-only senders (from `sourceUuid`) are stored as `uuid:<id>` in `channels.signal.allowFrom`.\n\n* `channels.signal.groupPolicy = open | allowlist | disabled`.\n* `channels.signal.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.\n\n## How it works (behavior)\n\n* `signal-cli` runs as a daemon; the gateway reads events via SSE.\n* Inbound messages are normalized into the shared channel envelope.\n* Replies always route back to the same number or group.\n\n* Outbound text is chunked to `channels.signal.textChunkLimit` (default 4000).\n* Optional newline chunking: set `channels.signal.chunkMode=\"newline\"` to split on blank lines (paragraph boundaries) before length chunking.\n* Attachments supported (base64 fetched from `signal-cli`).\n* Default media cap: `channels.signal.mediaMaxMb` (default 8).\n* Use `channels.signal.ignoreAttachments` to skip downloading media.\n* Group history context uses `channels.signal.historyLimit` (or `channels.signal.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).\n\n## Typing + read receipts\n\n* **Typing indicators**: OpenClaw sends typing signals via `signal-cli sendTyping` and refreshes them while a reply is running.\n* **Read receipts**: when `channels.signal.sendReadReceipts` is true, OpenClaw forwards read receipts for allowed DMs.\n* Signal-cli does not expose read receipts for groups.\n\n## Reactions (message tool)\n\n* Use `message action=react` with `channel=signal`.\n* Targets: sender E.164 or UUID (use `uuid:<id>` from pairing output; bare UUID works too).\n* `messageId` is the Signal timestamp for the message you’re reacting to.\n* Group reactions require `targetAuthor` or `targetAuthorUuid`.\n\n* `channels.signal.actions.reactions`: enable/disable reaction actions (default true).\n* `channels.signal.reactionLevel`: `off | ack | minimal | extensive`.\n  * `off`/`ack` disables agent reactions (message tool `react` will error).\n  * `minimal`/`extensive` enables agent reactions and sets the guidance level.\n* Per-account overrides: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.\n\n## Delivery targets (CLI/cron)\n\n* DMs: `signal:+15551234567` (or plain E.164).\n* UUID DMs: `uuid:<id>` (or bare UUID).\n* Groups: `signal:group:<groupId>`.\n* Usernames: `username:<name>` (if supported by your Signal account).\n\n## Configuration reference (Signal)\n\nFull configuration: [Configuration](/gateway/configuration)\n\n* `channels.signal.enabled`: enable/disable channel startup.\n* `channels.signal.account`: E.164 for the bot account.\n* `channels.signal.cliPath`: path to `signal-cli`.\n* `channels.signal.httpUrl`: full daemon URL (overrides host/port).\n* `channels.signal.httpHost`, `channels.signal.httpPort`: daemon bind (default 127.0.0.1:8080).\n* `channels.signal.autoStart`: auto-spawn daemon (default true if `httpUrl` unset).\n* `channels.signal.startupTimeoutMs`: startup wait timeout in ms (cap 120000).\n* `channels.signal.receiveMode`: `on-start | manual`.\n* `channels.signal.ignoreAttachments`: skip attachment downloads.\n* `channels.signal.ignoreStories`: ignore stories from the daemon.\n* `channels.signal.sendReadReceipts`: forward read receipts.\n* `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).\n* `channels.signal.allowFrom`: DM allowlist (E.164 or `uuid:<id>`). `open` requires `\"*\"`. Signal has no usernames; use phone/UUID ids.\n* `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist).\n* `channels.signal.groupAllowFrom`: group sender allowlist.\n* `channels.signal.historyLimit`: max group messages to include as context (0 disables).\n* `channels.signal.dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `channels.signal.dms[\"<phone_or_uuid>\"].historyLimit`.\n* `channels.signal.textChunkLimit`: outbound chunk size (chars).\n* `channels.signal.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.\n* `channels.signal.mediaMaxMb`: inbound/outbound media cap (MB).\n\nRelated global options:\n\n* `agents.list[].groupChat.mentionPatterns` (Signal does not support native mentions).\n* `messages.groupChat.mentionPatterns` (global fallback).\n* `messages.responsePrefix`.",
  "code_samples": [
    {
      "code": "## What it is\n\n* Signal channel via `signal-cli` (not embedded libsignal).\n* Deterministic routing: replies always go back to Signal.\n* DMs share the agent's main session; groups are isolated (`agent:<agentId>:signal:group:<groupId>`).\n\n## Config writes\n\nBy default, Signal is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).\n\nDisable with:",
      "language": "unknown"
    },
    {
      "code": "## The number model (important)\n\n* The gateway connects to a **Signal device** (the `signal-cli` account).\n* If you run the bot on **your personal Signal account**, it will ignore your own messages (loop protection).\n* For \"I text the bot and it replies,\" use a **separate bot number**.\n\n## Setup (fast path)\n\n1. Install `signal-cli` (Java required).\n2. Link a bot account:\n   * `signal-cli link -n \"OpenClaw\"` then scan the QR in Signal.\n3. Configure Signal and start the gateway.\n\nExample:",
      "language": "unknown"
    },
    {
      "code": "Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.\n\n## External daemon mode (httpUrl)\n\nIf you want to manage `signal-cli` yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point OpenClaw at it:",
      "language": "unknown"
    },
    {
      "code": "This skips auto-spawn and the startup wait inside OpenClaw. For slow starts when auto-spawning, set `channels.signal.startupTimeoutMs`.\n\n## Access control (DMs + groups)\n\nDMs:\n\n* Default: `channels.signal.dmPolicy = \"pairing\"`.\n* Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).\n* Approve via:\n  * `openclaw pairing list signal`\n  * `openclaw pairing approve signal <CODE>`\n* Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)\n* UUID-only senders (from `sourceUuid`) are stored as `uuid:<id>` in `channels.signal.allowFrom`.\n\nGroups:\n\n* `channels.signal.groupPolicy = open | allowlist | disabled`.\n* `channels.signal.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.\n\n## How it works (behavior)\n\n* `signal-cli` runs as a daemon; the gateway reads events via SSE.\n* Inbound messages are normalized into the shared channel envelope.\n* Replies always route back to the same number or group.\n\n## Media + limits\n\n* Outbound text is chunked to `channels.signal.textChunkLimit` (default 4000).\n* Optional newline chunking: set `channels.signal.chunkMode=\"newline\"` to split on blank lines (paragraph boundaries) before length chunking.\n* Attachments supported (base64 fetched from `signal-cli`).\n* Default media cap: `channels.signal.mediaMaxMb` (default 8).\n* Use `channels.signal.ignoreAttachments` to skip downloading media.\n* Group history context uses `channels.signal.historyLimit` (or `channels.signal.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).\n\n## Typing + read receipts\n\n* **Typing indicators**: OpenClaw sends typing signals via `signal-cli sendTyping` and refreshes them while a reply is running.\n* **Read receipts**: when `channels.signal.sendReadReceipts` is true, OpenClaw forwards read receipts for allowed DMs.\n* Signal-cli does not expose read receipts for groups.\n\n## Reactions (message tool)\n\n* Use `message action=react` with `channel=signal`.\n* Targets: sender E.164 or UUID (use `uuid:<id>` from pairing output; bare UUID works too).\n* `messageId` is the Signal timestamp for the message you’re reacting to.\n* Group reactions require `targetAuthor` or `targetAuthorUuid`.\n\nExamples:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Quick setup (beginner)",
      "id": "quick-setup-(beginner)"
    },
    {
      "level": "h2",
      "text": "What it is",
      "id": "what-it-is"
    },
    {
      "level": "h2",
      "text": "Config writes",
      "id": "config-writes"
    },
    {
      "level": "h2",
      "text": "The number model (important)",
      "id": "the-number-model-(important)"
    },
    {
      "level": "h2",
      "text": "Setup (fast path)",
      "id": "setup-(fast-path)"
    },
    {
      "level": "h2",
      "text": "External daemon mode (httpUrl)",
      "id": "external-daemon-mode-(httpurl)"
    },
    {
      "level": "h2",
      "text": "Access control (DMs + groups)",
      "id": "access-control-(dms-+-groups)"
    },
    {
      "level": "h2",
      "text": "How it works (behavior)",
      "id": "how-it-works-(behavior)"
    },
    {
      "level": "h2",
      "text": "Media + limits",
      "id": "media-+-limits"
    },
    {
      "level": "h2",
      "text": "Typing + read receipts",
      "id": "typing-+-read-receipts"
    },
    {
      "level": "h2",
      "text": "Reactions (message tool)",
      "id": "reactions-(message-tool)"
    },
    {
      "level": "h2",
      "text": "Delivery targets (CLI/cron)",
      "id": "delivery-targets-(cli/cron)"
    },
    {
      "level": "h2",
      "text": "Configuration reference (Signal)",
      "id": "configuration-reference-(signal)"
    }
  ],
  "url": "llms-txt#signal-(signal-cli)",
  "links": []
}