iMessage

对于新的 iMessage 部署，请使用 BlueBubbles。imsg 集成是传统方案，未来版本中可能会被移除。

状态：传统外部 CLI 集成。Gateway 会启动 imsg rpc，并通过 stdio 上的 JSON-RPC 进行通信（没有单独的守护进程/端口）。

BlueBubbles（推荐）

新部署首选的 iMessage 路径。

配对

iMessage 私信默认使用配对模式。

配置参考

完整的 iMessage 字段参考。

快速设置

本地 Mac（快速路径）
通过 SSH 连接远程 Mac

安装并验证 imsg

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

配置 OpenClaw

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

启动 gateway

openclaw gateway

批准首次私信配对（默认 dmPolicy）

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

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 使用严格的 host key 检查，因此中继主机的 host key 必须已经存在于 ~/.ssh/known_hosts 中。附件路径会根据允许的根目录（attachmentRoots / remoteAttachmentRoots）进行验证。

要求和权限（macOS）

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

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

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

访问控制和路由

DM 策略
群组策略 + 提及
会话和确定性回复

channels.imessage.dmPolicy 控制私信：

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

允许列表字段：channels.imessage.allowFrom。允许列表条目可以是 handle 或聊天目标（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:<agentId>:imessage:group:<chat_id>）。
回复会使用来源频道/目标元数据路由回 iMessage。

类群组线程行为：某些多参与者 iMessage 线程可能会带着 is_group=false 到达。如果该 chat_id 在 channels.imessage.groups 中被显式配置，OpenClaw 会将其视为群组流量（群组门控 + 群组会话隔离）。

ACP 会话绑定

传统 iMessage 聊天也可以绑定到 ACP 会话。快速操作流程：

在该私信或允许的群聊中运行 /acp spawn codex --bind here。
之后同一 iMessage 会话中的消息会路由到生成的 ACP 会话。
/new 和 /reset 会就地重置同一个已绑定的 ACP 会话。
/acp close 会关闭 ACP 会话并移除绑定。

通过顶层 bindings[] 条目支持已配置的持久绑定，使用 type: "acp" 和 match.channel: "imessage"。 match.peer.id 可以使用：

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

示例：

{
  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 绑定行为，请参见 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 指向该用户配置文件。

首次运行时，可能需要在该 bot 用户会话中进行 GUI 授权（Automation + Full Disk Access）。

通过 Tailscale 连接远程 Mac（示例）

常见拓扑：

gateway 运行在 Linux/VM 上
iMessage + imsg 运行在你 tailnet 中的一台 Mac 上
cliPath 包装脚本使用 SSH 运行 imsg
remoteHost 启用通过 SCP 拉取附件

示例：

{
  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",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

使用 SSH 密钥，以便 SSH 和 SCP 都是非交互式的。先确保主机密钥是受信任的（例如 ssh bot@mac-mini.tailnet-1234.ts.net），以便填充 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 使用严格的 host key 检查（StrictHostKeyChecking=yes）
出站媒体大小使用 channels.imessage.mediaMaxMb（默认 16 MB）

出站分块

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

寻址格式

推荐的显式目标：

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

也支持 handle 目标：

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

配置写入

iMessage 默认允许由频道发起的配置写入（用于 /config set|unset，当 commands.config: true 时）。禁用：

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

故障排查

未找到 imsg 或不支持 RPC

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

imsg rpc --help
openclaw channels status --probe

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

DM 被忽略

检查：

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
网关主机上的 SSH/SCP 密钥认证
网关主机的 ~/.ssh/known_hosts 中是否存在主机密钥
运行 Messages 的 Mac 上远程路径是否可读

macOS 权限提示被错过

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

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

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

概览

主流消息平台

开发者与自托管

区域平台

配置

BlueBubbles（推荐）

配对

配置参考

快速设置

要求和权限（macOS）

访问控制和路由

ACP 会话绑定

部署模式

媒体、分块和投递目标

配置写入

故障排查

配置参考指针

相关内容

概览

主流消息平台

开发者与自托管

区域平台

配置

Documentation Index

BlueBubbles（推荐）

配对

配置参考

​快速设置

​要求和权限（macOS）

​访问控制和路由

​ACP 会话绑定

​部署模式

​媒体、分块和投递目标

​配置写入

​故障排查

​配置参考指针

​相关内容

快速设置

要求和权限（macOS）

访问控制和路由

ACP 会话绑定

部署模式

媒体、分块和投递目标

配置写入

故障排查

配置参考指针

相关内容