imsg 是 OpenClaw 的 iMessage 旧版集成方案——Gateway 启动 imsg RPC 进程，通过标准输入输出通信。新部署请改用 BlueBubbles，功能更丰富且更稳定。本文仅用于仍在使用 imsg 的旧版场景，覆盖本地 Mac、远程 SSH、多账号、附件和 ACP 绑定配置。

iMessage（旧版：imsg）

提示：新的 iMessage 部署请使用 BlueBubbles。imsg 集成是旧版方案，可能在未来版本中移除。

状态：旧版外部 CLI 集成。Gateway 启动 imsg rpc 并通过标准输入输出上的 JSON-RPC 通信（无独立守护进程/端口）。

快速开始

本地 Mac（快速路径）：

bash

brew install steipete/tap/imsg
imsg rpc --help

配置 OpenClaw：

json5

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

启动 Gateway：

bash

openclaw gateway

批准第一个 DM 配对（默认 dmPolicy）：

bash

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

配对请求 1 小时后过期。

通过 SSH 连接远程 Mac：

OpenClaw 只需要一个兼容标准输入输出的 cliPath，你可以将 cliPath 指向一个通过 SSH 连接到远程 Mac 并运行 imsg 的包装脚本：

bash

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

启用附件时的推荐配置：

json5

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // 用于 SCP 附件获取
      includeAttachments: true,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

macOS 要求与权限

运行 imsg 的 Mac 上必须已登录 Messages
运行 OpenClaw/imsg 的进程上下文需要完全磁盘访问权限（访问 Messages 数据库）
需要自动化权限通过 Messages.app 发送消息

权限是按进程上下文授予的。如果 Gateway 在无头模式下运行，请在同一上下文中一次性运行交互命令触发授权提示：
bash
imsg chats --limit 1
# 或
imsg send <handle> "test"

访问控制与路由

DM 策略：

channels.imessage.dmPolicy 控制私信：

pairing（默认）
allowlist
open（需要 allowFrom 包含 "*"）
disabled

白名单字段：channels.imessage.allowFrom，条目可以是句柄或聊天目标（chat_id:*、chat_guid:*、chat_identifier:*）。

群组策略 + 提及：

channels.imessage.groupPolicy 控制群组处理：

allowlist（配置时的默认值）
open
disabled

群组发件人白名单：channels.imessage.groupAllowFrom。

iMessage 没有原生提及元数据，提及检测使用正则模式（agents.list[].groupChat.mentionPatterns，降级 messages.groupChat.mentionPatterns）。

授权发件人的控制命令可以绕过群组中的提及门控。

ACP 会话绑定

旧版 iMessage 聊天也可以绑定到 ACP 会话。快速操作：

在 DM 或允许的群聊中运行 /acp spawn codex --bind here
该 iMessage 对话中的后续消息路由到已创建的 ACP 会话
/new 和 /reset 就地重置同一绑定的 ACP 会话
/acp close 关闭 ACP 会话并移除绑定

也支持通过顶层 bindings[] 配置持久绑定，type: "acp" 和 match.channel: "imessage"。

match.peer.id 可以使用：

标准化 DM 句柄，如 +15555550123 或 user@example.com
chat_id:<id>（推荐用于稳定的群组绑定）
chat_guid:<guid>
chat_identifier:<identifier>

示例：

json5

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

详见 ACP Agents。

部署模式

专用 Bot macOS 用户（独立 iMessage 身份）：

使用专用 Apple ID 和 macOS 用户，隔离 Bot 流量与个人 Messages 档案。典型流程：

创建/登录专用 macOS 用户
用 Bot Apple ID 登录该用户的 Messages
在该用户中安装 imsg
创建 SSH 包装器让 OpenClaw 可以在该用户上下文运行 imsg
将 channels.imessage.accounts.<id>.cliPath 和 .dbPath 指向该用户档案

通过 Tailscale 连接远程 Mac 示例：

json5

{
  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 和 SCP 都无需交互，先确保主机密钥已在 ~/.ssh/known_hosts 中。

媒体、分块与投递目标

附件与媒体：

入站附件获取是可选的：channels.imessage.includeAttachments
设置 remoteHost 后，远程附件路径可通过 SCP 获取
附件路径必须匹配允许的根目录，默认：/Users/*/Library/Messages/Attachments
出站媒体大小：channels.imessage.mediaMaxMb（默认 16 MB）

出站分块：

文本块限制：channels.imessage.textChunkLimit（默认 4000）
块模式：channels.imessage.chunkMode（length 默认或 newline 段落优先）

寻址格式（推荐）：

chat_id:123（推荐，路由稳定）
chat_guid:...
chat_identifier:...

也支持句柄：imessage:+1555...、sms:+1555...、user@example.com

故障排查

imsg 未找到或不支持 RPC：

bash

imsg rpc --help
openclaw channels status --probe

如果 probe 报告不支持 RPC，请更新 imsg。

私信被忽略： 检查 channels.imessage.dmPolicy、allowFrom、配对批准（openclaw pairing list imessage）

群组消息被忽略： 检查 groupPolicy、groupAllowFrom、groups 白名单行为、提及模式配置

远程附件失败： 检查 remoteHost、remoteAttachmentRoots、SSH/SCP 密钥认证、主机密钥在 ~/.ssh/known_hosts 中是否存在

macOS 权限提示被错过： 在相同用户/会话上下文的交互式 GUI 终端重新运行并批准提示

常见问题

Q: imsg 和 BlueBubbles 我该选哪个？

A: 新部署选 BlueBubbles。BlueBubbles 功能更完整（编辑、撤回、Tapback），配置更稳定，imsg 是旧版方案随时可能被移除。只有在已有 imsg 环境且不便迁移时才继续使用 imsg。

Q: 远程 Mac 通过 SSH 使用 imsg，附件下载失败怎么解决？

A: 确认以下几点：① remoteHost 已正确设置（格式 user@host，无多余空格）；② Gateway 主机的 ~/.ssh/known_hosts 中已有远程主机密钥（先手动 SSH 一次让其自动写入）；③ 附件路径在 remoteAttachmentRoots 白名单内（默认 /Users/*/Library/Messages/Attachments）。

Q: DM 私信一直被忽略，没有触发配对码？

A: 检查 channels.imessage.dmPolicy（确认不是 disabled）和 channels.imessage.allowFrom（allowlist 模式需要发件人在白名单中）。若 dmPolicy 是 pairing，用 openclaw pairing list imessage 确认是否有待审批的配对请求。

iMessage（旧版：imsg） ​

快速开始 ​

macOS 要求与权限 ​

访问控制与路由 ​

ACP 会话绑定 ​

部署模式 ​

媒体、分块与投递目标 ​

故障排查 ​

常见问题 ​

相关链接 ​

iMessage（旧版：imsg）

快速开始

macOS 要求与权限

访问控制与路由

ACP 会话绑定

部署模式

媒体、分块与投递目标

故障排查

常见问题

相关链接