---
read_when:
    - تغییر خط لولهٔ رسانه یا پیوست‌ها
summary: قواعد مدیریت تصویر و رسانه برای ارسال، Gateway و پاسخ‌های عامل
title: پشتیبانی از تصویر و رسانه
x-i18n:
    generated_at: "2026-07-12T10:18:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 41d5bbd174b4fb35b616a9e90930485fd76dc8cfbad2e178f0823e6fb40c36f8
    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

- ورودی: مسیر فایل محلی **یا** نشانی 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، با سقف ۲۰ دقیقه) تبدیل می‌شود.
  - **ویدئو:** عبور مستقیم تا سقف 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 آن را در یک فایل موقت بارگیری می‌کند و متغیرهای قالب زیر را در دسترس قرار می‌دهد:
  - `{{MediaUrl}}` — نشانی شبه‌URL برای رسانه ورودی.
  - `{{MediaPath}}` — مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
- وقتی محیط ایزوله Docker برای هر نشست فعال باشد، رسانه ورودی در فضای کاری محیط ایزوله کپی می‌شود و `MediaPath`/`MediaUrl` به مسیری نسبی در محیط ایزوله، مانند `media/inbound/<filename>`، بازنویسی می‌شوند.
- درک رسانه (که از طریق `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`).
- پیش‌فرض صوت: 20MB (`tools.media.audio.maxBytes`).
- پیش‌فرض ویدئو: 50MB (`tools.media.video.maxBytes`).
- درک رسانه‌های بیش‌ازحد بزرگ انجام نمی‌شود، اما پاسخ همچنان با بدنه اصلی ارسال می‌شود.

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

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

## مرتبط

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