OpenClaw 通过 imsg CLI 工具接入 iMessage，Gateway 与 imsg 通过 stdio JSON-RPC 通信，无需独立守护进程。
注意：新部署推荐使用 BlueBubbles。
imsg为旧版集成，未来可能移除。
快速接入
1. 安装 imsg
bash
brew install steipete/tap/imsg
imsg rpc --help # 验证安装2. 配置 OpenClaw
json
{
"channels": {
"imessage": {
"enabled": true,
"cliPath": "/usr/local/bin/imsg",
"dbPath": "/Users/<你的用户名>/Library/Messages/chat.db"
}
}
}3. 启动 Gateway 并完成配对
bash
openclaw gateway
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>配对码有效期 1 小时。
macOS 权限要求
iMessage 接入需要以下系统权限：
- 完全磁盘访问权限：运行 OpenClaw/imsg 的进程需要读取 Messages 数据库
- 自动化权限：通过 Messages.app 发送消息所需
权限按进程上下文授予。如果 Gateway 以无头模式运行（LaunchAgent/SSH），需在同一用户上下文中执行一次交互式命令触发权限弹窗：
bash
imsg chats --limit 1
# 或
imsg send <handle> "test"部署模式
本地 Mac（最简）
Gateway 和 imsg 在同一台 Mac 上运行，直接配置 cliPath 和 dbPath 即可。
远程 Mac over SSH
Gateway 运行在 Linux/VM，iMessage 和 imsg 在 Mac 上：
创建 SSH 包装脚本（~/.openclaw/scripts/imsg-ssh）：
bash
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"bash
chmod +x ~/.openclaw/scripts/imsg-ssh配置（含附件支持）：
json
{
"channels": {
"imessage": {
"enabled": true,
"cliPath": "~/.openclaw/scripts/imsg-ssh",
"remoteHost": "user@gateway-host",
"includeAttachments": true,
"attachmentRoots": ["/Users/*/Library/Messages/Attachments"],
"remoteAttachmentRoots": ["/Users/*/Library/Messages/Attachments"]
}
}
}远程 Mac over Tailscale（推荐）
json
{
"channels": {
"imessage": {
"enabled": true,
"cliPath": "~/.openclaw/scripts/imsg-ssh",
"remoteHost": "bot@mac-mini.tailnet-1234.ts.net",
"includeAttachments": true,
"dbPath": "/Users/bot/Library/Messages/chat.db"
}
}
}包装脚本：
bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"使用 SSH 密钥实现无交互认证；先
ssh一次确保known_hosts中已有主机密钥。
专用 Bot macOS 用户（隔离方案）
- 创建专用 macOS 用户并登录
- 用独立 Apple ID 登录 Messages
- 在该用户下安装 imsg
- 创建 SSH 包装脚本指向该用户
- 在该用户的 GUI 会话中完成权限授权
访问控制
json
{
"channels": {
"imessage": {
"dmPolicy": "allowlist",
"allowFrom": ["+8613800138000", "user@example.com"],
"groupPolicy": "open"
}
}
}allowFrom 支持：手机号、邮箱、chat_id:*、chat_guid:*、chat_identifier:*
投递目标格式
| 格式 | 说明 |
|---|---|
chat_id:123 | 推荐，稳定路由 |
imessage:+8613800138000 | 手机号 |
user@example.com | Apple ID 邮箱 |
bash
# 列出聊天 ID
imsg chats --limit 20消息行为
- 文本分块：
textChunkLimit（默认 4000 字符） chunkMode: "newline"在段落边界分割- 媒体大小上限：
mediaMaxMb（默认 16MB） - 附件通过 SCP 抓取（远程模式，严格主机密钥检查）
故障排查
bash
imsg rpc --help # 验证 RPC 支持
openclaw channels status --probe # 检查连接状态
openclaw pairing list imessage # 查看配对状态DM 被忽略：检查 dmPolicy、allowFrom 和配对审批状态
群组消息被忽略：检查 groupPolicy、groupAllowFrom 和 mention 模式
远程附件失败：验证 remoteHost、SSH 密钥认证、known_hosts 和远程路径权限
权限提示未出现：在同一用户/会话的交互式 GUI 终端中重新运行 imsg chats --limit 1
原文：iMessage - OpenClaw | 来源：OpenClaw 官方文档