跳转至

Private API 操作

The action surface a checked private API bridge adds on top of plain text sends.

私有 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;索引和文本选择器仍可用于本地配置。

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

消息 ID

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

能力检测

OpenClaw 仅在缓存的检查状态表明桥接不可用时隐藏私有 API 操作。如果状态未知,操作仍会保持可见,并且分发检查会延迟执行,以便在 imsg launch 之后首次操作可以成功,而无需单独手动刷新状态。

已读回执和正在输入

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

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

早于按方法能力列表的旧版 imsg 构建会静默关闭正在输入/已读;OpenClaw 每次重启会记录一次性警告,以便能够归因缺失的回执。

入站点按反馈

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

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

  • "own"(默认):仅当用户对 bot 创建的消息做出反应时通知。
  • "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 禁用了投票、桥接不支持投票、投票发送失败,或者可用决策少于两个,提示会保留文本和点按反馈控件。
  • 文本回退将 👍(Like)映射到 allow-once,将 👎(Dislike)映射到 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.

投票和反应要求操作用户的 handle 必须是显式批准者。批准者列表从 `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`。

操作员说明:
- 投票和反应绑定同时存储在内存和 Gateway 的持久化键控存储中(TTL 与批准过期时间匹配),Gateway 还会轮询待处理提示以获取 tapback。Gateway 重启后,点击旧控件会被识别并吞掉,而不会进入 agent 聊天,但重启会结束进行中的命令;请请求新的批准,而不是期望旧控件恢复它。
- 操作员自己的 `is_from_me=true` tapback(例如来自配对的 Apple 设备)在该 handle 是显式批准者时解析批准。
- 只有配置了显式批准者时,批准提示才会路由到群聊;否则任何群成员都可能批准。
- 旧版文本样式 tapback(来自非常旧的 Apple 客户端的 `Liked "…"` 纯文本)无法解析批准,因为它们不携带消息 GUID;反应解析需要当前 macOS / iOS 客户端发出的结构化 tapback 元数据。
问题反应(1️⃣ / 2️⃣ / 3️⃣ / 4️⃣)

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

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

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