> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 圖片與媒體支援

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

WhatsApp 頻道透過 **Baileys Web** 運作。本文件說明目前用於傳送、Gateway 閘道器 與代理程式回覆的媒體處理規則。 本文件記錄了 send、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 風格播放：傳送帶有 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），讓行動裝置客戶端可內嵌循環播放。
* MIME 偵測優先順序為 magic bytes，其次為標頭，最後為副檔名。
* 說明文字來源為 `--message` 或 `reply.text`；允許空白說明文字。
* 記錄：非詳細模式顯示 `↩️`/`✅`；詳細模式包含大小與來源路徑/URL。

## 自動回覆管線

* `getReplyFromConfig` 會回傳 `{ text?, mediaUrl?, mediaUrls? }`。
* 當包含媒體時，網頁傳送端會使用與 `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`）。
* Oversize media skips understanding, but replies still go through with the original body.

## 測試注意事項

* Cover send + reply flows for image/audio/document cases.
* 驗證圖片重新壓縮（大小限制）與音訊的語音備忘錄旗標。
* 確保多媒體回覆會以序列方式分批傳送。