8.10 iMessage集成

通过外部 CLI 集成实现 OpenClaw 与 iMessage（macOS）的连接。网关通过 JSON-RPC over stdio 协议生成 imsg rpc 进程。

概述

状态：外部 CLI 集成

iMessage (imsg) 集成允许 OpenClaw 通过 macOS 上的 Messages 应用与 iMessage 联系人通信。该集成使用 imsg 命令行工具，通过 JSON-RPC over stdio 协议与网关通信。

快速设置

1. 在 macOS 上登录 Messages 应用
2. 通过 Homebrew 安装 imsg：

   brew install imsg

3. 配置 cliPath 和 dbPath
4. 授予完全磁盘访问权限和自动化权限

最小配置

使用扁平选项的最小配置：

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "~/Library/Messages/chat.db"
    }
  }
}

多账户设置

使用 accounts 配置多个账户：

{
  "channels": {
    "imessage": {
      "accounts": {
        "personal": {
          "cliPath": "/opt/homebrew/bin/imsg",
          "dbPath": "~/Library/Messages/chat.db"
        },
        "work": {
          "cliPath": "/usr/local/bin/imsg",
          "dbPath": "~/Work/Messages/chat.db"
        }
      }
    }
  }
}

远程/SSH 配置

支持通过 Tailscale 进行远程访问：

{
  "channels": {
    "imessage": {
      "enabled": true,
      "remote": true,
      "sshHost": "macbook.tailscale.net",
      "cliPath": "/opt/homebrew/bin/imsg"
    }
  }
}

访问控制

私信策略

私信默认使用 "pairing" 策略。未知发件人会收到配对码，在批准之前其消息会被忽略。

# 列出配对请求
openclaw pairing list imessage

# 批准配对
openclaw pairing approve imessage <code>

群组策略

群组支持以下策略：

• "open"：开放访问
• "allowlist"：仅允许列表中的用户
• "disabled"：禁用群组

{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["user1@example.com", "user2@example.com"]
    }
  }
}

群组级线程

具有 is_group=false 的群组级线程可以通过 channels.imessage.groups 手动隔离：

{
  "channels": {
    "imessage": {
      "groups": {
        "family-chat": {
          "chatId": "chat123456789",
          "policy": "open"
        }
      }
    }
  }
}

附件和媒体

• 附件需要设置 includeAttachments: true
• 媒体文件大小上限为 mediaMaxMb（默认 16 MB）

{
  "channels": {
    "imessage": {
      "includeAttachments": true,
      "mediaMaxMb": 20
    }
  }
}

消息分块

文本分块默认为 4000 字符，或使用 "newline" 模式：

{
  "channels": {
    "imessage": {
      "textChunkLimit": 4000,
      "chunkMode": "newline"
    }
  }
}

稳定寻址

优先使用 chat_id:123 进行稳定寻址。

macOS 权限要求

配置参考

提供者选项

• enabled：启用 iMessage 集成
• cliPath：imsg 可执行文件路径
• dbPath：Messages 数据库路径
• dmPolicy：私信策略（pairing/allowlist/open/disabled）
• groupPolicy：群组策略（allowlist/open/disabled）
• allowFrom：允许的用户列表
• groupAllowFrom：允许的群组用户列表
• includeAttachments：是否包含附件
• mediaMaxMb：媒体文件最大大小
• textChunkLimit：文本分块大小
• chunkMode：分块模式（chars/newline）

全局选项

• accounts：多账户配置对象
• remote：是否为远程连接
• sshHost：SSH 主机地址

故障排除

• 无法读取数据库：检查完全磁盘访问权限
• 无法发送消息：检查自动化权限和 Messages 应用状态
• 附件未显示：确保 includeAttachments: true 并检查文件大小限制
• 远程连接失败：验证 SSH 配置和 Tailscale 连接

常用命令

# 检查 iMessage 渠道状态
openclaw channels status

# 列出配对请求
openclaw pairing list imessage

# 批准配对
openclaw pairing approve imessage <code>

# 发送测试消息
openclaw message send --target "user@example.com" --message "Hello"

# 运行诊断
openclaw doctor