iMessage 私人 API 操作

• react：Add/remove iMessage 抽头（messageId、emoji、remove）。支持的回击映射为爱、喜欢、不喜欢、笑、强调和问题。不带表情符号的删除会清除设置的回击。
• reply：向现有消息发送线程回复（messageId、text 或 message，以及 chatGuid、chatId、chatIdentifier 或 to）。本地的带附件回复还需要 imsg 构建版本的 send-rich 支持 --file。使用远程 imsg v0.13.4 时，附件回复使用 JSON-RPC，并支持整条消息或第 0 部分；RPC 方法不支持非零附件部分索引。
• sendWithEffect：发送带有 iMessage 效果的文本（text 或 message、effect 或 effectId）。短名称：slam、loud、gentle、invisibleink、confetti、lasers、fireworks、balloon、heart、echo、happybirthday、shootingstar、sparkles、spotlight。
• edit：在支持的 macOS/private API 版本（messageId、text 或 newText）上编辑已发送消息。只能编辑网关本身发送的消息。
• unsend：在支持的 macOS/private API 版本 （messageId） 上撤回已发送的消息。只能取消发送网关本身发送的消息。
• 上传文件：发送media/files（buffer作为base64或水合media/path/filePath、filename，可选asVoice）。旧别名：sendAttachment。
• renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup：当当前目标是群组会话时管理群聊。这些动作会修改主机的 Messages 身份，因此要求发送者为所有者，或 Gateway 客户端具有 operator.admin 权限。
• poll：创建本机 Apple 消息轮询（pollQuestion、pollOption 重复 2 到 12 次，加上 chatGuid、chatId、 chatIdentifier 或 to）。 iOS/iPadOS/macOS 26+ 上的收件人可以本地查看并投票；较旧的 OS 版本获得“已发送民意调查”文本后备。需要 selectors.pollPayloadMessage。
• poll-vote：对现有投票进行投票（pollId 或 messageId，以及 pollOptionIndex、pollOptionId 或 pollOptionText 三者之一且只能选择一个）。需要 selectors.pollVoteMessage 和 poll.vote RPC 方法。远程 imsg v0.13.4 RPC 仅接受选项 ID，因此远程设置必须使用 pollOptionId；索引和文本选择器仍可用于本地设置。

已接受的入站投票会以问题、选项标签、投票数以及 poll-vote 所需的投票消息 ID 呈现给代理。远程账号还会包含每个稳定的选项 ID，并指示代理使用 pollOptionId。

入境iMessage上下文包括简短的MessageSid值和完整消息 GUID（MessageSidFull）当可用时。短 ID 的范围是最近的SQLite-支持回复缓存，并在使用前根据当前聊天进行检查。如果短路ID过期，用它重试MessageSidFull同时瞄准提供它的对话。完整 ID 不会绕过对话或帐户绑定，因此请替换ID来自与当前目标的另一次聊天。当当前对话证据不可用时，远程委派呼叫可以拒绝过时的完整 ID。

仅当缓存检查状态表明桥不可用时，OpenClaw 才会隐藏私有 API 操作。如果状态未知，则操作保持可见并延迟调度检查，以便第一个操作可以在 imsg launch 之后成功，而无需单独的手动状态刷新。

当私有 API 桥接可用时，已接受的入站聊天会被标记为已读，而直接聊天会在回合被接受时立刻显示正在输入气泡，同时代理准备上下文并生成回复。可通过以下方式禁用已读标记：

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

早于按方法能力列表门控的旧版 imsg 构建会静默关闭 typing/read；OpenClaw 会在每次重启后记录一次警告，以便将缺失的回执归因。

OpenClaw 会订阅 iMessage 点按回应，并将收到的反应作为系统事件路由，而不是普通消息文本，因此用户的点按回应不会触发普通回复循环。

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

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

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

当 approvals.exec.enabled 或 approvals.plugin.enabled 为 true 且请求原生路由到 iMessage 时，网关会提供带原生控件的批准提示：

• 在具有轮询和标题抑制支持的已检查私有 API 桥上，提示包括每个允许的决策的消息轮询。较旧的 imsg 版本没有 poll send --no-comment 保留在文本控件上。
• 如果通过 channels.imessage.actions.polls: false 禁用了投票、桥接不支持投票、发送投票失败，或者可用决策少于两个，则提示会保留文本和点按回应控件。
• 文本回退会将 👍（赞）映射为 allow-once，将 👎（不喜欢）映射为 deny。它还包含 /approve <id> <decision> 命令，在请求允许时也包括 allow-always。

投票和反应要求执行操作的用户句柄必须是显式批准者。批准者列表从 channels.imessage.allowFrom（或 channels.imessage.accounts.<id>.allowFrom）读取；请添加用户的 E.164 格式电话号码或其 Apple ID 邮箱（如 chat_id:* 这类聊天目标不是有效的批准者条目）。通配符条目 "*" 会被接受，但会允许任何发送者批准；空的批准者列表会完全禁用投票和反应快捷方式。这些快捷方式会有意绕过 reactionNotifications、dmPolicy 和 groupAllowFrom，因为显式批准者白名单才是批准解析时真正重要的唯一门槛。

目前，原生投票控件仅限于来源 iMessage 会话中的通道原生投递，或 iMessage 批准者 DM。由 approvals.exec.mode: "targets" 选定的显式转发目标（以及 "both" 的目标部分）仍然会使用现有的转发批准消息，而不是 iMessage 投票。

/approve 文本命令的授权遵循相同列表：当 channels.imessage.allowFrom 非空时，/approve <id> <decision> 会依据该批准者列表进行授权（而不是更宽泛的 DM 白名单），而只在 DM 白名单中获准、但不在 allowFrom 中的发送者会收到明确拒绝。当 allowFrom 为空时，仍保持同聊天回退机制，/approve 会授权 DM 白名单允许的任何人。请把所有应当批准的操作员——无论是通过 /approve 还是通过反应——都加入 allowFrom。

操作员注意：

• 投票和反应绑定同时存储在内存中和网关的持久键值存储中（TTL 与批准到期时间一致），网关还会轮询待处理提示以查找点按回应。网关重启后，对旧控件的点击会被识别并吞掉，而不会进入代理聊天，但重启会终止进行中的命令；应请求新的批准，而不要指望旧控件恢复它。
• 当该句柄是显式批准者时，操作员自己的 is_from_me=true 点按回应（例如来自配对的 Apple 设备）会解析批准。
• 只有在配置了显式批准者时，批准提示才会路由到群组对话；否则群组中的任何成员都可能批准。
• 旧式文本样式点按回应（来自非常旧 Apple 客户端的纯文本 Liked "…"）无法解析批准，因为它们不携带消息 GUID；反应解析需要当前 macOS / iOS 客户端发出的结构化点按回应元数据。

对于包含一个非秘密单选问题和一到四个选项的 ask_user 提示，OpenClaw 添加了编号的表情符号选项。使用匹配的号码对发送的提示作出反应以回答它。该反应必须携带机器人编写的消息的稳定GUID； OpenClaw 然后通过网关将该号码映射到存储的选项。过时或重复的点击将被忽略。

多问题、多选择和自由文本提示仍然仅限文本回复。问题反应遵循正常的 iMessage DM/group 入场规则。即使一般 reactionNotifications 是 "off"，它们也能被识别，而不会将不相关的反应转化为代理事件。