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.
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