Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

快速设置

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/user/Library/Messages/chat.db",
    },
  },
}

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

要求和权限（macOS）

• 运行 imsg 的 Mac 必须已登录 Messages。
• 运行 OpenClaw/imsg 的进程上下文需要完整磁盘访问权限（Messages 数据库访问）。
• 通过 Messages.app 发送消息需要自动化权限。
• 对于高级操作（回应 / 编辑 / 撤回发送 / 线程回复 / 效果 / 群组操作），必须禁用系统完整性保护 — 见下方启用 imsg 私有 API。基础文本和媒体发送/接收不需要它也能工作。

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

​

启用 imsg 私有 API

• 基础模式（默认，无需更改 SIP）：通过 send 发送出站文本和媒体、入站 watch/history、聊天列表。这就是全新 brew install steipete/tap/imsg 加上上方标准 macOS 权限后即可获得的能力。
• 私有 API 模式：imsg 将辅助 dylib 注入 Messages.app，以调用内部 IMCore 函数。这会解锁 react、edit、unsend、reply（线程式）、sendWithEffect、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及输入状态指示和已读回执。

read、typing、launch、由桥接支持的富发送、消息变更和聊天管理等高级功能是选择启用的。它们要求禁用 SIP，并将辅助 dylib 注入 Messages.app。当 SIP 启用时，imsg launch 会拒绝注入。

​

设置

1. 在运行 Messages.app 的 Mac 上安装（或升级）imsg：
   brew install steipete/tap/imsg
   imsg --version
   imsg status --on
   
   imsg status --on 输出会报告 bridge_version、rpc_methods 和每个方法的 selectors，因此你可以在开始前查看当前构建支持什么。
2. 禁用系统完整性保护。 这与 macOS 版本相关，因为底层 Apple 要求取决于操作系统和硬件：
   • macOS 10.13–10.15（Sierra–Catalina）： 通过 Terminal 禁用 Library Validation，重启到恢复模式，运行 csrutil disable，再重启。
   • macOS 11+（Big Sur 及更高版本），Intel： 恢复模式（或互联网恢复），csrutil disable，重启。
   • macOS 11+，Apple Silicon： 通过电源按钮启动序列进入恢复；在较新的 macOS 版本中，点击 Continue 时按住 Left Shift 键，然后运行 csrutil disable。虚拟机设置遵循单独流程 — 先创建 VM 快照。
   • macOS 26 / Tahoe： library-validation 策略和 imagent 私有授权检查进一步收紧；imsg 可能需要更新构建才能跟上。如果在 macOS 主版本升级后，imsg launch 注入或特定 selectors 开始返回 false，请先检查 imsg 的发布说明，再假设 SIP 步骤已成功。
   在运行 imsg launch 前，请按照 Apple 针对你的 Mac 的恢复模式流程禁用 SIP。
3. 注入辅助程序。 在 SIP 已禁用且 Messages.app 已登录的情况下：
   imsg launch
   
   当 SIP 仍启用时，imsg launch 会拒绝注入，因此这也可用来确认第 2 步已生效。
4. 从 OpenClaw 验证桥接：
   openclaw channels status --probe
   
   iMessage 条目应报告 works，且 imsg status --on | jq '.selectors' 应显示 retractMessagePart: true，以及你的 macOS 构建暴露的任意编辑 / 输入 / 已读 selectors。actions.ts 中的 OpenClaw 插件按方法门控只会公布底层 selector 为 true 的操作，因此你在智能体工具列表中看到的操作面反映了此主机上的桥接实际能做什么。

​

当你无法禁用 SIP 时

• imsg 会回退到基础模式 — 仅支持文本 + 媒体 + 接收。
• OpenClaw 插件仍会公布文本/媒体发送和入站监控；它只是会从操作面隐藏 react、edit、unsend、reply、sendWithEffect 和群组操作（根据按方法能力门控）。
• 你可以为 iMessage 工作负载运行一台单独的非 Apple-Silicon Mac（或专用机器人 Mac）并关闭 SIP，同时在你的主要设备上保持 SIP 启用。见下方专用机器人 macOS 用户（单独的 iMessage 身份）。

​

访问控制和路由

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Use British spelling." },
        "8421": {
          requireMention: true,
          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
        },
        "9907": {
          // explicit suppression: the wildcard "Use British spelling." does not apply here
          systemPrompt: "",
        },
      },
    },
  },
}

​

ACP 会话绑定

• 在私信或允许的群聊中运行 /acp spawn codex --bind here。
• 同一 iMessage 对话中的后续消息会路由到已生成的 ACP 会话。
• /new 和 /reset 会在原位重置同一个已绑定 ACP 会话。
• /acp close 会关闭 ACP 会话并移除绑定。

• 规范化的私信句柄，例如 +15555550123 或 [email protected]
• chat_id:<id>（推荐用于稳定的群组绑定）
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

​

部署模式

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

​

媒体、分块和投递目标

imsg chats --limit 20

​

私有 API 操作

{
  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,
      },
    },
  },
}

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

​

配置写入

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​

合并拆分发送的私信（同一次输入中的命令 + URL）

1. 一条文本消息（"Dump"）。
2. 一个 URL 预览气泡（"https://..."），并带有 OG 预览图片作为附件。

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

场景以及智能体看到的内容

​

Gateway 网关停机后的追赶

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

运行方式

​

游标和重试语义

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• 每次成功分发后，游标都会前进；当某行的分发抛出异常时，游标会保持不变，下一次启动会从保持的游标重试同一行。
• 当同一个 guid 连续抛出异常达到 maxFailureRetries 次后，追赶会记录一条 warn，并强制将游标推进到卡住的消息之后，确保后续启动可以继续前进。
• 已经放弃的 guid 在后续运行中一看到就跳过（不会尝试分发），并计入运行摘要中的 skippedGivenUp。

​

操作者可见信号

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chatscapped to perRunLimit=<Y>

​

何时保持关闭

• Gateway 网关持续运行，并有看门狗自动重启，间隔始终小于几秒，此时默认关闭即可。
• 私信量很低，错过消息也不会改变智能体行为；firstRunLookbackMinutes 初始窗口可能会在首次启用时分发令人意外的旧上下文。

​

故障排除

imsg rpc --help
imsg status --on
openclaw channels status --probe

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

openclaw channels status --probe --channel imessage

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

​

配置参考指针

• Configuration reference - iMessage
• Gateway 网关配置
• 配对

​

相关

• 渠道概览 — 所有支持的渠道
• BlueBubbles removal and the imsg iMessage path — 公告和迁移摘要
• Coming from BlueBubbles — 配置转换表和逐步切换流程
• 配对 — 私信认证和配对流程
• 群组 — 群组聊天行为和提及门控
• 频道路由 — 消息的会话路由
• 安全性 — 访问模型和加固