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