设置
安装插件，在已登录 Messages 的 Mac 上安装并验证 imsg，配置通道，并授予其所需的 macOS 权限。
安装插件¶
在 Gateway 主机上安装官方 iMessage 插件：
继续之前，请检查应用结果。
回复、轻点回应、效果、投票、附件和群组管理。
iMessage 私信默认使用配对模式。
当 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 代理，对于长生命周期的 JSON-RPC 都必须表现得像透明 stdio 管道。OpenClaw 会在通道生命周期内通过包装器的 stdin/stdout 交换小型换行符分隔的 JSON-RPC 消息：
- 在字节可用时立即转发每个 stdin 块/行 — 不要等待 EOF。
- 及时在反方向转发每个 stdout 块/行。
- 保留换行符。
- 避免固定大小的阻塞读取（
read(4096)、cat | buffer、默认 shellread），这些可能导致小帧饥饿。 - 将 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 发送消息需要自动化权限。
- 对于高级操作（回应 / 编辑 / 撤回 / 线程回复 / 效果 / 投票 / 群组操作），必须禁用系统完整性保护 — 参见启用 imsg 私有 API。基本文本和媒体收发无需禁用它。
Tip
权限按进程上下文授予。如果网关以无头方式运行（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 用户的本地会话中运行网关，或至少运行
imsg桥接。 - 在同一会话中授予完全磁盘访问权限和自动化权限后，为该用户使用 LaunchAgent 启动网关。
- 如果保留双用户 SSH 拓扑，请在启用通道之前，确认真实的出站
imsg send能够通过确切的包装器成功执行。如果无法授予自动化权限，请改为配置单用户imsg设置，而不是依赖 SSH 包装器进行发送。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw