PicoClaw MQTT 通道接入指南让任意设备通过 MQTT 与 AI 代理对话【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 内置了一个轻量的 MQTT 消息通道任何 MQTT 客户端嵌入式设备、传感器、服务脚本等都可以向 Broker 发布请求PicoClaw 订阅后交由 AI 代理处理再把结果发布回响应主题。本文以 docs/channels/mqtt/README.ja.md与 docs/channels/mqtt/README.md 内容一致为骨架结合 mqtt 通道实现源码 深入讲解主题结构、全部配置字段、环境变量、重连机制与安全注意事项读完即可用mosquitto_pub/mosquitto_sub在十几分钟内打通设备 → PicoClaw → AI → 设备的完整闭环。通道工作原理MQTT 通道采用典型的发布/订阅模型请求方向设备或服务把 JSON 消息发布到{prefix}/{agent_id}/{client_id}/request主题处理方向PicoClaw 以通配符订阅该主题下所有client_id的请求解析后交给消息总线bus.MessageBus进入 AI 代理处理管线响应方向处理完成后PicoClaw 把结果发布到{prefix}/{agent_id}/{client_id}/response主题客户端订阅该主题即可收到回复。从源码看MQTT 通道通过 init.go 中的 RegisterSafeFactory 注册为类型mqtt常量定义见 pkg/config/config_channel.go实现 channels.Channel 接口。由于它复用 BaseChannel 与消息总线入站消息会像其他聊天通道一样进入完整的代理处理流程这意味着 MQTT 不只是转发一条字符串而是可以获得与 Telegram、Discord 等通道同等的 AI 能力。快速上手五步打通设备对话1. 添加通道配置编辑配置文件~/.picoclaw/config.json加入 MQTT 通道最小配置只需broker与agent_id两个必填项{ channel_list: { mqtt: { enabled: true, type: mqtt, settings: { broker: tcp://localhost:1883, agent_id: assistant } } } }仓库中的 config/config.example.json 提供了完整的通道配置示例可作为参考模板。2. 启动网关picoclaw gateway启动日志会打印订阅主题与通道状态例如MQTT channel started、Subscribed to inbound topic: /picoclaw/assistant//request。3. 发布请求用任意 MQTT 客户端向请求主题发布 JSON 负载mosquitto_pub -t /picoclaw/assistant/device1/request \ -m {text: 请检查一下 CPU 使用率}4. 订阅响应mosquitto_sub -t /picoclaw/assistant/device1/response此时终端会打印 PicoClaw 生成的回复内容。5. 验证要点请求主题与响应主题的agent_id、client_id必须一致请求 JSON 的text字段为消息正文为空会被通道丢弃见下文入站解析若 Broker 需要认证还需配置.security.yml见下文。主题结构详解通道使用两段式主题完成请求/响应路由{prefix}/{agent_id}/{client_id}/request # 客户端 → PicoClaw {prefix}/{agent_id}/{client_id}/response # PicoClaw → 客户端段说明prefix主题前缀服务端配置默认/picoclawagent_idPicoClaw 实例标识符对应settings.agent_id字段client_id客户端自定义的会话标识符。同一设备持续使用相同 ID 即可保持对话上下文通配符订阅与主题解析从源码可见PicoClaw 实际订阅的是带单层通配符的主题从而服务任意数量的客户端订阅主题{prefix}/{agent_id}//request见 mqtt.go 的 subscribe 方法收到消息后clientIDFromTopic 先剥离{prefix}/{agent_id}/固定前缀再截取client_id段进而构造出会话 IDmqtt:{client_id}响应时按会话 ID 反向拼回{prefix}/{agent_id}/{client_id}/response主题见 Send 方法。topicPrefix()会做归一化处理剥离尾部斜杠若配置为空则回退到默认值/picoclaw见 mqtt.go因此前缀配成/picoclaw/或/picoclaw效果一致。消息负载格式JSON请求与响应均使用统一的 JSON 结构{ text: 消息内容 }入站侧只接受含非空text的 JSON解析失败或text为空都会记录警告并丢弃消息见 handleInbound。这是通道对负载格式的硬性校验客户端侧务必遵守。配置详解config.json 完整配置{ channel_list: { mqtt: { enabled: true, type: mqtt, settings: { broker: ssl://your-broker:8883, agent_id: assistant, topic_prefix: /picoclaw, client_id: , keep_alive: 60, qos: 0 } } } }.security.yml认证信息用户名与密码不要写入 config.json而是存放在~/.picoclaw/.security.yml运行时由安全配置机制合并读取相关实现见 pkg/config/security.gochannel_list: mqtt: settings: username: your_username password: your_password源码中用户名与密码使用SecureString类型MQTTSettings 定义该类型在保存与日志输出时会做敏感信息收集与脱敏处理避免凭据明文泄漏。配置字段一览字段位置必填默认值说明brokersettings是—MQTT Broker URL如tcp://host:1883、ssl://host:8883agent_idsettings是—代理标识符作为主题路径的一部分topic_prefixsettings否/picoclaw主题命名空间前缀username.security.yml否—Broker 认证用户名password.security.yml否—Broker 认证密码client_idsettings否自动生成发送给 Broker 的 paho 客户端 ID。未设置时按picoclaw-mqtt-{agent_id}-{8位hex}自动生成进程存活期间固定不变重连时复用同一 IDkeep_alivesettings否60MQTT 保活间隔秒qossettings否0发布与订阅的 QoS 级别0、1或2环境变量所有字段均可用环境变量覆盖struct tag 中的env定义见 pkg/config/config.go环境变量对应字段PICOCLAW_CHANNELS_MQTT_BROKERbrokerPICOCLAW_CHANNELS_MQTT_AGENT_IDagent_idPICOCLAW_CHANNELS_MQTT_TOPIC_PREFIXtopic_prefixPICOCLAW_CHANNELS_MQTT_USERNAMEusernamePICOCLAW_CHANNELS_MQTT_PASSWORDpasswordPICOCLAW_CHANNELS_MQTT_CLIENT_IDclient_idPICOCLAW_CHANNELS_MQTT_KEEP_ALIVEkeep_alivePICOCLAW_CHANNELS_MQTT_QOSqos适合在 Docker、Kubernetes 等容器化部署中通过环境变量注入 Broker 地址与凭据避免把配置写死在镜像里。源码级原理paho 客户端初始化通道基于 Eclipse Paho MQTT 客户端github.com/eclipse/paho.mqtt.golang实现Start 方法 完整展示了连接建立过程几个关键细节值得注意必填校验broker与agent_id为空时直接报错通道无法创建见 NewMQTTChannelclient_id 自动生成未配置时使用crypto/rand生成 4 字节随机数并 hex 编码拼出picoclaw-mqtt-{agent_id}-{8位hex}保证同一进程内唯一且进程生命周期内稳定keep_alive 兜底配置值 ≤ 0 时强制回退为 60 秒自动重连SetAutoReconnect(true)与SetConnectRetry(true)同时开启重连间隔固定为 5 秒TLS 默认跳过证书校验tls.Config{InsecureSkipVerify: true}配合ssl://协议使用连接超时建立连接最多等待 10 秒超时或失败会调用Disconnect(250)并返回错误订阅时序通过OnConnect回调在每次重连成功后执行订阅保证断线重连后订阅自动恢复首次订阅成功前Start不会返回。QoS 与消息可靠性qos同时作用于订阅client.Subscribe(topic, c.qos, ...)与发布client.Publish(topic, c.qos, false, data)发布时retained固定为false见 Send即不产生保留消息。生产环境可结合 Broker 侧 QoS 语义选择QoS 0 性能最好但可能丢消息对可靠性要求高的指令场景建议至少 QoS 1。断线重连机制PicoClaw 对连接断开采用自动恢复策略连接丢失后paho 客户端以5 秒间隔自动重连 Broker每次重连成功都会触发OnConnect回调重新建立订阅因此无需人工干预重连期间 broker 侧客户端 ID 保持不变Broker 会将其识别为同一会话避免会话状态错乱。日志中会通过ConnectionLostHandler记录MQTT connection lost警告方便排查网络波动。若 Broker 在 10 秒内不可达Start会直接报错退出因此启动前请确认 Broker 地址与网络可达性。注意事项与最佳实践TLS 支持Broker URL 使用ssl://即启用 SSL/TLS注意默认跳过证书校验InsecureSkipVerify: true生产环境若对中间人攻击敏感需要自行在源码层调整为可信 CA 校验流式响应开启流式输出时响应主题会收到多条消息需按顺序拼接才能得到完整回复client_id 与会话 ID 的区别主题路径中的client_id是客户端应用自定义的会话标识符用于维持对话上下文它与 PicoClaw 连接 Broker 所用的 paho 客户端 ID自动生成的picoclaw-mqtt-*是完全不同的两个概念不要混淆多实例部署若多个 PicoClaw 实例以相同agent_id连接同一 Broker必须为每个实例配置不同的client_id否则 broker 级客户端 ID 冲突会导致连接互踢访问控制MQTT 通道默认接受所有client_id的消息。通道配置还支持allow_from白名单等通用安全项BaseChannel 在空白名单时会打印安全警告见 base.go公网暴露的 Broker 上建议显式配置访问限制并优先使用 TLS 用户名密码认证。典型应用场景嵌入式/边缘设备开发板、传感器网关把采集数据或控制指令发到 request 主题由 AI 代理解析并生成回复或操作建议服务间集成将 PicoClaw 作为AI 消息服务接入现有微服务服务只需一个 MQTT 客户端即可获得自然语言处理能力IoT 控制面板面板订阅 response 主题统一展示 AI 回复同时向 request 主题下发指令实现统一的设备对话入口。结合 MQTT 通道源码 与本指南你已掌握主题约定、全部配置项与底层连接行为从mosquitto_pub发出一条 JSON 请求开始即可在数分钟内把 PicoClaw 接入自己的设备体系。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考