---
read_when:
    - تغییر پایپ‌لاین رسانه یا پیوست‌ها
summary: قواعد مدیریت تصویر و رسانه برای ارسال، Gateway و پاسخ‌های عامل
title: پشتیبانی از تصویر و رسانه
x-i18n:
    generated_at: "2026-05-06T17:59:55Z"
    model: gpt-5.5
    provider: openai
    source_hash: 069140a3ad3bade166d4576ead604b4675006a01e546672872379ce83291471c
    source_path: nodes/images.md
    workflow: 16
---

کانال WhatsApp از طریق **Baileys Web** اجرا می‌شود. این سند قواعد فعلی مدیریت رسانه را برای ارسال، Gateway، و پاسخ‌های عامل ثبت می‌کند.

## اهداف

- ارسال رسانه با کپشن اختیاری از طریق `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

- ورودی: مسیر فایل محلی **یا** URL با HTTP(S).
- جریان: بارگذاری در یک بافر، تشخیص نوع رسانه، و ساخت payload درست:
  - **تصاویر:** تغییر اندازه و فشرده‌سازی دوباره به JPEG (حداکثر ضلع 2048px) با هدف‌گیری `channels.whatsapp.mediaMaxMb` (پیش‌فرض: 50 MB).
  - **صدا/صوت/ویدیو:** عبور بدون تغییر تا 16 MB؛ صدا به‌صورت یادداشت صوتی (`ptt: true`) ارسال می‌شود.
  - **اسناد:** هر مورد دیگر، تا 100 MB، با حفظ نام فایل در صورت موجود بودن.
- پخش به سبک GIF در WhatsApp: یک MP4 با `gifPlayback: true` ارسال کنید (CLI: `--gif-playback`) تا کلاینت‌های موبایل آن را به‌صورت درون‌خطی تکرار کنند.
- تشخیص MIME ابتدا magic byteها، سپس هدرها، و بعد پسوند فایل را ترجیح می‌دهد.
- کپشن از `--message` یا `reply.text` می‌آید؛ کپشن خالی مجاز است.
- ثبت گزارش: حالت غیرمفصل `↩️`/`✅` را نشان می‌دهد؛ حالت مفصل شامل اندازه و مسیر/URL منبع است.

## خط لوله پاسخ خودکار

- `getReplyFromConfig` مقدار `{ text?, mediaUrl?, mediaUrls? }` را برمی‌گرداند.
- وقتی رسانه وجود دارد، فرستنده وب مسیرهای محلی یا URLها را با همان خط لوله `openclaw message send` حل می‌کند.
- اگر چند ورودی رسانه ارائه شود، به‌ترتیب و پشت سر هم ارسال می‌شوند.

## رسانه ورودی به فرمان‌ها (Pi)

- وقتی پیام‌های وب ورودی شامل رسانه باشند، OpenClaw آن را در یک فایل موقت دانلود می‌کند و متغیرهای قالب‌بندی را در دسترس می‌گذارد:
  - `{{MediaUrl}}` شبه-URL برای رسانه ورودی.
  - `{{MediaPath}}` مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
- وقتی sandbox داکر برای هر نشست فعال باشد، رسانه ورودی در فضای کاری sandbox کپی می‌شود و `MediaPath`/`MediaUrl` به یک مسیر نسبی مانند `media/inbound/<filename>` بازنویسی می‌شوند.
- درک رسانه (اگر از طریق `tools.media.*` یا `tools.media.models` مشترک پیکربندی شده باشد) پیش از قالب‌بندی اجرا می‌شود و می‌تواند بلوک‌های `[Image]`، `[Audio]`، و `[Video]` را در `Body` درج کند.
  - صدا `{{Transcript}}` را تنظیم می‌کند و از رونوشت برای تحلیل فرمان استفاده می‌کند تا فرمان‌های اسلش همچنان کار کنند.
  - توضیحات ویدیو و تصویر هر متن کپشن را برای تحلیل فرمان حفظ می‌کنند.
  - اگر مدل تصویر اصلی فعال از پیش به‌صورت بومی از بینایی پشتیبانی کند، OpenClaw بلوک خلاصه `[Image]` را رد می‌کند و به‌جای آن تصویر اصلی را به مدل می‌فرستد.
- به‌صورت پیش‌فرض فقط نخستین پیوست تصویر/صدا/ویدیوی مطابق پردازش می‌شود؛ برای پردازش چند پیوست، `tools.media.<cap>.attachments` را تنظیم کنید.

## محدودیت‌ها و خطاها

**سقف‌های ارسال خروجی (ارسال وب WhatsApp)**

- تصاویر: تا `channels.whatsapp.mediaMaxMb` (پیش‌فرض: 50 MB) پس از فشرده‌سازی دوباره.
- صدا/صوت/ویدیو: سقف 16 MB؛ اسناد: سقف 100 MB.
- رسانه بیش‌ازحد بزرگ یا ناخوانا → خطای شفاف در گزارش‌ها و پاسخ رد می‌شود.

**سقف‌های درک رسانه (رونویسی/توضیح)**

- پیش‌فرض تصویر: 10 MB (`tools.media.image.maxBytes`).
- پیش‌فرض صدا: 20 MB (`tools.media.audio.maxBytes`).
- پیش‌فرض ویدیو: 50 MB (`tools.media.video.maxBytes`).
- رسانه بیش‌ازحد بزرگ درک را رد می‌کند، اما پاسخ‌ها همچنان با بدنه اصلی عبور می‌کنند.

## نکات برای آزمون‌ها

- جریان‌های ارسال + پاسخ را برای موارد تصویر/صدا/سند پوشش دهید.
- فشرده‌سازی دوباره تصاویر (کران اندازه) و پرچم یادداشت صوتی برای صدا را اعتبارسنجی کنید.
- اطمینان حاصل کنید پاسخ‌های چندرسانه‌ای به‌صورت ارسال‌های ترتیبی منشعب می‌شوند.

## مرتبط

- [ثبت تصویر با دوربین](/fa/nodes/camera)
- [درک رسانه](/fa/nodes/media-understanding)
- [صدا و یادداشت‌های صوتی](/fa/nodes/audio)