iMessage

​

快速设置（新手）

1. 确保在此 Mac 上已登录”信息”。
2. 安装 imsg：
   • brew install steipete/tap/imsg
3. 配置 OpenClaw 的 channels.imessage.cliPath 和 channels.imessage.dbPath。
4. 启动 Gateway 网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。

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

​

简介

• 基于 macOS 上 imsg 的 iMessage 渠道。
• 确定性路由：回复始终返回到 iMessage。
• 私信共享智能体的主会话；群组是隔离的（agent:<agentId>:imessage:group:<chat_id>）。
• 如果多参与者会话以 is_group=false 到达，你仍可使用 channels.imessage.groups 按 chat_id 隔离（参见下方”类群组会话”）。

​

配置写入

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

​

要求

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

​

设置（快速路径）

1. 确保在此 Mac 上已登录”信息”。
2. 配置 iMessage 并启动 Gateway 网关。

​

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

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

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

# Run an interactive SSH once first to accept host keys:
#   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",
        },
      },
    },
  },
}

​

远程/SSH 变体（可选）

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

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

​

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

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway host (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

{
  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 "$@"

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

​

访问控制（私信 + 群组）

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

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

​

工作原理（行为）

• imsg 流式传输消息事件；Gateway 网关将它们规范化为共享渠道信封。
• 回复始终路由回相同的 chat id 或 handle。

​

类群组会话（is_group=false）

• 会话隔离（独立的 agent:<agentId>:imessage:group:<chat_id> 会话键）
• 群组允许列表 / 提及检测行为

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

​

媒体 + 限制

• 通过 channels.imessage.includeAttachments 可选附件摄取。
• 通过 channels.imessage.mediaMaxMb 设置媒体上限。

​

限制

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

​

寻址 / 投递目标

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

imsg chats --limit 20

​

配置参考（iMessage）

• channels.imessage.enabled：启用/禁用渠道启动。
• channels.imessage.cliPath：imsg 路径。
• channels.imessage.dbPath：“信息”数据库路径。
• 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：私信允许列表（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：私信历史限制（用户轮次）。每用户覆盖：channels.imessage.dms["<handle>"].historyLimit。
• channels.imessage.groups：每群组默认值 + 允许列表（使用 "*" 作为全局默认值）。
• channels.imessage.includeAttachments：将附件摄取到上下文。
• channels.imessage.mediaMaxMb：入站/出站媒体上限（MB）。
• channels.imessage.textChunkLimit：出站分块大小（字符）。
• channels.imessage.chunkMode：length（默认）或 newline 在长度分块前按空行（段落边界）分割。

• agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
• messages.responsePrefix。