MQTT
El canal mqtt se suscribe a temas en un broker MQTT y alimenta cada mensaje en el bucle del agente o en el motor SOP. Está condicionado por la característica de compilación channel-mqtt.
Este es una fuente de eventos SOP. Para la sintaxis del trigger y la coincidencia de temas, consulta SOP Fan-In: MQTT. Esta página cubre la conexión con el broker.
Configuración
La lista completa de campos, derivada del esquema en vivo. Para un suscriptor básico, establece broker_url y topics.
broker_url*
URL del broker MQTT (p. ej., mqtt://localhost:1883 o mqtts://broker.example.com:8883). Usa mqtt:// para conexiones sin cifrar o mqtts:// para TLS.
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abra /config/channels/mqtt y establezca el campo channels.mqtt.<alias>.broker_url.
zerocode
En el panel Config, establezca el campo channels.mqtt.<alias>.broker_url.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.broker_url <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__broker_url=
client_id*
ID de cliente MQTT (debe ser único por cada broker).
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abra /config/channels/mqtt y establezca el campo channels.mqtt.<alias>.client_id.
zerocode
En el panel Config, establece el campo channels.mqtt.<alias>.client_id.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.client_id <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__client_id=
excluded_tools
Herramientas excluidas de la especificación de herramientas de este canal. Cuando se establece, estas herramientas no se exponen al modelo al responder a través de este canal.
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abre /config/channels/mqtt y establece el campo channels.mqtt.<alias>.excluded_tools.
zerocode
En el panel de Config, establezca el campo channels.mqtt.<alias>.excluded_tools.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.excluded_tools <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__excluded_tools=
keep_alive_secs
Intervalo de keep-alive en segundos (valor predeterminado: 30). Evita la desconexión del broker por inactividad.
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abra /config/channels/mqtt y establezca el campo channels.mqtt.<alias>.keep_alive_secs.
zerocode
En el panel de Config, establece el campo channels.mqtt.<alias>.keep_alive_secs.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.keep_alive_secs <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__keep_alive_secs=
password 🔑
Contraseña para autenticación (opcional).
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abre /config/channels/mqtt y establece el campo channels.mqtt.<alias>.password.
zerocode
En el panel Config, establece el campo channels.mqtt.<alias>.password.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.password # entrada enmascarada, almacenada cifrada
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__password=
qos
Nivel de QoS de MQTT (0 = como mucho una vez, 1 = al menos una vez, 2 = exactamente una vez). Valor predeterminado: 1.
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abra /config/channels/mqtt y establezca el campo channels.mqtt.<alias>.qos.
zerocode
En el panel Config, establece el campo channels.mqtt.<alias>.qos.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.qos <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__qos=
topics
Temas a los que suscribirse (p. ej., sensors/#, alerts/+/critical). Se requiere al menos un tema.
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abre /config/channels/mqtt y establece el campo channels.mqtt.<alias>.topics.
zerocode
En el panel Config, configura el campo channels.mqtt.<alias>.topics.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.topics <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__topics=
use_tls
Habilita el cifrado TLS. Debe coincidir con el esquema de broker_url: - mqtt:// → use_tls: false - mqtts:// → use_tls: true
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abre /config/channels/mqtt y establece el campo channels.mqtt.<alias>.use_tls.
zerocode
En el panel Config, establece el campo channels.mqtt.<alias>.use_tls.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.use_tls <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__use_tls=
username
Nombre de usuario para autenticación (opcional).
Colócalo sobre cualquier superficie:
Panel de control del gateway
Abre /config/channels/mqtt y establece el campo channels.mqtt.<alias>.username.
zerocode
En el panel Config, establece el campo channels.mqtt.<alias>.username.
zeroclaw config
zeroclaw config set channels.mqtt.<alias>.username <value>
Variable de entorno
Exporte la anulación (shells POSIX; colóquelo en ~/.bashrc, ~/.zshrc, .env o un Dockerfile). Reemplace <alias> con el alias literal:
export ZEROCLAW_channels__mqtt__<alias>__username=
Referencia completa de campos: referencia de configuración.
TLS
Establece use_tls para que coincida con el esquema de broker_url: mqtts:// se empareja con use_tls = true, mqtt:// con use_tls = false. Una discrepancia es la causa más común de fallo de conexión.
Las conexiones MQTT usan MQTT 3.1.1. Las conexiones TLS verifican el certificado del broker y el nombre de host con el almacén de confianza del sistema. El cliente MQTT mantenido usa el mismo verificador de certificados de Rustls parcheado que el resto de la pila TLS.
keep_alive_secs debe caber en el intervalo de 16 bits del protocolo MQTT, de 0 a 65535 segundos. Un valor fuera de rango hace que falle el inicio del listener en lugar de truncarse.
Solución de problemas
| Síntoma | Causa probable | Corregir |
|---|---|---|
| Errores de conexión al iniciar | La URL del broker y el indicador TLS no coinciden | Empareja el esquema con use_tls (mqtt:// con false, mqtts:// con true) |
| Suscrito pero sin mensajes | el filtro de tema no coincide con el tema publicado | Verifica topics y comodines frente a lo que emite el publicador |
| SOP no se inicia | desajuste de tema o una condition fallida | Comprueba el tema trigger y la condición frente al payload |
Ver también
- SOP Fan-In: MQTT: sintaxis de activación y coincidencia de topics
- AMQP
- Visión general de los canales