Private API 操作

探测到的私有 API 桥接在普通文本发送之上增加的操作面。

私有 API 操作¶

当 imsg launch 正在运行，且 openclaw channels status --probe 报告 privateApi.available: true 时，消息工具除了普通文本发送外，还可以使用 iMessage 原生操作。

所有操作默认启用；使用 channels.imessage.actions 可关闭单个操作：

{
  channels: {
    imessage: {
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
        renameGroup: true,
        setGroupIcon: true,
        addParticipant: true,
        removeParticipant: true,
        leaveGroup: true,
        polls: true,
      },
    },
  },
}

可用操作

react：添加/移除 iMessage 点按反馈（messageId、emoji、remove）。支持的点按反馈对应 love、like、dislike、laugh、emphasize 和 question。不带 emoji 移除时会清除已设置的任意点按反馈。
reply：向现有消息发送线程回复（messageId、text 或 message，外加 chatGuid、chatId、chatIdentifier 或 to）。本地带附件回复还需要 send-rich 支持 --file 的 imsg 构建。对于远程 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/私有 API 版本上编辑已发送消息（messageId、text 或 newText）。只能编辑网关本身发送的消息。
unsend：在受支持的 macOS/私有 API 版本上撤回已发送消息（messageId）。只能撤回网关本身发送的消息。
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 方法。远程 imsg v0.13.4 RPC 仅接受选项 ID，因此远程设置必须使用 pollOptionId；索引和文本选择器仍可供本地设置使用。

已接受的传入投票会向 agent 渲染问题、选项标签、投票数以及 poll-vote 所需的投票消息 ID。远程账户还会包含每个稳定选项 ID，并指示 agent 使用 pollOptionId。

消息 ID

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

能力检测

OpenClaw 仅在缓存的探测状态显示桥接不可用时隐藏私有 API 操作。如果状态未知，操作仍会保持可见，并延迟分发探测，以便在 imsg launch 后首次操作可以成功，而无需单独手动刷新状态。

已读回执和正在输入

当私有 API 桥接启动后，已接受的传入聊天会被标记为已读，并且一旦回合被接受，直接聊天就会显示正在输入气泡，同时 agent 准备上下文并生成。使用以下配置禁用已读标记：

{
  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 时，网关会提供带有原生控件的审批提示：

在支持投票和注释抑制的探测私有 API 桥接上，提示会包含一个 Messages 投票，其中列出每个允许的决策。没有 poll send --no-comment 的旧版 imsg 版本仍使用文本控件。
如果通过 channels.imessage.actions.polls: false 禁用了投票、桥接不支持投票、投票发送失败，或可用决策少于两个，提示会保留文本和点按反馈控件。
文本回退将 👍（喜欢）映射到 allow-once，将 👎（不喜欢）映射到 deny。它还包括 /approve <id> <decision> 命令，在请求允许时包括 allow-always。

Poll votes and reactions require the acting user's handle to be an explicit approver. The approver list is read from channels.imessage.allowFrom (or channels.imessage.accounts.<id>.allowFrom); add the user's phone number in E.164 form or their Apple ID email (chat targets such as chat_id:* are not valid approver entries). The wildcard entry "*" is honored but allows any sender to approve; an empty approver list disables poll and reaction shortcuts entirely. These shortcuts intentionally bypass reactionNotifications, dmPolicy, and groupAllowFrom because the explicit-approver allowlist is the only gate that matters for approval resolution.

原生投票控件目前仅限于在源 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 与审批过期时间匹配），网关还会轮询待处理提示以获取 tapback。网关重启后，对旧控件的点击会被识别并吞掉，而不会进入 agent 聊天，但重启会结束进行中的命令；请请求新的审批，而不是期望旧控件恢复它。
- 操作员自己的 `is_from_me=true` tapback（例如来自配对的 Apple 设备）在该账号是显式审批人时解决审批。
- 仅当配置了显式审批人时，审批提示才会路由到群聊；否则任何群成员都可能审批。
- 旧版文本样式 tapback（来自非常旧的 Apple 客户端的 `Liked "…"` 纯文本）无法解决审批，因为它们不携带消息 GUID；反应解析需要当前 macOS / iOS 客户端发出的结构化 tapback 元数据。

问题反应（1️⃣ / 2️⃣ / 3️⃣ / 4️⃣）

对于包含一个非机密、单选问题且有一到四个选项的 ask_user 提示，OpenClaw 会添加带编号的表情选项。使用匹配的数字对已投递的提示做出反应即可回答。该反应必须携带机器人所发消息的稳定 GUID；随后 OpenClaw 会通过 Gateway 将该数字映射到规范选项。过期的或重复的点击会被忽略。

多问题、多选和自由文本提示仍仅限文本回复。问题反应遵循正常的 iMessage DM/群组准入规则。即使通用 reactionNotifications 为 "off"，它们也会被识别，而不会将无关反应变成 agent 事件。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw