iMessage 频道配置

OpenClaw 通过 BlueBubbles 桥接实现 iMessage 接入。你需要一台常开的 Mac 作为 BlueBubbles Server。

预计耗时

完成全部配置约需 30-45 分钟。

前置条件

• 一台 macOS 设备（必须保持开机运行）
• 已登录 iMessage 的 Apple ID
• Mac 上已安装并运行 BlueBubbles Server

macOS 26 Tahoe 已知问题

macOS 26 Tahoe 上 iMessage 编辑功能存在回归 bug（issue #32275）。编辑过的消息可能无法正确同步到 OpenClaw。如果你依赖消息编辑功能，建议暂时使用 macOS 15 Sequoia。

第一步：安装 BlueBubbles Server

1. 前往 BlueBubbles 官网 下载 macOS Server
2. 安装并启动 BlueBubbles Server
3. 按照初始设置向导完成 Google Firebase 配置（用于推送通知）
4. 确保 BlueBubbles 能正常收发 iMessage 消息

第二步：启用 Web API

1. 在 BlueBubbles Server 中，进入 Settings → API / Web
2. 开启 Enable REST API
3. 记录以下信息：
   • Server URL：通常为 http://localhost:1234 或你配置的地址
   • Password：API 访问密码

远程访问

如果 OpenClaw Gateway 和 BlueBubbles Server 不在同一台机器上，你需要通过 Cloudflare Tunnel、ngrok 或端口转发让 Gateway 能够访问 BlueBubbles 的 API 地址。

第三步：配置 OpenClaw

在 openclaw.yaml 中添加 iMessage 频道配置：

channels:
  imessage:
    enabled: true
    provider: bluebubbles
    serverUrl: "http://localhost:1234"     # BlueBubbles Server 地址
    password: "your-bluebubbles-password"  # API 密码
    webhookPath: "/webhooks/imessage"      # Webhook 回调路径

或通过命令行登录：

openclaw channels login imessage

第四步：配置 Webhook

BlueBubbles 通过 Webhook 将新消息推送给 OpenClaw Gateway。

1. 在 BlueBubbles Server 中，进入 Settings → Webhooks
2. 添加新的 Webhook URL，指向 Gateway 的 Webhook 路径：

http://<gateway-host>:<gateway-port>/webhooks/imessage

3. 勾选需要接收的事件类型（至少包含新消息事件）
4. 保存配置

第五步：启动并验证

openclaw start

用另一台设备（手机或其他 Mac）向你的 iMessage 账号发送一条消息，确认 OpenClaw 能正常接收并回复。

配置选项

配置项	说明	默认值
allowedContacts	允许对话的联系人白名单	所有人
systemPrompt	该频道专用的系统提示词	全局默认
model	该频道使用的 AI 模型	全局默认

支持的消息类型

• 文本消息
• 图片
• 文件 / 附件
• Tapback 回应（作为反馈信号）

不支持的功能

由于 BlueBubbles 桥接的限制，以下功能暂不支持：

• iMessage 应用（如 GamePigeon 等）
• 实时位置共享
• Apple Pay 请求

注意事项

Mac 必须保持运行

BlueBubbles Server 需要 Mac 始终开机并登录。建议：

• 禁用自动睡眠：系统设置 → 显示器 → 自动关闭显示器 设为"永不"
• 启用自动登录：确保断电重启后能自动恢复服务
• 使用 Mac mini 或旧款 Mac 作为专用服务器

常见问题

消息延迟很高？

1. 检查 BlueBubbles Server 是否正常运行
2. 确认 Webhook 地址配置正确且 Gateway 可达
3. 查看 BlueBubbles 和 OpenClaw 两侧的日志

收不到群组消息？

iMessage 群组消息需要在 BlueBubbles Webhook 设置中勾选群组消息事件。同时参考群聊消息处理了解触发策略配置。