II. 频道系统 - 6. iMessage

📍 课程位置

阶段：II. 频道系统
课序：第 6 课
前置知识：II-5. Signal
后续阶段：III. 自动化系统

---

🎯 本课核心问题（你不懂我就这样教你）

iMessage 接入最常见的困惑：

1. iMessage 不是开放平台，怎么接到 OpenClaw？
2. BlueBubbles / imsg-cli / AppleScript 这些东西到底谁负责什么？
3. 为什么"能收不能发"或"发不了给某个联系人"？
4. 怎么保证只有你能跟我聊，别人不能乱来？

一句话：

iMessage 接入通常属于"工程集成"，不是官方 bot。需要一个"桥接层"（比如 BlueBubbles）把 iMessage 事件变成 OpenClaw 可接收的 webhook/事件。

---

🧠 心智模型：iMessage = “桥接层 + OpenClaw channel”

类比：

• iMessage 原生没有 bot API
• 我们需要一个"翻译官/桥"
  • 负责：监听 iMessage 消息
  • 转成：HTTP webhook 或本地事件
  • 给 OpenClaw Gateway

常见桥接方案：

• BlueBubbles：iMessage 的桥接服务（常见）
• AppleScript/osascript：macOS 上控制 Messages.app（常用于发送）

---

✅ 验收标准

• iMessage 消息能进入 OpenClaw（能收）
• OpenClaw 能通过桥接层回复 iMessage（能发）
• 访问控制：只有你能 DM（pairing/allowlist）
• 出问题知道排查顺序

---

🔧 方案 A：BlueBubbles（推荐的桥接方式）

1）BlueBubbles 的角色

• 运行一个本地/局域网服务（有端口）
• 接收 iMessage 事件
• 通过 webhook 推给 OpenClaw

你可以把它理解成：

BlueBubbles = “iMessage 的网关”，OpenClaw = “统一总网关”。

2）OpenClaw 配置（以 BlueBubbles 为例）

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://localhost:1234",
      password: "<your-password>",
      webhookPath: "/bluebubbles-webhook",

      dmPolicy: "pairing",
      groupPolicy: "open"
    }
  }
}

---

🔐 访问控制（安全第一）

因为 iMessage 是真实通讯渠道，一定要做访问控制：

• 推荐 dmPolicy: "pairing"（陌生人需要配对码）
• 或 dmPolicy: "allowlist"（只允许你自己的号码）

如果你的目标是"只给自己用"，allowlist 更直接。

---

⚠️ 最常见的问题：能收但不能发/不能标记已读

这类问题通常不是 OpenClaw 的 bug，而是桥接层能力没开。

以 BlueBubbles 为例，常见原因：

• Private API 未启用
• helper 未连接
• Messages.app 权限不足

表现：

• 能收到消息
• 但回消息/已读/输入中状态失败

排查顺序建议：

1. 重启 BlueBubbles
2. 检查 Private API 是否启用
3. 检查 helper 连接状态
4. 检查 OpenClaw gateway 日志

---

🧪 最小可用验证（MVP）

你要先跑通"收消息"：

1. 给自己 iMessage 发一句"hi"
2. 看 OpenClaw 是否收到

再跑通"发消息"：

1. 让 OpenClaw 回复一句
2. 如果失败，优先看桥接层错误

---

📝 学习心得

iMessage 这章我最大的体会是：

• 它不像 Telegram/Slack 那样"拿 token 就行"
• 更像"系统集成"：桥接层状态、权限、服务稳定性才是关键

因此正确策略是：

1. 先把桥接层当作一个独立服务维护好
2. OpenClaw 只负责"接收事件 + 生成回复"
3. 出问题先看桥接层，再看 OpenClaw

---

✅ 本课总结（记住 5 句话）

1. iMessage 没有官方 bot API，必须靠桥接层。
2. BlueBubbles 是常见桥接方案，OpenClaw 通过它收发。
3. 安全第一：dmPolicy 用 pairing/allowlist。
4. "能收不能发"优先怀疑 Private API/helper/权限。
5. 排障顺序：桥接层 → OpenClaw 日志 → 配置。

---

🔗 相关资源

• 官方文档：https://docs.openclaw.ai/channels/imessage
• 配置参考：https://docs.openclaw.ai/gateway/configuration-reference
• 下一阶段：III. 自动化系统（Hooks / Webhooks / Cron）