iMessage

对于新的 iMessage 部署，请使用 BlueBubbles。imsg 集成是旧版集成，可能会在未来版本中移除。

Status：旧版外部 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", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /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）

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

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

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

访问控制和路由

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

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 可以使用：

规范化的私信 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。

部署模式

专用机器人 macOS 用户（独立 iMessage 身份）

使用专用 Apple ID 和 macOS 用户，使机器人流量与你的个人 Messages 配置隔离。典型流程：

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

首次运行可能需要在该机器人用户会话中进行 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 使用严格的主机密钥检查（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 默认允许由渠道发起配置写入（适用于 commands.config: true 时的 /config set|unset）。禁用：

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

故障排除

找不到 imsg 或不支持 RPC

验证二进制文件和 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 上远程路径的可读性

错过了 macOS 权限提示

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

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

确认运行 OpenClaw/imsg 的进程上下文已获得 Full Disk Access + Automation。

概览

消息平台

配置

BlueBubbles（推荐）

配对

配置参考

快速设置

要求和权限（macOS）

访问控制和路由

ACP 对话绑定

部署模式

媒体、分块和投递目标

配置写入

故障排除

配置参考指针

相关内容

概览

消息平台

配置

Documentation Index

BlueBubbles（推荐）

配对

配置参考

​快速设置

​要求和权限（macOS）

​访问控制和路由

​ACP 对话绑定

​部署模式

​媒体、分块和投递目标

​配置写入

​故障排除

​配置参考指针

​相关内容

快速设置

要求和权限（macOS）

访问控制和路由

ACP 对话绑定

部署模式

媒体、分块和投递目标

配置写入

故障排除

配置参考指针

相关内容