跳转到内容
OpenClaw Docs

iMessage

iMessage（旧版：imsg）

Section titled “iMessage（旧版：imsg）”

状态：旧版外部 CLI 集成。Gateway(网关) 会生成 imsg rpc 并通过 stdio 上的 JSON-RPC 进行通信（无单独的守护进程/端口）。

BlueBubbles (recommended)

新设置的首选 iMessage 路径。

Pairing

iMessage 私信默认为配对模式。

Configuration reference

完整的 iMessage 字段参考。

快速设置

Section titled “快速设置”

  1. Install and verify imsg

    Terminal window
    brew install steipete/tap/imsg
    imsg rpc --help

  2. Configure OpenClaw

    {
      channels: {
        imessage: {
          enabled: true,
          cliPath: "/usr/local/bin/imsg",
          dbPath: "/Users/

    /Library/Messages/chat.db”, }, }, }

  3. Start gateway

    Terminal window
    openclaw gateway

  4. Approve first 私信 pairing (default dmPolicy)

    Terminal window
    openclaw pairing list imessage
    openclaw pairing approve imessage
            配对请求将在 1 小时后过期。

要求和权限（macOS）

Section titled “要求和权限（macOS）”
  • 必须在运行 imsg 的 Mac 上登录 Messages（信息）。
  • 运行 OpenClaw/imsg 的进程上下文需要“完全磁盘访问权限”（访问 Messages 数据库）。
  • 通过 Messages.app 发送消息需要“自动化”权限。

访问控制和路由

Section titled “访问控制和路由”

channels.imessage.dmPolicy 控制私信：

  • pairing（默认）
  • allowlist
  • open（要求 allowFrom 包含 "*"）
  • disabled

允许列表字段：channels.imessage.allowFrom。

允许列表条目可以是句柄或聊天目标（chat_id:*，chat_guid:*，chat_identifier:*）。

ACP 会话绑定

Section titled “ACP 会话绑定”

旧版 iMessage 聊天也可以绑定到 ACP 会话。

快速操作流程：

  • 在私信或允许的群组聊天中运行 /acp spawn codex --bind here。
  • 该同一 iMessage 对话中的未来消息将路由到生成的 ACP 会话。
  • /new 和 /reset 会就地重置同一个绑定的 ACP 会话。
  • /acp close 关闭 ACP 会话并移除绑定。

通过顶层的 bindings[] 条目支持配置的持久绑定，包含 type: "acp" 和 match.channel: "imessage"。

match.peer.id 可以使用：

`（推荐用于稳定的群组绑定）

  • `chat_guid:

`

  • `chat_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" },
    },
  ],
}

有关共享 ACP 绑定行为，请参阅 ACP Agents。

部署模式

Section titled “部署模式”
专用机器人 macOS 用户（独立的 iMessage 身份）

使用专用的 Apple ID 和 macOS 用户，以便将机器人流量与您的个人信息资料隔离。

典型流程：

  1. 创建/登录专用的 macOS 用户。
  2. 在该用户中使用机器人 Apple ID 登录信息。
  3. 在该用户中安装 imsg。
  4. 创建 SSH 包装器，以便 OpenClaw 可以在该用户上下文中运行 imsg。
  5. 将 `channels.imessage.accounts.

.cliPath和.dbPath` 指向该用户配置文件。

首次运行可能需要在机器人用户会话中进行 GUI 批准（Automation + Full Disk Access）。
通过 Tailscale 远程连接 Mac（示例）
常见拓扑结构：


- 网关运行在 Linux/VM 上
- iMessage + `imsg` 运行在您 tailnet 中的 Mac 上
- `cliPath` 包装器使用 SSH 运行 `imsg`
- `remoteHost` 启用 SCP 附件获取


示例：
{
  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 "$@"
使用 SSH 密钥，以便 SSH 和 SCP 都是非交互式的。
确保首先信任主机密钥（例如 `ssh [email protected]`），以便填充 `known_hosts`。
多账号模式

iMessage 支持在 channels.imessage.accounts 下进行针对每个账号的配置。

每个账号都可以覆盖诸如 cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、历史记录设置和附件根目录允许列表等字段。

媒体、分块和传递目标

Section titled “媒体、分块和传递目标”
附件和媒体
  • 接收附件摄取是可选的：channels.imessage.includeAttachments
  • 当设置 remoteHost 时，可以通过 SCP 获取远程附件路径
  • 附件路径必须匹配允许的根目录：
    • channels.imessage.attachmentRoots (本地)
    • channels.imessage.remoteAttachmentRoots (远程 SCP 模式)
    • 默认根目录模式：/Users/*/Library/Messages/Attachments
  • SCP 使用严格的主机密钥检查 (StrictHostKeyChecking=yes)
  • 发出媒体大小使用 channels.imessage.mediaMaxMb (默认 16 MB)
发出分块
  • 文本分块限制：channels.imessage.textChunkLimit (默认 4000) - 分块模式：channels.imessage.chunkMode - length (默认) - newline (段落优先分割)
地址格式
首选的显式目标：


- `chat_id:123` (推荐用于稳定路由)
- `chat_guid:...`
- `chat_identifier:...`


也支持 Handle 目标：


- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`
Terminal window
imsg chats --limit 20

配置写入

Section titled “配置写入”

iMessage 默认允许渠道发起的配置写入（针对 commands.config: true 时的 /config set|unset）。

禁用：

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

故障排除

Section titled “故障排除”
imsg not found or RPC unsupported
验证二进制文件和 RPC 支持：
Terminal window
imsg rpc --help
openclaw channels status --probe
如果探测报告不支持 RPC，请更新 `imsg`。
私信 are ignored

检查：

  • channels.imessage.dmPolicy
  • channels.imessage.allowFrom
  • 配对批准（openclaw pairing list imessage）
Group messages are ignored

检查：

  • channels.imessage.groupPolicy
  • channels.imessage.groupAllowFrom
  • channels.imessage.groups 允许列表行为
  • 提及模式配置（agents.list[].groupChat.mentionPatterns）
远程附件失败

检查：

  • channels.imessage.remoteHost
  • channels.imessage.remoteAttachmentRoots
  • 来自 Gateway(网关) 主机的 SSH/SCP 密钥认证
  • Gateway(网关) 主机的 ~/.ssh/known_hosts 中存在主机密钥
  • 运行 Messages 的 Mac 上的远程路径可读性
错过了 macOS 权限提示
在相同的用户/会话上下文中，以交互式 GUI 终端重新运行并批准提示：
Terminal window
imsg chats --limit 1
imsg send

“test”

    确认为运行 OpenClaw/`imsg` 的进程上下文授予了完全磁盘访问权限 + 自动化权限。

配置参考指针

Section titled “配置参考指针”

相关

Section titled “相关”