OpenClaw 对接 iMessage 教程（macOS）

2026-01-24 · 8 分钟频道对接

概述

OpenClaw 支持将 iMessage 作为对话频道，让你直接通过 iPhone 或 Mac 的信息应用与 AI 助手交流。本教程将详细介绍在 macOS 上完成 iMessage 频道对接的完整流程。

前置要求

macOS 系统且信息（Messages）应用已登录 Apple ID
Homebrew 已安装
OpenClaw Gateway 正在运行

安装 imsg 工具

iMessage 对接依赖 imsg 命令行工具：

# 通过 Homebrew 安装
brew install steipete/tap/imsg

安装完成后验证：

imsg --version

配置 iMessage 频道

在 OpenClaw 配置文件中添加 iMessage 频道：

// ~/.openclaw/openclaw.json
{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",  // imsg 安装路径
      "dbPath": "~/Library/Messages/chat.db", // 消息数据库路径
      "service": "auto"  // 服务类型
    }
  }
}

service 选项

值	说明
`imessage`	仅使用 iMessage（需要对方也有 Apple 设备）
`sms`	仅使用短信（通过 iPhone 转发）
`auto`	自动选择（优先 iMessage，回退到短信）

DM 配对策略

配置私聊消息的配对策略，决定谁可以与 AI 私聊：

{
  "channels": {
    "imessage": {
      "pairing": {
        "policy": "allowlist",
        "allowlist": [
          "+8613800138000",
          "user@icloud.com"
        ]
      }
    }
  }
}

配对策略可以是手机号或 Apple ID 邮箱。

群组处理

iMessage 群组聊天支持三种处理模式：

open 模式

所有群组消息都会被处理：

{
  "channels": {
    "imessage": {
      "groups": {
        "mode": "open"
      }
    }
  }
}

allowlist 模式

仅处理白名单中的群组：

{
  "channels": {
    "imessage": {
      "groups": {
        "mode": "allowlist",
        "allowlist": [
          "chat123456789"  // 群组 ID
        ]
      }
    }
  }
}

disabled 模式

完全忽略所有群组消息：

{
  "channels": {
    "imessage": {
      "groups": {
        "mode": "disabled"
      }
    }
  }
}

消息限制

iMessage 频道有以下技术限制需要注意：

限制项	值	说明
文本分割	4000 字符	超长回复会自动分段发送
媒体大小	16MB	附件不能超过此限制
群聊历史	有限制	群组消息的历史读取深度有限
DM 历史	有限制	私聊消息的历史读取深度有限

附件处理

iMessage 频道通过 SCP 协议检索附件文件：

{
  "channels": {
    "imessage": {
      "attachments": {
        "enabled": true,
        "maxSize": "16MB",
        "allowedTypes": ["image/*", "application/pdf"]
      }
    }
  }
}

接收到的图片和文件会通过 SCP 从 Messages 数据库中提取，然后传递给 AI 模型处理。

远程 Mac 方案

如果你的主力机器不是 Mac，可以使用远程 Mac 运行 iMessage 频道：

SSH Wrapper 配置

{
  "channels": {
    "imessage": {
      "remote": {
        "enabled": true,
        "host": "mac-mini.local",
        "user": "admin",
        "sshKey": "~/.ssh/id_ed25519"
      }
    }
  }
}

结合 Tailscale

使用 Tailscale 建立安全的远程连接：

{
  "channels": {
    "imessage": {
      "remote": {
        "enabled": true,
        "host": "mac-mini.tail-xxxxx.ts.net",
        "user": "admin"
      }
    }
  }
}

这样即使 Mac Mini 放在家里，也能从任何地方通过 Tailnet 连接。

完整配置示例

// ~/.openclaw/openclaw.json
{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "~/Library/Messages/chat.db",
      "service": "auto",
      "pairing": {
        "policy": "allowlist",
        "allowlist": ["+8613800138000"]
      },
      "groups": {
        "mode": "allowlist",
        "allowlist": ["chat123456789"]
      },
      "attachments": {
        "enabled": true,
        "maxSize": "16MB"
      }
    }
  }
}

macOS 权限设置

iMessage 对接需要授予 OpenClaw 以下系统权限：

完全磁盘访问权限：读取 chat.db 数据库
- 系统设置 → 隐私与安全性 → 完全磁盘访问权限
自动化权限：控制信息应用发送消息
- 首次运行时系统会弹出授权提示

故障排查

收不到 iMessage 消息？

确认信息应用已登录且能正常收发消息
检查 dbPath 路径是否正确
验证完全磁盘访问权限是否已授予

发送消息失败？

运行 imsg --version 确认工具已正确安装
检查 cliPath 配置是否指向正确路径
确认目标联系人在白名单中

远程 Mac 连接失败？

测试 SSH 连接：ssh user@host "echo ok"
确认远程 Mac 上的信息应用正在运行
检查 Tailscale 连接状态