当前位置： 首页 > news >正文

OpenClaw从入门到应用——频道：BlueBubbles

news 2026/8/13 1:38:45

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

(macOS REST) 状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。推荐用于 iMessage 集成，相比传统的 imsg 通道，其 API 更丰富且设置更简单。

概述

  • 通过 BlueBubbles 辅助应用运行于 macOS（bluebubbles.app）。
  • 推荐/测试：macOS Sequoia (15)。macOS Tahoe (26) 也可工作；目前 Tahoe 上编辑功能不可用，群组图标更新可能报告成功但不同步。
  • OpenClaw 通过其 REST API（GET /api/v1/ping，POST /message/text，POST /chat/:id/*）与之通信。
  • 入站消息通过 webhooks 到达；出站回复、输入指示器、已读回执和轻拍回复（tapbacks）通过 REST 调用实现。
  • 附件和贴纸作为入站媒体被接收（并在可能时提供给智能体）。
  • 配对/白名单的工作方式与其他通道相同（/channels/pairing等），通过channels.bluebubbles.allowFrom+ 配对码。
  • 反应（reactions）像 Slack/Telegram 一样作为系统事件呈现，以便智能体在回复前可以“提及”它们。
  • 高级功能：编辑、撤回、回复线程、消息特效、群组管理。

快速开始

  1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 bluebubbles.app/install 上的说明操作）。
  2. 在 BlueBubbles 配置中，启用 Web API 并设置密码。
  3. 运行openclaw onboard并选择 BlueBubbles，或手动配置：
    { channels: { bluebubbles: { enabled: true, serverUrl: "http://192.168.1.100:1234", password: "example-password", webhookPath: "/bluebubbles-webhook", }, }, }
  4. 将 BlueBubbles webhooks 指向你的网关（示例：https://your-gateway-host:3000/bluebubbles-webhook?password=）。
  5. 启动网关；它将注册 webhook 处理器并开始配对。

安全提示：

  • 始终设置 webhook 密码。
  • 始终要求 webhook 认证。无论环回/代理拓扑如何，OpenClaw 会拒绝不包含与channels.bluebubbles.password匹配的密码/guid（例如?password=或x-password）的 BlueBubbles webhook 请求。
  • 密码认证在读取/解析完整 webhook 正文之前进行。

保持 Messages.app 存活（虚拟机/无头设置）

某些 macOS 虚拟机/常开设置可能导致 Messages.app 进入“空闲”状态（入站事件停止，直到应用被打开/前置）。一个简单的解决方法是每 5 分钟使用 AppleScript + LaunchAgent 轻触（poke）Messages。

1) 保存 AppleScript

保存为：~/Scripts/poke-messages.scpt
示例脚本（非交互式；不会抢夺焦点）：

try tell application "Messages" if not running then launch -- 触碰脚本界面以保持进程响应。 set _chatCount to (count of chats) end tell on error -- 忽略临时失败（首次运行提示、锁定的会话等）。 end try

2) 安装 LaunchAgent

保存为：~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPEplistPUBLIC"-//Apple//DTD PLIST 1.0//EN""http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plistversion="1.0"><dict><key>Label</key><string>com.user.poke-messages</string><key>ProgramArguments</key><array><string>/bin/bash</string><string>-lc</string><string>/usr/bin/osascript "$HOME/Scripts/poke-messages.scpt"</string></array><key>RunAtLoad</key><true/><key>StartInterval</key><integer>300</integer><key>StandardOutPath</key><string>/tmp/poke-messages.log</string><key>StandardErrorPath</key><string>/tmp/poke-messages.err</string></dict></plist>

说明：

  • 该脚本每 300 秒运行一次，并在登录时运行。
  • 首次运行可能触发 macOS自动化提示（osascript→ Messages）。请在与运行 LaunchAgent 相同的用户会话中批准它们。

加载它：

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist2>/dev/null||truelaunchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

入手指南

BlueBubbles 在交互式设置向导中可用：

openclaw onboard

向导会提示输入：

  • 服务器 URL（必填）：BlueBubbles 服务器地址（例如http://192.168.1.100:1234）
  • 密码（必填）：BlueBubbles 服务器设置中的 API 密码
  • Webhook 路径（可选）：默认为/bluebubbles-webhook
  • 私聊策略：配对、白名单、开放或禁用
  • 白名单：电话号码、邮箱或聊天目标

你也可以通过 CLI 添加 BlueBubbles：

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

访问控制（私聊 + 群组）

私聊：

  • 默认：channels.bluebubbles.dmPolicy = "pairing"。
  • 未知发送者会收到一个配对码；消息被忽略直到批准（配对码 1 小时后过期）。
  • 批准方式：
    • openclaw pairing list bluebubbles
    • openclaw pairing approve bluebubbles <code>
  • 配对是默认的令牌交换方式。详情：Pairing （链接已替换）

群组：

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled（默认：allowlist）。
  • channels.bluebubbles.groupAllowFrom控制在设置allowlist时谁可以在群组中触发。

提及门槛（群组）

BlueBubbles 支持群聊的提及门槛，匹配 iMessage/WhatsApp 行为：

  • 使用agents.list[].groupChat.mentionPatterns（或messages.groupChat.mentionPatterns）检测提及。
  • 当群组启用了requireMention时，智能体仅在被告知时响应。
  • 授权发送者的控制命令会绕过提及门槛。

按群组配置：

{ channels: { bluebubbles: { groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // 所有群组的默认值 "iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖 }, }, }, }

命令门槛

  • 控制命令（例如/config，/model）需要授权。
  • 使用allowFrom和groupAllowFrom确定命令授权。
  • 授权发送者即使在群组中未被提及也可以运行控制命令。

输入指示器 + 已读回执

  • 输入指示器：在响应生成之前和期间自动发送。
  • 已读回执：由channels.bluebubbles.sendReadReceipts控制（默认：true）。
  • 输入指示器：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入（通过 DELETE 手动停止不可靠）。
{ channels: { bluebubbles: { sendReadReceipts: false, // 禁用已读回执 }, }, }

高级操作

BlueBubbles 在配置中启用时支持高级消息操作：

{ channels: { bluebubbles: { actions: { reactions: true, // 轻拍回复（默认：true） edit: true, // 编辑已发送消息（macOS 13+，macOS 26 Tahoe 上不可用） unsend: true, // 撤回消息（macOS 13+） reply: true, // 按消息 GUID 回复线程 sendWithEffect: true, // 消息特效（slam, loud 等） renameGroup: true, // 重命名群聊 setGroupIcon: true, // 设置群聊图标/照片（macOS 26 Tahoe 上不稳定） addParticipant: true, // 添加参与者到群组 removeParticipant: true, // 从群组移除参与者 leaveGroup: true, // 离开群聊 sendAttachment: true, // 发送附件/媒体 }, }, }, }

可用操作：

  • react：添加/移除轻拍回复反应（messageId，emoji，remove）
  • edit：编辑已发送消息（messageId，text）
  • unsend：撤回消息（messageId）
  • reply：回复特定消息（messageId，text，to）
  • sendWithEffect：使用 iMessage 特效发送（text，to，effectId）
  • renameGroup：重命名群聊（chatGuid，displayName）
  • setGroupIcon：设置群聊图标/照片（chatGuid，media）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。
  • addParticipant：将某人添加到群组（chatGuid，address）
  • removeParticipant：从群组移除某人（chatGuid，address）
  • leaveGroup：离开群聊（chatGuid）
  • sendAttachment：发送媒体/文件（to，buffer，filename，asVoice）
  • 语音备忘录：设置asVoice: true配合MP3或CAF音频，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时将 MP3 转换为 CAF。

消息 ID（短 ID vs 完整 ID）

OpenClaw 可能呈现短消息 ID（例如1，2）以节省令牌。

  • MessageSid/ReplyToId可以是短 ID。
  • MessageSidFull/ReplyToIdFull包含提供者的完整 ID。
  • 短 ID 在内存中；重启或缓存清除后可能过期。
  • 操作接受短或完整的messageId，但如果短 ID 不再可用则会报错。

对于持久化自动化和存储，请使用完整 ID：

  • 模板：{{MessageSidFull}}，{{ReplyToIdFull}}
  • 上下文：入站负载中的MessageSidFull/ReplyToIdFull

有关模板变量，请参阅 Configuration （链接已替换）。

块流式传输

控制响应是作为单条消息发送还是分块流式传输：

{ channels: { bluebubbles: { blockStreaming: true, // 启用块流式传输（默认关闭） }, }, }

媒体 + 限制

  • 入站附件被下载并存储在媒体缓存中。
  • 媒体大小上限通过channels.bluebubbles.mediaMaxMb控制入站和出站媒体（默认：8 MB）。
  • 出站文本被分块为channels.bluebubbles.textChunkLimit（默认：4000 字符）。

配置参考

完整配置：Configuration （链接已替换）

提供者选项：

  • channels.bluebubbles.enabled：启用/禁用通道。
  • channels.bluebubbles.serverUrl：BlueBubbles REST API 基础 URL。
  • channels.bluebubbles.password：API 密码。
  • channels.bluebubbles.webhookPath：Webhook 端点路径（默认：/bluebubbles-webhook）。
  • channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
  • channels.bluebubbles.allowFrom：私聊白名单（句柄、邮箱、E.164 号码、chat_id:*、chat_guid:*）。
  • channels.bluebubbles.groupPolicy：open | allowlist | disabled（默认：allowlist）。
  • channels.bluebubbles.groupAllowFrom：群组发送者白名单。
  • channels.bluebubbles.groups：按群组配置（requireMention等）。
  • channels.bluebubbles.sendReadReceipts：发送已读回执（默认：true）。
  • channels.bluebubbles.blockStreaming：启用块流式传输（默认：false；流式回复所需）。
  • channels.bluebubbles.textChunkLimit：出站分块大小（字符数，默认：4000）。
  • channels.bluebubbles.chunkMode：length（默认）仅在超出textChunkLimit时分块；newline在长度分块前按空行（段落边界）分块。
  • channels.bluebubbles.mediaMaxMb：入站/出站媒体大小上限（MB，默认：8）。
  • channels.bluebubbles.mediaLocalRoots：允许的出站本地媒体路径的绝对本地目录显式白名单。默认情况下，除非配置此项，否则禁止发送本地路径。
    每个账户覆盖：channels.bluebubbles.accounts.<name>.mediaLocalRoots。
  • channels.bluebubbles.historyLimit：群组上下文的最大消息数（0 禁用）。
  • channels.bluebubbles.dmHistoryLimit：私聊历史记录限制。
  • channels.bluebubbles.actions：启用/禁用特定操作。
  • channels.bluebubbles.accounts：多账户配置。

相关全局选项：

  • agents.list[].groupChat.mentionPatterns（或messages.groupChat.mentionPatterns）。
  • messages.responsePrefix。

寻址/投递目标

优先使用chat_guid实现稳定路由：

  • chat_guid:iMessage;-;+15555550123（群组首选）
  • chat_id:123
  • chat_identifier:...
  • 直接句柄：+15555550123，user@example.com
  • 如果直接句柄没有现有的私聊，OpenClaw 将通过POST /api/v1/chat/new创建一个。这需要启用 BlueBubbles 私有 API。

安全

  • Webhook 请求通过将guid/password查询参数或标头与channels.bluebubbles.password进行比较来认证。来自localhost的请求也被接受。
  • 保持 API 密码和 webhook 端点机密（将其视为凭证）。
  • localhost 信任意味着同一主机上的反向代理可能会意外绕过密码。如果你代理网关，请在代理处要求认证，并配置gateway.trustedProxies。请参阅 Gateway security （链接已替换）。
  • 如果要将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。

故障排除

  • 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证网关路径是否与channels.bluebubbles.webhookPath匹配。
  • 配对码一小时后过期；使用openclaw pairing list bluebubbles和openclaw pairing approve bluebubbles <code>。
  • 反应需要 BlueBubbles 私有 API（POST /api/v1/message/react）；确保服务器版本公开它。
  • 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，编辑目前因私有 API 更改而无法使用。
  • 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标未同步。
  • OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果编辑在 macOS 26（Tahoe）上仍然显示，请使用channels.bluebubbles.actions.edit=false手动禁用它。
  • 状态/健康信息：openclaw status --all或openclaw status --deep。

有关一般通道工作流程参考，请参阅 Channels 和 Plugins 指南（链接已替换）。

Built with Mintlify。

http://www.cnnetsun.cn/news/1628673.html

相关文章：

  • Ruoyi-Cloud整合Seata2.0踩坑实录：从Nacos配置到分布式事务实战
  • 电脑风扇噪音难忍？FanControl让散热管理变简单 - 开源智能风扇控制解决方案全解析
  • 利用Pixel Couplet Gen进行A/B测试：优化春节活动页面转化率
  • 5大核心功能解锁网页资源：猫抓开源工具让媒体捕获效率提升300%
  • 为什么WindTerm成为开发者的首选终端工具？深度评测与替代方案对比
  • ESP32实战指南：继电器与伺服电机的精准控制方案
  • 如何用Real-ESRGAN-GUI让模糊图片重获新生：双引擎AI图像超分辨率实战指南
  • 佳能全能清零软件报错5B00,5B01,5B02,1700,1701,1702,1704,P07，通过下面软件轻松修好，亲测完美。
  • LeetCode 128. Longest Consecutive Sequence 题解
  • cadence设置叠层
  • 实测阿里造相Z-Image-Turbo：8步生成惊艳图片，新手友好WebUI体验
  • 告别foobar2000界面痛点：foobox-cn如何3步打造沉浸式音乐体验
  • ML-Decoder实战：如何用这个万能分类头提升你的多标签分类模型性能（附代码）
  • 手把手教你用UML用例图梳理业务流程（附真实项目案例）
  • Wireshark抓包实战：用一道CTF题彻底搞懂IP分片与UDP重组
  • MySQL日期类型选择指南：告别纠结，选对类型
  • 别再只调参了！深入WDCNN第一层宽卷积核：为什么它对振动信号诊断这么有效？
  • 深入解析UDS协议中的0x28通讯控制服务
  • AI梯度下降与交叉熵损失的核心思想解析
  • 别只跑Demo了！用Qwen2-VL-7B-Instruct模型打造你的本地多模态AI助手：从图片分析到文档问答
  • 收藏！AI时代高薪抢人大战，普通程序员如何不被裁，抓住升薪机遇？
  • 3步实现高效转换：让专业排版效率提升80%的开源解决方案
  • 如何用Mermaid Live Editor 5分钟创建专业图表
  • MedGemma-X优化升级：如何配置systemd服务实现开机自启与崩溃自愈
  • PyTorch 2.8镜像实战指南：基于FFmpeg 6.0的视频I/O性能优化与GPU硬编解码
  • 从“对话”到“执行”：OpenClaw龙虾在物业行业的深度应用场景解析
  • 使用快马平台基于OpenSpec一键生成可运行API原型，加速接口设计验证
  • 赋能商贸流通：如何甄选好用的订货管理系统助力企业增长
  • 【可分离架构物理信息神经网络：破解维度灾难的分离变量方法论】第3章 张量分解PINN：CP、TT与Tucker架构
  • comfyui_controlnet_aux功能异常修复实用指南：从诊断到预防的完整解决方案