iMessage (imsg)

状态：外部 CLI 集成。Gateway 会启动 imsg rpc（基于 stdio 的 JSON-RPC）。

快速设置（新手向）

确保这台 Mac 上的”信息”app 已登录。
安装 imsg：
- brew install steipete/tap/imsg
配置 OpenClaw 的 channels.imessage.cliPath 和 channels.imessage.dbPath。
启动 Gateway 并批准 macOS 的权限提示（自动化 + 完全磁盘访问权限）。

最小配置：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<你的用户名>/Library/Messages/chat.db",
    },
  },
}

这是什么

基于 macOS 上的 imsg 实现的 iMessage Channel。
确定性路由：回复总是返回到 iMessage。
DM 共享 Agent 的主 Session；群组是隔离的（agent:<agentId>:imessage:group:<chat_id>）。
如果一个多人对话以 is_group=false 到达，你仍然可以通过 channels.imessage.groups 用 chat_id 隔离它（见下文”类群组对话”）。

配置写入

默认情况下，iMessage 允许通过 /config set|unset 触发配置更新（需要 commands.config: true）。

禁用方式：

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

系统要求

已登录”信息”app 的 macOS。
OpenClaw + imsg 需要完全磁盘访问权限（访问 Messages 数据库）。
发送消息时需要自动化权限。
channels.imessage.cliPath 可以指向任何代理 stdin/stdout 的命令（比如通过 SSH 连接到另一台 Mac 并运行 imsg rpc 的包装脚本）。

设置（快速路径）

确保这台 Mac 上的”信息”app 已登录。
配置 iMessage 并启动 Gateway。

专用机器人 macOS 用户（隔离身份）

如果你想让机器人从独立的 iMessage 身份发送消息（保持你的个人”信息”app 干净），可以使用专用的 Apple ID + 专用的 macOS 用户。

创建一个专用的 Apple ID（例如：[email protected]）。
- Apple 可能需要手机号进行验证 / 双重认证。
创建一个 macOS 用户（例如：openclawhome）并登录。
在该 macOS 用户中打开”信息”app，使用机器人 Apple ID 登录 iMessage。
启用远程登录（系统设置 → 通用 → 共享 → 远程登录）。
安装 imsg：
- brew install steipete/tap/imsg
设置 SSH，使 ssh <bot-macos-user>@localhost true 无需密码即可工作。
将 channels.imessage.accounts.bot.cliPath 指向一个 SSH 包装脚本，以机器人用户身份运行 imsg。

首次运行注意：发送/接收消息可能需要在 机器人 macOS 用户 中进行 GUI 权限批准（自动化 + 完全磁盘访问权限）。如果 imsg rpc 看起来卡住或退出，登录到该用户（屏幕共享很有用），运行一次性的 imsg chats --limit 1 / imsg send ...，批准提示，然后重试。

包装脚本示例（chmod +x）。将 <bot-macos-user> 替换为你实际的 macOS 用户名：

#!/usr/bin/env bash
set -euo pipefail

# 首先运行一次交互式 SSH 以接受主机密钥：
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

配置示例：

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

对于单账户设置，使用扁平选项（channels.imessage.cliPath、channels.imessage.dbPath）而不是 accounts 映射。

远程/SSH 变体（可选）

如果你想在另一台 Mac 上使用 iMessage，将 channels.imessage.cliPath 设置为一个包装脚本，通过 SSH 在远程 macOS 主机上运行 imsg。OpenClaw 只需要 stdio。

包装脚本示例：

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

远程附件： 当 cliPath 通过 SSH 指向远程主机时，Messages 数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 channels.imessage.remoteHost 自动通过 SCP 获取这些文件：

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH 包装脚本到远程 Mac
      remoteHost: "user@gateway-host", // 用于 SCP 文件传输
      includeAttachments: true,
    },
  },
}

如果未设置 remoteHost，OpenClaw 会尝试通过解析包装脚本中的 SSH 命令自动检测它。建议显式配置以提高可靠性。

通过 Tailscale 连接远程 Mac（示例）

如果 Gateway 运行在 Linux 主机/虚拟机上，但 iMessage 必须在 Mac 上运行，Tailscale 是最简单的桥接方式：Gateway 通过 tailnet 与 Mac 通信，通过 SSH 运行 imsg，并通过 SCP 传回附件。

架构：

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway 主机 (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - openclaw gateway           │          SCP (attachments)        │ - Messages signed in     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname or 100.x.y.z)
              ▼
        user@gateway-host

具体配置示例（Tailscale 主机名）：

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

包装脚本示例（~/.openclaw/scripts/imsg-ssh）：

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

注意事项：

确保 Mac 已登录”信息”app，并启用了远程登录。
使用 SSH 密钥，使 ssh [email protected] 无需提示即可工作。
remoteHost 应与 SSH 目标匹配，以便 SCP 可以获取附件。

多账户支持：使用 channels.imessage.accounts 进行每账户配置和可选的 name。参见 gateway/configuration 了解共享模式。不要提交 ~/.openclaw/openclaw.json（它通常包含 token）。

访问控制（DM + 群组）

DM：

默认：channels.imessage.dmPolicy = "pairing"。
未知发送者会收到 Pairing 码；消息在批准前会被忽略（码在 1 小时后过期）。
批准方式：
- openclaw pairing list imessage
- openclaw pairing approve imessage <CODE>
Pairing 是 iMessage DM 的默认 token 交换方式。详情：Pairing

群组：

channels.imessage.groupPolicy = open | allowlist | disabled。
channels.imessage.groupAllowFrom 控制当设置为 allowlist 时谁可以在群组中触发。
提及门控使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns），因为 iMessage 没有原生的提及元数据。
多 Agent 覆盖：在 agents.list[].groupChat.mentionPatterns 上设置每个 Agent 的模式。

工作原理（行为）

imsg 流式传输消息事件；Gateway 将它们规范化为共享的 Channel 信封。
回复总是路由回相同的 chat id 或 handle。

类群组对话（`is_group=false`）

某些 iMessage 对话可以有多个参与者，但仍然以 is_group=false 到达，这取决于”信息”app 如何存储聊天标识符。

如果你在 channels.imessage.groups 下显式配置了 chat_id，OpenClaw 会将该对话视为”群组”，用于：

Session 隔离（独立的 agent:<agentId>:imessage:group:<chat_id> Session 键）
群组白名单 / 提及门控行为

示例：

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

当你想为特定对话设置隔离的个性/模型时，这很有用（参见 Multi-agent routing）。对于文件系统隔离，参见 Sandboxing。

媒体 + 限制

通过 channels.imessage.includeAttachments 可选地摄取附件。
通过 channels.imessage.mediaMaxMb 限制媒体大小。

限制

出站文本会分块到 channels.imessage.textChunkLimit（默认 4000）。
可选的换行分块：设置 channels.imessage.chunkMode="newline" 以在长度分块之前按空行（段落边界）拆分。
媒体上传受 channels.imessage.mediaMaxMb（默认 16）限制。

寻址 / 投递目标

优先使用 chat_id 以实现稳定路由：

chat_id:123（推荐）
chat_guid:...
chat_identifier:...
直接 handle：imessage:+1555 / sms:+1555 / [email protected]

列出聊天：

imsg chats --limit 20

配置参考（iMessage）

完整配置：Configuration

Provider 选项：

channels.imessage.enabled：启用/禁用 Channel 启动。
channels.imessage.cliPath：imsg 的路径。
channels.imessage.dbPath：Messages 数据库路径。
channels.imessage.remoteHost：当 cliPath 指向远程 Mac 时，用于 SCP 附件传输的 SSH 主机（例如 user@gateway-host）。如果未设置，会从 SSH 包装脚本自动检测。
channels.imessage.service：imessage | sms | auto。
channels.imessage.region：短信区域。
channels.imessage.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
channels.imessage.allowFrom：DM 白名单（handle、邮箱、E.164 号码或 chat_id:*）。open 需要 "*"。iMessage 没有用户名；使用 handle 或聊天目标。
channels.imessage.groupPolicy：open | allowlist | disabled（默认：allowlist）。
channels.imessage.groupAllowFrom：群组发送者白名单。
channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit：作为上下文包含的最大群组消息数（0 禁用）。
channels.imessage.dmHistoryLimit：DM 历史记录限制（用户轮次）。每用户覆盖：channels.imessage.dms["<handle>"].historyLimit。
channels.imessage.groups：每群组默认值 + 白名单（使用 "*" 作为全局默认值）。
channels.imessage.includeAttachments：将附件摄取到上下文中。
channels.imessage.mediaMaxMb：入站/出站媒体上限（MB）。
channels.imessage.textChunkLimit：出站分块大小（字符）。
channels.imessage.chunkMode：length（默认）或 newline，在长度分块之前按空行（段落边界）拆分。