Fix OpenClaw Signal Errors: 5 Proven Solutions

Key takeaways

OpenClaw's Signal channel runs through signal-cli. Most errors land in three buckets: registration failures from Signal's rate limiter, daemon connection problems when signal-cli isn't running or the socket path is wrong, and file permission errors on VPS installs. Start with the daemon. If signal-cli isn't running, nothing else matters.

Key takeaways

OpenClaw (previously known as Clawdbot and Moltbot) connects to Signal through signal-cli, an unofficial Signal command-line client. Unlike Telegram or Discord, Signal has no official bot API. You register a real phone number, run signal-cli as a persistent daemon, and OpenClaw talks to it over a local socket.

Setting this up took me longer than I expected. Signal's rate limiter is aggressive, the socket path varies by install type, and permission errors on VPS installs can look exactly like other failures. This guide covers what I ran into and what actually fixed it.

Registration failed: rate limited by Signal

Signal rate-limits new phone number registrations. Hit that limit and signal-cli returns:

Registration failed with status: REJECTED

or

Error during registration: org.whispersystems.signalservice.api.push.exceptions.RateLimitException

Signal does this to slow down spam accounts. The fix is a captcha. Here's what actually fixed it for me.

Get the captcha token:

Go to https://signalcaptchas.com/registration/generate.html in a browser. Complete the captcha. When done, the page shows a URL starting with signalcaptcha://. Copy that full URL.

Register with the captcha flag:

signal-cli -a +15551234567 register --captcha signalcaptcha://YOURTOKEN

Replace +15551234567 with your number in E.164 format. Replace YOURTOKEN with what you copied.

Signal sends a verification SMS. Confirm it:

signal-cli -a +15551234567 verify VERIFICATION_CODE

If registration keeps failing

Double-check your phone number format. Signal requires E.164: + followed by country code and the full number, no spaces or dashes. +15551234567 is right. 555-123-4567 is not.

Also check for a partial registration. signal-cli stores account data in ~/.local/share/signal-cli/ (or /var/lib/signal-cli/ for system-wide installs). If a previous attempt failed partway, that leftover data blocks the new registration. Clean it up:

rm -rf ~/.local/share/signal-cli/data/+15551234567

Then try again from the top.

signal-cli daemon not running or wrong socket path

OpenClaw connects to signal-cli through a Unix socket. If signal-cli isn't running, you get this in the gateway logs:

Signal channel error: connection refused

or

Failed to connect to signal-cli socket: no such file or directory

I've debugged this exact scenario three times. Every time it came down to either the daemon not running or the socket path being wrong in the config. Check both.

Check if signal-cli is running:

ps aux | grep signal-cli

Nothing? Start it:

signal-cli -a +15551234567 daemon --socket

This starts signal-cli in daemon mode. The default socket path is /run/user/$(id -u)/signal-cli/socket. Match the socket path in OpenClaw config:

Open ~/.openclaw/config/config.json. The Signal section looks like this:

{
  "channels": {
    "signal": {
      "enabled": true,
      "accounts": {
        "default": {
          "phone_number": "+15551234567",
          "signal_cli_socket": "/run/user/1000/signal-cli/socket"
        }
      }
    }
  }
}

The signal_cli_socket value must match where signal-cli actually put the socket. Check:

ls /run/user/$(id -u)/signal-cli/

Update the config to match, then restart:

openclaw gateway restart

Running signal-cli as a system service

On a VPS, you want signal-cli starting on boot. Here is a minimal systemd unit file:

[Unit]
Description=signal-cli daemon
After=network.target
 
[Service]
Type=simple
User=signal-cli
ExecStart=/usr/bin/signal-cli -a +15551234567 daemon --system
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

Save it to /etc/systemd/system/signal-cli.service and enable it:

systemctl daemon-reload
systemctl enable --now signal-cli

The --system flag switches to system-wide DBus mode. The socket path changes to /run/signal-cli/socket. Update your OpenClaw config to match.

Permission errors on the signal-cli config directory

This one shows up on fresh VPS installs where signal-cli was set up as a system service under a dedicated user. The config directory /var/lib/signal-cli/ is owned by the signal-cli user. OpenClaw runs as a different user. I missed this for a while because the error looked like the daemon wasn't running at all.

The error in the logs:

Permission denied: /var/lib/signal-cli/data/

Or from signal-cli itself:

java.io.IOException: Permission denied

Fix ownership and group access:

sudo chown -R signal-cli:signal-cli /var/lib/signal-cli/
sudo chmod 750 /var/lib/signal-cli/

Add the OpenClaw user to the signal-cli group:

sudo usermod -aG signal-cli openclaw

Log out and back in for the group change to take effect. Then restart the gateway.

Verify socket permissions:

ls -la /run/signal-cli/socket

You should see srwxrwx--- 1 signal-cli signal-cli. The socket is owned by the signal-cli group. Your OpenClaw user needs group membership to access it.

Linking device timeout: QR code expired

Instead of registering a new number, you can link OpenClaw as a secondary device on an existing Signal account. The QR code has a short scan window. Miss it and you get:

Error: timeout while waiting for QR scan

or

Linking failed: device link request expired

Generate a fresh link request:

signal-cli link --name "OpenClaw"

This prints a sgnl://linkdevice?... URL. To see it as a QR code instead:

signal-cli link --name "OpenClaw" | qrencode -t utf8

Scan the QR code from the Signal app on your phone. Per the signal-cli link documentation, the QR code window is approximately 60 seconds. Once scanned, signal-cli prints:

Associated successfully with phone number: +15551234567

The --name flag sets the device name in Signal's linked devices list. Use something you'll recognize.

Verify the link worked

Send a test message to your Signal number from another device. Then check the signal-cli logs:

journalctl -u signal-cli -f

You should see incoming message events. If you see them, the link is working.

Messages not delivered

OpenClaw sends messages but the recipient gets nothing. No error in the logs. This is annoying to debug because signal-cli reports success even when the message doesn't arrive.

Trust relationship required for fresh accounts:

Signal uses sealed sender to reduce metadata exposure. For a freshly registered number, the recipient's Signal app may silently reject messages from an unknown account. Send a direct message from your phone's Signal app to the recipient first. After that initial contact, OpenClaw messages go through.

Test signal-cli directly:

Rule out signal-cli as the source of the problem. Send a test message directly without OpenClaw involved:

signal-cli -a +15551234567 -v send -m "test message" +15559876543

If this works from the command line but OpenClaw messages still don't arrive, the issue is in the OpenClaw Signal channel config, not signal-cli.

Check pairing approval:

OpenClaw requires pairing approval before processing incoming messages. Check for pending pairings:

openclaw pairing pending

Approve any that show up:

openclaw pairing approve signal +15551234567

FAQ

Can I use the same Signal number for both my phone and OpenClaw?

Yes. Link OpenClaw as a secondary device instead of registering a new primary account. Run signal-cli link --name "OpenClaw" and scan the QR code from your Signal app. Your phone stays primary. OpenClaw gets a linked slot. Signal limits the total number of linked devices per account.

Why does registration keep failing even after the captcha?

The captcha token goes stale fast. Copy it from the signalcaptchas.com page and run the registration command within about 30 seconds. If it still fails after that, the phone number may be flagged by Signal's fraud detection. Try a different number or wait 24 hours.

How do I know if signal-cli is actually working?

Test it independently, without OpenClaw:

signal-cli -a +15551234567 receive

If this returns received messages or exits cleanly, signal-cli works. If it errors, fix signal-cli first before touching the OpenClaw config.

Sources

• signal-cli GitHub repository - Source, installation, and usage docs
• signal-cli Wiki: Registration with Captcha - Captcha registration flow
• signal-cli Wiki: DBus Service - System service setup and permissions
• OpenClaw Signal Channel Documentation - Config reference for the Signal channel

Conclusion

Signal errors in OpenClaw come down to three areas: registration rate limits, daemon connection failures, and file permissions on VPS installs. Work through them in order. Get signal-cli running and verifiable from the command line before touching the OpenClaw config.

If signal-cli works standalone but OpenClaw still can't connect, the socket path is wrong. That mismatch causes more wasted time than anything else in this stack.

For initial Signal setup from scratch, the OpenClaw Signal setup guide has the full walkthrough. The fix OpenClaw Telegram errors and fix OpenClaw Discord errors guides cover the same troubleshooting pattern for those channels. Once everything is running, the piece on building a second brain with your AI agent over on EmergentWeirdness shows what you can actually do with a working OpenClaw setup.

Changelog

• 2026-02-17: Initial publication.
• 2026-02-25: Added changelog.