imsg

imsg

对于当前 iMessage 模式公开的操作，优先使用通用 message 工具。当任务需要本地 Messages.app 历史记录、目标发现、监控，或 message 未提供的管理／私有 API 功能时，使用 imsg。

如果已配置的频道能够路由回复，则不要使用此技能在当前 OpenClaw 对话中回复；同样，也不要将其用于 Telegram、Signal、WhatsApp、Discord 或 Slack。

Agent 流程

1. 首先确定目标对话。
2. 选择私信、现有群聊或新群聊。
3. 优先使用可用的 message 操作；否则，选择能够保留所请求语义的、能力要求最低的 imsg 命令。
4. 除非用户已经提供确切的收件人、内容和操作，否则，在任何发送或可见状态变更前都要确认。
5. 使用稳定标识符执行：普通发送、监控和历史记录优先使用 --chat-id；桥接操作使用 --chat 聊天 GUID。

当多个聊天对象或句柄都可能匹配时，绝不能仅凭随口提供的名称推断收件人。发送前，应展示匹配对象的显示名称、句柄、群聊参与者和消息文本／操作。

主机要求

• macOS 14+，且 Messages.app 已登录，才能执行发送、表情回应和桥接操作。
• 对于 OpenClaw iMessage，强烈建议使用私有 API 模式。它支持回复、精确轻拍回应、特效、投票、附件回复、已读／正在输入操作和群聊管理。基础模式作为读取内容及发送纯文本或文件的备用方案。
• 运行 imsg 或 OpenClaw 的进程上下文需要完全磁盘访问权限；如果无法访问 Messages 数据库，读取将失败。
• 使用公开的 send 时，需要为 Messages.app 授予自动化权限。
• 运行公开的 imsg react 需要辅助功能权限，因为该命令使用 System Events 进行 UI 自动化。桥接 tapback 则使用私有 API。
• 可选的 Contacts 权限，用于解析联系人名称。
• SMS 发送要求将用户 iPhone 上的“信息转发”设置到此 Mac。
• 在 Linux 上只能读取复制得到的 chat.db；无法发送、回应、启动 Messages.app、标记为已读或输入文字。

确定目标

读取时使用 --json。输出为换行分隔的 JSON；如果 jq 可用，使用 jq -s，也可直接逐行处理对象。

imsg chats --limit 25 --json | jq -s
imsg search --query "dinner" --match contains --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg group --chat-id 42 --json

目标规则：

• 向手机号码或邮箱地址发送私信：用户提供了准确句柄时，或唯一匹配到一个聊天对象后，使用 imsg send --to。
• 现有私信对话：与重新解析名称相比，imsg send --chat-id <id> 更安全。
• 现有群聊：使用 imsg group --chat-id <id> --json 检查；使用 --chat-id 发送，并使用 group 提供的聊天 GUID 进行桥接。
• 新群聊：仅当用户明确要求创建群聊，或没有现有群聊匹配时，才使用 chat-create。
• 群聊名称有歧义：应确认参与者，而不只是显示名称。
• SMS：仅在用户提出要求或不想使用 iMessage 后备方式时，使用 --service sms。SMS 中继需要启用“信息转发”。

不要将 jq 作为使用此技能时的硬性前置条件；它只是用于示例的便捷格式化工具。

能力选择

当当前 message 架构未涵盖该操作或需要本地历史记录时，使用 imsg 标准命令：

• 读取、列出、搜索、监听：chats、group、history、search、watch
• 发送基础文本或文件：send
• 对聊天中最近收到的一条消息进行标准轻点回应：react

对于 OpenClaw 用户通常期望的原生 iMessage 操作，使用私有 API 桥接：

• 富文本回复、文本格式、效果、主题、多部分发送
• Apple Messages 原生投票和投票操作
• 按消息 GUID 发送轻点回应或移除轻点回应
• 编辑、取消发送、删除、仍然通知
• 已读回执、正在输入指示器、桥接事件监听
• 创建群组、设置群组名称、设置照片、管理成员、退出、删除和标记操作
• 账户、whois 和昵称检查

进行 OpenClaw 渠道设置时，尽早检查桥接可用性：

imsg status --json

如果主机支持桥接操作，但尚未将桥接注入 Messages，请先征得同意，再运行 imsg launch。此操作会终止并重新启动 Messages.app 以注入桥接，因此应将其视为用户可见的状态变化：

imsg launch
imsg status --json

如果 SIP、库验证、私有权限检查或缺少选择器仍会阻止该能力，请说明此主机无法使用所请求的私有 API 操作，并在存在相近的非桥接操作时予以提供。不要将线程回复、效果、主题、投票或针对 GUID 的轻点回应静默降级为普通发送或 react。

私信场景

准确指定接收方标识，进行基本发送：

imsg send --to "+14155551212" --text "On my way" --service auto

已知私信线程：

imsg send --chat-id 42 --text "On my way"
imsg send --chat-id 42 --file /path/to/photo.jpg

仅在用户要求时强制指定渠道：

imsg send --to "+14155551212" --text "green bubble" --service sms
imsg send --to "+14155551212" --text "iMessage only" --service imessage --no-sms-fallback

线程回复、设置格式、添加效果或回复时附带附件：

imsg send-rich --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --text "reply text"
imsg send-rich --chat 'iMessage;-;+15551234567' --text 'hello world' \
  --format '[{"start":0,"length":5,"styles":["bold"]}]'
imsg send-rich --chat 'iMessage;-;+15551234567' --text "boom" --effect impact
imsg send-attachment --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --file /path/to/file.jpg

格式范围以 UTF-16 位置表示。支持的样式包括 bold、italic、underline 和 strikethrough；生成 JSON 时使用 --format-file。

群组场景

执行操作前先检查：

imsg group --chat-id 42 --json
imsg history --chat-id 42 --limit 20 --json | jq -s

向现有群组发送消息：

imsg send --chat-id 42 --text "Works for me"

在现有群组中通过桥接回复或发起投票：

imsg send-rich --chat 'iMessage;+;chat0000' \
  --reply-to <message-guid> --text "replying in thread"
imsg poll send --chat 'iMessage;+;chat0000' \
  --question "Dinner?" --option "Pizza" --option "Sushi"

仅在明确请求时创建或修改群组：

imsg chat-create --addresses '+15551111111,+15552222222' --name 'Crew' --text 'gm'
imsg chat-name --chat 'iMessage;+;chat0000' --name 'Renamed'
imsg chat-photo --chat 'iMessage;+;chat0000' --file /path/to/group.jpg
imsg chat-add-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-leave --chat 'iMessage;+;chat0000'
imsg chat-delete --chat 'iMessage;+;chat0000'
imsg chat-mark --chat 'iMessage;+;chat0000' --read

群组变更非常显眼。在更改群组成员、名称、照片、已读状态，或退出、删除群组之前，请确认目标群组和参与者列表。

轻点回应与回复

公开的 react 功能有限：它只能对聊天中最近收到的一条消息作出轻点回应。

imsg react --chat-id 42 --reaction like
imsg react --chat-id 42 --reaction love
imsg react --chat-id 42 --reaction dislike
imsg react --chat-id 42 --reaction laugh
imsg react --chat-id 42 --reaction emphasis
imsg react --chat-id 42 --reaction question

若要针对特定消息 GUID 作出轻点回应或移除轻点回应，请使用桥接 tapback：

imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love
imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love --remove

使用 send-rich --reply-to <message-guid> 发送线程回复。如果用户说“那条”或“上一条”，请确认所引用的消息。

投票

Apple Messages 原生投票需要桥接。创建时至少需要两个 --option 值。投票时必须提供 --option-id、--option-index 或 --option 中的一个。

Messages 只会呈现投票气泡中的选项，因此当前的 imsg poll send 会在投票之后尽力将 --question 作为普通说明文字回显。使用 --comment 可覆盖该说明文字。如果仅说明文字失败，请勿自动重试：投票可能已经送达。

imsg poll send --chat 'iMessage;-;+15551234567' \
  --question "Dinner?" --option "Pizza" --option "Sushi" --comment "Vote by 5pm"
imsg poll send --chat 'iMessage;+;chat0000' --reply-to <message-guid> \
  --question "Approve?" --option "Yes" --option "No"
imsg poll vote --chat 'iMessage;+;chat0000' \
  --poll <poll-message-guid> --option-id <option-id>

使用以下命令查找投票 ID 和选项：

imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null) | {guid, poll}'

history 和 watch 会利用无标题的传入原生投票所对应的纯文本说明行，回填该投票的 poll.question。投票记录行是 poll 事件，而不是轻点回应；无需 watch --reactions 即可看到这些事件。

监听与长时间运行的 Agent

若只需短时等待一次，请使用 watch：

imsg watch --chat-id 42 --since-rowid 9000 --json
imsg watch --chat-id 42 --attachments --convert-attachments --json
imsg watch --chat-id 42 --reactions --json
imsg watch --chat-id 42 --bb-events --json

--since-rowid 不包含指定行。不指定时，watch 从最新一行开始。watch 使用文件系统事件，并以低频轮询作为后备，因此错过 SQLite 辅助进程事件后也能补齐。即使不指定 --reactions，也会显示投票对象。

对于守护进程或多聊天集成，请使用 imsg rpc。它通过标准输入和标准输出使用 JSON-RPC 2.0。使用较新的桥接方法或投票方法前，先检查 imsg status --json 中的 rpc_methods。

安全规则

• 每次发送前都要确认收件人、聊天和内容，除非用户的请求中已包含准确值。
• 确认可见的状态变更：已读回执、输入状态、编辑、撤回、删除、投票表态、表情回应、群组成员资格、群名称／照片、退出或删除聊天。
• 未经批准，绝不向未知号码或联系人名称匹配不明确的对象发送消息。
• 确认附件存在且为所需文件。
• 优先使用 E.164 电话号码；仅在本地格式需要时使用 --region US 或其他地区代码。
• 对于仅适用于桥接的操作，使用桥接操作，但必须先确认可见的状态变更和破坏性操作。