iMessage - Apple 消息接入 (Legacy)

Legacy（传统方案）提示

此方案为旧版 iMessage 接入方式，仅适用于 macOS 且配置复杂。新用户请优先使用 BlueBubbles 方案，它更稳定且功能更丰富。

前置要求

• macOS 12 Monterey 或更高版本（仅支持 macOS）
• 已登录 Apple ID 并激活 iMessage
• Homebrew 包管理器
• OpenClaw Gateway（网关）已安装并运行

安装 imsg

brew install steipete/tap/imsg
imsg --version

macOS 权限配置

imsg 需要 TCC（Transparency, Consent, and Control）权限才能访问 Messages 数据库和自动化功能。

Full Disk Access（完全磁盘访问权限）

打开 System Settings（系统设置） > Privacy & Security > Full Disk Access，点击 + 添加 Terminal 和 imsg 可执行文件。

查找 imsg 路径

which imsg
# 然后在 System Settings UI 中手动添加

重置 TCC 权限

sudo tccutil reset SystemPolicyAllFiles
# 重置后在 System Settings 中重新添加

Automation（自动化权限）

打开 System Settings > Privacy & Security > Automation，确保 Terminal 对 Messages（信息） 的控制权限已开启。

首次运行

首次运行 imsg 时 macOS 会弹出权限请求对话框，点击 Allow 即可。

配置 OpenClaw

{
  channels: {
    imessage: {
      enabled: true,
      dmPolicy: "pairing",       // DM Policy（私信策略）
      allowFrom: [],              // 允许的手机号 / Apple ID 列表
      sendDelay: 1000             // 发送延迟（毫秒），避免触发风控
    }
  }
}

启动与验证

openclaw gateway restart
openclaw logs --channel imessage

使用另一台设备通过 iMessage 发送测试消息，日志中出现接收记录即配置成功。配对批准：

openclaw pairing approve imessage <pairing-code>

权限问题排查

无法读取消息数据库

出现 Permission denied 时：确认 Full Disk Access 已授予，重启终端，或重新授权：

sudo tccutil reset SystemPolicyAllFiles com.apple.Terminal

无法发送消息

1. 确认 Automation 权限中 Messages 已开启
2. 手动测试：imsg send "+1234567890" "Hello from imsg"

TCC 权限损坏

macOS 升级后权限可能损坏，重置后重新授权：

sudo tccutil reset SystemPolicyAllFiles
sudo tccutil reset AppleEvents

迁移到 BlueBubbles

1. 停止 Gateway：openclaw gateway stop
2. 安装 BlueBubbles Server（参考 BlueBubbles 文档）
3. 更新配置，将 imessage 替换为 bluebubbles
4. 可选迁移对话记录：openclaw migrate imessage-to-bluebubbles

BlueBubbles 优势

更稳定的消息收发、支持 Rich Media（富媒体）、提供 REST API、支持远程管理。

已知限制

• 仅支持 macOS，Windows/Linux 无法使用
• Mac 需常开运行，睡眠后无法收发消息
• 依赖 Messages App，一台 Mac 仅支持一个 iMessage 账号

🇨🇳 中国用户须知

iMessage 在中国大陆可正常使用，是 Apple 生态内置的通讯服务。

适用场景：面向 Apple 用户的客服系统、iOS/macOS 设备通知、海外 Apple 用户沟通。

注意事项：

• 非 Apple 用户发送的短信（绿色气泡）可能无法正确处理
• 中国大陆 Apple ID 可正常使用 iMessage
• 建议使用独立 Apple ID 运行 Bot
• Mac mini（M 系列芯片）是经济的 iMessage 服务器方案