پشتیبانی از تصویر و رسانه

کانال 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 منبع است.

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

• 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 یا به‌ازای هر ورودی بازنویسی می‌شود).
• برای رسانه بیش‌ازحد بزرگ، درک رسانه انجام نمی‌شود، اما پاسخ همچنان با بدنه اصلی ارسال می‌شود.

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

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

مرتبط

• ثبت تصویر با دوربین
• درک رسانه
• صدا و پیام‌های صوتی