iMessage

​

快速设置

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: extra allowed attachment roots (merged with the default
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

要求和权限（macOS）

• Messages 必须在运行 imsg 的 Mac 上登录。
• 运行 OpenClaw/imsg 的进程上下文需要 Full Disk Access（用于访问 Messages DB）。
• 通过 Messages.app 发送消息需要 Automation 权限。
• 对于高级操作（react / edit / unsend / threaded reply / effects / polls / group ops），必须禁用 System Integrity Protection — 请参阅启用 imsg 私有 API。基础文本和媒体收发不需要禁用它。

imsg chats --limit 1
# or
imsg send <handle> "test"

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

​

启用 imsg 私有 API

• 基础模式（默认，无需更改 SIP）：通过 send 发送出站文本和媒体，入站 watch/history，聊天列表。这是全新 brew install steipete/tap/imsg 加上上面标准 macOS 权限后即可获得的模式。
• 私有 API 模式：imsg 将辅助 dylib 注入 Messages.app，以调用内部 IMCore 函数。这会解锁 react、edit、unsend、reply（threaded）、sendWithEffect、poll 和 poll-vote（原生 Messages 投票）、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及正在输入指示和已读回执。

高级功能，例如 read、typing、launch、bridge 支持的富发送、消息变更和聊天管理，都是选择启用的。它们要求禁用 SIP，并将辅助 dylib 注入 Messages.app。当 SIP 启用时，imsg launch 会拒绝注入。

​

设置

1. 在运行 Messages.app 的 Mac 上安装（或升级）imsg：
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   imsg status --json 输出会报告 bridge_version、rpc_methods 和按方法列出的 selectors，因此你可以在开始前查看当前构建支持什么。
2. 禁用 System Integrity Protection，并且（在现代 macOS 上）禁用 Library Validation。 将非 Apple 辅助 dylib 注入 Apple 签名的 Messages.app 需要关闭 SIP，并且放宽 library validation。Recovery 模式下的 SIP 步骤因 macOS 版本而异：
   • macOS 10.13-10.15（Sierra-Catalina）： 通过 Terminal 禁用 Library Validation，重启到 Recovery Mode，运行 csrutil disable，然后重启。
   • macOS 11+（Big Sur 及更高版本），Intel： 进入 Recovery Mode（或 Internet Recovery），运行 csrutil disable，然后重启。
   • macOS 11+，Apple Silicon： 使用电源按钮启动流程进入 Recovery；在近期 macOS 版本中，点击 Continue 时按住左 Shift 键，然后运行 csrutil disable。虚拟机设置遵循单独流程，因此请先创建 VM 快照。
   在 macOS 11 及更高版本上，仅运行 csrutil disable 通常不够。 Apple 仍会把 Messages.app 作为平台二进制文件强制执行 library validation，因此即使 SIP 关闭，adhoc 签名的辅助程序也会被拒绝（Library Validation failed: ... platform binary, but mapped file is not）。禁用 SIP 后，还要禁用 library validation 并重启：
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26（Tahoe），已在 26.5.1 验证： 关闭 SIP 加上上面的 DisableLibraryValidation 命令，足以在 26.0 到 26.5.x 中注入辅助程序。不需要 boot-args。 该 plist 是决定性因素，也是 Tahoe 上注入失败时最常漏掉的步骤：
   • 有该 plist： imsg launch 会注入，且 imsg status 会报告 advanced_features: true。
   • 没有该 plist（即使 SIP 关闭）： imsg launch 会失败并显示 Failed to launch: Timeout waiting for Messages.app to initialize。AMFI 在加载时拒绝 adhoc 辅助程序，因此 bridge 永远无法就绪，launch 最终超时。这个超时是大多数人在 Tahoe 上遇到的症状；修复方法是上面的 plist，而不是采取更激进的措施。
   如果 macOS 升级后 imsg launch 注入或特定 selectors 开始返回 false，此门槛通常就是原因。请先检查 SIP 和 library-validation 状态，再假设 SIP 步骤本身失败。如果这些设置正确但 bridge 仍无法注入，请收集 imsg status --json 和 imsg launch 输出，并报告给 imsg 项目，而不是削弱更多系统范围的安全控制。
3. 注入 helper。 在 SIP 已禁用且 Messages.app 已登录的情况下：
   imsg launch
   
   当 SIP 仍处于启用状态时，imsg launch 会拒绝注入，因此这也可以作为第 2 步已生效的确认。
4. 从 OpenClaw 验证 bridge：
   openclaw channels status --probe
   
   iMessage 条目应报告 works，并且 imsg status --json | jq '{rpc_methods, selectors}' 应显示你的 macOS 构建暴露的能力。创建投票需要 selectors.pollPayloadMessage；投票需要同时具备 selectors.pollVoteMessage 和 poll.vote RPC 方法。OpenClaw 插件只通告缓存探测支持的操作，而空缓存会保持乐观，并在首次分发时探测。

​

当 SIP 保持启用时

• imsg 会回退到基础模式——仅支持文本 + 媒体 + 接收。
• OpenClaw 插件仍会通告文本/媒体发送和入站监控；它会从操作表面隐藏 react、edit、unsend、reply、sendWithEffect 和群组操作（按照逐方法能力门控）。
• 你可以运行一台单独的非 Apple-Silicon Mac（或专用 bot Mac），为 iMessage 工作负载关闭 SIP，同时在你的主设备上保持 SIP 启用。请参阅下方的 Dedicated bot macOS user (separate iMessage identity)。

​

访问控制和路由

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

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Use British spelling." },
        "8421": {
          requireMention: true,
          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
        },
        "9907": {
          // explicit suppression: the wildcard "Use British spelling." does not apply here
          systemPrompt: "",
        },
      },
    },
  },
}

​

ACP 对话绑定

• 在私信或允许的群组聊天中运行 /acp spawn codex --bind here。
• 同一 iMessage 对话中的未来消息会路由到已生成的 ACP 会话。
• /new 和 /reset 会在原处重置同一个已绑定 ACP 会话。
• /acp close 会关闭 ACP 会话并移除绑定。

• 规范化的私信 handle，例如 +15555550123 或 user@example.com
• chat_id:<id>（推荐用于稳定群组绑定）
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

​

部署模式

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

媒体、分块和投递目标

imsg chats --limit 20

​

私有 API 操作

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

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

​

配置写入

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​

合并拆分发送的私信（一次输入中的命令 + URL）

1. 文本消息（"Dump"）。
2. URL 预览气泡（"https://..."），带有作为附件的 OG 预览图片。

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // 选择启用（默认：false）
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms 覆盖观察到的 Messages.app URL 预览延迟。
        imessage: 7000,
      },
    },
  },
}

​

场景以及智能体看到的内容

​

桥接或 Gateway 网关重启后的入站恢复

• 重放去重。 每条已分发的入站消息都会按其 Apple GUID 记录在持久化插件状态（imessage.inbound-dedupe）中，在摄取时声明，并在处理后提交（瞬时失败时释放，以便重试）。任何已处理的内容都会被丢弃，而不是重复分发。这让恢复可以积极重放，而无需逐消息记账。
• 停机恢复。 启动时，监视器会记住最后分发的 chat.db rowid（一个持久化的按账户游标），并将它作为 since_rowid 传给 imsg watch.subscribe，因此 imsg 会重放 Gateway 网关停机期间落入的行，然后跟随实时数据。重放被限制在最近 500 行以及约 2 小时内的消息，去重会丢弃任何已处理内容。
• 陈旧积压年龄围栏。 启动边界以上的行是真正的实时消息；如果某行的发送日期比到达时间早超过约 15 分钟，它就是 Push 刷出的积压，会被抑制。重放行（位于边界或边界以下）改用更宽的恢复窗口，因此最近错过的消息会送达，而久远历史不会送达。

​

操作员可见信号

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (<N> suppressed since start)

​

迁移

​

故障排查

imsg rpc --help
imsg status --json
openclaw channels status --probe

imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/Library/Messages/chat.db \
  "select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg send <handle> "test"

​

配置参考指针

• Configuration reference - iMessage
• Gateway 配置
• 配对

​

相关

• 渠道概览 — 所有受支持的渠道
• BlueBubbles removal and the imsg iMessage path — 公告和迁移摘要
• Coming from BlueBubbles — 配置转换表和分步切换流程
• 配对 — 私信认证和配对流程
• Groups — 群聊行为和提及门控
• 频道路由 — 消息的会话路由
• Security — 访问模型和加固