---
read_when:
    - تغییر خط لولهٔ رسانه یا پیوست‌ها
summary: قواعد مدیریت تصویر و رسانه برای ارسال، Gateway و پاسخ‌های عامل
title: پشتیبانی از تصاویر و رسانه‌ها
x-i18n:
    generated_at: "2026-04-29T23:08:03Z"
    model: gpt-5.5
    provider: openai
    source_hash: 1eb07bc638a755be5597e78c07041a52cfc0297b00d70c5adbfe5f3ad8c1a372
    source_path: nodes/images.md
    workflow: 16
---

# پشتیبانی از تصویر و رسانه (2025-12-05)

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

## اهداف

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

## سطح CLI

- `openclaw message send --media <path-or-url> [--message <caption>]`
  - `--media` اختیاری است؛ کپشن می‌تواند برای ارسال‌های فقط‌رسانه خالی باشد.
  - `--dry-run` محموله resolve‌شده را چاپ می‌کند؛ `--json` مقدار `{ channel, to, messageId, mediaUrl, caption }` را خروجی می‌دهد.

## رفتار کانال WhatsApp Web

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

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

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

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

- وقتی پیام‌های وب ورودی شامل رسانه باشند، OpenClaw آن را در یک فایل موقت دانلود می‌کند و متغیرهای قالب‌سازی را در دسترس می‌گذارد:
  - `{{MediaUrl}}` شبه-URL برای رسانه ورودی.
  - `{{MediaPath}}` مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
- وقتی یک sandbox Docker در سطح هر نشست فعال باشد، رسانه ورودی در workspace مربوط به 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)
