Skip to content

Fix OpenClaw Signal Errors: 5 Proven Solutions

·5 min read·By Christopher Kvamme

OpenClaw was previously known as Clawdbot and Moltbot. Configuration and commands depend on the version in use.

Fix OpenClaw Signal errors fast: registration rate limits with captcha, signal-cli daemon failures, permission errors, and message delivery problems.

Fix OpenClaw Signal Errors: 5 Proven Solutions
Share:
On this page

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:

text

Registration failed with status: REJECTED

or

text

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:

bash

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:

bash

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:

bash

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:

text

Signal channel error: connection refused

or

text

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:

bash

ps aux | grep signal-cli

Nothing? Start it:

bash

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:

json

{
  "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:

bash

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

Update the config to match, then restart:

bash

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:

text

[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:

bash

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:

text

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

Or from signal-cli itself:

text

java.io.IOException: Permission denied

Fix ownership and group access:

bash

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:

bash

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:

bash

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:

text

Error: timeout while waiting for QR scan

or

text

Linking failed: device link request expired

Generate a fresh link request:

bash

signal-cli link --name "OpenClaw"

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

bash

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:

text

Associated successfully with phone number: +15551234567

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

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

bash

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:

bash

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:

bash

openclaw pairing pending

Approve any that show up:

bash

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:

bash

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

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.
Did I get something wrong? Or have any other feedback? Let me know here.

More from Stack Junkie.

Get new articles by email.

More guides in The OpenClaw Handbook