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", // 用于通过 SCP 拉取附件
      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 发送消息需要自动化权限。
• 对于高级操作（react / edit / unsend / threaded reply / effects / group ops），必须禁用系统完整性保护（SIP）——见下方 启用 imsg 私有 API。基础文本和媒体收发在不禁用 SIP 的情况下也能工作。

imsg chats --limit 1
# 或
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 发送外发文本和媒体、入站监控/历史、聊天列表。这就是在全新安装 brew install steipete/tap/imsg 并授予上面列出的标准 macOS 权限后可直接获得的能力。
• 私有 API 模式：imsg 会将一个 helper dylib 注入 Messages.app，以调用内部 IMCore 函数。这会解锁 react、edit、unsend、reply（线程式）、sendWithEffect、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
   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，重启进入 Recovery Mode，运行 csrutil disable，然后重启。
   • macOS 11+（Big Sur 及更高版本），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 作为平台二进制文件执行 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 26.5.1（Apple Silicon）上通过受控的前后对比得到确认：有 plist 时，dylib 会映射进 Messages.app，bridge 会启动；移除 plist 并重启后，imsg launch 会产生上面的超时失败，并且 dylib 不会被映射。 如果在 macOS 升级后，imsg launch 注入或某些特定 selectors 开始返回 false，通常就是这个门槛导致的。在假设 SIP 步骤本身失败之前，请先检查你的 SIP 和 library-validation 状态。如果这些设置都正确，但 bridge 仍然无法注入，请收集 imsg status --json 和 imsg launch 的输出并反馈给 imsg 项目，而不是进一步削弱系统级安全控制。 在运行 imsg launch 之前，请按照 Apple 针对你的 Mac 的恢复模式流程禁用 SIP。
3. 注入 helper。 在 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 构建所暴露的编辑 / 输入状态 / 已读等选择器。OpenClaw 插件在 actions.ts 中按方法进行的能力门控，只会公开其底层 selector 为 true 的操作，因此你在代理工具列表中看到的动作范围，反映了该主机上的桥接实际能做什么。

​

当你无法禁用 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 会话并移除绑定。

• 规范化的 DM handle，例如 +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" },
    },
  ],
}

​

部署模式

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.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,
      },
    },
  },
}

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

​

配置写入

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

​

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

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

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

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms 适用于大多数环境；如果你的 Mac
        // 比较慢或内存压力较大（观测到的间隔此时可能超过 2 秒），
        // 可提高到 4000 ms。
        imessage: 2500,
      },
    },
  },
}

​

场景以及代理看到的内容

​

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

• 重放去重。 每条已分发的入站消息都会通过其 Apple GUID 记录到持久化插件状态（imessage.inbound-dedupe）中，在接收时认领，并在处理完成后提交（若发生临时失败则释放，以便重试）。任何已经处理过的内容都会被丢弃，而不会重复分发。这使得恢复可以激进地重放，而无需逐条记录状态。
• 停机恢复。 启动时，监控会记住最后一次分发的 chat.db 行号（每个账户持久化的游标），并将其作为 since_rowid 传给 imsg watch.subscribe，这样 imsg 就会重放网关停机期间到达的那些行，然后继续追踪实时流。重放范围限制在最近的若干行以及约 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

#!/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 认证与配对流程
• 群组 — 群聊行为与提及门控
• 通道路由 — 消息会话路由
• 安全性 — 访问模型与加固