iMessage (imsg) 整合指南

想要自動化 iMessage 總是很頭痛。iMessage 的封閉生態系讓開發者很難直接透過 API 串接，通常得繞一大圈才能讓訊息進出。如果你正在尋找一種直接與 macOS 系統通訊的方式，而不是透過複雜的第三方服務，這篇指南會帶你走過最直接的配置路徑。

需要準備的東西

在開始之前，請確保你具備以下條件：

一台運行 macOS 的電腦，且已登入 Messages
已安裝 imsg CLI 工具
具備 Full Disk Access（完全磁碟存取權限）以讀取訊息資料庫
具備 Automation（自動化）權限以透過 Messages.app 發送訊息

快速開始

這裡是 5 分鐘內完成本地 Mac 配置的最快路徑：

1. 安裝並驗證 imsg

在你的 Mac 終端機執行：

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. 啟動 Gateway

openclaw gateway

4. 核准第一個 DM 配對

iMessage 的私訊預設使用配對模式，核准請求會在 1 小時後過期：

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

遠端部署與權限處理

如果你想在 Linux 或 VM 上執行 OpenClaw，但透過 SSH 控制遠端的 Mac，可以建立一個 wrapper script：

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

然後在配置中指定 remoteHost 以支援附件抓取：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host",
      includeAttachments: true,
    },
  },
}

處理 macOS 權限提示

權限是根據進程上下文授予的。如果你的 Gateway 以 headless 模式（例如 LaunchAgent 或 SSH）執行，請在同一個上下文執行一次互動式指令來觸發權限彈窗：

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

存取控制與路由

私訊 (DM) 政策

你可以透過 channels.imessage.dmPolicy 控制誰可以傳訊息給你：

pairing (預設)
allowlist (搭配 allowFrom 使用)
open (需要將 allowFrom 設為 ["*"])
disabled

群組政策與提及 (Mentions)

iMessage 本身沒有原生「提及」元數據。OpenClaw 使用正規表達式 (regex) 來偵測：

偵測模式：agents.list[].groupChat.mentionPatterns
如果沒有配置模式，則無法強制執行提及過濾。
來自授權發送者的控制指令可以繞過群組中的提及過濾。

媒體與訊息傳遞

附件：預設不抓取，需開啟 channels.imessage.includeAttachments。
訊息分段：如果文字太長，會根據 textChunkLimit (預設 4000) 進行切分。你可以選擇 length 模式或 newline (段落優先) 模式。
目標格式：建議使用 chat_id:123 以獲得穩定的路由，但也支援 imessage:+1555... 或 Email 格式。

疑難排解

imsg 找不到或不支援 RPC

驗證 binary 與 RPC 支援：

imsg rpc --help
openclaw channels status --probe

如果 probe 顯示不支援 RPC，請更新 imsg。

私訊 (DM) 被忽略

請檢查：

channels.imessage.dmPolicy 的設定
channels.imessage.allowFrom 名單
配對核准狀態 (openclaw pairing list imessage)

遠端附件抓取失敗

請檢查：

channels.imessage.remoteHost 是否正確
Gateway 主機到 Mac 的 SSH/SCP 金鑰驗證是否已設定為非互動式
Mac 上的訊息路徑是否具備讀取權限

錯過了 macOS 權限彈窗

在同一個使用者階段 (session) 的 GUI 終端機重新執行指令：

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

確保已手動在「系統設定」中授予 Full Disk Access 與 Automation 權限。

如果你在配置過程中遇到任何問題，可以詢問 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。