iMessage

​

安装插件

openclaw plugins install @openclaw/imessage

​

快速设置

brew install steipete/tap/imsg
brew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/home/openclaw/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@messages-mac", // 运行 Messages.app 和 imsg 的 Mac
      // 此路径在 Messages Mac 上解析，而不是在 Gateway 主机上解析。
      dbPath: "/Users/user/Library/Messages/chat.db",
      includeAttachments: true,
      // 可选：额外允许的附件根目录（与默认的
      // /Users/*/Library/Messages/Attachments 合并）。
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

要求与权限（macOS）

• Messages 必须在运行 imsg 的 Mac 上登录。
• 运行 OpenClaw/imsg 的进程上下文需要“完全磁盘访问权限”（用于访问 Messages 数据库）。
• 通过 Messages.app 发送消息需要“自动化”权限。
• 对于高级操作（回应 / 编辑 / 撤回 / 线程回复 / 特效 / 投票 / 群组操作），必须禁用系统完整性保护（System Integrity Protection）——请参见 启用 imsg 私有 API。基础文本和媒体的收发不需要它。

​

启用 imsg 私有 API

• 基本模式（默认，无需更改 SIP）：通过 send 发送文本和媒体、入站监控／历史记录、聊天列表。这就是你在全新安装 brew install steipete/tap/imsg 再加上上面的标准 macOS 权限后开箱即用所获得的能力。
• 私有 API 模式：imsg 会向 Messages.app 注入一个 helper dylib，以调用内部 IMCore 函数。这将解锁 react、edit、unsend、reply（线程式）、sendWithEffect、poll 和 poll-vote（原生 Messages 投票）、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及输入指示和已读回执。

诸如 read、typing、launch、基于桥接的富发送、消息变更和聊天管理等高级功能都是可选的。它们需要禁用 SIP，并将一个 helper dylib 注入到 Messages.app 中。启用 SIP 时，imsg launch 会拒绝注入。

​

设置

1. 在运行 Messages.app 的 Mac 上安装（或升级）imsg：
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg status --json
   
   imsg status --json 的输出会报告 bridge_version、rpc_methods 以及每个方法的 selectors，这样你就能在开始之前看到当前构建支持哪些能力。
2. 禁用系统完整性保护，并且（在现代 macOS 上）禁用 Library Validation。 将非 Apple 的 helper dylib 注入到 Apple 签名的 Messages.app 需要关闭 SIP 并且放宽 library validation。Recovery 模式下的 SIP 步骤取决于 macOS 版本：
   • macOS 10.13-10.15（Sierra-Catalina）： 通过 Terminal 禁用 Library Validation，重启进入恢复模式，运行 csrutil disable，然后重启。
   • macOS 11+（Big Sur 及更高版本），Intel： 进入恢复模式（或 Internet Recovery），运行 csrutil disable，然后重启。
   • macOS 11+，Apple Silicon： 使用电源键启动流程进入恢复模式；在较新的 macOS 版本上，点击 Continue 时按住 Left Shift 键，然后运行 csrutil disable。虚拟机环境遵循单独流程，因此请先拍摄 VM 快照。
   在 macOS 11 及更高版本上，单独执行 csrutil disable 通常还不够。 Apple 仍然会将 Messages.app 作为平台二进制文件执行 library validation，因此即使关闭 SIP，adhoc 签名的 helper 也会被拒绝（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 之间注入 helper。不需要 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 helper，因此 bridge 永远无法就绪，启动最终超时。这个超时是大多数人在 Tahoe 上遇到的症状；修复方法就是上面的 plist，而不是采取更激进的手段。
   如果在 macOS 升级后，imsg launch 注入失败，或者某些特定 selectors 开始返回 false，通常就是这个门槛导致的。在假设 SIP 步骤本身失败之前，请先检查你的 SIP 和 library-validation 状态。如果这些设置都正确，但 bridge 仍然无法注入，请收集 imsg status --json 和 imsg launch 的输出并反馈给 imsg 项目，而不是进一步削弱系统级安全控制。
3. 注入 helper。 在禁用 SIP 且已登录 Messages.app 的情况下：
   imsg launch
   
   当 SIP 仍然启用时，imsg launch 会拒绝注入，因此这也可作为第 2 步是否生效的确认。
4. 从 OpenClaw 验证桥接：
   openclaw channels status --probe
   
   iMessage 条目应报告为 works，并且 imsg status --json | jq '{rpc_methods, selectors}' 应显示你的 macOS 构建所暴露的能力。创建投票需要 selectors.pollPayloadMessage；投票需要 selectors.pollVoteMessage 和 poll.vote RPC method。OpenClaw 插件只会公开缓存探测所支持的操作，而空缓存则保持乐观，并在首次分发时进行探测。

​

当 SIP 保持启用时

• imsg 会回退到基本模式——仅支持文本＋媒体＋接收。
• OpenClaw 插件仍会展示文本／媒体发送和入站监控；它会根据按方法能力门控隐藏 react、edit、unsend、reply、sendWithEffect 和群组操作。
• 你可以使用一台独立的非 Apple Silicon Mac（或专用 bot Mac）在关闭 SIP 的情况下承担 iMessage 工作负载，同时在主设备上保持 SIP 启用。请参见下面的 专用 bot macOS 用户（独立 iMessage 身份）。

​

访问控制和路由

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

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { "systemPrompt": "请使用英式拼写。" },
        "8421": {
          requireMention: true,
          systemPrompt: "这是值班轮班聊天。回复请控制在 3 句以内。",
        },
        "9907": {
          // 显式抑制：通配符 "请使用英式拼写。" 不适用于此处
          systemPrompt: "",
        },
      },
    },
  },
}

​

ACP 会话绑定

• 在该私信或允许的群聊中运行 /acp spawn codex --bind here。
• 之后同一 iMessage 会话中的消息将路由到生成的 ACP 会话。
• /new 和 /reset 会就地重置同一个已绑定的 ACP 会话。
• /acp close 会关闭 ACP 会话并移除绑定。

• 规范化的私信 handle，例如 +15555550123 或 [email protected]
• chat_id:<id>（推荐用于稳定的群组绑定）
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  agents: {
    entries: {
      codex: {
        default: true,
        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: "/home/openclaw/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] 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,
    },
  },
}

​

合并拆分发送的 DM（命令 + URL 在同一条输入中）

brew update && brew upgrade imsg

​

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

• 持久化重放保护。 在推进恢复游标之前，OpenClaw 会将共享 SQLite 入站队列中的每一条原始行以其 Apple GUID 作为事件 ID 写入日志。完成的行会保留一份约 4 小时的墓碑记录，最多 10,000 条，因此即使重启后，具有相同 GUID 的重放也会被丢弃。待处理的行会一直可恢复，直到调度器接管它为止。
• 宕机恢复。 启动时，监视器会记住最后一个持久化接纳的 chat.db 行号（按账号持久化的游标），并将其作为 since_rowid 传递给 imsg watch.subscribe，因此 imsg 会重放那些尚未写入日志的行，然后继续跟踪实时新增内容。崩溃前已写入日志的行会从 SQLite 中恢复。重放范围限制为最近 500 行，并且仅限于约 2 小时以内的消息，GUID 墓碑会丢弃任何已经处理过的内容。
• 过时积压年龄防线。 启动边界之上的行是真正的实时消息；其中发送时间比到达时间早超过约 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"

​

配置参考指针

• iMessage 配置参考
• 网关配置
• 配对

​

相关内容

• 通道概览 — 所有受支持的通道
• BlueBubbles 移除与 imsg iMessage 路径 — 公告与迁移摘要
• 从 BlueBubbles 迁移过来 — 配置转换表与逐步切换
• 配对 — DM 认证与配对流程
• 群组 — 群聊行为与提及门控
• 通道路由 — 消息会话路由
• 安全性 — 访问模型与加固