Signal Channel

Connect OpenClaw to Signal using signal-cli with phone number registration

Signal integration requires signal-cli, a command-line interface for Signal. This provides end-to-end encrypted messaging with full support for DMs, groups, reactions, and media.

Prerequisites

• A dedicated phone number for the bot (cannot be your personal Signal number)
• signal-cli installed on your system
• Java Runtime Environment (JRE) 17 or newer

You cannot use your personal Signal number with signal-cli. You need a separate phone number that is not already registered with Signal.

Quick Start

The interactive onboarding can guide you through Signal setup:

openclaw init

Select Signal and follow the prompts.

Installing signal-cli

macOS (Homebrew)

brew install signal-cli

Ubuntu/Debian

# Add repository
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/signal-cli.gpg] https://updates.signal.org/linux/apt xenial main" > /etc/apt/sources.list.d/signal-cli.list'

# Add signing key
wget -O- https://updates.signal.org/linux/signing-key.asc | gpg --dearmor | sudo tee /usr/share/keyrings/signal-cli.gpg > /dev/null

# Install
sudo apt update
sudo apt install signal-cli

From Binary

1. Download the latest release from signal-cli releases
2. Extract: tar xf signal-cli-*.tar.gz
3. Add to PATH or use full path in config

Verify Installation

signal-cli --version

You should see output like: signal-cli 0.11.12

Registering a Signal Number

1. Register your number

   Replace [phone] with your bot’s phone number (E.164 format):

   signal-cli -a [phone] register
   

   You’ll receive an SMS with a verification code.

2. Verify with code

   Enter the verification code you received:

   signal-cli -a [phone] verify 123-456
   

   (Replace 123-456 with the actual code)

3. Test the connection

   Send a test message to yourself:

   signal-cli -a [phone] send -m "Test message" [phone]
   

Linking as a Secondary Device (Alternative)

If you prefer to link signal-cli as a secondary device:

signal-cli link -n "OpenClaw"

This will display a QR code. Scan it with Signal on your phone:

1. Open Signal → Settings → Linked Devices
2. Tap ”+” to add a device
3. Scan the QR code

After linking, get your registered number:

signal-cli listAccounts

Configuration

Basic Setup

Configure Signal in openclaw.config.json:

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

Key	Type	Default	Description
enabled	boolean	false	Enable Signal channel
account	string	-	Bot’s phone number in E.164 format (e.g., [phone])
cliPath	string	"signal-cli"	Path to signal-cli binary
dmPolicy	string	"pairing"	DM access policy: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Allowed sender identifiers (phone numbers or UUIDs)

DM Policies

• pairing (recommended): Unknown senders get a pairing code; approve with openclaw pairing approve signal <identifier>
• allowlist: Only senders in allowFrom can message
• open: Anyone can message (set allowFrom: ["*"])
• disabled: Ignore all Signal DMs

AllowFrom Formats

Signal supports two identifier formats:

Phone numbers (E.164 format):

{
  "channels": {
    "signal": {
      "allowFrom": ["[phone]", "[phone]"]
    }
  }
}

UUIDs (Signal’s internal identifier):

{
  "channels": {
    "signal": {
      "allowFrom": [
        "uuid:123e4567-e89b-12d3-a456-426614174000",
        "uuid:987fcdeb-51a2-43d3-b789-123456789abc"
      ]
    }
  }
}

UUIDs are more reliable as they don’t change when a user changes their phone number.

Group Configuration

Signal groups work automatically once configured. To restrict access or settings per group:

{
  "channels": {
    "signal": {
      "groups": {
        "group-id-base64": {
          "enabled": true,
          "requireMention": false,
          "allowFrom": ["[phone]"],
          "toolPolicy": "allowlist"
        }
      }
    }
  }
}

Get group IDs with:

signal-cli -a [phone] listGroups

Media Handling

Signal supports:

• Images (JPEG, PNG, GIF)
• Videos (MP4)
• Audio files
• Voice messages
• Documents

Media is automatically downloaded and processed.

Reactions

Signal supports emoji reactions:

{
  "channels": {
    "signal": {
      "reactions": {
        "enabled": true
      }
    }
  }
}

Multi-Account Support

You can configure multiple Signal accounts:

{
  "channels": {
    "signal": {
      "accounts": {
        "personal": {
          "enabled": true,
          "account": "[phone]",
          "allowFrom": ["[phone]"]
        },
        "work": {
          "enabled": true,
          "account": "[phone]",
          "allowFrom": ["[phone]"]
        }
      }
    }
  }
}

Each account must be registered separately with signal-cli.

Troubleshooting

signal-cli not found

Ensure signal-cli is installed and in your PATH:

which signal-cli

If not found, either:

1. Add signal-cli to your PATH
2. Specify the full path in config:

{
  "channels": {
    "signal": {
      "cliPath": "/usr/local/bin/signal-cli"
    }
  }
}

Registration failed

Common issues:

• Number already registered: Cannot use a number already registered to Signal
• Invalid number format: Must be E.164 format (e.g., [phone])
• SMS not received: Check phone number is correct and can receive SMS
• Rate limited: Wait 24 hours before retrying

For virtual numbers (e.g., Google Voice), Signal may reject registration.

Verification code invalid

• Ensure you’re using the exact code from SMS (including dashes if present)
• Code expires after 10 minutes - request a new one if expired
• Don’t add extra spaces or characters

Request a new code:

signal-cli -a [phone] register

Messages not being received

Check status with probe:

openclaw channels status --probe

Common issues:

• signal-cli daemon not running
• Sender not in allowFrom (if using allowlist policy)
• Check logs: openclaw logs --follow | grep signal

Restart signal-cli:

signal-cli -a [phone] daemon

Cannot send messages

Ensure recipient is registered with Signal:

signal-cli -a [phone] getUserStatus [phone]

If not registered, you’ll see an error. They must install Signal first.

Groups not working

Ensure:

1. Bot is a member of the group
2. Group ID is correctly configured
3. Group policy allows messages

List groups:

signal-cli -a [phone] listGroups -d

Join a group (if you have an invite link):

signal-cli -a [phone] joinGroup --uri "https://signal.group/..."

Linked device disconnected

If you linked as a secondary device and it disconnects:

1. Unlink old device in Signal app
2. Run signal-cli link -n "OpenClaw" again
3. Scan new QR code

Primary registration is more stable than linking.

Running signal-cli Daemon

For production use, run signal-cli as a daemon:

# Start daemon
signal-cli -a [phone] daemon

# Or as systemd service (Linux)
sudo systemctl start signal-cli

OpenClaw will communicate with the daemon via DBus (Linux) or direct socket (macOS).

Security Considerations

• End-to-end encryption is maintained through signal-cli
• Registration credentials are stored in ~/.local/share/signal-cli/data/ by default
• Backup credentials regularly - you cannot recover them if lost
• Use a dedicated number - don’t share with other services
• Use allowlist mode for production bots with known users

Advanced Configuration

Custom Data Directory

{
  "channels": {
    "signal": {
      "dataDir": "/path/to/signal-cli/data"
    }
  }
}

Daemon Socket Path

{
  "channels": {
    "signal": {
      "socketPath": "/var/run/signal-cli/socket"
    }
  }
}

Next Steps

iMessage Setup

Set up iMessage on macOS

Pairing Guide

Learn about pairing codes and approvals

Configuration Reference

Full configuration options

Multi-Channel

Using multiple channels together