Skip to main content

​
iMessage (imsg)

iMessage 渠道通过外部 CLI 集成。Gateway 网关生成 imsg rpc（基于 stdio 的 JSON-RPC）。

​
快速设置

要求：
  • 已登录“信息”的 macOS
  • OpenClaw + imsg 的完全磁盘访问权限
  • 发送时需要自动化权限
1

安装 imsg

brew install steipete/tap/imsg
2

配置 OpenClaw

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

启动 Gateway 网关

openclaw gateway run
批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。

​
配置选项

​
基础配置

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

{
  "channels": {
    "imessage": {
      "dmPolicy": "pairing"
    }
  }
}
iMessage 支持 handle、邮箱、E.164 号码或 chat_id:*。
{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "*": { "requireMention": true },
        "42": {
          "requireMention": false,
          "skills": ["search"],
          "systemPrompt": "群组专用提示"
        }
      }
    }
  }
}

​
专用机器人 macOS 用户

如果你希望机器人从独立的 iMessage 身份发送（并保持你的个人“信息”整洁）：
1

创建专用 Apple ID

例如：[email protected]
Apple 可能需要电话号码进行验证 / 2FA。
2

创建 macOS 用户

例如：openclawhome
  1. 创建 macOS 用户并登录
  2. 在该用户中打开“信息”
  3. 使用机器人 Apple ID 登录 iMessage
3

启用远程登录

系统设置 → 通用 → 共享 → 远程登录
4

设置 SSH 包装器

创建包装器脚本（chmod +x）：
#!/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" "$@"
替换 <bot-macos-user> 为你的实际 macOS 用户名。
5

配置 OpenClaw

{
  "channels": {
    "imessage": {
      "enabled": true,
      "accounts": {
        "bot": {
          "name": "Bot",
          "enabled": true,
          "cliPath": "/path/to/imsg-bot",
          "dbPath": "/Users/<bot-macos-user>/Library/Messages/chat.db"
        }
      }
    }
  }
}
首次运行注意事项：发送/接收可能需要在机器人 macOS 用户中进行 GUI 批准。如果 imsg rpc 看起来卡住或退出，请登录该用户，运行一次 imsg chats --limit 1 / imsg send ...，批准提示，然后重试。

​
远程/SSH 变体

​
Tailscale 连接远程 Mac

如果 Gateway 网关运行在 Linux 主机/虚拟机上，但 iMessage 必须运行在 Mac 上，使用 Tailscale： 
┌──────────────────────────────┐          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"
    }
  }
}

​
SSH 包装器脚本

~/.openclaw/scripts/imsg-ssh： 
#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"
  • 确保 Mac 已登录“信息”，并已启用远程登录
  • 使用 SSH 密钥使 ssh [email protected] 无需提示即可工作
  • remoteHost 应与 SSH 目标匹配，以便 SCP 可以获取附件

​
寻址

优先使用 chat_id 进行稳定路由： 
# 推荐：chat_id
openclaw message send --channel imessage --target chat_id:123 --message "hello"

# chat_guid
openclaw message send --channel imessage --target chat_guid:... --message "hello"

# 直接 handle
openclaw message send --channel imessage --target imessage:+1555 --message "hello"
openclaw message send --channel imessage --target [email protected] --message "hello"

​
列出聊天

imsg chats --limit 20

​
类群组会话

某些 iMessage 会话可能有多个参与者，但仍以 is_group=false 到达。 如果你在 channels.imessage.groups 下显式配置了 chat_id，OpenClaw 会将该会话视为“群组”： 
{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15555550123"],
      "groups": {
        "42": { "requireMention": false }
      }
    }
  }
}
这将使用独立的 agent:<agentId>:imessage:group:<chat_id> 会话键。

​
媒体处理

​
附件

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

​
限制

{
  "channels": {
    "imessage": {
      "textChunkLimit": 4000,
      "mediaMaxMb": 16,
      "chunkMode": "length"  // length | newline
    }
  }
}

​
故障排除

原因： 缺少完全磁盘访问权限或自动化权限解决方案：
  1. 系统设置 → 隐私与安全 → 完全磁盘访问权限
  2. 添加 OpenClaw 和 imsg
  3. 系统设置 → 隐私与安全 → 自动化
  4. 添加 OpenClaw
原因： cliPath 不正确解决方案：
which imsg
使用输出路径更新 cliPath。
原因： 未设置 remoteHost解决方案：
{
  "channels": {
    "imessage": {
      "remoteHost": "user@gateway-host"
    }
  }
}
检查项：
  1. dmPolicy 正确配置
  2. 如果使用配对，批准发送者： 
    openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

​
多账户支持

运行多个 iMessage 账号： 
{
  "channels": {
    "imessage": {
      "accounts": {
        "personal": {
          "name": "个人",
          "cliPath": "/usr/local/bin/imsg",
          "dbPath": "/Users/me/Library/Messages/chat.db",
          "dmPolicy": "pairing"
        },
        "bot": {
          "name": "Bot",
          "cliPath": "/path/to/imsg-bot",
          "dbPath": "/Users/bot/Library/Messages/chat.db",
          "dmPolicy": "allowlist",
          "allowFrom": ["+15551234567"]
        }
      }
    }
  }
}

​
相关资源

配对系统

了解如何批准新用户

配置参考

完整的 iMessage 配置选项

故障排除

解决常见问题

BlueBubbles

更完整的 iMessage 集成