圖片與媒體支援 — 2025-12-05

WhatsApp 頻道透過 Baileys Web 運作。本文說明傳送、Gateway 及 agent 回覆中的媒體處理規則。

目標

• 透過 openclaw message send --media 傳送媒體及可選的說明文字。
• 允許網頁收件匣的自動回覆在文字之外附帶媒體。
• 各類型限制維持合理且可預測。

CLI 介面

• openclaw message send --media <path-or-url> [--message <caption>]
  • --media 為可選；說明文字可為空（僅傳送媒體）。
  • --dry-run 輸出解析後的 payload；--json 輸出 { channel, to, messageId, mediaUrl, caption }。

WhatsApp Web 頻道行為

• 輸入：本機檔案路徑或 HTTP(S) URL。
• 流程：載入 Buffer、偵測媒體類型，建構對應 payload：
  • 圖片： 縮放並重新壓縮為 JPEG（最大邊 2048px），目標大小為 agents.defaults.mediaMaxMb（預設 5 MB），上限 6 MB。
  • 音訊/語音/影片： 直接傳遞，上限 16 MB；音訊以語音訊息發送（ptt: true）。
  • 文件： 其他類型，上限 100 MB，可用時保留原始檔名。
• WhatsApp GIF 播放效果：傳送 MP4 並設定 gifPlayback: true（CLI：--gif-playback），讓行動裝置以迴圈方式內嵌播放。
• MIME 偵測優先順序：magic bytes → headers → 副檔名。
• 說明文字來自 --message 或 reply.text；允許空白說明。
• 記錄：非 verbose 模式顯示 ↩️/✅；verbose 模式包含大小與來源路徑/URL。

自動回覆流程

• getReplyFromConfig 回傳 { text?, mediaUrl?, mediaUrls? }。
• 當回覆包含媒體時，web 傳送器使用與 openclaw message send 相同的流程解析本機路徑或 URL。
• 多個媒體項目依序傳送。

接收媒體轉指令（Pi）

• 當接收的 web 訊息包含媒體時，OpenClaw 下載至暫存檔並提供範本變數：
  • {{MediaUrl}}：接收媒體的虛擬 URL。
  • {{MediaPath}}：執行指令前寫入的本機暫存路徑。
• 啟用逐工作階段 Docker 沙箱時，接收媒體會複製到沙箱工作區，MediaPath/MediaUrl 改寫為相對路徑如 media/inbound/<filename>。
• 媒體理解功能（若透過 tools.media.* 或共用 tools.media.models 設定）在範本處理前執行，可將 [Image]、[Audio] 和 [Video] 區塊插入 Body。
  • 音訊設定 {{Transcript}}，並以轉錄文字進行指令解析，斜線指令因此仍可正常運作。
  • 影片和圖片描述會保留說明文字供指令解析使用。
• 預設只處理第一個符合的圖片/音訊/影片附件；設定 tools.media.<cap>.attachments 可處理多個附件。

限制與錯誤

對外傳送上限（WhatsApp web 傳送）

• 圖片：重新壓縮後約 6 MB 上限。
• 音訊/語音/影片：16 MB 上限；文件：100 MB 上限。
• 超過大小或無法讀取的媒體 → 記錄中顯示明確錯誤，該回覆被跳過。

媒體理解上限（轉錄/描述）

• 圖片預設：10 MB（tools.media.image.maxBytes）。
• 音訊預設：20 MB（tools.media.audio.maxBytes）。
• 影片預設：50 MB（tools.media.video.maxBytes）。
• 超過大小的媒體會跳過理解功能，但回覆仍以原始內容繼續處理。

測試注意事項

• 涵蓋圖片/音訊/文件的傳送及回覆流程。
• 驗證圖片重新壓縮（大小限制）及音訊的語音訊息標記。
• 確認多媒體回覆會展開為依序傳送。