OpenClaw

OpenClaw iMessage (Legacy) 頻道

即時通訊
進階

透過 macOS 上的 imsg CLI 工具將 OpenClaw 連接到 Apple iMessage。此舊版整合使用 JSON-RPC over stdio 介面，透過原生 macOS 訊息資料庫讀取和傳送 iMessage。注意：此頻道已棄用——對於新部署，我們強烈建議使用 BlueBubbles，它提供了更穩健的基於 REST API 的整合方案，並支援更多功能。

快速資訊
難度進階
分類即時通訊
支援功能數2 / 6

iMessage (Legacy) 支援功能

文字訊息

支援

媒體與檔案

支援

表情回應

不支援

討論串

不支援

語音訊息

不支援

群組聊天

不支援

iMessage (Legacy) 前置條件

  • 一台執行 macOS 的 Mac，且已在訊息 app 中登入 Apple ID
  • 為 OpenClaw 和 imsg 二進位檔授予「完整磁碟存取權限」
  • 傳送訊息的自動化權限（透過 macOS TCC 彈窗授予）
  • 透過 Homebrew 安裝 imsg CLI：brew install steipete/tap/imsg
  • OpenClaw Gateway 已安裝並執行

iMessage (Legacy) 快速設定

1

安裝 imsg CLI

執行 'brew install steipete/tap/imsg' 安裝 iMessage CLI 工具。安裝後，在 GUI 終端機中執行一次 'imsg' 以觸發 macOS 的權限授權彈窗（完整磁碟存取和自動化權限）。

2

授予 macOS 權限

開啟系統設定 > 隱私權與安全性。為 imsg 二進位檔和 OpenClaw 程序授予「完整磁碟存取權限」。訊息 app 的自動化權限會在 imsg 首次嘗試傳送訊息時自動彈出授權提示。

3

設定並啟動

在 ~/.openclaw/openclaw.json 中新增 iMessage 頻道設定，設定 cliPath 和 dbPath。執行 'openclaw start' 啟動 Gateway，然後傳送一條測試 iMessage 來驗證連線。

iMessage (Legacy) 設定範例

config.json
{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "/Users/<username>/Library/Messages/chat.db"
    }
  }
}

iMessage (Legacy) 深入了解

棄用說明

iMessage 頻道是一個舊版整合，可能在未來的 OpenClaw 版本中被移除。它依賴第三方 imsg CLI 和 macOS 特有的 TCC 權限系統，在系統更新後可能出現相容性問題。 對於新部署，我們強烈建議遷移到 BlueBubbles 頻道，它提供： • 基於 REST API 的架構（無 CLI 依賴） • 表情回應支援 • 群組聊天支援 • 透過 Web 介面進行跨平台伺服器管理 • 更可靠的基於 Webhook 的訊息投遞 現有的 iMessage 設定將繼續運作，但此整合不會再新增功能。
此頻道已棄用。請使用 BlueBubbles 進行新的 iMessage 整合。

架構概述

iMessage 整合透過 JSON-RPC over stdio 方式啟動 imsg CLI 子程序來運作： 1. Gateway 啟動 'imsg rpc' 作為子程序，透過 stdin/stdout 進行通訊。 2. imsg CLI 使用 SQLite 從 macOS 訊息資料庫（chat.db）讀取新訊息。 3. 當新訊息到達時，imsg 透過 JSON-RPC 通知 Gateway。 4. Gateway 將訊息交由 AI 代理處理，並透過 imsg 傳送回覆，imsg 使用 macOS 自動化功能傳送 iMessage。 此架構要求 Gateway 執行在已登入訊息 app 的同一台 Mac 上。回覆會確定性地路由回 iMessage，每個對話（私訊或群組）都保持獨立的工作階段隔離。

私訊策略

私訊策略控制機器人如何處理一對一的 iMessage 對話。 **pairing（預設）** — 未知傳送者會收到一個配對碼，必須確認後機器人才會回應。這可以防止未授權存取。 **allowlist** — 只有 allowFrom 中列出的手機號碼或 Apple ID 可以與機器人互動。 **open** — 任何 iMessage 傳送者都會收到回覆。需設定 allowFrom: ["*"] 來啟用。 **disabled** — 機器人忽略所有私訊。
openclaw.json
{
  "channels": {
    "imessage": {
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890", "user@icloud.com"]
    }
  }
}

群組聊天設定

群組聊天策略控制機器人在 iMessage 群組對話中的行為。 **open** — 機器人在被加入的任何群組中回覆所有訊息。 **allowlist** — 機器人僅在設定中明確列出的群組中回覆。 **disabled（預設）** — 機器人不在群組聊天中回覆。 啟用群組聊天後，可以設定基於提及的觸發機制，使機器人僅在被提及名稱時才回覆，減少繁忙群組中的干擾。
openclaw.json
{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "mentionPattern": "@bot"
    }
  }
}

透過 SSH 遠端 Mac 部署

對於無頭或遠端部署場景，imsg CLI 可以透過 SSH 在另一台 Mac 上執行。Gateway 透過 SSH 連線啟動 imsg 程序，附件透過 SCP 傳輸。 這在執行訊息 app 的 Mac 位於不同位置時非常有用（例如 Mac Mini 伺服器），而 Gateway 執行在其他地方。 要求： • 基於 SSH 金鑰的驗證（無互動式提示） • 遠端 Mac 必須已安裝 imsg 並授予權限 • SCP 必須可用於附件傳輸
openclaw.json
{
  "channels": {
    "imessage": {
      "remoteHost": "mac-server.local",
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}
使用 SSH 金鑰驗證以避免互動式密碼提示。
Tailscale 等工具可以簡化對 Mac 伺服器的遠端存取。

macOS 權限（TCC）

iMessage 整合需要特定的 macOS 隱私權限（由 TCC 框架管理）： **完整磁碟存取** — 讀取訊息資料庫（chat.db）所需。imsg 二進位檔和 OpenClaw 程序都需要此權限。 **自動化** — 透過訊息 app 傳送訊息所需。此權限通常在 imsg 首次嘗試傳送時透過系統彈窗授予。 如果在無頭環境中執行（例如透過 SSH 或 launchd），權限彈窗可能不會出現。此時，需要在互動式 GUI 終端機工作階段中執行一次 'imsg' 來觸發彈窗，然後可以恢復無頭執行。
macOS 權限彈窗僅在 GUI 工作階段中出現。請在無頭部署前至少以互動方式執行一次 imsg。

iMessage (Legacy) 設定參考

enabled
Type: booleanDefault: true

啟用或停用 iMessage 頻道

cliPath
Type: stringDefault: "/usr/local/bin/imsg"

imsg CLI 二進位檔的路徑。Homebrew 在 Apple Silicon Mac 上安裝到 /opt/homebrew/bin/imsg，在 Intel Mac 上安裝到 /usr/local/bin/imsg

dbPath
Type: stringDefault: "~/Library/Messages/chat.db"

macOS 訊息 SQLite 資料庫的路徑

dmPolicy
Type: stringDefault: "pairing"

私訊存取策略：'pairing'、'allowlist'、'open' 或 'disabled'

groupPolicy
Type: stringDefault: "disabled"

群組聊天策略：'open'、'allowlist' 或 'disabled'

allowFrom
Type: string[]Default: []

允許聯繫機器人的手機號碼或 Apple ID

includeAttachments
Type: booleanDefault: false

是否處理傳入訊息中的媒體附件

mediaMaxMb
Type: numberDefault: 10

媒體附件的最大檔案大小（MB）

textChunkLimit
Type: numberDefault: 4000

每條傳送訊息的最大字元數

chunkMode
Type: stringDefault: "length"

文字分割模式：'length'（按字元數）或 'newline'（按段落）

historyLimit
Type: numberDefault: 20

作為對話上下文包含的最大歷史訊息數

configWrites
Type: booleanDefault: true

允許透過 iMessage 使用 /config set|unset 命令

remoteHost
Type: stringDefault: ""

用於在遠端 Mac 上執行 imsg 的 SSH 主機名稱

iMessage (Legacy) 常見問題

iMessage (Legacy) 故障排除

機器人無法收發訊息

imsg 二進位檔或 OpenClaw 程序缺少 macOS 權限（完整磁碟存取或自動化）。

開啟系統設定 > 隱私權與安全性。確認 imsg 和 OpenClaw 都已獲得完整磁碟存取權限。在 GUI 終端機中執行 'imsg' 以觸發缺失的權限彈窗。授權後重新啟動 Gateway。
權限彈窗不出現

程序執行在無頭環境中（SSH、launchd），macOS 無法顯示 TCC 彈窗。

透過 GUI 工作階段（螢幕共享或實體存取）登入 Mac。在 Terminal.app 中執行 'imsg' 以觸發彈窗。權限授予後可恢復無頭執行。
錯誤：chat.db 未找到或存取被拒絕

dbPath 設定不正確，或未授予完整磁碟存取權限。

確認 dbPath 指向正確的訊息資料庫（通常為 ~/Library/Messages/chat.db）。在系統設定中確保 OpenClaw 程序已啟用完整磁碟存取權限。
遠端 SSH 連線失敗

未設定 SSH 金鑰驗證，或遠端主機不可達。

確保 Gateway 主機和遠端 Mac 之間已設定 SSH 金鑰驗證。使用 'ssh <remoteHost> imsg --version' 手動測試連線。檢查防火牆和網路連通性。
檢視完整文件返回所有頻道

相關頻道

WhatsApp

Medium

OpenClaw 透過 Baileys 協定使用 QR Code 連接

設定指南

Telegram

Easy

OpenClaw 透過 grammY 框架整合 Bot API

設定指南

Discord

Easy

OpenClaw 使用 discord.js 整合 Bot Token

設定指南