OpenClaw iMessage (Legacy) 渠道
通过 macOS 上的 imsg CLI 工具将 OpenClaw 连接到 Apple iMessage。此旧版集成使用 JSON-RPC over stdio 接口，通过原生 macOS 信息数据库读取和发送 iMessage。注意：此渠道已弃用——对于新部署，我们强烈建议使用 BlueBubbles，它提供了更强大的基于 REST API 的集成方案，并支持更多功能。
iMessage (Legacy) 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
不支持
消息线程
不支持
语音消息
不支持
群聊
不支持
iMessage (Legacy) 前置条件
- 一台运行 macOS 的 Mac，且已在信息 app 中登录 Apple ID
- 为 OpenClaw 和 imsg 二进制文件授予"完全磁盘访问权限"
- 发送消息的自动化权限（通过 macOS TCC 弹窗授予）
- 通过 Homebrew 安装 imsg CLI：brew install steipete/tap/imsg
- OpenClaw Gateway 已安装并运行
iMessage (Legacy) 快速设置
安装 imsg CLI
运行 'brew install steipete/tap/imsg' 安装 iMessage CLI 工具。安装后，在 GUI 终端中运行一次 'imsg' 以触发 macOS 的权限授权弹窗（完全磁盘访问和自动化权限）。
授予 macOS 权限
打开系统设置 > 隐私与安全性。为 imsg 二进制文件和 OpenClaw 进程授予"完全磁盘访问权限"。信息 app 的自动化权限会在 imsg 首次尝试发送消息时自动弹出授权提示。
配置并启动
在 ~/.openclaw/openclaw.json 中添加 iMessage 渠道配置，设置 cliPath 和 dbPath。运行 'openclaw start' 启动 Gateway，然后发送一条测试 iMessage 来验证连接。
iMessage (Legacy) 配置示例
{
"channels": {
"imessage": {
"enabled": true,
"cliPath": "/opt/homebrew/bin/imsg",
"dbPath": "/Users/<username>/Library/Messages/chat.db"
}
}
}iMessage (Legacy) 深入了解
弃用说明
架构概述
私聊策略
{
"channels": {
"imessage": {
"dmPolicy": "pairing",
"allowFrom": ["+1234567890", "user@icloud.com"]
}
}
}群聊配置
{
"channels": {
"imessage": {
"groupPolicy": "allowlist",
"mentionPattern": "@bot"
}
}
}通过 SSH 远程 Mac 部署
{
"channels": {
"imessage": {
"remoteHost": "mac-server.local",
"cliPath": "/usr/local/bin/imsg"
}
}
}macOS 权限（TCC）
iMessage (Legacy) 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用 iMessage 渠道 |
| cliPath | string | "/usr/local/bin/imsg" | imsg CLI 二进制文件的路径。Homebrew 在 Apple Silicon Mac 上安装到 /opt/homebrew/bin/imsg，在 Intel Mac 上安装到 /usr/local/bin/imsg |
| dbPath | string | "~/Library/Messages/chat.db" | macOS 信息 SQLite 数据库的路径 |
| dmPolicy | string | "pairing" | 私聊访问策略：'pairing'、'allowlist'、'open' 或 'disabled' |
| groupPolicy | string | "disabled" | 群聊策略：'open'、'allowlist' 或 'disabled' |
| allowFrom | string[] | [] | 允许联系机器人的手机号或 Apple ID |
| includeAttachments | boolean | false | 是否处理传入消息中的媒体附件 |
| mediaMaxMb | number | 10 | 媒体附件的最大文件大小（MB） |
| textChunkLimit | number | 4000 | 每条发送消息的最大字符数 |
| chunkMode | string | "length" | 文本分割模式：'length'（按字符数）或 'newline'（按段落） |
| historyLimit | number | 20 | 作为对话上下文包含的最大历史消息数 |
| configWrites | boolean | true | 允许通过 iMessage 使用 /config set|unset 命令 |
| remoteHost | string | "" | 用于在远程 Mac 上运行 imsg 的 SSH 主机名 |
启用或禁用 iMessage 渠道
imsg CLI 二进制文件的路径。Homebrew 在 Apple Silicon Mac 上安装到 /opt/homebrew/bin/imsg，在 Intel Mac 上安装到 /usr/local/bin/imsg
macOS 信息 SQLite 数据库的路径
私聊访问策略：'pairing'、'allowlist'、'open' 或 'disabled'
群聊策略：'open'、'allowlist' 或 'disabled'
允许联系机器人的手机号或 Apple ID
是否处理传入消息中的媒体附件
媒体附件的最大文件大小（MB）
每条发送消息的最大字符数
文本分割模式：'length'（按字符数）或 'newline'（按段落）
作为对话上下文包含的最大历史消息数
允许通过 iMessage 使用 /config set|unset 命令
用于在远程 Mac 上运行 imsg 的 SSH 主机名
iMessage (Legacy) 常见问题
iMessage (Legacy) 故障排查
imsg 二进制文件或 OpenClaw 进程缺少 macOS 权限（完全磁盘访问或自动化）。
进程运行在无头环境中（SSH、launchd），macOS 无法显示 TCC 弹窗。
dbPath 配置不正确，或未授予完全磁盘访问权限。
未配置 SSH 密钥认证，或远程主机不可达。