影像與媒體支援

WhatsApp 通道執行於 Baileys Web。本頁說明傳送、閘道與代理回覆的媒體處理規則。

目標

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

--media <path-or-url> — 附加媒體（圖片/音訊/影片/文件）；接受本機路徑或 URL。選用；純媒體傳送時標題可為空。
--gif-playback — 將影片媒體視為 GIF 播放（僅 WhatsApp）。
--force-document — 將媒體作為文件傳送，以避免通道壓縮（Telegram、WhatsApp）；適用於圖片、GIF 和影片。
--reply-to <id>、--thread-id <id>、--pin、--silent — 與純文字傳送共用的傳遞/討論串選項。
--dry-run — 列印解析後的承載內容並略過傳送。
--json — 將結果列印為 JSON：{ action, channel, dryRun, handledBy, messageId?, payload }（payload 帶有通道特定的傳送結果，包含任何媒體參照）。

輸入：本機檔案路徑或 HTTP(S) URL。
流程：載入至緩衝區、偵測媒體種類，然後依種類建立外送承載內容：
- 圖片： 最佳化以符合 channels.whatsapp.mediaMaxMb 以下（預設 50MB）。不透明圖片會重新壓縮為 JPEG（預設邊長階梯從 2048px 開始，重複超過大小時向下遞減）；具透明度的圖片會保留為 PNG。如果來源已是符合大小與邊長預算的可接受 JPEG/PNG/WebP，原始位元組會保持不變，而不是重新壓縮。動畫 GIF 絕不會重新編碼，只會檢查大小。
- 音訊/語音： 除非已是原生語音音訊（.ogg/.opus，或 audio/ogg/audio/opus），否則外送音訊會先透過 ffmpeg 轉碼為 Opus/OGG（48kHz 單聲道、64kbps、上限 20 分鐘），再作為語音備忘（ptt: true）傳送。
- 影片： 16MB 以內直通。
- 文件： 其他任何內容，上限 100MB，可用時保留檔名。
WhatsApp GIF 樣式播放：傳送帶有 gifPlayback: true 的 MP4（命令列介面：--gif-playback），讓行動用戶端在行內循環播放。
MIME 偵測優先使用嗅探到的魔術位元組，其次是副檔名，再其次是回應標頭；一般性的嗅探容器（application/octet-stream、zip）絕不會覆蓋更具體的副檔名對應（例如 XLSX 與 ZIP）。
標題來自 --message 或 reply.text；允許空標題。
記錄：非詳細模式顯示 ↩️/✅；詳細模式包含大小與來源路徑/URL。

上述 16MB 音訊/影片與 100MB 文件數值，是未傳入明確位元組上限時使用的共用各類型媒體預設值。WhatsApp 傳送會從 channels.whatsapp.mediaMaxMb 設定明確上限（預設 50MB），並對該帳號的各種類型一律套用。

getReplyFromConfig 會傳回回覆承載內容（或承載內容陣列），其中包含 text?、mediaUrl? 和 mediaUrls? 等欄位。
媒體存在時，Web 傳送器會使用與 openclaw message send 相同的管線解析本機路徑或 URL。
若提供多個媒體項目，會依序傳送。

當傳入 Web 訊息包含媒體時，OpenClaw 會將其下載至暫存檔，並公開範本變數：
- {{MediaUrl}} — 傳入媒體的偽 URL。
- {{MediaPath}} — 執行命令前寫入的本機暫存路徑。
啟用每工作階段 Docker 沙箱時，傳入媒體會複製到沙箱工作區，且 MediaPath/MediaUrl 會重寫為沙箱相對路徑，例如 media/inbound/<filename>。
媒體理解（透過 tools.media.* 或共用 tools.media.models 設定）會在範本處理前執行，並可將 [Image]、[Audio] 和 [Video] 區塊插入 Body。
- 音訊會設定 {{Transcript}}，並使用轉錄稿進行命令解析，因此斜線命令仍可運作。
- 影片和圖片描述會保留任何標題文字供命令解析。
- 如果使用中的主要模型已原生支援視覺，OpenClaw 會略過 [Image] 摘要區塊，改將原始圖片傳給模型。
預設只會處理第一個符合的圖片/音訊/影片附件；設定 tools.media.<capability>.attachments 可處理多個附件。

外送傳送上限（WhatsApp Web 傳送）

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