ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-BlueBubbles (iMessage)

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

BlueBubbles (iMessage)

通过 BlueBubbles 将 Hermes 连接到 Apple iMessage — 这是一个免费、开源的 macOS 服务器，可将 iMessage 桥接到任何设备。

前提条件

  • 一台 Mac（始终保持运行）并运行 BlueBubbles Server
  • 在该 Mac 上的 Messages.app 中登录了 Apple ID
  • BlueBubbles Server v1.0.0 或更高版本（Webhook 需要此版本）
  • Hermes 与 BlueBubbles 服务器之间的网络连通性

设置

1. 安装 BlueBubbles Server

从 bluebubbles.app 下载并安装。完成设置向导 — 使用你的 Apple ID 登录，并配置连接方式（本地网络、Ngrok、Cloudflare 或动态 DNS）。

2. 获取服务器 URL 和密码

在 BlueBubbles Server → 设置 → API 中，记下：

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

3. 配置 Hermes

运行设置向导：

bash
hermes gateway setup

选择 BlueBubbles (iMessage) 并输入你的服务器 URL 和密码。

或者直接在 ~/.hermes/.env 中设置环境变量：

bash
BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

可选：在群聊中要求提及

默认情况下，Hermes 会响应所有授权的 BlueBubbles/iMessage 私聊或群聊消息。若要使群聊变为可选加入，请启用提及门控：

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

启用 require_mention: true 后，私聊仍正常工作，但群聊消息会被忽略，除非它们匹配提及模式。如果你没有配置自定义模式，Hermes 会使用保守的默认模式，匹配 Hermes 和 @Hermes agent 的变体。

如需自定义代理名称，请设置正则表达式模式：

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

4. 授权用户

选择以下一种方式：

私聊配对（推荐）： 当有人给你的 iMessage 发送消息时，Hermes 会自动向他们发送一个配对码。使用以下命令批准：

bash
hermes pairing approve bluebubbles <CODE>

使用 hermes pairing list 查看待处理的配对码和已批准的用户。

预授权特定用户（在 ~/.hermes/.env 中）：

bash
BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

开放访问（在 ~/.hermes/.env 中）：

bash
BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 启动网关

bash
hermes gateway run

Hermes 将连接到你的 BlueBubbles 服务器，注册一个 Webhook，并开始监听 iMessage 消息。

工作原理

text
iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • 入站： 当新消息到达时，BlueBubbles 将 Webhook 事件发送到本地监听器。无需轮询 — 即时投递。
  • 出站： Hermes 通过 BlueBubbles REST API 发送消息。
  • 媒体： 支持双向传输图片、语音消息、视频和文档。入站附件会被下载并本地缓存，供代理处理。

环境变量

变量必需默认值描述
BLUEBUBBLES_SERVER_URL是—BlueBubbles 服务器 URL
BLUEBUBBLES_PASSWORD是—服务器密码
BLUEBUBBLES_WEBHOOK_HOST否127.0.0.1Webhook 监听器绑定地址
BLUEBUBBLES_WEBHOOK_PORT否8645Webhook 监听器端口
BLUEBUBBLES_WEBHOOK_PATH否/bluebubbles-webhookWebhook URL 路径
BLUEBUBBLES_HOME_CHANNEL否—用于定时任务投递的电话/邮箱
BLUEBUBBLES_ALLOWED_USERS否—逗号分隔的授权用户
BLUEBUBBLES_ALLOW_ALL_USERS否false允许所有用户
BLUEBUBBLES_REQUIRE_MENTION否false在群聊中响应前是否需要提及模式
BLUEBUBBLES_MENTION_PATTERNS否Hermes 唤醒词JSON 数组、换行分隔或逗号分隔的正则表达式模式，用于群聊提及匹配

自动将消息标记为已读由 ~/.hermes/config.yaml 中 platforms.bluebubbles.extra 下的 send_read_receipts 键控制（默认值：true）。没有对应的环境变量。

功能

文本消息

发送和接收 iMessage。Markdown 会被自动剥离，以提供干净的纯文本投递。

富媒体

  • 图片： 照片会原生显示在 iMessage 对话中
  • 语音消息： 音频文件作为 iMessage 语音消息发送
  • 视频： 视频附件
  • 文档： 文件作为 iMessage 附件发送

Tapback 反应

支持爱心、点赞、不喜欢、大笑、强调和疑问反应。需要 BlueBubbles Private API 辅助工具。

输入指示器

在代理处理消息时，iMessage 对话中会显示“正在输入...”。需要 Private API。

已读回执

处理完成后自动将消息标记为已读。需要 Private API。

聊天寻址

你可以通过邮箱或电话号码来寻址聊天 — Hermes 会自动将其解析为 BlueBubbles 聊天 GUID。无需使用原始 GUID 格式。

Private API

某些功能需要 BlueBubbles Private API 辅助工具：

  • Tapback 反应
  • 输入指示器
  • 已读回执
  • 通过地址创建新聊天

没有 Private API 时，基本的文本消息和媒体功能仍然可用。

故障排除

“无法连接服务器”

  • 确认服务器 URL 正确且 Mac 处于运行状态
  • 检查 BlueBubbles Server 是否正在运行
  • 确保网络连通性（防火墙、端口转发）

消息未到达

  • 检查 Webhook 是否已在 BlueBubbles Server → 设置 → API → Webhooks 中注册
  • 确认 Mac 可以访问 Webhook URL
  • 使用 hermes logs gateway 检查 Webhook 错误（或使用 hermes logs -f 实时跟踪）

“Private API 辅助工具未连接”

  • 安装 Private API 辅助工具：docs.bluebubbles.app
  • 没有它，基本消息功能仍可工作 — 只有反应、输入指示器和已读回执需要它
AI 前沿
上一篇

hermes教程-Honcho 内存

下一篇

hermes教程-BlueBubbles (iMessage)

分享: