---
read_when:
    - تغییر پایپ‌لاین رسانه یا پیوست‌ها
summary: قواعد مدیریت تصویر و رسانه برای ارسال، Gateway و پاسخ‌های عامل
title: پشتیبانی از تصویر و رسانه
x-i18n:
    generated_at: "2026-07-27T15:23:21Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 71f5591f4268593c142056370802b702899787a79f9ca1fbde6ea8e422f34023
    source_path: nodes/images.md
    workflow: 16
---

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

## اهداف

- ارسال رسانه با زیرنویس اختیاری از طریق `openclaw message send --media`.
- امکان گنجاندن رسانه در کنار متن در پاسخ‌های خودکار صندوق ورودی وب.
- حفظ محدودیت‌های معقول و قابل پیش‌بینی برای هر نوع.

## سطح CLI

`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` نتیجه ارسال مختص کانال، شامل هرگونه ارجاع رسانه، را در بر دارد).

## رفتار کانال وب WhatsApp

- ورودی: مسیر فایل محلی **یا** URL از نوع HTTP(S).
- روند: بارگذاری در یک بافر، تشخیص نوع رسانه و سپس ساخت محموله خروجی متناسب با نوع:
  - **تصاویر:** برای قرارگرفتن زیر `channels.whatsapp.mediaMaxMb` (پیش‌فرض 50MB) بهینه می‌شوند. تصاویر مات مجدداً به JPEG فشرده می‌شوند (نردبان پیش‌فرض اندازه ضلع از 2048px آغاز می‌شود و با هر بار عبور از محدودیت حجم کاهش می‌یابد)؛ تصاویر دارای شفافیت به‌صورت PNG نگه داشته می‌شوند. اگر منبع از قبل JPEG/PNG/WebP قابل‌قبولی در محدوده حجم و طول ضلع باشد، بایت‌های اصلی بدون تغییر حفظ می‌شوند و فشرده‌سازی مجدد انجام نمی‌شود. GIFهای متحرک هرگز دوباره کدگذاری نمی‌شوند و فقط حجمشان بررسی می‌شود.
  - **صدا/پیام صوتی:** مگر اینکه صدا از قبل در قالب بومی پیام صوتی باشد (`.ogg`/`.opus` یا `audio/ogg`/`audio/opus`)؛ صدای خروجی پیش از ارسال به‌صورت پیام صوتی (`ptt: true`) با استفاده از `ffmpeg` به Opus/OGG (تک‌کاناله با 48kHz، نرخ 64kbps و حداکثر مدت 20 دقیقه) تبدیل می‌شود.
  - **ویدئو:** عبور بدون تغییر تا سقف 16MB.
  - **اسناد:** هر مورد دیگر تا سقف 100MB، با حفظ نام فایل در صورت موجودبودن.
- پخش به‌سبک GIF در WhatsApp: یک MP4 با `gifPlayback: true` (CLI:‏ `--gif-playback`) ارسال می‌شود تا کلاینت‌های موبایل آن را به‌صورت درون‌خطی تکرار کنند.
- تشخیص MIME ابتدا بایت‌های جادویی شناسایی‌شده، سپس پسوند فایل و بعد هدرهای پاسخ را ترجیح می‌دهد؛ یک قالب محفظه عمومی شناسایی‌شده (`application/octet-stream`، `zip`) هرگز نگاشت مشخص‌تر پسوند را نادیده نمی‌گیرد (برای مثال XLSX در برابر ZIP).
- زیرنویس از `--message` یا `reply.text` دریافت می‌شود؛ زیرنویس خالی مجاز است.
- گزارش‌گیری: حالت غیرمفصل `↩️`/`✅` را نشان می‌دهد؛ حالت مفصل شامل حجم و مسیر/URL منبع است.

<Note>
مقادیر 16MB برای صدا/ویدئو و 100MB برای سند که در بالا آمده‌اند، پیش‌فرض‌های مشترک رسانه برای هر نوع هستند که در صورت مشخص‌نشدن سقف صریح بایت استفاده می‌شوند. ارسال‌های WhatsApp سقفی صریح را از `channels.whatsapp.mediaMaxMb` (پیش‌فرض 50MB) تعیین می‌کنند که برای آن حساب به‌طور یکسان بر همه انواع اعمال می‌شود.
</Note>

## پایپ‌لاین پاسخ خودکار

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

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

- وقتی پیام‌های ورودی وب شامل رسانه باشند، OpenClaw آن را در یک فایل موقت بارگیری می‌کند و متغیرهای قالب‌سازی زیر را ارائه می‌دهد:
  - `{{AttachmentUrl}}` — URL اصلی یا ارجاع ارائه‌دهنده برای پیوست فعلی.
  - `{{AttachmentPath}}` — مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
  - `{{AttachmentContentType}}` — نوع محتوای MIME.
  - `{{AttachmentDir}}` — دایرکتوری حاوی مسیر محلی.
  - `{{AttachmentIndex}}` — نمایه واقعیت منبع با مبدأ صفر.
- وقتی محیط ایزوله Docker برای هر نشست فعال باشد، رسانه ورودی به فضای کاری محیط ایزوله کپی می‌شود و مسیر/ارجاع پیوست به مسیری نسبی نسبت به محیط ایزوله مانند `media/inbound/<filename>` بازنویسی می‌شود.
- `{{MediaPath}}`، `{{MediaUrl}}`، `{{MediaType}}` و `{{MediaDir}}` در طول بازه مهاجرت SDK افزونه، به‌عنوان نام‌های مستعار سازگاری منسوخ باقی می‌مانند.
- درک رسانه (پیکربندی‌شده از طریق `tools.media.*` یا `tools.media.models` مشترک) پیش از قالب‌سازی اجرا می‌شود و می‌تواند بلوک‌های `[Image]`، `[Audio]` و `[Video]` را در `Body` درج کند.
  - صدا `{{Transcript}}` را تنظیم می‌کند و از رونوشت برای تجزیه فرمان استفاده می‌کند تا فرمان‌های اسلش همچنان کار کنند.
  - توضیحات ویدئو و تصویر هرگونه متن زیرنویس را برای تجزیه فرمان حفظ می‌کنند.
  - اگر مدل اصلی فعال از قبل به‌صورت بومی از بینایی پشتیبانی کند، OpenClaw از بلوک خلاصه `[Image]` صرف‌نظر می‌کند و در عوض تصویر اصلی را به مدل می‌فرستد.
- به‌طور پیش‌فرض فقط نخستین پیوست منطبق تصویر/صدا/ویدئو پردازش می‌شود؛ برای انتخاب چند پیوست از `tools.media.<capability>.attachments` استفاده کنید.

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

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

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

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

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

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

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

## مرتبط

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