iMessage

Status：原生外部 CLI 集成。Gateway 网关会启动 imsg rpc，并通过 stdio 上的 JSON-RPC 通信（没有单独的守护进程/端口）。高级操作需要 imsg launch 和成功的私有 API 探测。

快速设置

brew install steipete/tap/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>

#!/usr/bin/env bashexec 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: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

要求和权限（macOS）

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

启用 imsg 私有 API

imsg 提供两种运行模式：

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

要使用此渠道页面记录的高级操作能力，你需要私有 API 模式。imsg README 明确说明了该要求：

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

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

设置

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

   brew install steipete/tap/imsgimsg --versionimsg status --json

   imsg status --json 输出会报告 bridge_version、rpc_methods 和每个方法的 selectors，因此你可以在开始前查看当前构建支持什么。

2. 禁用系统完整性保护。 这与 macOS 版本相关，因为底层 Apple 要求取决于操作系统和硬件：

   • macOS 10.13–10.15（Sierra–Catalina）： 通过 Terminal 禁用 Library Validation，重启到恢复模式，运行 csrutil disable，再重启。
   • macOS 11+（Big Sur 及更高版本），Intel： 恢复模式（或互联网恢复），csrutil disable，重启。
   • macOS 11+，Apple Silicon： 通过电源按钮启动序列进入恢复；在较新的 macOS 版本中，点击 Continue 时按住 Left Shift 键，然后运行 csrutil disable。虚拟机设置遵循单独流程 — 先创建 VM 快照。
   • macOS 26 / Tahoe： library-validation 策略和 imagent 私有授权检查进一步收紧；imsg 可能需要更新构建才能跟上。如果在 macOS 主版本升级后，imsg launch 注入或特定 selectors 开始返回 false，请先检查 imsg 的发布说明，再假设 SIP 步骤已成功。

   在运行 imsg launch 前，请按照 Apple 针对你的 Mac 的恢复模式流程禁用 SIP。

3. 注入辅助程序。 在 SIP 已禁用且 Messages.app 已登录的情况下：

   imsg launch

   当 SIP 仍启用时，imsg launch 会拒绝注入，因此这也可用来确认第 2 步已生效。

4. 从 OpenClaw 验证桥接：

   openclaw channels status --probe

   iMessage 条目应报告 works，且 imsg status --json | jq '.selectors' 应显示 retractMessagePart: true，以及你的 macOS 构建暴露的任意编辑 / 输入 / 已读 selectors。actions.ts 中的 OpenClaw 插件按方法门控只会公布底层 selector 为 true 的操作，因此你在智能体工具列表中看到的操作面反映了此主机上的桥接实际能做什么。

如果 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 和群组操作（根据按方法能力门控）。
• 你可以为 iMessage 工作负载运行一台单独的非 Apple-Silicon Mac（或专用机器人 Mac）并关闭 SIP，同时在你的主要设备上保持 SIP 启用。见下方专用机器人 macOS 用户（单独的 iMessage 身份）。

访问控制和路由

{  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 会话绑定

旧版 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 或 [email protected]
• 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: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

媒体、分块和投递目标

imsg chats --limit 20

私有 API 操作

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

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

{  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 发给我”），然后到第 2 轮才看到 URL，此时命令上下文已经丢失。这是 Apple 的发送管线行为，并不是 OpenClaw 或 imsg 引入的。

channels.imessage.coalesceSameSenderDms 会让一个私信选择把连续的同发送者行合并成一个智能体轮次。群组聊天会继续按消息分发，以保留多用户轮次结构。

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

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

Gateway 网关停机后的追赶

当 Gateway 网关离线（崩溃、重启、Mac 休眠、机器关机）时，imsg watch 会在 Gateway 网关恢复后从当前 chat.db 状态继续；默认情况下，间隔期间到达的任何内容都不会被看到。追赶会在下一次启动时重放这些消息，确保智能体不会静默错过入站流量。

追赶功能默认禁用。按渠道启用：

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

运行方式

每次 monitorIMessageProvider 启动执行一轮，顺序为 imsg launch 就绪 → watch.subscribe → performIMessageCatchup → 实时分发循环。追赶本身使用 chats.list + 每个聊天的 messages.history，并通过与 imsg watch 相同的 JSON-RPC 客户端调用。追赶期间到达的任何内容都会照常流经实时分发；现有入站去重缓存会吸收与重放行之间的任何重叠。

每条重放行都会走实时分发路径（evaluateIMessageInbound + dispatchInboundMessage），因此允许列表、群组策略、防抖器、回声缓存和已读回执在重放消息与实时消息上的行为完全一致。

游标和重试语义

追赶会在 <openclawStateDir>/imessage/catchup/<account>__<hash>.json 保存按账号划分的游标（OpenClaw 状态目录默认是 ~/.openclaw，可用 OPENCLAW_STATE_DIR 覆盖）：

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• 每次成功分发后，游标都会前进；当某行的分发抛出异常时，游标会保持不变，下一次启动会从保持的游标重试同一行。
• 当同一个 guid 连续抛出异常达到 maxFailureRetries 次后，追赶会记录一条 warn，并强制将游标推进到卡住的消息之后，确保后续启动可以继续前进。
• 已经放弃的 guid 在后续运行中一看到就跳过（不会尝试分发），并计入运行摘要中的 skippedGivenUp。

操作者可见信号

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

WARN ... capped to perRunLimit 行表示单次启动没有清空全部积压。如果你的间隔经常超过默认的 50 行处理量，请提高 perRunLimit（最大 500）。

何时保持关闭

• Gateway 网关持续运行，并有看门狗自动重启，间隔始终小于几秒，此时默认关闭即可。
• 私信量很低，错过消息也不会改变智能体行为；firstRunLookbackMinutes 初始窗口可能会在首次启用时分发令人意外的旧上下文。

启用追赶后，首次没有游标的启动只会回看 firstRunLookbackMinutes（默认 30 分钟），而不是完整的 maxAgeMinutes 窗口；这样可避免重放启用前的长历史消息。

故障排除

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

#!/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 — 配置转换表和逐步切换流程
• 配对 — 私信认证和配对流程
• 群组 — 群组聊天行为和提及门控
• 频道路由 — 消息的会话路由
• 安全性 — 访问模型和加固