iMessage（旧版：imsg）

警告： 新的 iMessage 部署请使用 BlueBubbles。

imsg 集成已是旧版，可能在未来版本中移除。

状态：旧版外部 CLI 集成。Gateway 启动 imsg rpc 并通过 stdio 上的 JSON-RPC 通信（不需要单独的守护进程/端口）。

• BlueBubbles（推荐） — 新部署首选的 iMessage 方案。
• 配对 — iMessage 私信默认使用配对模式。
• 配置参考 — 完整的 iMessage 字段参考。

快速设置

本地 Mac（快速路径）

  ### 步骤 1：安装并验证 imsg

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

  ### 步骤 2：配置 OpenClaw

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

  ### 步骤 3：启动 Gateway

openclaw gateway

  ### 步骤 4：批准首次私信配对（默认 dmPolicy）

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    配对请求在 1 小时后过期。

通过 SSH 连接远程 Mac

OpenClaw 只需要一个兼容 stdio 的 `cliPath`，因此你可以将 `cliPath` 指向一个通过 SSH 连接远程 Mac 并运行 `imsg` 的包装脚本。

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

启用附件时的推荐配置：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // 用于 SCP 附件获取
      includeAttachments: true,
      // 可选：覆盖允许的附件根目录。
      // 默认包含 /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

如果未设置 `remoteHost`，OpenClaw 会尝试通过解析 SSH 包装脚本来自动检测。
`remoteHost` 格式必须为 `host` 或 `user@host`（不能含空格或 SSH 选项）。
OpenClaw 对 SCP 使用严格的主机密钥检查，因此中继主机密钥必须已存在于 `~/.ssh/known_hosts` 中。
附件路径会根据允许的根目录验证（`attachmentRoots` / `remoteAttachmentRoots`）。

要求与权限（macOS）

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

提示： 权限按进程上下文授予。如果 Gateway 以无头方式运行（LaunchAgent/SSH），请在同一上下文中运行一次交互式命令来触发提示：

imsg chats --limit 1
# 或
imsg send <handle> "test"

访问控制与路由

私信策略

`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`。

运行时回退：如果 `groupAllowFrom` 未设置，iMessage 群组发送者检查会在可用时回退到 `allowFrom`。
运行时注意：如果 `channels.imessage` 完全缺失，运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使 `channels.defaults.groupPolicy` 已设置）。

群组的提及门控：

- iMessage 没有原生提及元数据
- 提及检测使用正则模式（`agents.list[].groupChat.mentionPatterns`，备选 `messages.groupChat.mentionPatterns`）
- 没有配置模式时无法执行提及门控

已授权发送者的控制命令可在群组中绕过提及门控。

会话和确定性回复

- 私信使用直接路由；群组使用群组路由。
- 默认 `session.dmScope=main` 下，iMessage 私信归入 Agent 主会话。
- 群组会话隔离（`agent:<agentId>:imessage:group:<chat_id>`）。
- 回复通过源频道/目标元数据路由回 iMessage。

类群组线程行为：

某些多参与者 iMessage 线程可能以 `is_group=false` 的形式到达。
如果该 `chat_id` 在 `channels.imessage.groups` 下有显式配置，OpenClaw 会将其视为群组流量（群组门控 + 群组会话隔离）。

部署模式

使用专用的 Apple ID 和 macOS 用户，使 Bot 流量与个人 Messages 配置文件隔离。

典型流程：

1. 创建/登录专用的 macOS 用户。
2. 在该用户中使用 Bot Apple ID 登录 Messages。
3. 在该用户中安装 `imsg`。
4. 创建 SSH 包装脚本，使 OpenClaw 可以在该用户上下文中运行 `imsg`。
5. 将 `channels.imessage.accounts.<id>.cliPath` 和 `.dbPath` 指向该用户配置文件。

首次运行可能需要在该 Bot 用户会话中进行 GUI 审批（自动化 + 完全磁盘访问）。

常见拓扑：

- Gateway 运行在 Linux/VM 上
- iMessage + `imsg` 运行在 tailnet 中的 Mac 上
- `cliPath` 包装脚本使用 SSH 运行 `imsg`
- `remoteHost` 启用 SCP 附件获取

示例：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

使用 SSH 密钥使 SSH 和 SCP 均为非交互式。
确保主机密钥已受信任（例如先运行 `ssh [email protected]`）以填充 `known_hosts`。

iMessage 支持在 `channels.imessage.accounts` 下进行按账户配置。

每个账户可以覆盖 `cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、历史设置和附件根目录白名单等字段。

媒体、分块和投递目标

- 入站附件接收为可选：`channels.imessage.includeAttachments`
- 当设置了 `remoteHost` 时，远程附件路径可通过 SCP 获取
- 附件路径必须匹配允许的根目录：
  - `channels.imessage.attachmentRoots`（本地）
  - `channels.imessage.remoteAttachmentRoots`（远程 SCP 模式）
  - 默认根目录模式：`/Users/*/Library/Messages/Attachments`
- SCP 使用严格的主机密钥检查（`StrictHostKeyChecking=yes`）
- 出站媒体大小使用 `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...`
- `[email protected]`

imsg chats --limit 20

配置写入

iMessage 默认允许频道触发的配置写入（用于 /config set|unset，需要 commands.config: true）。

禁用：

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

故障排查

验证二进制文件和 RPC 支持：

imsg rpc --help
openclaw channels status --probe

如果探测报告 RPC 不支持，请更新 `imsg`。

检查：

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- 配对审批（`openclaw pairing list imessage`）

检查：

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` 白名单行为
- 提及模式配置（`agents.list[].groupChat.mentionPatterns`）

检查：

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- Gateway 主机的 SSH/SCP 密钥认证
- Gateway 主机上 `~/.ssh/known_hosts` 中是否存在主机密钥
- 运行 Messages 的 Mac 上远程路径的可读性

在同一用户/会话上下文的交互式 GUI 终端中重新运行并批准提示：

imsg chats --limit 1
imsg send <handle> "test"

确认运行 OpenClaw/`imsg` 的进程上下文已授予「完全磁盘访问」+「自动化」权限。

配置参考指引

• 配置参考 - iMessage
• Gateway 配置
• 配对
• BlueBubbles