Channel - iMessage

OpenClaw 通过 imsg bridge 原生集成 iMessage，使用 JSON-RPC over stdio 通信（无独立 daemon/端口）。高级操作需要 imsg launch 和私有 API 探针成功。

注意：BlueBubbles 支持已移除，需迁移到 channels.imessage。

快速配置

本地 Mac

# 安装 imsg
brew install steipete/tap/imsg
imsg rpc --help
imsg launch
 
# 配置 OpenClaw

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/user/Library/Messages/chat.db",
    },
  },
}

# 启动 gateway 并审批首个 DM 配对
openclaw gateway
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

远程 Mac（SSH）

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host",
      includeAttachments: true,
    },
  },
}

macOS 权限要求

Messages 必须在运行 imsg 的 Mac 上登录
需要完全磁盘访问权限（Full Disk Access）
需要自动化权限（Automation）用于通过 Messages.app 发送消息
高级操作（react/edit/unsend/线程回复/效果/群组管理）需要禁用 SIP

私有 API 模式

imsg 有两种模式：

基础模式（默认，无需禁用 SIP）：文本和媒体发送/接收
私有 API 模式：注入 dylib 到 Messages.app，解锁 react、edit、unsend、reply（线程）、sendWithEffect、群组管理等

启用私有 API：

# 1. 禁用 SIP（在 Recovery Mode 中）
csrutil disable
 
# 2. 注入 helper
imsg launch
 
# 3. 验证
openclaw channels status --probe

安全警告：禁用 SIP 是真实的安全权衡，在 Apple Silicon Mac 上还会禁止安装 iOS app。

访问控制

dmPolicy：pairing（默认）| allowlist | open | disabled
groupPolicy：allowlist（默认）| open | disabled
群聊有两道白名单门：sender/chat-target allowlist + groups registry，两者都必须通过

群聊最小配置：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

私有 API 操作

{
  channels: {
    imessage: {
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        renameGroup: true,
        addParticipant: true,
        removeParticipant: true,
        leaveGroup: true,
      },
    },
  },
}

消息合并（coalesceSameSenderDms）

Apple Messages 发送”命令 + URL”时会拆分为两条 chat.db 记录（间隔 0.8-2.0 秒）。启用合并可将同一发送者的连续消息合并为一个 agent turn：

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true,  // 默认 false
    },
  },
}

启用后 DM 延迟增加约 2500ms（等待可能的后续消息）。

离线追赶（Catchup）

Gateway 离线期间的消息默认不会被处理。启用 catchup 可在重启后回放：

{
  channels: {
    imessage: {
      catchup: {
        enabled: true,
        maxAgeMinutes: 120,
        perRunLimit: 50,
      },
    },
  },
}

目标格式

chat_id:123（推荐，稳定路由）
chat_guid:...
imessage:+1555...
user@example.com

Wiki AI

目录