coderClaw

Signal (signal-cli)

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

Prerequisites

Quick setup (beginner)

  1. Use a separate Signal number for the bot (recommended).
  2. Install signal-cli (Java required if you use the JVM build).
  3. Choose one setup path:
    • Path A (QR link): signal-cli link -n "CoderClaw" and scan with Signal.
    • Path B (SMS register): register a dedicated number with captcha + SMS verification.
  4. Configure CoderClaw and restart the gateway.
  5. Send a first DM and approve pairing (coderclaw pairing approve signal <CODE>).

Minimal config:

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

Field reference:

Field Description
account Bot phone number in E.164 format (+15551234567)
cliPath Path to signal-cli (signal-cli if on PATH)
dmPolicy DM access policy (pairing recommended)
allowFrom Phone numbers or uuid:<id> values allowed to DM

What it is

Config writes

By default, Signal is allowed to write config updates triggered by /config set|unset (requires commands.config: true).

Disable with:

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

The number model (important)

  1. Install signal-cli (JVM or native build).
  2. Link a bot account:
    • signal-cli link -n "CoderClaw" 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.

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 signal-cli on the gateway host:
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 (signal-cli-${VERSION}.tar.gz), install JRE 25+ first. Keep signal-cli updated; upstream notes that old releases can break as Signal server APIs change.

  1. Register and verify the number:
signal-cli -a +<BOT_PHONE_NUMBER> register

If captcha is required:

  1. Open https://signalcaptchas.org/registration/generate.html.
  2. Complete captcha, copy the 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):
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
  1. Configure CoderClaw, restart gateway, verify channel:
# If you run the gateway as a user systemd service:
systemctl --user restart coderclaw-gateway

# Then verify:
coderclaw doctor
coderclaw channels status --probe
  1. Pair your DM sender:
    • Send any message to the bot number.
    • Approve code on the server: coderclaw pairing approve signal <PAIRING_CODE>.
    • Save the bot number as a contact on your phone to avoid “Unknown contact”.

Important: registering a phone number account with signal-cli can de-authenticate the main Signal app session for that number. Prefer a dedicated bot number, or use QR link mode if you need to keep your existing phone app setup.

Upstream references:

External daemon mode (httpUrl)

If you want to manage signal-cli yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point CoderClaw at it:

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

This skips auto-spawn and the startup wait inside CoderClaw. For slow starts when auto-spawning, set channels.signal.startupTimeoutMs.

Access control (DMs + groups)

DMs:

Groups:

How it works (behavior)

Media + limits

Typing + read receipts

Reactions (message tool)

Examples:

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:

Delivery targets (CLI/cron)

Troubleshooting

Run this ladder first:

coderclaw status
coderclaw gateway status
coderclaw logs --follow
coderclaw doctor
coderclaw channels status --probe

Then confirm DM pairing state if needed:

coderclaw pairing list signal

Common failures:

Extra checks:

coderclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/coderclaw/coderclaw-$(date +%Y-%m-%d).log" | tail -20

For triage flow: /channels/troubleshooting.

Security notes

Configuration reference (Signal)

Full configuration: Configuration

Provider options:

Related global options:

This site is open source. Improve this page.