MQTT
The mqtt channel subscribes to topics on an MQTT broker and feeds each message into the agent loop or the SOP engine. It is gated by the channel-mqtt build feature.
This is a SOP event source. For trigger syntax and topic matching, see SOP Fan-In: MQTT. This page covers the broker connection.
Configuration
The full field list, derived from the live schema. For a basic subscriber you set broker_url and topics.
broker_url*
MQTT broker URL (e.g., mqtt://localhost:1883 or mqtts://broker.example.com:8883). Use mqtt:// for plain connections or mqtts:// for TLS.
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.broker_url field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.broker_url field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.broker_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__mqtt__<alias>__broker_url=
client_id*
MQTT client ID (must be unique per broker).
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.client_id field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.client_id field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.client_id <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__mqtt__<alias>__client_id=
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/mqtt and set the channels.mqtt.<alias>.excluded_tools field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.excluded_tools field.
zeroclaw config
zeroclaw config set channels.mqtt.<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__mqtt__<alias>__excluded_tools=
keep_alive_secs
Keep-alive interval in seconds (default: 30). Prevents broker disconnect on idle.
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.keep_alive_secs field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.keep_alive_secs field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.keep_alive_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__mqtt__<alias>__keep_alive_secs=
password 🔑
Password for authentication (optional).
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.password field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.password field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.password # masked input, stored encrypted
Environment variable
Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:
export ZEROCLAW_channels__mqtt__<alias>__password=
qos
MQTT QoS level (0 = at-most-once, 1 = at-least-once, 2 = exactly-once). Default: 1.
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.qos field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.qos field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.qos <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__mqtt__<alias>__qos=
topics
Topics to subscribe to (e.g., sensors/#, alerts/+/critical). At least one topic is required.
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.topics field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.topics field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.topics <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__mqtt__<alias>__topics=
use_tls
Enable TLS encryption. Must match the broker_url scheme: - mqtt:// → use_tls: false - mqtts:// → use_tls: true
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.use_tls field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.use_tls field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.use_tls <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__mqtt__<alias>__use_tls=
username
Username for authentication (optional).
Set it on any surface:
Gateway dashboard
Open /config/channels/mqtt and set the channels.mqtt.<alias>.username field.
zerocode
In the Config pane, set the channels.mqtt.<alias>.username field.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.username <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__mqtt__<alias>__username=
Full field reference: config reference.
TLS
Set use_tls to match the scheme of broker_url: mqtts:// pairs with use_tls = true, mqtt:// with use_tls = false. A mismatch is the most common connection failure.
MQTT connections use MQTT 3.1.1. TLS connections verify the broker certificate and hostname against the system trust store. The maintained MQTT client uses the same patched Rustls certificate verifier as the rest of the TLS stack.
keep_alive_secs must fit the MQTT protocol’s 16-bit interval, from 0 to 65535 seconds. An out-of-range value fails listener startup instead of being truncated.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Connection errors at startup | broker URL and TLS flag disagree | Pair the scheme with use_tls (mqtt:// with false, mqtts:// with true) |
| Subscribed but no messages | topic filter does not match the published topic | Verify topics and wildcards against what the publisher emits |
| SOP not starting | topic mismatch or a failing condition | Check the trigger topic and condition against the payload |
See also
- SOP Fan-In: MQTT: trigger syntax and topic matching
- AMQP
- Channels overview