درک رسانه‌ای

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

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

نحوهٔ کار

پیکربندی

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

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

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

گزینه‌های مخصوص Deepgram در providerOptions.deepgram قرار می‌گیرند (فیلد سطح‌بالای deepgram: { detectLanguage, punctuate, smartFormat } منسوخ شده است، اما همچنان خوانده می‌شود).

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

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

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared entries  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",  ],  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 فراتر رود، برای آن مدل نادیده گرفته می‌شود و مدل بعدی امتحان می‌شود.
• فایل‌های صوتی کوچک‌تر از ۱۰۲۴ بایت خالی/خراب در نظر گرفته می‌شوند و پیش از رونویسی نادیده گرفته می‌شوند؛ در عوض، عامل یک رونوشت جای‌نگهدار قطعی دریافت می‌کند.
• اگر مدل اصلی فعال تصویر از بینایی به‌صورت بومی پشتیبانی کند، 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) هنگامی مفیدند که رابط‌های برنامه‌نویسی ارائه‌دهندگان در دسترس نباشند.
• حالت‌های شناخته‌شدهٔ خروجی فایل مرجع قطعی هستند: فایل رونویسی استنباط‌شدهٔ خالی یا مفقود، به‌جای استفاده از خروجی پیشرفت 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" باشد، خروجی‌ها با [تصویر 1/2]، [صدا 2/2] و مانند آن برچسب‌گذاری می‌شوند.

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

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

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

{  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",            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",          ],          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", "{{MediaPath}}"],          },        ],      },      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",              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",            ],          },        ],      },    },  },}

{  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 برای محدودکردن محل اجرای درک استفاده کنید (برای مثال، فقط پیام‌های مستقیم).

مرتبط

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