iMessage（舊版：imsg）¶

建議： 新的 iMessage 設定請使用 BlueBubbles。

imsg 頻道是舊版的外部 CLI 整合，未來版本可能會移除。

Status: legacy external CLI integration. 狀態：舊版外部 CLI 整合。Gateway 會啟動 imsg rpc（以 stdio 進行 JSON-RPC）。

快速設定（初學者）¶

確認此 Mac 上的「訊息」已登入。
安裝 imsg： - brew install steipete/tap/imsg
使用 channels.imessage.cliPath 與 channels.imessage.dbPath 設定 OpenClaw。
啟動 Gateway，並核准任何 macOS 提示（自動化 + 完整磁碟存取）。

最小設定：

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

它是什麼¶

由 macOS 上的 imsg 支援的 iMessage 頻道。
確定性路由：回覆一律回到 iMessage。
私訊共用代理程式的主要工作階段；群組則是隔離的（agent:<agentId>:imessage:group:<chat_id>）。
若多參與者執行緒以 is_group=false 抵達，你仍可透過 channels.imessage.groups 使用 chat_id 進行隔離（見下方「類群組執行緒」）。

設定寫入¶

預設允許 iMessage 寫入由 /config set|unset 觸發的設定更新（需要 commands.config: true）。

停用方式：

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

需求¶

已登入「訊息」的 macOS。
為 OpenClaw + imsg 提供完整磁碟存取（存取「訊息」資料庫）。
傳送時需要自動化權限。
channels.imessage.cliPath 可指向任何可代理 stdin/stdout 的指令（例如：透過 SSH 連線到另一台 Mac 並執行 imsg rpc 的包裝腳本）。

疑難排解 macOS 隱私權與安全性 TCC¶

若傳送／接收失敗（例如 imsg rpc 非零結束、逾時，或 Gateway 看似卡住），常見原因是未核准的 macOS 權限提示。

macOS 會依應用程式／行程情境授予 TCC 權限。請在執行 imsg 的相同情境中核准提示（例如 Terminal/iTerm、LaunchAgent 工作階段，或由 SSH 啟動的行程）。 Approve prompts in the same context that runs imsg (for example, Terminal/iTerm, a LaunchAgent session, or an SSH-launched process).

檢查清單：

完整磁碟存取：允許執行 OpenClaw 的行程（以及任何執行 imsg 的 shell／SSH 包裝器）存取。這是讀取「訊息」資料庫（chat.db）所必需。 This is required to read the Messages database (chat.db).
自動化 → 訊息：允許執行 OpenClaw 的行程（及／或你的終端機）控制 Messages.app 以進行外送。
imsg CLI 健康狀態：確認已安裝 imsg 並支援 RPC（imsg rpc --help）。

提示：若 OpenClaw 以無頭模式執行（LaunchAgent/systemd/SSH），macOS 的提示很容易錯過。請在 GUI 終端機中執行一次互動式指令以強制顯示提示，然後重試： Run a one-time interactive command in a GUI terminal to force the prompt, then retry:

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

相關的 macOS 資料夾權限（桌面／文件／下載）：/platforms/mac/permissions。

設定（快速路徑）¶

確認此 Mac 上的「訊息」已登入。
設定 iMessage 並啟動 Gateway。

專用機器人 macOS 使用者（用於隔離身分）¶

若你希望機器人以獨立的 iMessage 身分傳送（並保持你的個人「訊息」乾淨），請使用專用的 Apple ID + 專用的 macOS 使用者。

建立專用 Apple ID（例如：my-cool-bot@icloud.com）。 - Apple 可能需要電話號碼進行驗證／2FA。
建立 macOS 使用者（例如：openclawhome）並登入。
在該 macOS 使用者中開啟「訊息」，並使用機器人的 Apple ID 登入 iMessage。
啟用「遠端登入」（系統設定 → 一般 → 共享 → 遠端登入）。
安裝 imsg： - brew install steipete/tap/imsg
設定 SSH，讓 ssh <bot-macos-user>@localhost true 無需密碼即可運作。
將 channels.imessage.accounts.bot.cliPath 指向一個 SSH 包裝器，以機器人使用者身分執行 imsg。

First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the bot macOS user. If imsg rpc looks stuck or exits, log into that user (Screen Sharing helps), run a one-time imsg chats --limit 1 / imsg send ..., approve prompts, then retry. See Troubleshooting macOS Privacy and Security TCC.

Example wrapper (chmod +x). 範例包裝器（chmod +x）。請將 <bot-macos-user> 替換為你實際的 macOS 使用者名稱：

#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

範例設定：

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

單一帳號設定請使用扁平選項（channels.imessage.cliPath、channels.imessage.dbPath），而非 accounts 對應表。

遠端／SSH 變體（選用）¶

若你希望在另一台 Mac 上使用 iMessage，請將 channels.imessage.cliPath 設為一個包裝器，透過 SSH 在遠端 macOS 主機上執行 imsg。OpenClaw 只需要 stdio。 OpenClaw only needs stdio.

範例包裝器：

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

Remote attachments: When cliPath points to a remote host via SSH, attachment paths in the Messages database reference files on the remote machine. OpenClaw can automatically fetch these over SCP by setting channels.imessage.remoteHost:

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

若未設定 remoteHost，OpenClaw 會嘗試解析你的包裝腳本中的 SSH 指令來自動偵測。為了可靠性，建議明確設定。 Explicit configuration is recommended for reliability.

透過 Tailscale 的遠端 Mac（範例）¶

若 Gateway 在 Linux 主機／VM 上執行，但 iMessage 必須在 Mac 上運作，Tailscale 是最簡單的橋接方式：Gateway 透過 tailnet 與 Mac 通訊，經由 SSH 執行 imsg，並將附件以 SCP 傳回。

架構：

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#000000',
    'secondaryColor': '#f9f9fb',
    'tertiaryColor': '#ffffff',
    'clusterBkg': '#f9f9fb',
    'clusterBorder': '#000000',
    'nodeBorder': '#000000',
    'mainBkg': '#ffffff',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
flowchart TB
 subgraph T[" "]
 subgraph Tailscale[" "]
    direction LR
      Gateway["<b>Gateway host (Linux/VM)<br></b><br>openclaw gateway<br>channels.imessage.cliPath"]
      Mac["<b>Mac with Messages + imsg<br></b><br>Messages signed in<br>Remote Login enabled"]
  end
    Gateway -- SSH (imsg rpc) --> Mac
    Mac -- SCP (attachments) --> Gateway
    direction BT
    User["user@gateway-host"] -- "Tailscale tailnet (hostname or 100.x.y.z)" --> Gateway
end

具體設定範例（Tailscale 主機名稱）：

{
  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",
    },
  },
}

範例包裝器（~/.openclaw/scripts/imsg-ssh）：

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

注意事項：

確保 Mac 已登入「訊息」，且已啟用遠端登入。
使用 SSH 金鑰，讓 ssh bot@mac-mini.tailnet-1234.ts.net 無需提示即可運作。
remoteHost 應與 SSH 目標相符，以便 SCP 擷取附件。

多帳號支援：使用 channels.imessage.accounts 搭配每個帳號的設定，以及選用的 name。共享模式請見［gateway/configuration］(/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。請勿提交 ~/.openclaw/openclaw.json（通常包含權杖）。 See gateway/configuration for the shared pattern. Don't commit ~/.openclaw/openclaw.json (it often contains tokens).

存取控制（私訊 + 群組）¶

私訊（DMs）：

預設：channels.imessage.dmPolicy = "pairing"。
未知寄件者會收到配對碼；在核准前會忽略訊息（配對碼 1 小時後過期）。
Approve via:
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
Pairing is the default token exchange for iMessage DMs. Details: Pairing

群組：

channels.imessage.groupPolicy = open | allowlist | disabled。
當設定 allowlist 時，channels.imessage.groupAllowFrom 會控制誰可以在群組中觸發。
由於 iMessage 沒有原生提及中繼資料，提及閘控使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
多代理程式覆寫：在 agents.list[].groupChat.mentionPatterns 上設定每個代理程式的模式。

運作方式（行為）¶

imsg 會串流訊息事件；Gateway 會將其正規化為共用的頻道封裝。
回覆一律路由回相同的聊天 ID 或 handle。

類群組執行緒（`is_group=false`）¶

某些 iMessage 執行緒可能有多位參與者，但依「訊息」儲存聊天識別碼的方式不同，仍可能以 is_group=false 抵達。

若你在 channels.imessage.groups 下明確設定 chat_id，OpenClaw 會將該執行緒視為「群組」，以便：

工作階段隔離（獨立的 agent:<agentId>:imessage:group:<chat_id> 工作階段金鑰）
群組允許清單／提及閘控行為

範例：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "42": { requireMention: false },
      },
    },
  },
}

當你希望為特定執行緒使用隔離的人格／模型時，這非常實用（請見［多代理程式路由］(/concepts/multi-agent)）。檔案系統隔離請見［沙箱隔離］(/gateway/sandboxing)。 For filesystem isolation, see Sandboxing.

媒體 + 限制¶

透過 channels.imessage.includeAttachments 的選用附件匯入。
透過 channels.imessage.mediaMaxMb 的媒體上限。

限制¶

外送文字會分段為 channels.imessage.textChunkLimit（預設 4000）。
選用的換行分段：設定 channels.imessage.chunkMode="newline"，在依長度分段前先依空白行（段落邊界）分割。
媒體上傳上限由 channels.imessage.mediaMaxMb 控制（預設 16）。

定址／投遞目標¶

建議使用 chat_id 以獲得穩定路由：

chat_id:123（建議）
chat_guid:...
chat_identifier:...
直接 handle：imessage:+1555／sms:+1555／user@example.com

列出聊天：

imsg chats --limit 20

設定參考（iMessage）¶

完整設定：設定

提供者選項：

channels.imessage.enabled：啟用／停用頻道啟動。
channels.imessage.cliPath：imsg 的路徑。
channels.imessage.dbPath：「訊息」資料庫路徑。
channels.imessage.remoteHost：當 cliPath 指向遠端 Mac（例如 user@gateway-host）時，用於 SCP 附件傳輸的 SSH 主機。若未設定，將從 SSH 包裝器自動偵測。 Auto-detected from SSH wrapper if not set.
channels.imessage.service：imessage | sms | auto。
channels.imessage.region：SMS 區域。
channels.imessage.dmPolicy：pairing | allowlist | open | disabled（預設：配對）。
channels.imessage.allowFrom：私訊允許清單（handle、電子郵件、E.164 號碼，或 chat_id:*）。open 需要 "*"。iMessage 沒有使用者名稱；請使用 handle 或聊天目標。 open requires "*". iMessage has no usernames; use handles or chat targets.
channels.imessage.groupPolicy：open | allowlist | disabled（預設：允許清單）。
channels.imessage.groupAllowFrom：群組寄件者允許清單。
channels.imessage.historyLimit／channels.imessage.accounts.*.historyLimit：納入為上下文的群組訊息最大數量（0 代表停用）。
channels.imessage.dmHistoryLimit: DM history limit in user turns. channels.imessage.dmHistoryLimit：以使用者回合計的私訊歷史上限。每位使用者的覆寫：channels.imessage.dms["<handle>"].historyLimit。
channels.imessage.groups：每個群組的預設值 + 允許清單（全域預設請使用 "*"）。
channels.imessage.includeAttachments：將附件匯入至上下文。
channels.imessage.mediaMaxMb：入站／出站媒體上限（MB）。
channels.imessage.textChunkLimit：外送分段大小（字元）。
channels.imessage.chunkMode：length（預設）或 newline，在依長度分段前先依空白行（段落邊界）分割。

Related global options:

agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
messages.responsePrefix。

Overview

Messaging platforms

Configuration

iMessage

iMessage（舊版：imsg）¶

快速設定（初學者）¶

它是什麼¶

設定寫入¶

需求¶

疑難排解 macOS 隱私權與安全性 TCC¶

設定（快速路徑）¶

專用機器人 macOS 使用者（用於隔離身分）¶

遠端／SSH 變體（選用）¶

透過 Tailscale 的遠端 Mac（範例）¶

存取控制（私訊 + 群組）¶

運作方式（行為）¶

類群組執行緒（`is_group=false`）¶

媒體 + 限制¶

限制¶

定址／投遞目標¶

設定參考（iMessage）¶

Overview

Messaging platforms

Configuration

iMessage（舊版：imsg）¶

快速設定（初學者）¶

它是什麼¶

設定寫入¶

需求¶

疑難排解 macOS 隱私權與安全性 TCC¶

設定（快速路徑）¶

專用機器人 macOS 使用者（用於隔離身分）¶

遠端／SSH 變體（選用）¶

透過 Tailscale 的遠端 Mac（範例）¶

存取控制（私訊 + 群組）¶

運作方式（行為）¶

類群組執行緒（is_group=false）¶

媒體 + 限制¶

限制¶

定址／投遞目標¶

設定參考（iMessage）¶

類群組執行緒（`is_group=false`）¶