MQTT
mqtt 通道订阅 MQTT broker 上的主题，并将每条消息输入到 agent loop 或 SOP 引擎中。它受 channel-mqtt 构建特性控制。
这是一个 SOP 事件源。 关于触发器语法和主题匹配，请参阅 SOP Fan-In: MQTT。本页涵盖代理连接。
配置
来自实时 schema 派生的完整字段列表。对于基本订阅者，您设置 broker_url 和 topics。
broker_url*
MQTT broker URL（例如 mqtt://localhost:1883 或 mqtts://broker.example.com:8883）。普通连接使用 mqtt://，TLS 使用 mqtts://。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.broker_url 字段。
zerocode
在 Config 窗格中，设置 channels.mqtt.<alias>.broker_url 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.broker_url <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__broker_url=
client_id*
MQTT 客户端 ID（在每个 broker 中必须唯一）。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.client_id 字段。
zerocode
在 Config 面板中，设置 channels.mqtt.<alias>.client_id 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.client_id <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__client_id=
excluded_tools
从此通道的工具规范中排除的工具。设置后，通过此通道响应时不会向模型公开这些工具。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.excluded_tools 字段。
zerocode
在 Config 窗格中，设置 channels.mqtt.<alias>.excluded_tools 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.excluded_tools <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__excluded_tools=
keep_alive_secs
保活间隔（秒）（默认：30）。防止代理在空闲时断开连接。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.keep_alive_secs 字段。
zerocode
在 Config 面板中，设置 channels.mqtt.<alias>.keep_alive_secs 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.keep_alive_secs <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__keep_alive_secs=
password 🔑
用于身份验证的密码（可选）。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt，并设置 channels.mqtt.<alias>.password 字段。
zerocode
在 Config 面板中，设置 channels.mqtt.<alias>.password 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.password # 掩码输入，加密存储
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__password=
qos
MQTT QoS 级别（0 = 至多一次，1 = 至少一次，2 = 恰好一次）。默认值：1。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.qos 字段。
zerocode
在 Config 窗格中，设置 channels.mqtt.<alias>.qos 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.qos <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__qos=
topics
要订阅的主题（例如，sensors/#、alerts/+/critical）。至少需要一个主题。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.topics 字段。
zerocode
在 Config 面板中，设置 channels.mqtt.<alias>.topics 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.topics <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__topics=
use_tls
启用 TLS 加密。必须与 broker_url 方案匹配：- mqtt:// → use_tls: false - mqtts:// → use_tls: true
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.use_tls 字段。
zerocode
在 Config 面板中，设置 channels.mqtt.<alias>.use_tls 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.use_tls <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__use_tls=
username
用于身份验证的用户名（可选）。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/mqtt 并设置 channels.mqtt.<alias>.username 字段。
zerocode
在 Config 窗格中，设置 channels.mqtt.<alias>.username 字段。
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.username <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__mqtt__<alias>__username=
完整字段参考：配置参考。
TLS
将 use_tls 设置为与 broker_url 的方案一致：mqtts:// 对应 use_tls = true，mqtt:// 对应 use_tls = false。不匹配是最常见的连接失败原因。
故障排除
| 症状 | 可能的原因 | 修复 |
|---|---|---|
| 启动时连接错误 | broker URL 和 TLS 标志不一致 | 将 scheme 与 use_tls 配对（mqtt:// 对应 false，mqtts:// 对应 true） |
| 已订阅但没有消息 | 主题过滤器不匹配已发布的主题 | 验证 topics 和通配符是否与发布者发出的内容一致 |
| SOP 未启动 | 主题不匹配或失败的 condition | 根据负载检查 trigger 主题和条件 |
另见
- SOP Fan-In: MQTT：触发语法和主题匹配
- AMQP
- 通道概述