iMessage

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

一般流程：

1. 建立／登入專用的 macOS 使用者。
2. 在該使用者中，使用機器人的 Apple ID 登入「訊息」。
3. 在該使用者中安裝 imsg。
4. 建立 SSH 包裝程式，讓 OpenClaw 能在該使用者的環境中執行 imsg。
5. 將 channels.imessage.accounts.<id>.cliPath 和 .dbPath 指向該使用者設定檔。

第一次執行時，可能需要在該機器人使用者工作階段的圖形介面中核准權限（自動化 + 完整磁碟存取權）。

常見拓撲：

• 閘道在 Linux／VM 上執行
• iMessage + imsg 在你 tailnet 中的 Mac 上執行
• cliPath 包裝程式使用 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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

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

iMessage 支援在 channels.imessage.accounts 下設定各帳號。

每個帳號都能覆寫 cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、歷史記錄設定和附件根目錄允許清單等欄位。

設定 channels.imessage.dmHistoryLimit，以使用該對話最近解碼的 imsg 歷史記錄，作為新私人訊息工作階段的初始內容。使用 channels.imessage.dms["<sender>"].historyLimit 設定各傳送者的覆寫值，包括使用 0 停用某位傳送者的歷史記錄。

iMessage 私人訊息歷史記錄會視需要從 imsg 擷取。若未設定 dmHistoryLimit，將停用全域私人訊息歷史記錄的初始填入；但若某位傳送者的 channels.imessage.dms["<sender>"].historyLimit 為正值，仍會為該傳送者啟用初始填入。

• 傳入附件的擷取功能預設為關閉 — 設定 channels.imessage.includeAttachments: true，將照片、語音備忘錄、影片和其他附件轉送給代理程式。停用時，僅含附件的 iMessage 會在送達代理程式前遭到捨棄，並且可能完全不會產生 Inbound message 記錄行。
• 設定 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.streaming.chunkMode
  • length（預設）
  • newline（優先依段落分割）
• 傳出 Markdown 的粗體／斜體／底線／刪除線會轉換成原生樣式文字（macOS 15+ 的收件者會顯示樣式；較舊版本的收件者會看到不含標記的純文字）；Markdown 表格會依照頻道的 Markdown 表格模式轉換
• channels.imessage.sendTransport（auto 為預設值，另有 bridge、applescript）選擇 imsg 傳送訊息的方式

建議使用明確目標：

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

也支援帳號代稱目標：

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

imsg chats --limit 20

• react：新增／移除 iMessage 點按回應（messageId、emoji、remove）。支援的點按回應對應愛心、讚、倒讚、大笑、強調和疑問。不指定表情符號即執行移除時，會清除目前設定的任何點按回應。
• reply：對現有訊息傳送討論串回覆（messageId、text 或 message，以及 chatGuid、chatId、chatIdentifier 或 to）。回覆並附加附件還需要使用其 send-rich 支援 --file 的 imsg 組建版本。
• sendWithEffect：使用 iMessage 特效傳送文字（text 或 message、effect 或 effectId）。短名稱：slam、loud、gentle、invisibleink、confetti、lasers、fireworks、balloon、heart、echo、happybirthday、shootingstar、sparkles、spotlight。
• edit：在支援的 macOS／私有 API 版本上編輯已傳送的訊息（messageId、text 或 newText）。只能編輯由閘道本身傳送的訊息。
• unsend：在支援的 macOS／私有 API 版本上收回已傳送的訊息（messageId）。只能收回由閘道本身傳送的訊息。
• upload-file：傳送媒體／檔案（buffer 使用 base64，或已載入的 media/path/filePath、filename，以及選用的 asVoice）。舊版別名：sendAttachment。
• renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup：目前目標為群組對話時管理群組聊天。這些動作會變更主機的「訊息」身分，因此需要擁有者傳送者或 operator.admin 閘道用戶端。
• poll：建立原生 Apple「訊息」投票（pollQuestion、重複 2 至 12 次的 pollOption，以及 chatGuid、chatId、chatIdentifier 或 to）。使用 iOS/iPadOS/macOS 26+ 的收件者可直接查看並投票；較舊的作業系統版本會收到「Sent a poll」文字備援訊息。需要 selectors.pollPayloadMessage。
• poll-vote：對現有投票進行投票（pollId 或 messageId，以及 pollOptionIndex、pollOptionId 或 pollOptionText 中恰好一項）。需要 selectors.pollVoteMessage 和 poll.vote RPC 方法。

已接受的傳入投票會呈現給代理程式，其中包含問題、編號的選項標籤、票數，以及 poll-vote 所需的投票訊息 ID。

傳入的 iMessage 環境資訊會同時包含簡短的 MessageSid 值，以及可用時的完整訊息 GUID（MessageSidFull）。簡短 ID 的有效範圍僅限近期以 SQLite 為後端的回覆快取，使用前會先核對目前的聊天。如果簡短 ID 已過期，請在以提供該 ID 的對話為目標時，改用其 MessageSidFull 重試。完整 ID 不會略過對話或帳號繫結，因此若 ID 來自其他聊天，請換成目前目標中的 ID。當無法取得目前對話的證據時，遠端委派呼叫可能會拒絕過時的完整 ID。

OpenClaw 只會在快取的探查狀態指出橋接器無法使用時，隱藏私有 API 動作。如果狀態未知，動作仍會顯示，且會在分派時延遲探查，使 imsg launch 之後的第一個動作無須另外手動重新整理狀態即可成功。

私有 API 橋接器啟用時，已接受的傳入聊天會標示為已讀；而在回合獲接受後，私人聊天會立即顯示輸入中的氣泡，同時代理程式準備環境資訊並產生內容。若要停用標示已讀：

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

在各方法功能清單出現前的舊版 imsg 組建版本中，輸入狀態／已讀功能會在無提示的情況下遭到停用；OpenClaw 每次重新啟動時會記錄一次警告，以便判斷未收到回條的原因。

OpenClaw 會訂閱 iMessage 點按回應，並將已接受的回應作為系統事件路由，而非一般訊息文字，因此使用者的點按回應不會觸發一般回覆迴圈。

通知模式由 channels.imessage.reactionNotifications 控制：

• "own"（預設）：僅在使用者回應機器人撰寫的訊息時通知。
• "all"：針對已授權傳送者的所有傳入點按回應發出通知。
• "off"：忽略傳入點按回應。

各帳號的覆寫值使用 channels.imessage.accounts.<id>.reactionNotifications。

當 approvals.exec.enabled 或 approvals.plugin.enabled 為 true，且要求路由至 iMessage 時，閘道會以原生方式傳送核准提示，並接受點按回應以完成處理：

• 👍（讚點按回應）→ allow-once
• 👎（倒讚點按回應）→ deny
• allow-always 仍可作為手動備援：將 /approve <id> allow-always 作為一般回覆傳送。

回應處理要求做出回應之使用者的帳號代稱必須明確列為核准者。核准者清單讀取自 channels.imessage.allowFrom（或 channels.imessage.accounts.<id>.allowFrom）；請加入使用者採 E.164 格式的電話號碼或其 Apple ID 電子郵件地址（chat_id:* 等聊天目標不是有效的核准者項目）。支援萬用字元項目 "*"，但這會允許任何傳送者核准；空白核准者清單會完全停用回應捷徑。回應捷徑會刻意略過 reactionNotifications、dmPolicy 和 groupAllowFrom，因為明確核准者允許清單是完成核准時唯一重要的閘門。

/approve 文字命令授權遵循相同清單：當 channels.imessage.allowFrom 不為空時，會依據該核准者清單授權 /approve <id> <decision>（而非較廣泛的私人訊息允許清單），且私人訊息允許清單允許、但不在 allowFrom 中的傳送者會收到明確的拒絕訊息。當 allowFrom 為空時，同一聊天備援會維持生效，且 /approve 會授權私人訊息允許清單所允許的所有人。請將所有應能核准的操作員（無論透過 /approve 或回應）加入 allowFrom。

Operator 注意事項：

• 回應綁定會同時儲存在記憶體與閘道的持久化鍵值儲存區中（TTL 與核准到期時間一致），而且閘道也會輪詢待處理提示中的 tapback，因此即使 tapback 在閘道重新啟動後不久才送達，仍可完成核准。
• 當操作者自己的 is_from_me=true tapback（例如來自已配對的 Apple 裝置）所使用的識別代號是明確指定的核准者時，便可完成核准。
• 只有在已設定明確核准者時，核准提示才會路由至群組對話；否則任何群組成員都可能核准。
• 舊版文字樣式的 tapback（Liked "…"，來自非常舊的 Apple 用戶端的純文字）無法完成核准，因為其中不含訊息 GUID；回應解析需要目前 macOS / iOS 用戶端所發出的結構化 tapback 中繼資料。

對於含有一個非機密單選問題及一至四個選項的 ask_user 提示，OpenClaw 會加入編號表情符號選項。請以相符的數字回應已送達的提示來作答。該回應必須包含由機器人撰寫之訊息的穩定 GUID；OpenClaw 隨後會透過閘道將數字對應至標準選項。過期或重複的點按會被忽略。

多問題、多選及自由文字提示仍只能透過文字回覆。問題回應遵循一般 iMessage 私訊／群組准入規則。即使一般 reactionNotifications 為 "off"，仍會辨識這類回應，而不會將無關回應轉為代理程式事件。

驗證二進位檔及 RPC 支援：

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

如果探測回報不支援 RPC，請更新 imsg。如果無法使用私有 API 動作，請在已登入的 macOS 使用者工作階段中執行 imsg launch，然後再次探測。如果閘道並非在 macOS 上執行，請改用上方的「透過 SSH 使用遠端 Mac」設定，而非預設的本機 imsg 路徑。

首先確認訊息是否已抵達本機 Mac。如果 chat.db 沒有變化，即使 imsg status --json 回報橋接器狀態正常，OpenClaw 也無法接收訊息。

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

如果從手機傳送的訊息未建立新資料列，請先修復 macOS Messages 與 Apple Push 層，再變更 OpenClaw 組態。通常一次性的服務重新整理便已足夠：

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

從手機傳送一則新的 iMessage，並在偵錯 OpenClaw 工作階段之前，確認出現新的 chat.db 資料列或 imsg watch 事件。請勿將此操作設為定期執行的橋接器重新啟動迴圈；在工作進行期間反覆執行 imsg launch 並重新啟動閘道，可能中斷傳遞並使進行中的頻道執行流程擱置。

預設的 cliPath: "imsg" 必須在已登入 Messages 的 Mac 上執行。在 Linux 或 Windows 上，請將 channels.imessage.cliPath 設定為包裝函式指令碼，透過 SSH 連線至該 Mac 並執行 imsg "$@"。

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

然後執行：

openclaw channels status --probe --channel imessage

檢查：

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

檢查：

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• channels.imessage.groups 允許清單行為
• 提及模式組態（agents.entries.*.groupChat.mentionPatterns）

檢查：

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

請在相同使用者／工作階段情境中的互動式 GUI 終端機內重新執行，並核准提示：

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

確認執行 OpenClaw/imsg 的處理程序情境已獲授予「完全磁碟存取權」與「自動化」權限。