iMessage（旧版：imsg）

注意：对于新的 iMessage 部署，请使用 BlueBubbles。
imsg 集成属于旧版方案，可能在未来版本中移除。

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

推荐新部署使用 BlueBubbles（功能更丰富的 iMessage 接入路径）。

快速设置

本地 Mac（快速路径）

第一步：安装并验证 imsg

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

第四步：批准首次私信配对（默认 dmPolicy）

bash

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

配对请求 1 小时后过期。

远程 Mac（通过 SSH）

OpenClaw 只需要一个兼容 stdio 的 cliPath，因此可以将 cliPath 指向一个 SSH 脚本，通过 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,
      // 可选：覆盖允许的附件根目录
      // 默认包含 /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），请在该上下文中一次性运行交互式命令以触发权限提示：

bash

imsg chats --limit 1
# 或
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 主会话
群组会话隔离（agent:<agentId>:imessage:group:<chat_id>）
回复通过来源渠道/目标元数据路由回 iMessage

群组类线程行为：

部分多参与者 iMessage 线程可能以 is_group=false 到达。若该 chat_id 在 channels.imessage.groups 中明确配置，OpenClaw 将其视为群组流量（群组门控 + 群组会话隔离）。

部署模式

专用 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 审批（自动化 + 完全磁盘访问）。

远程 Mac（通过 Tailscale，示例）

常见拓扑：

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

示例：

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

bash

imsg chats --limit 20

配置写入

iMessage 默认允许渠道发起的配置写入（/config set|unset 命令，需 commands.config: true）。

禁用方法：

json5

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

故障排除

imsg 未找到或 RPC 不支持

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

bash

imsg rpc --help
openclaw channels status --probe

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

macOS 权限提示被错过

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

bash

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

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

配置参考

配置参考 - iMessage
Gateway 配置
配对
BlueBubbles（推荐的 iMessage 接入方式，让你的龙虾与 Apple 生态深度联动）

iMessage（旧版：imsg） ​

快速设置 ​

本地 Mac（快速路径） ​

远程 Mac（通过 SSH） ​

要求与权限（macOS） ​

访问控制与路由 ​

私信策略 ​

群组策略 + 提及 ​

会话与确定性回复 ​

部署模式 ​

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

远程 Mac（通过 Tailscale，示例） ​

多账号模式 ​

媒体、分块与投递目标 ​

附件与媒体 ​

出站分块 ​

寻址格式 ​

配置写入 ​

故障排除 ​

imsg 未找到或 RPC 不支持 ​

私信被忽略 ​

群组消息被忽略 ​

远程附件获取失败 ​

macOS 权限提示被错过 ​

配置参考 ​

iMessage（旧版：imsg）

快速设置

本地 Mac（快速路径）

远程 Mac（通过 SSH）

要求与权限（macOS）

访问控制与路由

私信策略

群组策略 + 提及

会话与确定性回复

部署模式

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

远程 Mac（通过 Tailscale，示例）

多账号模式

媒体、分块与投递目标

附件与媒体

出站分块

寻址格式

配置写入

故障排除

imsg 未找到或 RPC 不支持

私信被忽略

群组消息被忽略

远程附件获取失败

macOS 权限提示被错过

配置参考