iMessage（舊版：imsg）

警告： 新的 iMessage 部署請使用 BlueBubbles。

imsg 整合為舊版，可能在未來版本中移除。

狀態：舊版外部 CLI 整合。閘道啟動 imsg rpc 並透過 JSON-RPC over stdio 通訊（無獨立 daemon/連接埠）。

• BlueBubbles（建議） — 新安裝使用 iMessage 的首選方案。
• 配對 — iMessage DM 預設使用配對模式。
• 設定參考 — iMessage 完整欄位參考。

快速設定

Mac 本機（快速路徑）

  ### 步驟 1：安裝並驗證 imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### 步驟 2：設定 OpenClaw

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

  ### 步驟 3：啟動閘道

openclaw gateway

  ### 步驟 4：核准首次配對 DM（預設 dmPolicy）

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    配對請求在 1 小時後過期。

遠端 Mac（透過 SSH）

OpenClaw 只需要一個與 stdio 相容的 `cliPath`，因此你可以將 `cliPath` 指向一個透過 SSH 連接到遠端 Mac 並執行 `imsg` 的 wrapper 腳本。

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

啟用附件時的建議設定：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

如果未設定 `remoteHost`，OpenClaw 會嘗試透過分析 SSH wrapper 腳本來自動偵測。
`remoteHost` 應為 `host` 或 `user@host`（不含空格或 SSH 選項）。
OpenClaw 的 SCP 使用嚴格的主機金鑰驗證，因此 relay 主機的金鑰必須已存在於 `~/.ssh/known_hosts` 中。
附件路徑會依允許的根目錄進行驗證（`attachmentRoots` / `remoteAttachmentRoots`）。

需求與權限（macOS）

• 執行 imsg 的 Mac 上 Messages 必須已登入。
• 執行 OpenClaw/imsg 的處理程序上下文需要「完整磁碟存取」權限（存取 Messages 資料庫）。
• 透過 Messages.app 傳送訊息需要「自動化」權限。

提示： 權限是依處理程序上下文授予的。如果閘道以無頭方式（LaunchAgent/SSH）執行，請在該相同上下文中執行一次互動式指令以觸發權限提示：

imsg chats --limit 1
# 或
imsg send <handle> "test"

存取控制與路由

DM 政策

`channels.imessage.dmPolicy` 控制私訊：

- `pairing`（預設）
- `allowlist`
- `open`（需要 `allowFrom` 包含 `"*"`）
- `disabled`

允許名單欄位：`channels.imessage.allowFrom`。

允許名單項目可以是 handle 或聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。

群組政策 + 提及

`channels.imessage.groupPolicy` 控制群組處理：

- `allowlist`（設定時的預設值）
- `open`
- `disabled`

群組發送者允許名單：`channels.imessage.groupAllowFrom`。

執行時備用：如果未設定 `groupAllowFrom`，iMessage 的群組發送者檢查會在可用時回退到 `allowFrom`。
執行時注意：如果 `channels.imessage` 完全不存在，執行時會回退到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy`）。

群組的提及過濾：

- iMessage 沒有原生的提及中繼資料
- 提及偵測使用正規表示式模式（`agents.list[].groupChat.mentionPatterns`，備用 `messages.groupChat.mentionPatterns`）
- 未設定模式時，無法套用提及過濾

已授權發送者的控制指令可跳過群組中的提及過濾。

工作階段與確定性回覆

- DM 使用直接路由；群組使用群組路由。
- 在預設 `session.dmScope=main` 下，iMessage DM 會合併到代理的主工作階段。
- 群組工作階段是隔離的（`agent:<agentId>:imessage:group:<chat_id>`）。
- 回覆使用原始頻道/目標的中繼資料傳回 iMessage。

類似群組的討論串行為：

有些多參與者的 iMessage 討論串可能以 `is_group=false` 到達。
如果該 `chat_id` 明確設定在 `channels.imessage.groups` 中，OpenClaw 會將其視為群組流量（群組過濾 + 群組工作階段隔離）。

部署模式

使用專用的 Apple ID 和獨立的 macOS 使用者，讓機器人的流量與你的個人 Messages 設定檔隔離。

一般流程：

1. 建立/登入專用的 macOS 使用者。
2. 以機器人的 Apple ID 登入該使用者的 Messages。
3. 在該使用者中安裝 `imsg`。
4. 建立 SSH wrapper 讓 OpenClaw 在該使用者的上下文中執行 `imsg`。
5. 將 `channels.imessage.accounts.<id>.cliPath` 和 `.dbPath` 指向該使用者的設定檔。

首次執行可能需要在機器人使用者的工作階段中透過 GUI 核准（自動化 + 完整磁碟存取）。

常見拓撲：

- 閘道在 Linux/VM 上執行
- iMessage + `imsg` 在你 tailnet 上的 Mac 中執行
- `cliPath` wrapper 使用 SSH 執行 `imsg`
- `remoteHost` 允許透過 SCP 擷取附件

範例：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

使用 SSH 金鑰讓 SSH 和 SCP 都不需要互動式操作。
事先確認主機金鑰是受信任的（例如先執行 `ssh [email protected]`）以確保 `known_hosts` 已填充。

iMessage 支援在 `channels.imessage.accounts` 中的每帳戶設定。

每個帳戶可以覆寫 `cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、歷史記錄設定和允許的附件根目錄清單等欄位。

媒體、分段與送達目標

- 收到附件的擷取是選填的：`channels.imessage.includeAttachments`
- 遠端附件路徑可在設定 `remoteHost` 時透過 SCP 擷取
- 附件路徑必須符合允許的根目錄：
  - `channels.imessage.attachmentRoots`（本地）
  - `channels.imessage.remoteAttachmentRoots`（遠端 SCP 模式）
  - 預設根目錄：`/Users/*/Library/Messages/Attachments`
- SCP 使用嚴格的主機金鑰驗證（`StrictHostKeyChecking=yes`）
- 傳出媒體大小使用 `channels.imessage.mediaMaxMb`（預設 16 MB）

- 文字分段限制：`channels.imessage.textChunkLimit`（預設 4000）
- 分段模式：`channels.imessage.chunkMode`
  - `length`（預設）
  - `newline`（優先依段落分割）

建議使用明確目標：

- `chat_id:123`（建議用於穩定路由）
- `chat_guid:...`
- `chat_identifier:...`

也支援 handle 目標：

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

設定寫入

iMessage 預設允許頻道觸發的設定寫入（用於 commands.config: true 時的 /config set|unset）。

停用：

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

疑難排解

驗證二進位檔和 RPC 支援：

imsg rpc --help
openclaw channels status --probe

如果探測回報不支援 RPC，請更新 `imsg`。

檢查：

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- 配對核准狀態（`openclaw pairing list imessage`）

檢查：

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` 中的允許名單行為
- 提及模式設定（`agents.list[].groupChat.mentionPatterns`）

檢查：

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- 閘道主機的 SSH/SCP 金鑰驗證
- 主機金鑰存在於閘道主機的 `~/.ssh/known_hosts` 中
- 遠端路徑在執行 Messages 的 Mac 上的可讀性

在相同的使用者/工作階段上下文中，於互動式 GUI 終端機中重新執行並核准提示：

imsg chats --limit 1
imsg send <handle> "test"

確認執行 OpenClaw/`imsg` 的處理程序上下文已授予「完整磁碟存取」+「自動化」權限。

設定參考

• 設定參考 - iMessage
• 閘道設定
• 配對
• BlueBubbles