设置
安装插件,在已登录 Messages 的 Mac 上安装并验证 imsg,配置通道,并授予其所需的 macOS 权限。
安装插件¶
在 Gateway 主机上安装官方 iMessage 插件:
在继续之前,请检查应用结果。
回复、Tapbacks、特效、投票、附件及群组管理。
iMessage 私信(DM)默认进入配对模式。
当 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
4. 批准首次 DM 配对(默认 dmPolicy)
配对请求将在 1 小时后过期。
大多数设置不需要 SSH。仅在 Gateway 无法运行于已登录 Messages 的 Mac 上时,才使用此拓扑。将 `cliPath` 指向 **Gateway 主机**上的一个兼容 stdio 的包装器,该包装器通过 SSH 连接到 Messages Mac 并运行 `imsg`。请使用包装器的绝对路径,以便服务启动时不依赖 shell 的主目录展开。
在该远程 Mac 上安装和更新 `imsg`,而不是在 Gateway 主机上:
启用附件时的推荐配置:
{
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),请在同一上下文中运行一次性交互式命令以触发授权提示:
SSH 包装器发送因 AppleEvents -1743 失败
远程 SSH 配置可以读取聊天、通过 channels status --probe,并处理入站消息,但出站发送仍会因 AppleEvents 授权错误而失败:
请检查已登录 Mac 用户的 TCC 数据库,或“系统设置 > 隐私与安全性 > 自动化”。如果自动化条目记录的是 /usr/libexec/sshd-keygen-wrapper,而不是 imsg 或本地 shell 进程,macOS 可能不会为该 SSH 服务端客户端提供可用的 Messages 切换开关:
在这种情况下,重复执行 tccutil reset AppleEvents 或通过同一 SSH 包装器重新运行 imsg send 可能仍会失败,因为需要 Messages 自动化的进程上下文是 SSH 包装器,而不是 UI 可以授权的某个应用。
请改用其中一个受支持的 imsg 进程上下文:
- 在已登录 Messages 的用户的本地会话中运行 Gateway,或至少运行
imsg桥接。 - 在同一会话中授予完全磁盘访问权限和自动化权限后,为该用户使用 LaunchAgent 启动 Gateway。
- 如果保留双用户 SSH 拓扑,请在启用通道之前,确认真实的出站
imsg send能够通过完全相同的包装器成功执行。如果无法为其授予自动化权限,请重新配置为单用户imsg配置,而不是依赖 SSH 包装器进行发送。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw