iMessage

若要進行新的 iMessage 部署，請使用 BlueBubbles。imsg 整合屬於舊版功能，可能會在未來版本中移除。

狀態：舊版外部 CLI 整合。Gateway 會啟動 imsg rpc，並透過 stdio 上的 JSON-RPC 通訊（沒有獨立的守護程式/連接埠）。

BlueBubbles (recommended)

新設定建議使用的 iMessage 路徑。

Pairing

iMessage 私訊預設使用配對模式。

Configuration reference

完整的 iMessage 欄位參考。

快速設定

Local Mac (fast path)
Remote Mac over SSH

Install and verify imsg

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

Configure OpenClaw

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

Start gateway

openclaw gateway

Approve first DM pairing (default dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

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

#!/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 script 自動偵測。 remoteHost 必須是 host 或 user@host（不可有空格或 SSH 選項）。 OpenClaw 對 SCP 使用嚴格的主機金鑰檢查，因此轉送主機金鑰必須已存在於 ~/.ssh/known_hosts。附件路徑會根據允許的根目錄（attachmentRoots / remoteAttachmentRoots）進行驗證。

需求與權限（macOS）

Messages 必須已在執行 imsg 的 Mac 上登入。
執行 OpenClaw/imsg 的程序環境需要完整磁碟存取權（Messages 資料庫存取）。
需要自動化權限，才能透過 Messages.app 傳送訊息。

權限是依程序環境授予。如果 gateway 以無頭模式執行（LaunchAgent/SSH），請在同一環境中執行一次互動式命令以觸發提示：

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

存取控制與路由

DM policy
Group policy + mentions
Sessions and deterministic replies

channels.imessage.dmPolicy 控制直接訊息：

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

Allowlist 欄位：channels.imessage.allowFrom。Allowlist 項目可以是 handle 或聊天目標（chat_id:*、chat_guid:*、chat_identifier:*）。

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

allowlist（已設定時的預設值）
open
disabled

群組傳送者 allowlist：channels.imessage.groupAllowFrom。執行階段後援：如果未設定 groupAllowFrom，iMessage 群組傳送者檢查會在可用時退回使用 allowFrom。執行階段注意事項：如果完全缺少 channels.imessage，執行階段會退回到 groupPolicy="allowlist" 並記錄警告（即使已設定 channels.defaults.groupPolicy）。群組的提及 gating：

iMessage 沒有原生提及 metadata
提及偵測使用 regex patterns（agents.list[].groupChat.mentionPatterns，後援為 messages.groupChat.mentionPatterns）
未設定 patterns 時，無法強制執行提及 gating

來自授權傳送者的控制命令可以在群組中略過提及 gating。

私訊使用直接路由；群組使用群組路由。
使用預設 session.dmScope=main 時，iMessage 私訊會收斂到 agent main session。
群組 session 會隔離（agent:<agentId>:imessage:group:<chat_id>）。
回覆會使用來源 channel/target metadata 路由回 iMessage。

類群組 thread 行為：某些多參與者 iMessage threads 可能會以 is_group=false 抵達。如果該 chat_id 明確設定於 channels.imessage.groups 下，OpenClaw 會將其視為群組流量（群組 gating + 群組 session 隔離）。

ACP 對話繫結

舊版 iMessage 聊天也可以繫結到 ACP sessions。快速操作流程：

在私訊或允許的群組聊天內執行 /acp spawn codex --bind here。
之後同一個 iMessage 對話中的訊息會路由到產生的 ACP session。
/new 和 /reset 會就地重設同一個已繫結的 ACP session。
/acp close 會關閉 ACP session 並移除繫結。

已設定的持久繫結可透過最上層 bindings[] 項目支援，其中 type: "acp" 且 match.channel: "imessage"。 match.peer.id 可以使用：

標準化的私訊 handle，例如 +15555550123 或 user@example.com
chat_id:<id>（建議用於穩定的群組繫結）
chat_guid:<guid>
chat_identifier:<identifier>

範例：

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

請參閱 ACP Agents 了解共用的 ACP 繫結行為。

部署模式

Dedicated bot macOS user (separate iMessage identity)

使用專用 Apple ID 和 macOS 使用者，讓 bot 流量與你的個人 Messages profile 隔離。典型流程：

建立/登入專用 macOS 使用者。
在該使用者中使用 bot Apple ID 登入 Messages。
在該使用者中安裝 imsg。
建立 SSH wrapper，讓 OpenClaw 可以在該使用者環境中執行 imsg。
將 channels.imessage.accounts.<id>.cliPath 和 .dbPath 指向該使用者 profile。

第一次執行可能需要在該 bot 使用者 session 中進行 GUI 核准（自動化 + 完整磁碟存取）。

Remote Mac over Tailscale (example)

常見拓撲：

gateway 在 Linux/VM 上執行
iMessage + imsg 在你 tailnet 中的一台 Mac 上執行
cliPath wrapper 使用 SSH 執行 imsg
remoteHost 啟用 SCP 附件擷取

範例：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

使用 SSH 金鑰，讓 SSH 和 SCP 都能非互動執行。請先確保主機金鑰已受信任（例如 ssh bot@mac-mini.tailnet-1234.ts.net），讓 known_hosts 已填入。

Multi-account pattern

iMessage 支援 channels.imessage.accounts 下的逐帳號設定。每個帳號都可以覆寫 cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、history settings，以及附件根目錄 allowlists 等欄位。

媒體、分塊與遞送目標

Attachments and media

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

Outbound chunking

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

Addressing formats

建議的明確目標：

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

也支援 handle 目標：

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

設定寫入

iMessage 預設允許 channel 發起的設定寫入（適用於 commands.config: true 時的 /config set|unset）。停用：

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

疑難排解

imsg not found or RPC unsupported

驗證 binary 與 RPC 支援：

imsg rpc --help
openclaw channels status --probe

如果 probe 回報 RPC 不受支援，請更新 imsg。

DMs are ignored

檢查：

channels.imessage.dmPolicy
channels.imessage.allowFrom
配對核准（openclaw pairing list imessage）

Group messages are ignored

檢查：

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
channels.imessage.groups allowlist 行為
提及 pattern 設定（agents.list[].groupChat.mentionPatterns）

Remote attachments fail

檢查：

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
來自 gateway host 的 SSH/SCP 金鑰驗證
gateway host 上的 ~/.ssh/known_hosts 中存在主機金鑰
執行 Messages 的 Mac 上的遠端路徑可讀性

macOS permission prompts were missed

在同一使用者/session 環境中的互動式 GUI terminal 重新執行並核准提示：

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

確認完整磁碟存取 + 自動化已授予執行 OpenClaw/imsg 的程序環境。

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

BlueBubbles (recommended)

Pairing

Configuration reference

快速設定

需求與權限（macOS）

存取控制與路由

ACP 對話繫結

部署模式

媒體、分塊與遞送目標

設定寫入

疑難排解

設定參考指標

相關

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Documentation Index

BlueBubbles (recommended)

Pairing

Configuration reference

​快速設定

​需求與權限（macOS）

​存取控制與路由

​ACP 對話繫結

​部署模式

​媒體、分塊與遞送目標

​設定寫入

​疑難排解

​設定參考指標

​相關

快速設定

需求與權限（macOS）

存取控制與路由

ACP 對話繫結

部署模式

媒體、分塊與遞送目標

設定寫入

疑難排解

設定參考指標

相關