🤖HermesBlog
Hermes 消息平台接入 · 第14篇2026/8/9· Easy Understand Hermes Agent

让 AI 用上 iMessage？BlueBubbles 帮你搞定！

Hermes 消息平台接入第14篇：BlueBubbles。在 iPhone 的 iMessage 里用 Hermes。

让 AI 用上 iMessage？BlueBubbles 帮你搞定！

嘿，各位！今天咱们来聊一个特别酷的东西——让 Hermes 用 iMessage 给你发消息。想象一下，你的 AI 助手突然有了苹果的“蓝泡泡”，是不是瞬间高大上了？

这是啥原理？

简单说，BlueBubbles 是一个跑在 Mac 上的免费开源服务器，它把 iMessage 桥接到任何设备上。Hermes 通过它就能收发 iMessage 了，就像用微信一样方便。

准备工作

你需要：

  • 一台常开的 Mac（装 BlueBubbles Server）
  • Mac 上登录了 Apple ID 的“信息”应用
  • BlueBubbles Server v1.0.0 或更高版本（老版本不支持 webhook）

三步搞定配置

第一步：装服务器

去 bluebubbles.app 下载安装，跟着向导走就行。连接方式可以选本地网络、Ngrok、Cloudflare 等，看你的需求。

第二步：记下服务器地址和密码

打开 BlueBubbles Server → 设置 → API，记下：

  • 服务器 URL（比如 http://192.168.1.10:1234）
  • 服务器密码

第三步：配置 Hermes

运行设置向导：

hermes gateway setup

选择 BlueBubbles (iMessage)，填入刚才记下的信息。

或者直接编辑 ~/.hermes/.env 文件：

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=你的服务器密码

群聊防打扰小技巧

默认情况下，Hermes 会回复所有消息。如果你只想让它响应特定称呼，可以在 ~/.hermes/config.yaml 里开启：

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

这样私聊照常回复，但群聊里只有提到“Hermes”或“@Hermes agent“才会响应。想自定义称呼？设置正则表达式就行：

platforms:
  bluebubbles:
    extra:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

授权用户，安全第一

推荐方式——配对码： 有人给你发 iMessage 时，Hermes 会自动发配对码。用这个命令批准：

hermes pairing approve bluebubbles <CODE>

查看待处理的配对码用 hermes pairing list。

指定用户： 在 .env 里加：

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

完全开放（慎用）：

BLUEBUBBLES_ALLOW_ALL_USERS=true

启动，并确认真的连上了

hermes gateway run

Hermes 会自动注册 webhook、开始监听 iMessage。但“看起来跑起来了”和“真的通了”是两码事，建议按下面三步确认：

① 先看配置项有没有被显式关掉

设置向导只把凭据写进 ~/.hermes/.env，不会往 ~/.hermes/config.yaml 写 platforms.bluebubbles.enabled。没有这个键时，凭据就足以让适配器启动；但显式写了 enabled: false 就一定压过凭据——如果你以前用过别的 iMessage 桥接而把 BlueBubbles 关掉过，向导会报成功，适配器却永远不启动。

hermes config get platforms.bluebubbles.enabled
  • true —— 显式启用
  • Config key not set —— 没有显式设置，凭据说了算
  • false —— 被显式禁用；重跑向导也不会改回来，得自己设成 true

② 在网关日志里找两行“铁证”

hermes logs gateway
[bluebubbles] connected to http://192.168.1.10:1234 (private_api=False, helper=False)
[bluebubbles] webhook registered with server: http://localhost:8645/bluebubbles-webhook?password=***

③ 用另一台设备给自己发条测试消息：收到回复（新私聊则是配对码）才算端到端打通。

两个 URL，方向正好相反

配置里有两条 URL 最容易搞混，记住它们的方向：

  • BLUEBUBBLES_SERVER_URL（如 http://192.168.1.10:1234）—— Hermes 主动调用你 BlueBubbles 服务器的 API，就是 BlueBubbles Server → 设置 → API 里显示的服务地址
  • webhook（默认 http://localhost:8645/bluebubbles-webhook）—— BlueBubbles 主动 POST 新消息事件给 Hermes。主机/端口/路径来自 BLUEBUBBLES_WEBHOOK_HOST / BLUEBUBBLES_WEBHOOK_PORT / BLUEBUBBLES_WEBHOOK_PATH

webhook 不用你手动建：网关一连上，Hermes 就通过 BlueBubbles REST API（/api/v1/webhook）自己注册 new-message 和 updated-message 事件，干净关闭时再注销掉。两个细节值得知道：

  • 注册的 URL 把服务器密码作为查询参数带上（?password=…），因为 BlueBubbles 的 webhook API 不支持自定义请求头——入站事件就靠它认证
  • webhook 监听默认绑在 127.0.0.1。Hermes 和 BlueBubbles 在同一台机器上没问题；不在同一台，就要把 BLUEBUBBLES_WEBHOOK_HOST 设成那台 Mac 能访问到的地址

有啥好玩的？

  • 文字消息：收发 iMessage，自动去掉 Markdown 格式
  • 图片/语音/视频/文件：双向传输，入站附件自动缓存
  • Tapback 反应：👍❤️😂 都能发（需要 Private API）
  • 正在输入提示：AI 思考时显示“正在输入…”（需要 Private API）
  • 已读回执：处理完自动标记已读（需要 Private API）

遇到问题？

  • 连不上服务器：检查 Mac 是否开机、BLUEBUBBLES_SERVER_URL 是否正确、防火墙有没有放行。注意 Hermes 用的是 .env 里的地址，不是 BlueBubbles 界面里那个（DHCP 换 IP 后界面上的可能已经过期）
  • 收不到消息：先用 hermes logs gateway 看 webhook 报错。Hermes 连上时会自己注册 webhook，只有日志里出现注册失败才需要去 BlueBubbles Server → 设置 → API → Webhooks 里翻；UI 里有一行 webhook 记录并不代表投递成功，真正的证据是 Hermes 记录到消息并回了话。另外：跨机器部署时默认的 127.0.0.1 那台 Mac 访问不到，要设 BLUEBUBBLES_WEBHOOK_HOST 并重启网关
  • 向导成功了，适配器却从不启动：因为 enabled: false 压过凭据。用 hermes config get platforms.bluebubbles.enabled 查，必要时显式设成 true；从别的 iMessage 桥接切过来时最容易踩这个坑（两个桥接同时开着还会重复处理消息）
  • 一台 Mac 上跑了两个 BlueBubbles 服务器（Apple ID 弄错）：两个 macOS 用户各跑一个服务器、各自有 API 端口和 Apple ID。用 curl "http://<server-url>/api/v1/server/info?password=<password>" 比对 computer_id，确认 Hermes 连的是哪一个；多用户部署要一个用户一个端口，并且不要注销跑服务器那个用户
  • 重复回复：已知问题——会话处理可能把同一个联系人拆成两个会话（raw-GUID 形式和手机号/邮箱形式），跟踪 issue #30708 和 #34372
  • 反复出现「♻️ Recovered reply」或发送卡住好几分钟：如果配了 BLUEBUBBLES_HOME_CHANNEL，网关重启和平台重连会通知 home channel，可能把待发回复重新投递一遍；而 BlueBubbles 侧静默发送失败（后台 macOS 用户常见的 Not authorized to send Apple events to Messages. (-1743)，超时还特别长）会让重试堆积，挤掉 webhook 投递。发送可靠性没验证前，先让 home channel 留空
  • Private API 报错：去 这里 装辅助包。顺带说一句：「不用 Private API 也能基本收发消息」的前提是 BlueBubbles 能在已登录用户的图形会话里驱动「信息」应用——如果那台 Mac 停在登录界面，或者服务器用户被快速用户切换踢到后台，AppleScript 发送就会失败，这种情况下连可靠发送都需要 Private API，而不只是那些附加功能（多用户部署参考 BlueBubbles: multiple users on the same Mac）

好了，快去试试让你的 AI 用上 iMessage 吧！有问题评论区见～

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/messaging/bluebubbles

← 返回全部文章