iMessage

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

典型流程：

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

首次运行时，可能需要在该机器人用户会话中通过 GUI 授予权限（Automation + Full Disk Access）。

常见拓扑：

• 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 bashexec 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.dmHistoryLimit，使用该对话最近解码的 imsg 历史记录为新的私信会话提供初始上下文。使用 channels.imessage.dms["<sender>"].historyLimit 进行按发送者覆盖，包括使用 0 为某个发送者禁用历史记录。

iMessage 私信历史记录会按需从 imsg 获取。不设置 dmHistoryLimit 会禁用全局私信历史记录的初始填充，但正数的按发送者 channels.imessage.dms["<sender>"].historyLimit 仍会为该发送者启用初始填充。

• 入站附件摄取默认关闭——设置 channels.imessage.includeAttachments: true，将照片、语音备忘录、视频和其他附件转发给智能体。禁用此项后，仅包含附件的 iMessage 会在到达智能体之前被丢弃，并且可能完全不会生成 Inbound message 日志行。
• 设置 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.streaming.chunkMode
  • length（默认）
  • newline（优先按段落拆分）
• 出站 Markdown 粗体/斜体/下划线/删除线会转换为原生样式文本（macOS 15+ 接收方会显示相应样式；旧版本接收方看到的是不含标记的纯文本）；Markdown 表格会根据该渠道的 Markdown 表格模式进行转换
• channels.imessage.sendTransport（默认 auto、bridge、applescript）选择 imsg 如何执行发送

首选的显式目标：

• chat_id:123（建议用于稳定路由）
• chat_guid:...
• chat_identifier:...

也支持句柄目标：

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

imsg chats --limit 20

• react：添加/移除 iMessage 点按回应（messageId、emoji、remove）。支持的点按回应分别映射为爱心、赞、踩、笑、强调和疑问。不指定表情符号进行移除时，会清除当前设置的任何点按回应。
• reply：向现有消息发送线程式回复（messageId、text 或 message，以及 chatGuid、chatId、chatIdentifier 或 to）。带附件回复还需要一个 imsg 构建版本，且其 send-rich 支持 --file。
• sendWithEffect：使用 iMessage 效果发送文本（text 或 message、effect 或 effectId）。短名称：slam、loud、gentle、invisibleink、confetti、lasers、fireworks、balloon、heart、echo、happybirthday、shootingstar、sparkles、spotlight。
• edit：在受支持的 macOS/私有 API 版本上编辑已发送的消息（messageId、text 或 newText）。只有 Gateway 网关自身发送的消息才能编辑。
• unsend：在受支持的 macOS/私有 API 版本上撤回已发送的消息（messageId）。只有 Gateway 网关自身发送的消息才能撤回。
• upload-file：发送媒体/文件（buffer 采用 base64，或已填充的 media/path/filePath、filename，可选 asVoice）。旧版别名：sendAttachment。
• renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup：当前目标为群组对话时，用于管理群聊。这些操作会修改主机的 Messages 身份，因此需要所有者发送者或 operator.admin Gateway 网关客户端。
• poll：创建原生 Apple Messages 投票（pollQuestion、重复 2 至 12 次的 pollOption，以及 chatGuid、chatId、chatIdentifier 或 to）。使用 iOS/iPadOS/macOS 26+ 的接收方可以原生查看并投票；旧版操作系统会收到“已发送投票”的文本回退消息。需要 selectors.pollPayloadMessage。
• poll-vote：对现有投票进行投票（pollId 或 messageId，并且必须恰好指定 pollOptionIndex、pollOptionId 或 pollOptionText 之一）。需要 selectors.pollVoteMessage 和 poll.vote RPC 方法。

已接受的入站投票会呈现给智能体，其中包含问题、带编号的选项标签、票数，以及 poll-vote 所需的投票消息 ID。

入站 iMessage 上下文会包含短 MessageSid 值，并在可用时包含完整消息 GUID（MessageSidFull）。短 ID 的作用域限于近期由 SQLite 支持的回复缓存，并且使用前会根据当前聊天进行检查。如果短 ID 已过期，请在以提供该 ID 的对话为目标时，使用其 MessageSidFull 重试。完整 ID 不会绕过对话或账户绑定，因此应将来自其他聊天的 ID 替换为来自当前目标的 ID。如果缺少当前对话的证据，远程委托调用可能会拒绝过期的完整 ID。

只有当缓存的探测状态表明桥接不可用时，OpenClaw 才会隐藏私有 API 操作。如果状态未知，操作仍然可见，并在分派时延迟执行探测，因此在 imsg launch 之后，首次操作无需单独手动刷新状态即可成功。

私有 API 桥接启动后，已接受的入站聊天会被标记为已读；私聊在轮次被接受后会立即显示正在输入气泡，同时智能体准备上下文并生成内容。使用以下配置禁用已读标记：

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

在按方法能力列表出现之前的旧版 imsg 构建会静默关闭正在输入状态/已读功能；OpenClaw 每次重启会记录一次警告，以便确定回执缺失的原因。

OpenClaw 会订阅 iMessage 点按回应，并将已接受的表情回应作为系统事件路由，而不是作为普通消息文本处理，因此用户的点按回应不会触发常规回复循环。

通知模式由 channels.imessage.reactionNotifications 控制：

• "own"（默认）：仅当用户回应机器人发送的消息时通知。
• "all"：对已授权发送者的所有入站点按回应发出通知。
• "off"：忽略入站点按回应。

按账户覆盖使用 channels.imessage.accounts.<id>.reactionNotifications。

当 approvals.exec.enabled 或 approvals.plugin.enabled 为 true，并且请求路由到 iMessage 时，Gateway 网关会以原生方式投递审批提示，并接受点按回应来处理该请求：

• 👍（赞点按回应）→ allow-once
• 👎（踩点按回应）→ deny
• allow-always 仍作为手动回退：将 /approve <id> allow-always 作为普通回复发送。

表情回应处理要求作出回应的用户句柄必须是显式审批者。审批者列表从 channels.imessage.allowFrom（或 channels.imessage.accounts.<id>.allowFrom）读取；添加 E.164 格式的用户电话号码或其 Apple ID 电子邮件地址（chat_id:* 等聊天目标不是有效的审批者条目）。通配符条目 "*" 会生效，但会允许任何发送者进行审批；空审批者列表会完全禁用表情回应快捷方式。表情回应快捷方式会特意绕过 reactionNotifications、dmPolicy 和 groupAllowFrom，因为显式审批者允许列表是解决审批请求时唯一有效的门控条件。

/approve 文本命令授权遵循同一列表：当 channels.imessage.allowFrom 非空时，/approve <id> <decision> 会根据该审批者列表进行授权（而不是范围更广的私信允许列表），私信允许列表中获准但未包含在 allowFrom 中的发送者会收到明确的拒绝。当 allowFrom 为空时，同一聊天回退仍然有效，并且 /approve 会授权私信允许列表准许的任何人。将所有应当能够审批的操作员——无论是通过 /approve 还是通过表情回应——都添加到 allowFrom。

操作员说明：

• 表情回应绑定会同时存储在内存和 Gateway 网关的持久化键值存储中（TTL 与审批过期时间一致），Gateway 网关还会轮询待处理提示中的点回表情，因此即使点回表情在 Gateway 网关重启后不久到达，仍可完成审批。
• 当操作员自己的 is_from_me=true 点回表情（例如来自已配对的 Apple 设备）所对应的句柄是明确指定的审批者时，该点回表情会完成审批。
• 仅当配置了明确的审批者时，审批提示才会路由到群组会话中；否则任何群组成员都可以批准。
• 旧版文本样式的点回表情（来自非常旧的 Apple 客户端的 Liked "…" 纯文本）无法完成审批，因为它们不携带消息 GUID；表情回应解析需要当前 macOS / iOS 客户端发出的结构化点回表情元数据。

对于包含一个非敏感单选问题及一到四个选项的 ask_user 提示，OpenClaw 会添加带编号的表情符号选项。使用匹配的数字对已送达的提示作出表情回应即可回答。该表情回应必须携带由 Bot 编写的消息的稳定 GUID；随后 OpenClaw 会通过 Gateway 网关将该数字映射到规范选项。过期或重复的点击会被忽略。

多问题、多选和自由文本提示仍然只能通过文本回复。问题表情回应遵循常规的 iMessage 私信/群组准入规则。即使常规 reactionNotifications 为 "off"，也能识别这些表情回应，而不会将无关的表情回应转换为智能体事件。

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

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

如果探测报告不支持 RPC，请更新 imsg。如果私有 API 操作不可用，请在已登录的 macOS 用户会话中运行 imsg launch，然后再次探测。如果 Gateway 网关未在 macOS 上运行，请使用上文的通过 SSH 连接远程 Mac 的设置，而不是默认的本地 imsg 路径。

首先确认消息是否已到达本地 Mac。如果 chat.db 没有变化，那么即使 imsg status --json 报告桥接器健康，OpenClaw 也无法接收消息。

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

如果从手机发送的消息未创建新行，请先修复 macOS Messages 和 Apple Push 层，再更改 OpenClaw 配置。执行一次服务刷新通常就足够：

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

从手机发送一条新的 iMessage，并确认出现新的 chat.db 行或 imsg watch 事件，然后再调试 OpenClaw 会话。不要将此操作作为定期重新启动桥接器的循环；在工作进行期间重复执行 imsg launch 并重启 Gateway 网关，可能会中断消息送达并使正在进行的渠道运行陷入停滞。

默认的 cliPath: "imsg" 必须在已登录 Messages 的 Mac 上运行。在 Linux 或 Windows 上，请将 channels.imessage.cliPath 设置为一个包装脚本，通过 SSH 连接到该 Mac 并运行 imsg "$@"。

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

然后运行：

openclaw channels status --probe --channel imessage

检查：

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

检查：

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• channels.imessage.groups 允许列表行为
• 提及模式配置（agents.entries.*.groupChat.mentionPatterns）

检查：

• channels.imessage.remoteHost
• channels.imessage.remoteAttachmentRoots
• 来自 Gateway 网关主机的 SSH/SCP 密钥身份验证
• Gateway 网关主机上的 ~/.ssh/known_hosts 中存在主机密钥
• 运行 Messages 的 Mac 上的远程路径可读性

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

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

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