OpenClaw Signal first run: one conversation, one rollback path

Published May 4, 2026 · OpenClaw Blog

A Signal bot can be online and still be a poor first experiment. A transport probe can reach the daemon without telling you whether the right number is active, who may start a conversation, or what happens when the setup needs to be undone.

The first run should answer one small question: can one approved sender receive one useful reply through the intended Signal account while groups, attachments, configuration changes, and real side effects remain out of scope?

OpenClaw's current Signal documentation describes a downloadable channel plugin that uses signal-cli over an HTTP connection to either a native daemon or a REST container. OpenClaw does not embed libsignal. That separation gives you a useful checkpoint before the Gateway sees a message: prove that the Signal account works, then prove that OpenClaw admits exactly one sender.

This tutorial follows that order. It is narrower than a general integration reference because the stopping point matters as much as the first reply.

Keep the first run small

Use a disposable or dedicated setup if you can. The target configuration is:

• one separate Signal number for the bot;
• one private direct message from a test sender;
• dmPolicy set to pairing;
• groupPolicy set to disabled;
• attachments ignored during the first test; and
• one harmless text task that does not ask the agent to read files, run commands, publish content, or contact another service.

The first four items are OpenClaw configuration choices documented on the official Signal channel page. The last item is an operator boundary. It is not a guarantee supplied by Signal or OpenClaw. A prompt that says do not use tools is useful test material, but it is not a substitute for a restricted tool policy.

Prerequisites and the number decision

Start with an installed OpenClaw Gateway, a working model provider, the OpenClaw CLI, a shell on the Gateway host, and a Signal account that you are prepared to use for testing. You also need a second Signal identity that can send the test DM. Do not use a real customer, production group, or sensitive conversation as the first sender.

OpenClaw recommends a separate Signal number for the bot. Its documentation also notes that a bot running on your personal Signal account ignores its own messages as loop protection. A separate number avoids that confusing result and keeps the test conversation apart from personal traffic.

There are two account paths:

• Link an existing account. The OpenClaw guide documents signal-cli link -n 'OpenClaw', followed by a QR scan in Signal. This is the convenient path when the account already exists and you control its primary device.
• Register a dedicated number. The upstream signal-cli README documents registration with a phone number, followed by SMS or voice verification. OpenClaw warns that registering a number can de-authenticate the main Signal app session for that number, so do not use your personal number for this branch.

Upstream also says that signal-cli needs to stay current because Signal Server changes can make old releases stop working correctly. Check the version installed on the Gateway before you attach it. The account password and cryptographic keys are stored locally, usually under ~/.local/share/signal-cli/data/ or the directory selected by $XDG_DATA_HOME. Record the actual path without copying its contents into a ticket, prompt, screenshot, or repository.

1. Prepare signal-cli before connecting OpenClaw

For a QR-linked account, begin the link flow from the Gateway host:

signal-cli link -n 'OpenClaw'

Scan the resulting QR code with the primary Signal device that owns the bot number. The Signal support page on linked devices explains that a secondary client is linked from the phone's Linked devices screen. Keep that phone available; it is also the device you will use if you later need to remove the link.

For a dedicated number registered through signal-cli, the documented shape is:

signal-cli -a <BOT_PHONE_NUMBER> register
signal-cli -a <BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

Use the number in international format and follow any current CAPTCHA or verification instructions from the upstream project. Never put a real verification code in a shared command transcript.

Before handing the account to OpenClaw, you may run a small standalone transport check with a test recipient:

signal-cli -a <BOT_PHONE_NUMBER> send -m 'OpenClaw transport check' <TEST_RECIPIENT>
signal-cli -a <BOT_PHONE_NUMBER> receive

This is a proposed check, not a result reported here. Stop the standalone receive process before OpenClaw takes ownership of the account's normal receive path. Keep the message harmless. The purpose is to find a registration or account problem before adding Gateway routing to the diagnosis.

2. Install the channel and write a narrow configuration

OpenClaw's Signal page documents the plugin and guided setup:

openclaw plugins install @openclaw/signal
openclaw channels add

The wizard checks for signal-cli and asks for the bot number and executable path. If signal-cli is not on PATH, use the path the wizard or your service environment can actually reach. A shell that finds the binary does not prove that a background Gateway service will find it too.

Merge the Signal block into the existing configuration. Do not replace the whole configuration file with a tutorial snippet:

{
  channels: {
    signal: {
      enabled: true,
      account: '<BOT_PHONE_NUMBER>',
      transport: {
        kind: 'managed-native',
        cliPath: 'signal-cli',
        receiveMode: 'on-start'
      },
      dmPolicy: 'pairing',
      groupPolicy: 'disabled',
      configWrites: false,
      ignoreAttachments: true
    }
  }
}

The field names come from the current Signal configuration reference. account is the bot number in E.164 form. dmPolicy: 'pairing' keeps unknown direct-message senders out of the agent workflow until you approve them. groupPolicy: 'disabled' makes the first run a DM-only test. ignoreAttachments: true prevents inbound attachment downloads while you are checking text delivery. configWrites: false disables Signal-triggered /config set and /config unset changes.

The transport block is for the managed native path. OpenClaw also supports external native and container transports, but adding that branch to a first conversation makes the result harder to interpret. Pick one transport, record it, and leave the other modes for a later test.

3. Probe the Gateway before sending a message

Run the read-only checks in the Gateway environment:

openclaw status
openclaw gateway status
openclaw channels status --channel signal --probe

Keep a log view available while you test:

openclaw logs --follow

The OpenClaw channels CLI reference distinguishes the live probe path from the local inventory path. channels status --probe contacts the Gateway and runs the account probe; for Signal, the documented probe includes the daemon version. If the Gateway cannot be reached, status may fall back to a configuration summary. A configured account is not the same thing as a connected account.

For a clean starting point, look for an enabled Signal account, a running channel, and a successful transport check. Exact labels vary by release. If configuration validation fails, the Signal documentation points to openclaw doctor --fix. If the service environment changed, restart the Gateway after correcting the executable path.

4. Pair one sender, then run one conversation

From the test sender, send a plain message to the bot number. With pairing enabled, OpenClaw should create a pending DM request instead of processing the message as an agent turn. The pairing documentation says that codes expire after one hour, pending requests are capped at three per channel account, and an approval grants direct-message access only.

Inspect the request on the Gateway:

openclaw pairing list signal
openclaw pairing approve signal <PAIRING_CODE>

Approve only the sender you intended to use. Do not treat the pairing code as permission to access groups, nodes, host commands, or every future action. It is an inbound DM access decision.

Now send one text-only request. For example:

Reply with exactly READY. Do not use tools or access files.

The sentence is test material, not a security control. The proposed acceptance check is that one reply appears in the same direct conversation, from the bot number you recorded, with no unrelated outbound activity. Save the timestamp, sender identity, account identifier, relevant Gateway log lines, and the visible reply. Do not claim success until you have checked all five.

Do not add a group, an attachment, a second sender, or a real task yet. Each would introduce another variable. If you want to verify a useful response rather than an exact token, use a short sentence and ask for a bounded summary. Keep the expected answer simple enough that a person can review it without trusting the model's confidence.

What is documented and what still needs testing

The documentation establishes the channel architecture, the Signal account and transport fields, the pairing commands, and the status-probe path. It also documents the failure signatures for a silent daemon, a blocked DM, and a group message that does not trigger.

Your first conversation is a proposed test. It should establish that the selected account can receive an approved DM and route a reply back to Signal. It does not establish that every tool is safe, that a group configuration is correct, that a restart preserves the intended state, or that a future signal-cli upgrade will behave the same way.

The editorial inference is simple: a green probe followed by a blocked DM points first to pairing or access policy, not immediately to a broken transport. Check the pending request and effective dmPolicy before changing the account or reinstalling the plugin.

5. Roll back in two layers

Decide what rollback means before you widen the setup. There are two different things to undo: OpenClaw's channel runtime and Signal's linked account state.

For a reversible OpenClaw rollback, use the channel removal flow without the destructive flag:

openclaw channels remove --channel signal

The current CLI reference says that without --delete, the command asks to disable the account and keeps its configuration. For runtime-backed plugins it also asks the Gateway to stop the selected account before updating the configuration. That is the useful first rollback because it stops the listener without throwing away the settings you may need to inspect.

Do not start with:

openclaw channels remove --channel signal --delete

The same reference says that --delete removes the configuration entries without prompting. Reserve that for a deliberate cleanup after you have decided that the account configuration is no longer needed. If you only want to pause the channel, disabling it is the safer record to keep.

If you used the QR link path, remove the linked client from the primary Signal phone. The official unlinking instructions use Signal Settings, Linked devices, and the Unlink action. The support page notes that unlinking a desktop client leaves the mobile account registered. That is different from deleting the Signal account.

Do not delete the signal-cli data directory as a quick fix. It contains account state and cryptographic material. OpenClaw's Signal documentation recommends backing up that state before a server migration or rebuild. Keep a protected copy according to your normal secret-handling process, and remove it only after you understand the account path you used and no longer need the identity.

Failure paths to check before changing the design

• signal-cli is missing. Check the executable path used by the Gateway, not only the interactive shell. Run the status probe again after correcting it. If the service's PATH changed, restart the Gateway.
• The daemon is reachable but the bot is silent. The official troubleshooting page says to check the Signal account, transport kind, transport URL, and receive mode. Then run openclaw pairing list signal. A healthy transport can still reject an unapproved DM.
• No pairing request appears. Confirm that the message reached the bot number, that the channel uses dmPolicy: 'pairing', and that the pending-request cap has not been reached. Codes expire, and the bot does not issue a new pairing message for every repeated attempt from the same sender.
• The bot answers itself nowhere. Check the number model first. OpenClaw's loop protection ignores messages sent by the bot's own Signal account. Use a separate sender and a separate bot number.
• A group does not respond. That is expected while groupPolicy is disabled. A DM approval does not grant group access. If you later test groups, make that a new experiment with an allowlist and mention rule.
• The channel disappears after an update. Run openclaw status --all, openclaw doctor, and the channel probe. The troubleshooting guide distinguishes a configured channel from a plugin that failed to load or register.
• The link stops working later. Signal says the primary phone must come online at least once every 30 days, linked devices can be unlinked after 45 days of inactivity, and an account can have at most five linked devices. These are maintenance limits, not OpenClaw pairing failures.

When a failure remains ambiguous, keep the account disabled and preserve the logs. Reinstalling, changing transport modes, and opening group access at the same time removes the evidence that would tell you which boundary failed.

Acceptance record for the first run

Before calling the setup ready for a real workflow, keep a small record containing the bot number, the selected account path, the signal-cli version, the effective Signal config, the status-probe output, the pairing approval, the single test message, and the rollback decision. The record can say that the run passed, needs revision, or remains unverified. It should not say that Signal integration is production-ready merely because one reply appeared.

Once the narrow test is understood, add one change at a time. A group, an attachment, a file-reading tool, or a second account deserves its own expected result and its own stop condition. The first conversation has done its job when you know exactly what it proved and exactly what it did not.

Sources

• OpenClaw: Signal — plugin architecture, separate bot number, setup paths, configuration fields, pairing, troubleshooting, and local account-state guidance. Accessed 2026-09-13.
• OpenClaw: Pairing — DM pairing behavior, code expiry, request limits, and the scope of an approval. Accessed 2026-09-13.
• OpenClaw: Channels CLI — live channel probes, account removal behavior, and the difference between disabling and deleting. Accessed 2026-09-13.
• OpenClaw: Channel troubleshooting — Signal failure signatures and the initial diagnostic path. Accessed 2026-09-13.
• AsamK/signal-cli README — linking, registration, verification, sending, receiving, update requirements, and local storage. Accessed 2026-09-13.
• Signal Support: Linked Devices — linking a secondary device, linked-device limits, and device maintenance. Accessed 2026-09-13.
• Signal Support: Unlinking devices — removing a linked client without unregistering the mobile account. Accessed 2026-09-13.