Hỗ trợ Hình ảnh & Media — 2025-12-05

Channel WhatsApp chạy qua Baileys Web. Tài liệu này ghi lại các quy tắc xử lý media hiện tại cho send, gateway và agent replies.

Mục tiêu

openclaw message send --media <path-or-url> [--message <caption>]
- --media là tùy chọn; caption có thể để trống cho trường hợp chỉ gửi media.
- --dry-run in ra payload đã resolve; --json xuất ra { channel, to, messageId, mediaUrl, caption }.

Input: đường dẫn file local hoặc HTTP(S) URL.
Flow: load vào Buffer, phát hiện loại media, và build payload phù hợp:
- Images: resize & nén lại thành JPEG (cạnh tối đa 2048px) nhắm đến agents.defaults.mediaMaxMb (mặc định 5 MB), giới hạn tối đa 6 MB.
- Audio/Voice/Video: pass-through tối đa 16 MB; audio được gửi dưới dạng voice note (ptt: true).
- Documents: mọi thứ khác, tối đa 100 MB, với tên file được giữ nguyên khi có.
WhatsApp GIF-style playback: gửi MP4 với gifPlayback: true (CLI: --gif-playback) để mobile clients loop inline.
MIME detection ưu tiên magic bytes, sau đó headers, rồi file extension.
Caption lấy từ --message hoặc reply.text; caption trống cũng được chấp nhận.
Logging: chế độ non-verbose hiển thị ↩️/✅; verbose bao gồm size và source path/URL.

getReplyFromConfig trả về { text?, mediaUrl?, mediaUrls? }.
Khi có media, web sender resolve local paths hoặc URLs dùng cùng pipeline như openclaw message send.
Nhiều media entries được gửi tuần tự nếu được cung cấp.

Khi inbound web messages bao gồm media, OpenClaw download về temp file và expose các templating variables:
- {{MediaUrl}} pseudo-URL cho inbound media.
- {{MediaPath}} đường dẫn temp local được ghi trước khi chạy command.
Khi per-session Docker sandbox được bật, inbound media được copy vào sandbox workspace và MediaPath/MediaUrl được viết lại thành đường dẫn tương đối như media/inbound/<filename>.
Media understanding (nếu được config qua tools.media.* hoặc shared tools.media.models) chạy trước templating và có thể chèn các blocks [Image], [Audio], và [Video] vào Body.
- Audio set {{Transcript}} và dùng transcript cho command parsing nên slash commands vẫn hoạt động.
- Video và image descriptions giữ nguyên caption text cho command parsing.
Mặc định chỉ attachment image/audio/video đầu tiên được xử lý; set tools.media.<cap>.attachments để xử lý nhiều attachments.

Outbound send caps (WhatsApp web send)

Media understanding caps (transcription/description)