Skip to content
OpenClaw Docs

iMessage

iMessage (舊版：imsg)

Section titled “iMessage (舊版：imsg)”

狀態：舊版的外部 CLI 整合。閘道會產生 imsg rpc 並透過 stdio 上的 JSON-RPC 進行通訊（無需獨立的 daemon/port）。

BlueBubbles (recommended)

新設定的首選 iMessage 方案。

配對

iMessage 私訊預設為配對模式。

組態參考

完整的 iMessage 欄位參考。

快速設定

Section titled “快速設定”

  1. Install and verify imsg

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

  2. Configure OpenClaw

    {
      channels: {
        imessage: {
          enabled: true,
          cliPath: "/usr/local/bin/imsg",
          dbPath: "/Users/

    /Library/Messages/chat.db”, }, }, }

  3. Start gateway

    Terminal window
    openclaw gateway

  4. Approve first DM pairing (default dmPolicy)

    Terminal window
    openclaw pairing list imessage
    openclaw pairing approve imessage
            配對請求在 1 小時後過期。

需求和權限 (macOS)

Section titled “需求和權限 (macOS)”
  • 必須在執行 imsg 的 Mac 上登入訊息。
  • 執行 OpenClaw/imsg 的進程上下文需要「完全磁碟存取權限」（存取訊息資料庫）。
  • 透過 Messages.app 傳送訊息需要「自動化」權限。

存取控制與路由

Section titled “存取控制與路由”

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

  • pairing (預設)
  • allowlist
  • open (要求 allowFrom 包含 "*")
  • disabled

允許清單欄位：channels.imessage.allowFrom。

允許清單條目可以是 handles 或 chat targets (chat_id:*, chat_guid:*, chat_identifier:*)。

ACP 對話綁定

Section titled “ACP 對話綁定”

舊版 iMessage 聊天也可以綁定到 ACP 會話。

快速操作員流程：

  • 在私訊或允許的群組聊天中執行 /acp spawn codex --bind here。
  • 之後同一個 iMessage 對話中的訊息會路由到產生的 ACP 連線階段。
  • /new 和 /reset 會就地重置同一個已綁定的 ACP 連線階段。
  • /acp close 會關閉 ACP 連線階段並移除綁定。

透過頂層 bindings[] 項目並包含 type: "acp" 和 match.channel: "imessage"，可支援設定的持久綁定。

match.peer.id 可以使用：

`（建議用於穩定的群組綁定）

  • `chat_guid:

`

  • `chat_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 綁定行為。

部署模式

Section titled “部署模式”
專用機器人 macOS 使用者（獨立的 iMessage 身份）

使用專用的 Apple ID 和 macOS 使用者，以便將機器人流量與您的個人訊息設定檔隔離。

典型流程：

  1. 建立/登入專用的 macOS 使用者。
  2. 使用該使用者的機器人 Apple ID 登入訊息。
  3. 在該使用者中安裝 imsg。
  4. 建立 SSH 包裝器，以便 OpenClaw 可以在該使用者語境中執行 imsg。
  5. 將 `channels.imessage.accounts.

.cliPath和.dbPath` 指向該使用者設定檔。

首次執行可能需要在那個機器人使用者工作階段中進行 GUI 核准（Automation + 完全磁碟存取權）。
透過 Tailscale 連線的遠端 Mac (範例)
常見的拓樸：


- gateway 執行於 Linux/VM
- iMessage + `imsg` 執行於您 tailnet 中的 Mac
- `cliPath` 包裝器使用 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` 才會被填入。
Multi-account pattern

iMessage 支援在 channels.imessage.accounts 下進行帳戶特定設定。

每個帳戶都可以覆寫欄位，例如 cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、歷史記錄設定以及附件根目錄允許清單。

媒體、分塊與傳送目標

Section titled “媒體、分塊與傳送目標”
附件與媒體
  • 接收附件的擷取是選用的：channels.imessage.includeAttachments
  • 當設定 remoteHost 時，可以透過 SCP 取得遠端附件路徑
  • 附件路徑必須符合允許的根目錄：
    • channels.imessage.attachmentRoots (本地)
    • channels.imessage.remoteAttachmentRoots (遠端 SCP 模式)
    • 預設根目錄模式：/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...`
- `[email protected]`
Terminal window
imsg chats --limit 20

設定寫入

Section titled “設定寫入”

iMessage 預設允許通道發起的設定寫入（針對 /config set|unset 當 commands.config: true 時）。

停用：

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

疑難排解

Section titled “疑難排解”
imsg not found or RPC unsupported
驗證二進位檔案和 RPC 支援：
Terminal window
imsg rpc --help
openclaw channels status --probe
如果探測回報不支援 RPC，請更新 `imsg`。
DMs are ignored

檢查：

  • 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 上遠端路徑的可讀性
macOS 權限提示被錯過
在相同的使用者/工作階段內容中，於互動式 GUI 終端機內重新執行並批准提示：
Terminal window
imsg chats --limit 1
imsg send

“test”

    確認執行 OpenClaw/`imsg` 的程序內容已獲得完全磁碟存取權 + 自動化權限。

設定參考指引

Section titled “設定參考指引”

相關

Section titled “相關”