Private API

私有 API 模式可解锁原生 iMessage 操作。它需要关闭 SIP、放宽库验证，并成功注入辅助程序。

启用 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、基于桥接的富媒体发送、消息修改和聊天管理）是可选启用的。它们需要禁用 SIP，并将一个辅助 dylib 注入到 Messages.app。当 SIP 启用时，imsg launch 会拒绝注入。

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

设置¶

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

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg --version
imsg status --json

imsg status --json 的输出会报告 bridge_version、rpc_methods 以及每个方法的 selectors，以便你在开始之前了解当前构建支持哪些功能。

1. 禁用系统完整性保护（System Integrity Protection），以及（在现代 macOS 上）库验证（Library Validation）。 将非 Apple 辅助 dylib 注入 Apple 签名的 Messages.app 需要关闭 SIP 并且 放宽库验证。恢复模式中的 SIP 步骤因 macOS 版本而异：
2. macOS 10.13-10.15（Sierra-Catalina）： 通过 Terminal 禁用库验证，重启到恢复模式，运行 csrutil disable，然后重新启动。
3. macOS 11+（Big Sur 及更高版本），Intel： 进入恢复模式（或互联网恢复），运行 csrutil disable，然后重新启动。
4. macOS 11+，Apple Silicon： 使用电源按钮启动序列进入恢复模式；在较新的 macOS 版本中，点击“继续”时按住 左 Shift 键，然后运行 csrutil disable。虚拟机设置遵循单独的流程，因此请先创建 VM 快照。

在 macOS 11 及更高版本上，仅运行 csrutil disable 通常是不够的。 Apple 仍然会对作为平台二进制的 Messages.app 强制执行库验证，因此即使关闭了 SIP，adhoc 签名的辅助程序也会被拒绝（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 会在加载时拒绝 adhoc 辅助程序，因此桥接永远不会就绪，启动会超时。这个超时是大多数人在 Tahoe 上遇到的症状；修复方法是使用上述 plist，而不是采取更激进的措施。

如果在 macOS 升级后，imsg launch 注入或特定 selectors 开始返回 false，这个门槛通常是原因。在假设 SIP 步骤本身失败之前，先检查你的 SIP 和库验证状态。如果这些设置正确但桥接仍无法注入，请收集 imsg status --json 以及 imsg launch 输出，并将其报告给 imsg 项目，而不是削弱额外的全系统安全控制。

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

imsg launch

imsg launch 在 SIP 仍启用时会拒绝注入，因此这也同时确认了步骤 2 已生效。

1. 从 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 身份）。