Image and media support

Image and media support 문서는 OpenClaw 공식 문서(nodes/images)를 한국어로 정리한 가이드입니다. Image and media handling rules for send, gateway, and agent replies 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Image and media handling rules for send, gateway, and agent replies

한국어 가이드 범위: nodes/images 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Goals
CLI Surface
WhatsApp Web channel behavior
Auto-Reply Pipeline
Inbound Media To Commands
Limits and errors
Notes for Tests
관련 문서

상세 내용

본문

The WhatsApp channel runs on Baileys Web. This page covers media handling rules for send, gateway, and agent replies.

Goals

주요 항목:

Send media with an optional caption via openclaw message send --media.
Allow auto-replies from the web inbox to include media alongside text.
Keep per-type limits sane and predictable.

CLI Surface

openclaw message send --target --media [--message ]

주요 항목:

--media <path-or-url> — attach media (image/audio/video/document); accepts local paths or URLs. Optional; caption can be empty for media-only sends.
--gif-playback — treat video media as GIF playback (WhatsApp only).
--force-document — send media as a document to avoid channel compression (Telegram, WhatsApp); applies to images, GIFs, and videos.
--reply-to <id>, --thread-id <id>, --pin, --silent — delivery/threading options shared with text-only sends.
--dry-run — print the resolved payload and skip sending.
--json — print the result as JSON: { action, channel, dryRun, handledBy, messageId?, payload } (payload carries the channel-specific send result, including any media reference).

WhatsApp Web channel behavior

The 16MB audio/video and 100MB document figures above are the shared per-kind media defaults used when no explicit byte cap is passed. WhatsApp sends set an explicit cap from channels.whatsapp.mediaMaxMb (default 50MB), which applies uniformly across kinds for that account.

주요 항목:

Input: local file path or HTTP(S) URL.
Flow: load into a buffer, detect media kind, then build the outbound payload per kind:
Images: optimized to fit under channels.whatsapp.mediaMaxMb (default 50MB). Opaque images are recompressed to JPEG (default side ladder starts at 2048px, descending on repeated size misses); images with transparency are kept as PNG. If the source is already an acceptable JPEG/PNG/WebP within the size and side-length budget, the original bytes are preserved unchanged instead of being recompressed. Animated GIFs are never re-encoded, only size-checked.
Audio/voice: unless already native voice audio (.ogg/.opus, or audio/ogg/audio/opus), outbound audio is transcoded via ffmpeg to Opus/OGG (48kHz mono, 64kbps, capped at 20 minutes) before sending as a voice note (ptt: true).
Video: pass-through up to 16MB.
Documents: anything else, up to 100MB, with filename preserved when available.
WhatsApp GIF-style playback: send an MP4 with gifPlayback: true (CLI: --gif-playback) so mobile clients loop it inline.
MIME detection prefers sniffed magic bytes, then the file extension, then response headers; a generic sniffed container (application/octet-stream, zip) never overrides a more specific extension mapping (for example XLSX vs ZIP).
Caption comes from --message or reply.text; empty caption is allowed.
Logging: non-verbose shows ↩️/✅; verbose includes size and source path/URL.

Auto-Reply Pipeline

주요 항목:

getReplyFromConfig returns a reply payload (or array of payloads) with text?, mediaUrl?, and mediaUrls? among other fields.
When media is present, the web sender resolves local paths or URLs using the same pipeline as openclaw message send.
Multiple media entries are sent sequentially if provided.

Inbound Media To Commands

주요 항목:

When inbound web messages include media, OpenClaw downloads it to a temp file and exposes templating variables:
{{AttachmentUrl}} — original URL or provider reference for the current attachment.
{{AttachmentPath}} — local temp path written before running the command.
{{AttachmentContentType}} — MIME content type.
{{AttachmentDir}} — directory containing the local path.
{{AttachmentIndex}} — zero-based source fact index.
When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and the attachment path/reference is rewritten to a sandbox-relative path like media/inbound/<filename>.
{{MediaPath}}, {{MediaUrl}}, {{MediaType}}, and {{MediaDir}} remain deprecated compatibility aliases during the plugin SDK migration window.
Media understanding (configured via tools.media.* or shared tools.media.models) runs before templating and can insert [Image], [Audio], and [Video] blocks into Body.
Audio sets {{Transcript}} and uses the transcript for command parsing so slash commands still work.
Video and image descriptions preserve any caption text for command parsing.
If the active primary model already supports vision natively, OpenClaw skips the [Image] summary block and passes the original image to the model instead.
By default only the first matching image/audio/video attachment is processed; use tools.media.<capability>.attachments to select multiple attachments.

Limits and errors

tools.media.models[] entry with maxBytes).

주요 항목:

Images: up to channels.whatsapp.mediaMaxMb (default 50MB) after optimization.
Audio/video: 16MB cap (shared default; overridden by mediaMaxMb when sending through WhatsApp).
Documents: 100MB cap (shared default; overridden by mediaMaxMb when sending through WhatsApp).
Oversize or unreadable media produces a clear error in logs, and the reply is skipped.
Image default: 10MB (override with tools.media.image.maxBytes, or per
Audio default: 20MB (override with tools.media.audio.maxBytes, or per entry).
Video default: 50MB (override with tools.media.video.maxBytes, or per entry).
Oversize media skips understanding, but the reply still goes through with the original body.

Notes for Tests

주요 항목:

Cover send and reply flows for image/audio/document cases.
Validate size bounds after image optimization and the voice-note flag for audio.
Ensure multi-media replies fan out as sequential sends.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/nodes/images
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Image and media support

핵심 요약

Image and media handling rules for send, gateway, and agent replies

한국어 가이드 범위: nodes/images 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Goals
CLI Surface
WhatsApp Web channel behavior
Auto-Reply Pipeline
Inbound Media To Commands
Limits and errors
Notes for Tests
관련 문서

상세 내용

본문

The WhatsApp channel runs on Baileys Web. This page covers media handling rules for send, gateway, and agent replies.

Goals

주요 항목:

Send media with an optional caption via openclaw message send --media.
Allow auto-replies from the web inbox to include media alongside text.
Keep per-type limits sane and predictable.

CLI Surface

openclaw message send --target --media [--message ]

주요 항목:

--media <path-or-url> — attach media (image/audio/video/document); accepts local paths or URLs. Optional; caption can be empty for media-only sends.
--gif-playback — treat video media as GIF playback (WhatsApp only).
--force-document — send media as a document to avoid channel compression (Telegram, WhatsApp); applies to images, GIFs, and videos.
--reply-to <id>, --thread-id <id>, --pin, --silent — delivery/threading options shared with text-only sends.
--dry-run — print the resolved payload and skip sending.
--json — print the result as JSON: { action, channel, dryRun, handledBy, messageId?, payload } (payload carries the channel-specific send result, including any media reference).

WhatsApp Web channel behavior

주요 항목:

Input: local file path or HTTP(S) URL.
Flow: load into a buffer, detect media kind, then build the outbound payload per kind:
Images: optimized to fit under channels.whatsapp.mediaMaxMb (default 50MB). Opaque images are recompressed to JPEG (default side ladder starts at 2048px, descending on repeated size misses); images with transparency are kept as PNG. If the source is already an acceptable JPEG/PNG/WebP within the size and side-length budget, the original bytes are preserved unchanged instead of being recompressed. Animated GIFs are never re-encoded, only size-checked.
Audio/voice: unless already native voice audio (.ogg/.opus, or audio/ogg/audio/opus), outbound audio is transcoded via ffmpeg to Opus/OGG (48kHz mono, 64kbps, capped at 20 minutes) before sending as a voice note (ptt: true).
Video: pass-through up to 16MB.
Documents: anything else, up to 100MB, with filename preserved when available.
WhatsApp GIF-style playback: send an MP4 with gifPlayback: true (CLI: --gif-playback) so mobile clients loop it inline.
MIME detection prefers sniffed magic bytes, then the file extension, then response headers; a generic sniffed container (application/octet-stream, zip) never overrides a more specific extension mapping (for example XLSX vs ZIP).
Caption comes from --message or reply.text; empty caption is allowed.
Logging: non-verbose shows ↩️/✅; verbose includes size and source path/URL.

Auto-Reply Pipeline

주요 항목:

getReplyFromConfig returns a reply payload (or array of payloads) with text?, mediaUrl?, and mediaUrls? among other fields.
When media is present, the web sender resolves local paths or URLs using the same pipeline as openclaw message send.
Multiple media entries are sent sequentially if provided.

Inbound Media To Commands

주요 항목:

When inbound web messages include media, OpenClaw downloads it to a temp file and exposes templating variables:
{{AttachmentUrl}} — original URL or provider reference for the current attachment.
{{AttachmentPath}} — local temp path written before running the command.
{{AttachmentContentType}} — MIME content type.
{{AttachmentDir}} — directory containing the local path.
{{AttachmentIndex}} — zero-based source fact index.
When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and the attachment path/reference is rewritten to a sandbox-relative path like media/inbound/<filename>.
{{MediaPath}}, {{MediaUrl}}, {{MediaType}}, and {{MediaDir}} remain deprecated compatibility aliases during the plugin SDK migration window.
Media understanding (configured via tools.media.* or shared tools.media.models) runs before templating and can insert [Image], [Audio], and [Video] blocks into Body.
Audio sets {{Transcript}} and uses the transcript for command parsing so slash commands still work.
Video and image descriptions preserve any caption text for command parsing.
If the active primary model already supports vision natively, OpenClaw skips the [Image] summary block and passes the original image to the model instead.
By default only the first matching image/audio/video attachment is processed; use tools.media.<capability>.attachments to select multiple attachments.

Limits and errors

tools.media.models[] entry with maxBytes).

주요 항목:

Images: up to channels.whatsapp.mediaMaxMb (default 50MB) after optimization.
Audio/video: 16MB cap (shared default; overridden by mediaMaxMb when sending through WhatsApp).
Documents: 100MB cap (shared default; overridden by mediaMaxMb when sending through WhatsApp).
Oversize or unreadable media produces a clear error in logs, and the reply is skipped.
Image default: 10MB (override with tools.media.image.maxBytes, or per
Audio default: 20MB (override with tools.media.audio.maxBytes, or per entry).
Video default: 50MB (override with tools.media.video.maxBytes, or per entry).
Oversize media skips understanding, but the reply still goes through with the original body.

Notes for Tests

주요 항목:

Cover send and reply flows for image/audio/document cases.
Validate size bounds after image optimization and the voice-note flag for audio.
Ensure multi-media replies fan out as sequential sends.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/nodes/images
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Image and media support

핵심 요약

문서 구성

상세 내용

본문

Goals

CLI Surface

WhatsApp Web channel behavior

Auto-Reply Pipeline

Inbound Media To Commands

Limits and errors

Notes for Tests

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Image and media support

핵심 요약

문서 구성

상세 내용

본문

Goals

CLI Surface

WhatsApp Web channel behavior

Auto-Reply Pipeline

Inbound Media To Commands

Limits and errors

Notes for Tests

관련 문서

실습 체크리스트

관련 링크

관련 가이드