Signal
ZeroClaw’s Signal channel talks to a running signal-cli HTTP daemon. Signal does not provide an official bot API, so ZeroClaw connects to signal-cli over local HTTP and lets signal-cli own the Signal account, device keys, and message transport.
Use this channel when you already operate a Signal account with signal-cli, or when you can run the daemon next to ZeroClaw. If you only have the Signal desktop or mobile app installed, that is not enough by itself; ZeroClaw needs the HTTP daemon endpoint.
Who can talk to the agent
Inbound senders are gated against the peer set resolved for the bound
agent, drawn from the peer_groups config the agent belongs to. Matching strips
a leading @ and is case-insensitive against the channel’s native sender
identifier. An empty set denies everyone; a set containing "*" accepts
anyone; otherwise only the listed external peers (and peer agents) are accepted.
This is separate from gateway pairing (gateway.require_pairing), which
authenticates HTTP/WebSocket clients, not chat-channel senders.
A peer group for signal sets channel to signal, lists the allowed senders in
external_peers (for signal, an E.164 phone number or a signal-cli source identifier; ["*"] accepts anyone), optionally
names peer agents for cross-agent dispatch, an ignore blocklist, and an
output_modality (mirror, voice, or text). See Peer Groups
for the field reference.
Where to set this:
Gateway dashboard
Open /config/peer_groups in the web dashboard.
zerocode
In the Config pane, under Peer groups.
You can also narrow traffic at the channel level: dm_only = true ignores
groups; group_ids = ["<signal-group-id>"] accepts only listed groups while
still accepting DMs; ignore_attachments and ignore_stories drop those
message types before they reach the agent.
Prerequisites
- A Signal account linked or registered in
signal-cli. - A running
signal-cliHTTP daemon, for examplesignal-cli daemon --http 127.0.0.1:8686. - A ZeroClaw build with the
channel-signalfeature enabled.
Keep the daemon bound to localhost unless you have put it behind your own authenticated network boundary. The daemon can send and receive as the linked Signal account.
Configure the channel
account*
E.164 phone number of the signal-cli account (e.g. “+1234567890”).
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.account field.
zerocode
In the Config pane, set the channels.signal.<alias>.account field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.account <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__account=
approval_timeout_secs
Seconds to wait for operator approval on always_ask tools before auto-denying.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.approval_timeout_secs field.
zerocode
In the Config pane, set the channels.signal.<alias>.approval_timeout_secs field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.approval_timeout_secs <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__approval_timeout_secs=
dm_only
When true, only accept direct messages and ignore all group traffic. Mutually exclusive with group_ids (which is ignored when this is set). Migrated from the legacy group_id = "dm" sentinel.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.dm_only field.
zerocode
In the Config pane, set the channels.signal.<alias>.dm_only field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.dm_only <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__dm_only=
excluded_tools
Tools excluded from this channel’s tool spec. When set, these tools are not exposed to the model when responding via this channel.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.excluded_tools field.
zerocode
In the Config pane, set the channels.signal.<alias>.excluded_tools field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.excluded_tools <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__excluded_tools=
group_ids
Group IDs to filter messages. Empty = accept all messages (DMs and groups). When non-empty, only messages from listed groups are accepted (DMs are still accepted unless dm_only flips the policy to DMs-only). Migrated from the legacy group_id singular field.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.group_ids field.
zerocode
In the Config pane, set the channels.signal.<alias>.group_ids field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.group_ids <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__group_ids=
http_url*
Base URL for the signal-cli HTTP daemon (e.g. "http://127.0.0.1:8686").
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.http_url field.
zerocode
In the Config pane, set the channels.signal.<alias>.http_url field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.http_url <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__http_url=
ignore_attachments
Skip messages that are attachment-only (no text body).
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.ignore_attachments field.
zerocode
In the Config pane, set the channels.signal.<alias>.ignore_attachments field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.ignore_attachments <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__ignore_attachments=
ignore_stories
Skip incoming story messages.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.ignore_stories field.
zerocode
In the Config pane, set the channels.signal.<alias>.ignore_stories field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.ignore_stories <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__ignore_stories=
proxy_url
Per-channel proxy URL (http, https, socks5, socks5h). Overrides the global [proxy] setting for this channel only.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.proxy_url field.
zerocode
In the Config pane, set the channels.signal.<alias>.proxy_url field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.proxy_url <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__proxy_url=
reply_min_interval_secs
Per-(channel, recipient) outbound pacing floor in seconds. Range: 0..=REPLY_MIN_INTERVAL_MAX_SECS (0 disables).
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.reply_min_interval_secs field.
zerocode
In the Config pane, set the channels.signal.<alias>.reply_min_interval_secs field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.reply_min_interval_secs <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__reply_min_interval_secs=
reply_queue_depth_max
Per-(channel, recipient) outbound pacing queue depth. Range: 0..=REPLY_QUEUE_DEPTH_CEILING. When reply_min_interval_secs > 0 and this value is 0, the pacing wrapper substitutes DEFAULT_REPLY_QUEUE_DEPTH (16). When the queue is full, the newest send is dropped and a WARN is logged.
Set it on any surface:
Gateway dashboard
Open /config/channels/signal and set the channels.signal.<alias>.reply_queue_depth_max field.
zerocode
In the Config pane, set the channels.signal.<alias>.reply_queue_depth_max field.
zeroclaw config
zeroclaw config set channels.signal.<alias>.reply_queue_depth_max <value>
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__signal__<alias>__reply_queue_depth_max=
Gateway dashboard
Open /config/channels/signal in the web dashboard.
zerocode
In the Config pane, under Channels.
Bind the channel to an agent via that agent’s channels list.
Start and check
Start the daemon first, then start ZeroClaw channels:
sh
signal-cli daemon --http 127.0.0.1:8686
zeroclaw channel start
Use zeroclaw channel doctor to confirm ZeroClaw can load the configured channel. If the channel fails at runtime, check that http_url points at the daemon, the account is registered in signal-cli, and the build includes channel-signal.
Common confusion
The signal-cli project is primarily known as a CLI, but ZeroClaw needs its HTTP daemon mode. If you installed only the command-line binary and never started the daemon, ZeroClaw has nothing to connect to.