跳转至

设置

安装插件,在已登录 Messages 的 Mac 上安装并验证 imsg,配置通道,并授予其所需的 macOS 权限。

安装插件

在 Gateway 主机上安装官方 iMessage 插件:

openclaw plugins install @openclaw/imessage

在继续之前,请检查应用结果。

私有 API 操作

回复、Tapbacks、特效、投票、附件及群组管理。

配对

iMessage 私信(DM)默认进入配对模式。

远程 Mac

当 Gateway 未运行在 Messages Mac 上时,请使用 SSH 包装器。

配置参考

完整的 iMessage 字段参考。

快速设置

1. 安装并验证 imsg

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe
    当本地设置向导检测到缺少默认的 `imsg` 命令时,它可能会提示通过 Homebrew 安装 `steipete/tap/imsg`。如果检测到由 Homebrew 管理的 `imsg`,它可能会提示重新安装或更新它。自定义的 `cliPath` 包装器不会被修改。

2. 配置 OpenClaw

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

3. 启动 Gateway

openclaw gateway

4. 批准首次 DM 配对(默认 dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
    配对请求将在 1 小时后过期。
大多数设置不需要 SSH。仅在 Gateway 无法运行于已登录 Messages 的 Mac 上时,才使用此拓扑。将 `cliPath` 指向 **Gateway 主机**上的一个兼容 stdio 的包装器,该包装器通过 SSH 连接到 Messages Mac 并运行 `imsg`。请使用包装器的绝对路径,以便服务启动时不依赖 shell 的主目录展开。
在该远程 Mac 上安装和更新 `imsg`,而不是在 Gateway 主机上:
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", // Mac that runs Messages.app and imsg
      // This path is interpreted on the Messages Mac, not on the Gateway host.
      dbPath: "/Users/user/Library/Messages/chat.db",
      includeAttachments: true,
      // Optional: extra allowed attachment roots (merged with the default
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}
`remoteHost` 标识 Messages Mac。OpenClaw 将其同时用于入站附件拉取和出站附件暂存。对于出站文件,OpenClaw 会在该 Mac 上创建一个仅所有者可访问的临时路径,通过现有的严格 SSH/SCP 传输方式复制文件,仅将远程路径传递给 `imsg`,并会在成功、失败或超时后尝试删除。清理失败的 SSH 调用会发出警告,并可能留下仅所有者可访问的临时目录。

建议设置显式的 `remoteHost`,设置后其优先级最高。为兼容起见,OpenClaw 会在每个进程内自动检测一次现有的透明 `exec ssh ... imsg "$@"` 包装器形态,并在监控、检查、发送和私有操作中复用该主机。自动检测仅适用于文档中描述的简单透明包装器;像 ProxyJump/ProxyCommand 这类选项丰富的包装器必须配置 `remoteHost`。
`remoteHost` 必须是 `host` 或 `user@host`(不能包含空格或 SSH 选项);不安全的取值会被忽略。
OpenClaw 对 SSH/SCP 使用严格的主机密钥检查,因此 Messages Mac 的主机密钥必须已存在于 Gateway 主机的 `~/.ssh/known_hosts` 中。
附件路径会根据允许的根目录(`attachmentRoots` / `remoteAttachmentRoots`)进行验证。

Warning

你置于 imsg 之前的任何 cliPath 包装器或 SSH 代理,都必须像透明的 stdio 管道一样支持长期 JSON-RPC 通信。OpenClaw 在通道的整个生命周期内通过包装器的 stdin/stdout 交换以换行符分隔的小型 JSON-RPC 消息:

  • 只要有字节可用,就立即转发每个 stdin 块/行——不要等待 EOF。
  • 及时按相反方向转发每个 stdout 块/行。
  • 保留换行符。
  • 避免固定大小的阻塞式读取(read(4096)、cat | buffer、shell 默认的 read),以免饿死小型帧。
  • 将 stderr 与 JSON-RPC stdout 流分开。

如果某个包装器会缓冲 stdin,直到填满一个大块才输出,那么它产生的症状会看起来像 iMessage 中断——出现 imsg rpc timeout (chats.list) 或频道反复重启——尽管 imsg rpc 本身是健康的。上面的 ssh -T host imsg "$@" 是安全的,因为它会转发 OpenClaw 的 cliPath 参数(如 rpc 和 --db)。像 ssh host imsg | grep -v '^DEBUG' 这样的管道则不安全——行缓冲工具仍可能持有帧;如果必须过滤,请在每个阶段使用 stdbuf -oL -eL。

要求和权限(macOS)

  • 运行 imsg 的 Mac 上必须已登录 Messages。
  • 运行 OpenClaw/imsg 的进程上下文需要完全磁盘访问权限(用于访问 Messages 数据库)。
  • 需要通过 Messages.app 发送消息时,需要自动化权限。
  • 对于高级操作(react / edit / unsend / threaded reply / effects / polls / group ops),必须禁用 System Integrity Protection——请参阅启用 imsg 私有 API。基本的文本和媒体发送/接收不需要它也能工作。

Tip

权限按进程上下文授予。如果 Gateway 以无头方式运行(LaunchAgent/SSH),请在同一上下文中运行一次性交互式命令以触发授权提示:

imsg chats --limit 1
# or
imsg send <handle> "test"
SSH 包装器发送因 AppleEvents -1743 失败

远程 SSH 配置可以读取聊天、通过 channels status --probe,并处理入站消息,但出站发送仍会因 AppleEvents 授权错误而失败:

Not authorized to send Apple events to Messages. (-1743)

请检查已登录 Mac 用户的 TCC 数据库,或“系统设置 > 隐私与安全性 > 自动化”。如果自动化条目记录的是 /usr/libexec/sshd-keygen-wrapper,而不是 imsg 或本地 shell 进程,macOS 可能不会为该 SSH 服务端客户端提供可用的 Messages 切换开关:

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

在这种情况下,重复执行 tccutil reset AppleEvents 或通过同一 SSH 包装器重新运行 imsg send 可能仍会失败,因为需要 Messages 自动化的进程上下文是 SSH 包装器,而不是 UI 可以授权的某个应用。

请改用其中一个受支持的 imsg 进程上下文:

  • 在已登录 Messages 的用户的本地会话中运行 Gateway,或至少运行 imsg 桥接。
  • 在同一会话中授予完全磁盘访问权限和自动化权限后,为该用户使用 LaunchAgent 启动 Gateway。
  • 如果保留双用户 SSH 拓扑,请在启用通道之前,确认真实的出站 imsg send 能够通过完全相同的包装器成功执行。如果无法为其授予自动化权限,请重新配置为单用户 imsg 配置,而不是依赖 SSH 包装器进行发送。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw