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

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

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

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

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

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

مرتبط

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