iMessage

状态：原生外部 CLI 集成。Gateway 网关会启动 imsg rpc，并通过 stdio 使用 JSON-RPC 通信——无需单独的守护进程或端口。强烈建议使用私有 API 模式，以获得完整的 iMessage 渠道功能；回复、点按回应、特效、投票、附件回复和群组操作都需要运行 imsg launch，并成功通过私有 API 探测。

对于常见的本地设置，OpenClaw 设置流程可在已登录 Messages 的 Mac 上，经用户确认后通过 Homebrew 安装或更新 imsg。手动设置和 SSH 包装器拓扑仍由操作员管理：请在将运行 Gateway 网关或包装器的同一用户上下文中安装或更新 imsg。

快速设置

brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg rpc --helpimsg launchopenclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

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

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // 用于通过 SCP 获取附件  includeAttachments: true,  // 可选：额外允许的附件根目录（与默认的  // /Users/*/Library/Messages/Attachments 合并）。  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

要求和权限（macOS）

• 运行 imsg 的 Mac 必须已登录 Messages。
• 运行 OpenClaw/imsg 的进程上下文需要 Full Disk Access（用于访问 Messages 数据库）。
• 通过 Messages.app 发送消息需要 Automation 权限。
• 对于高级操作（回应 / 编辑 / 撤回 / 线程回复 / 特效 / 投票 / 群组操作），必须禁用 System Integrity Protection——请参阅启用 imsg 私有 API。无需禁用它即可进行基本的文本和媒体收发。

无权向 Messages 发送 Apple events。(-1743)

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

启用 imsg 私有 API

imsg 提供两种运行模式。对于 OpenClaw，建议使用私有 API 模式，因为它能为渠道提供用户所期望的原生 iMessage 操作。基本模式仍适合低风险安装、初始验证，或者无法禁用 SIP 的主机。

• 基本模式（默认，无需更改 SIP）：通过 send 发送出站文本和媒体、监听和查看入站历史记录、列出聊天。这是全新运行 brew install steipete/tap/imsg 并授予上述标准 macOS 权限后即可获得的功能。
• 私有 API 模式：imsg 将辅助 dylib 注入 Messages.app，以调用内部 IMCore 函数。这样可解锁 react、edit、unsend、reply（线程式）、sendWithEffect、poll 和 poll-vote（原生 Messages 投票）、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及输入状态指示和已读回执。

本页面推荐的操作功能集需要私有 API 模式。imsg README 明确说明了相关要求：

read、typing、launch、由 Bridge 支持的富内容发送、消息修改和聊天管理等高级功能需要主动启用。它们要求禁用 SIP，并将辅助 dylib 注入 Messages.app。启用 SIP 时，imsg launch 会拒绝执行注入。

这种辅助注入技术使用 imsg 自己的 dylib 来访问 Messages 私有 API。OpenClaw iMessage 路径中没有第三方服务器或 BlueBubbles 运行时。

设置

1. 在运行 Messages.app 的 Mac 上安装（或升级）imsg：

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg 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。恢复模式下的 SIP 操作因 macOS 版本而异：

   • **macOS 10.13-10.15 (Sierra-Catalina)：**通过 Terminal 禁用 Library Validation，重启进入 Recovery Mode，运行 csrutil disable，然后重新启动。
   • **macOS 11+ (Big Sur and later)，Intel：**进入 Recovery Mode（或 Internet Recovery），运行 csrutil disable，然后重新启动。
   • **macOS 11+，Apple Silicon：**使用电源按钮启动流程进入 Recovery；在较新的 macOS 版本中，点击 Continue 时按住 Left Shift 键，然后运行 csrutil disable。虚拟机设置采用单独的流程，因此请先创建 VM 快照。

   在 macOS 11 及更高版本中，仅执行 csrutil disable 通常还不够。 Apple 仍会对作为平台二进制文件的 Messages.app 强制执行库验证，因此即使已关闭 SIP，临时签名的辅助程序也会被拒绝（Library Validation failed: ... platform binary, but mapped file is not）。禁用 SIP 后，还需禁用库验证并重新启动：

   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 会在加载时拒绝临时签名的辅助程序，因此桥接永远无法就绪，启动最终超时。这是大多数人在 Tahoe 上遇到的超时症状；修复方法是设置上述 plist，而不是采取更激进的措施。

   如果升级 macOS 后，imsg launch 注入失败或特定 selectors 开始返回 false，通常就是此验证关卡导致的。在认定 SIP 步骤本身失败之前，请检查 SIP 和库验证状态。如果这些设置正确，但桥接仍无法注入，请收集 imsg status --json 和 imsg launch 的输出并报告给 imsg 项目，而不是进一步削弱系统范围的安全控制。

3. **注入辅助程序。**禁用 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 方法。OpenClaw 插件仅公布缓存探测结果所支持的操作；如果缓存为空，则保持乐观状态，并在首次分发时进行探测。

如果 openclaw channels status --probe 将该渠道报告为 works，但特定操作在分发时抛出“iMessage <action> requires the imsg private API bridge”，请再次运行 imsg launch——辅助程序可能会脱离（例如 Messages.app 重新启动、操作系统更新等），而缓存的 available: true 状态会继续公布这些操作，直到下一次探测刷新状态。

SIP 保持启用时

如果你的威胁模型不允许禁用 SIP：

• imsg 会回退到基本模式——仅支持文本、媒体和接收。
• OpenClaw 插件仍会公布文本/媒体发送和入站监控能力；它会从操作表面隐藏 react、edit、unsend、reply、sendWithEffect 和群组操作（依据逐方法能力验证关卡）。
• 你可以使用一台单独的非 Apple Silicon Mac（或专用机器人 Mac），关闭其 SIP 来处理 iMessage 工作负载，同时让主要设备保持启用 SIP。请参阅下方的专用机器人 macOS 用户（独立 iMessage 身份）。

访问控制和路由

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "使用英式拼写。" },        "8421": {          requireMention: true,          systemPrompt: "这是值班轮换聊天。回复不超过 3 句话。",        },        "9907": {          // 显式抑制：通配符“使用英式拼写。”不在此处应用          systemPrompt: "",        },      },    },  },}

ACP 对话绑定

iMessage 聊天可以绑定到 ACP 会话。

快速操作流程：

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

配置的持久绑定使用顶层 bindings[] 条目，其中包含 type: "acp" 和 match.channel: "imessage"。

match.peer.id 可以使用：

• 规范化的私信句柄，例如 +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" },    },  ],}

有关共享 ACP 绑定行为，请参阅 ACP 智能体。

部署模式

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

媒体、分块和投递目标

imsg chats --limit 20

私有 API 操作

当 imsg launch 正在运行，且 openclaw channels status --probe 报告 privateApi.available: true 时，消息工具除了发送普通文本外，还可以使用 iMessage 原生操作。

所有操作默认启用；使用 channels.imessage.actions 可分别关闭各项操作：

{  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,    },  },}

配置写入

默认情况下，iMessage 允许由渠道发起配置写入（即当 commands.config: true 时使用 /config set|unset）。

禁用方法：

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

合并拆分发送的私信（在同一次撰写中包含命令和 URL）

当用户同时输入命令和 URL（例如 Dump https://example.com/article）时，Apple 的 Messages 应用会将发送内容拆分为 两个独立的 chat.db 行：

1. 一条文本消息（"Dump"）。
2. 一个 URL 预览气泡（"https://..."），其附件中包含 OG 预览图像。

在大多数环境中，这两行会相隔约 0.8-2.0 秒到达 OpenClaw。如果不进行合并，智能体在第 1 个轮次中只会收到命令（并且通常会回复“请把 URL 发给我”），而 URL 要到第 2 个轮次才会到达。这是 Apple 的发送管线所致，并非 OpenClaw 或 imsg 引入的行为。

channels.imessage.coalesceSameSenderDms 可选择将私信中连续的同一发送者记录加入缓冲。当 imsg 在某条源记录上公开结构化 URL 预览标记 balloon_bundle_id: "com.apple.messages.URLBalloonProvider" 时，OpenClaw 只合并这个真正的拆分发送，并将其他所有已缓冲记录保留为独立轮次。在完全不产生气泡元数据的旧版 imsg 中，OpenClaw 无法区分拆分发送与多次独立发送，因此会回退为合并该缓冲桶。这会保留引入元数据前的行为，避免将 Dump <url> 拆分发送退化为两个轮次。群聊仍按消息逐条分发，以保留多用户轮次结构。

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

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

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

“启用标志”列展示产生 balloon_bundle_id 的 imsg 版本上的行为。在完全不产生气泡元数据的旧版 imsg 中，下表标记为“两个轮次”/“N 个轮次”的记录会改为回退到旧版合并（一个轮次）：OpenClaw 无法从结构上区分拆分发送和多次独立发送，因此会保留引入元数据前的合并行为。版本开始产生气泡元数据后，精确分离便会生效。

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

iMessage 会恢复 Gateway 网关停机期间错过的消息，同时抑制 Apple 在 Push 恢复后可能集中刷出的陈旧“积压消息炸弹”。默认行为始终启用，并建立在入站去重机制之上。

• 重放去重。 每条已分发的入站消息都会按其 Apple GUID 记录在持久化插件状态（imessage.inbound-dedupe）中：在摄取时声明，处理后提交（发生瞬时故障时释放，以便重试）。任何已处理的消息都会被丢弃，而不是重复分发。正因如此，恢复功能可以积极重放，而无需逐条维护消息记录。
• 停机恢复。 启动时，监视器会记住最后分发的 chat.db rowid（持久化的按账户游标），并通过 since_rowid 将其传递给 imsg watch.subscribe，这样 imsg 会先重放 Gateway 网关停机期间写入的记录，然后持续跟踪实时消息。重放范围限制为最近 500 条记录和最多约 2 小时前的消息，去重机制会丢弃任何已处理的消息。
• 陈旧积压消息年龄防线。 启动边界以上的记录确实是实时消息；如果某条记录的发送日期比到达时间早超过约 15 分钟，则属于 Push 集中刷出的积压消息，会被抑制。重放记录（位于边界或边界以下）则使用更宽的恢复窗口，因此最近错过的消息会被送达，而久远历史消息不会。

恢复功能适用于本地和远程 cliPath 设置，因为 since_rowid 重放通过同一个 imsg RPC 连接运行。区别在于窗口：当 Gateway 网关可以读取 chat.db（本地）时，它会固定启动 rowid 边界、限制重放跨度，并送达最多约两小时前错过的消息。通过远程 SSH cliPath 时，它无法读取数据库，因此重放不设上限，并且每条记录都使用实时年龄防线——它仍会恢复最近错过的消息，并抑制旧积压消息，只是使用更窄的实时窗口。要使用更宽的恢复窗口，请在运行 Messages 的 Mac 上运行 Gateway 网关。

操作员可见信号

被抑制的积压消息会按默认级别记录日志，绝不会静默丢弃（recovery 标志表示应用了哪个窗口）：

imessage: 已抑制陈旧入站积压消息 account=<id> sent=<iso> recovery=<bool>（启动后共抑制 &lt;N&gt; 条）

迁移

channels.imessage.catchup.* 已弃用——停机恢复是自动的，新设置无需任何配置。包含 catchup.enabled: true 的现有配置仍会作为恢复重放窗口的兼容性配置文件受到支持。已禁用的补收配置块（enabled: false 或未设置 enabled: true）将被淘汰；openclaw doctor --fix 会将其移除。

故障排除

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

配置参考指引

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

相关内容

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