درک رسانه‌ها

OpenClaw می‌تواند رسانه‌های ورودی (تصویر/صوت/ویدئو) را پیش از اجرای پایپ‌لاین پاسخ خلاصه کند تا تجزیهٔ فرمان و مسیریابی به‌جای بایت‌های خام بر اساس متنی کوتاه انجام شود. قابلیت درک، ابزارهای محلی یا کلیدهای ارائه‌دهنده را به‌طور خودکار شناسایی می‌کند؛ همچنین می‌توان مدل‌های مشخصی را پیکربندی کرد. رسانهٔ اصلی همیشه طبق روال معمول به مدل تحویل داده می‌شود؛ اگر درک ناموفق یا غیرفعال باشد، جریان پاسخ بدون تغییر ادامه می‌یابد.

Pluginهای فروشندگان، فرادادهٔ قابلیت‌ها را ثبت می‌کنند (اینکه کدام ارائه‌دهنده از کدام نوع رسانه پشتیبانی می‌کند، مدل پیش‌فرض و اولویت). هستهٔ OpenClaw مالک پیکربندی مشترک tools.media، ترتیب بازگشت و یکپارچه‌سازی پایپ‌لاین پاسخ است.

نحوهٔ کار

پیکربندی

tools.media شامل یک فهرست مدل برچسب‌گذاری‌شده بر اساس قابلیت، به‌همراه کنترل‌های کوچک مختص هر قابلیت است:

{  tools: {    media: {      concurrency: 2, // حداکثر اجرای هم‌زمان قابلیت‌ها (پیش‌فرض)      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

کلیدهای مختص هر قابلیت (image/audio/video):

اعلان‌ها، محدودیت‌ها، راهنماهای زبان، بازنویسی‌های درخواست و گزینه‌های ارائه‌دهنده را می‌توان به‌عنوان پیش‌فرض قابلیت تنظیم کرد یا در ورودی‌های منفرد tools.media.models[] بازنویسی کرد. هنگامی که هیچ مدل مشخصی پیکربندی نشده باشد، پیش‌فرض‌های قابلیت ارائه‌دهندگان شناسایی‌شده به‌طور خودکار را نیز پوشش می‌دهند.

ورودی‌های مدل

هر ورودی models[] یک ورودی ارائه‌دهنده (پیش‌فرض) یا ورودی CLI است:

{  type: "provider", // در صورت حذف، پیش‌فرض است  provider: "openai",  model: "gpt-5.6-sol",  prompt: "تصویر را در حداکثر 500 نویسه توصیف کنید.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"],  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "رسانهٔ موجود در {{AttachmentPath}} را بخوانید و آن را در حداکثر {{MaxChars}} نویسه توصیف کنید.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

اعتبارنامه‌های ارائه‌دهنده

درک رسانه توسط ارائه‌دهنده از همان فرایند حل احراز هویت فراخوانی‌های عادی مدل استفاده می‌کند: نمایه‌های احراز هویت، متغیرهای محیطی و سپس models.providers.<providerId>.apiKey. ورودی‌های tools.media.models[] فیلد درون‌خطی apiKey را نمی‌پذیرند.

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

برای نمایه‌ها، متغیرهای محیطی و URLهای پایهٔ سفارشی، به ابزارها و ارائه‌دهندگان سفارشی مراجعه کنید.

قواعد و رفتار

• رسانه‌ای که اندازه‌اش از maxBytes بیشتر باشد، برای آن مدل نادیده گرفته می‌شود و مدل بعدی امتحان می‌شود.
• فایل‌های صوتی کوچک‌تر از 1024 بایت، خالی/خراب در نظر گرفته می‌شوند و پیش از رونویسی نادیده گرفته می‌شوند؛ در عوض، عامل یک رونوشت جایگزین قطعی دریافت می‌کند.
• اگر مدل اصلی فعال تصویر از قبل به‌صورت بومی از بینایی پشتیبانی کند، OpenClaw بلوک خلاصهٔ [Image] را نادیده می‌گیرد و تصویر اصلی را مستقیماً به مدل می‌دهد. MiniMax یک استثنا است: minimax، minimax-cn، minimax-portal و minimax-portal-cn همیشه درک تصویر را از طریق ارائه‌دهندهٔ رسانهٔ MiniMax-VL-01 تحت مالکیت Plugin مسیریابی می‌کنند، حتی اگر فرادادهٔ قدیمی گفت‌وگوی MiniMax M2.x مدعی ورودی تصویر باشد (فقط MiniMax-M3 و نسخه‌های بعدی به‌عنوان مدل‌های دارای قابلیت بینایی بومی در نظر گرفته می‌شوند).
• اگر مدل اصلی Gateway/WebChat فقط متنی باشد، پیوست‌های تصویر به‌شکل ارجاع‌های برون‌سپاری‌شدهٔ media://inbound/* حفظ می‌شوند تا ابزارهای تصویر/PDF یا یک مدل تصویر پیکربندی‌شده همچنان بتوانند آن‌ها را بررسی کنند و پیوست از دست نرود.
• مقدار صریح openclaw infer image describe --file <path> --model <provider/model> (نام مستعار: openclaw capability image describe) آن ارائه‌دهنده/مدل دارای قابلیت تصویر را مستقیماً اجرا می‌کند؛ از جمله ارجاع‌های Ollama مانند ollama/qwen2.5vl:7b، هنگامی که یک مدل منطبق دارای قابلیت تصویر در models.providers.ollama.models[] پیکربندی شده باشد.
• اگر <capability>.enabled برابر با false نباشد اما هیچ مدلی پیکربندی نشده باشد، OpenClaw هنگامی که ارائه‌دهندهٔ مدل پاسخ فعال از قابلیت موردنظر پشتیبانی کند، آن مدل را امتحان می‌کند.

شناسایی خودکار (پیش‌فرض)

هنگامی که tools.media.<capability>.enabled برابر با false نباشد و هیچ مدلی پیکربندی نشده باشد، OpenClaw گزینه‌های زیر را به‌ترتیب امتحان می‌کند و در نخستین گزینهٔ عملی متوقف می‌شود:

برای غیرفعال‌کردن شناسایی خودکار یک قابلیت:

{  tools: {    media: {      audio: {        enabled: false,      },    },  },}

پشتیبانی از پراکسی (فراخوانی‌های ارائه‌دهندهٔ صوت/ویدئو)

درک مبتنی بر ارائه‌دهنده برای صوت و ویدئو از متغیرهای محیطی استاندارد پراکسی خروجی، از جمله قواعد دورزدن NO_PROXY/no_proxy، پیروی می‌کند: HTTPS_PROXY، HTTP_PROXY، ALL_PROXY، https_proxy، http_proxy، all_proxy. متغیرهای حروف کوچک بر حروف بزرگ اولویت دارند. اگر هیچ‌کدام تنظیم نشده باشند، درک رسانه از خروج مستقیم استفاده می‌کند؛ اگر مقدار پراکسی بدشکل باشد، OpenClaw هشداری ثبت می‌کند و به دریافت مستقیم بازمی‌گردد. درک تصویر از این مسیر پراکسی عبور نمی‌کند.

قابلیت‌ها

برای محدودکردن یک ورودی models[] به انواع مشخصی از رسانه، capabilities را روی آن تنظیم کنید. برای فهرست‌های مشترک، OpenClaw پیش‌فرض‌ها را برای هر ارائه‌دهندهٔ همراه استنتاج می‌کند:

برای ورودی‌های CLI، مقدار capabilities را صریحاً تنظیم کنید تا از تطبیق‌های غیرمنتظره جلوگیری شود؛ اگر حذف شود، ورودی برای هر فهرست قابلیتی که در آن ظاهر می‌شود واجد شرایط است.

ماتریس پشتیبانی ارائه‌دهندگان

راهنمای انتخاب مدل

• هنگامی که کیفیت و ایمنی اهمیت دارد، برای هر قابلیت رسانه‌ای قوی‌ترین مدل نسل فعلی را ترجیح دهید.
• برای عامل‌های مجهز به ابزار که ورودی‌های نامطمئن را مدیریت می‌کنند، از مدل‌های رسانه‌ای قدیمی‌تر یا ضعیف‌تر اجتناب کنید.
• برای دسترس‌پذیری، دست‌کم یک مدل جایگزین برای هر قابلیت نگه دارید (مدل باکیفیت + مدل سریع‌تر/ارزان‌تر).
• مدل‌های جایگزین CLI (whisper-cli، whisper، gemini) هنگام در دسترس نبودن APIهای ارائه‌دهنده کمک می‌کنند.
• حالت‌های شناخته‌شده خروجی فایل مرجع قطعی هستند: فایل رونویسی استنباط‌شده خالی یا مفقود، به‌جای بازگشت به خروجی پیشرفت CLI، هیچ رونویسی‌ای تولید نمی‌کند.
• parakeet-mlx: از --output-format txt (یا all) همراه با --output-dir و الگوی خروجی پیش‌فرض {filename} استفاده کنید. متغیرهای محیطی بالادستی PARAKEET_OUTPUT_FORMAT و PARAKEET_OUTPUT_TEMPLATE نیز رعایت می‌شوند. OpenClaw مقدار <output-dir>/<media-basename>.txt را می‌خواند؛ قالب پیش‌فرض srt، قالب‌های دیگر و الگوهای خروجی سفارشی همچنان از stdout استفاده می‌کنند.

خط‌مشی پیوست‌ها

attachments مخصوص هر قابلیت تعیین می‌کند کدام پیوست‌ها پردازش شوند:

هنگامی که mode: "all"، خروجی‌ها با [Image 1/2]، [Audio 2/2] و موارد مشابه برچسب‌گذاری می‌شوند.

استخراج پیوست فایل

• متن استخراج‌شده فایل، پیش از افزوده‌شدن به پرامپت رسانه، به‌عنوان محتوای خارجی نامطمئن محصور می‌شود و از نشانگرهای مرزی مانند <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> به‌همراه یک خط فراداده Source: External استفاده می‌کند.
• این مسیر عمداً بنر طولانی SECURITY NOTICE: را حذف می‌کند تا پرامپت رسانه کوتاه بماند؛ نشانگرهای مرزی و فراداده همچنان اعمال می‌شوند.
• فایلی که هیچ متن قابل‌استخراجی ندارد، [No extractable text] را دریافت می‌کند.
• اگر یک PDF به تصاویر رندرشده صفحات بازگردد، OpenClaw آن تصاویر را به مدل‌های پاسخ‌گوی دارای قابلیت بینایی ارسال می‌کند و جای‌نگهدار [PDF content rendered to images] را در بلوک فایل نگه می‌دارد.

نمونه‌های پیکربندی

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", capabilities: ["image"] },        {          provider: "google",          model: "gemini-3-flash-preview",          capabilities: ["image", "audio", "video"],        },        {          type: "cli",          command: "gemini",          args: [            "-m",            "gemini-3-flash",            "--allowed-tools",            "read_file",            "رسانه موجود در {{AttachmentPath}} را بخوانید و آن را در <= {{MaxChars}} نویسه توصیف کنید.",          ],          capabilities: ["image", "video"],        },      ],      audio: {        attachments: { mode: "all", maxAttachments: 2 },      },      video: {        maxChars: 500,      },    },  },}

{  tools: {    media: {      audio: {        enabled: true,        models: [          { provider: "openai", model: "gpt-4o-mini-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{AttachmentPath}}"],          },        ],      },      video: {        enabled: true,        maxChars: 500,        models: [          { provider: "google", model: "gemini-3-flash-preview" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "رسانه موجود در {{AttachmentPath}} را بخوانید و آن را در <= {{MaxChars}} نویسه توصیف کنید.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-5" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "رسانه موجود در {{AttachmentPath}} را بخوانید و آن را در <= {{MaxChars}} نویسه توصیف کنید.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        models: [          {            provider: "google",            model: "gemini-3.1-pro-preview",            capabilities: ["image", "video", "audio"],          },        ],      },      audio: {        models: [          {            provider: "google",            model: "gemini-3.1-pro-preview",            capabilities: ["image", "video", "audio"],          },        ],      },      video: {        models: [          {            provider: "google",            model: "gemini-3.1-pro-preview",            capabilities: ["image", "video", "audio"],          },        ],      },    },  },}

خروجی وضعیت

هنگام اجرای درک رسانه، /status شامل یک خط خلاصه برای هر قابلیت است:

📎 رسانه: تصویر موفق (openai/gpt-5.6-sol) · صدا موفق (whisper-cli مشاهده‌شده=metal)

برای فهرست‌برداری پیش از اجرا، openclaw capability audio providers را اجرا کنید. ردیف‌های محلی، گزینه جایگزین برنده محلی را جدا از انتخاب سراسری ارائه‌دهنده، آمادگی و فیلدهای مجزای بک‌اند دارای قابلیت/درخواستی/مشاهده‌شده نشان می‌دهند. همین انتخاب محلی به‌صورت یک یافته اطلاعاتی doctor نیز در دسترس است:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

نکات

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

مطالب مرتبط

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