درک رسانه‌ها

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

رفتار رسانه‌ای اختصاصی فروشنده‌ها توسط Pluginهای فروشنده ثبت می‌شود، در حالی که هستهٔ OpenClaw مالک پیکربندی مشترک tools.media، ترتیب بازگشت جایگزین، و یکپارچه‌سازی با پایپ‌لاین پاسخ است.

اهداف

• اختیاری: پیش‌هضم رسانه‌های ورودی به متن کوتاه برای مسیریابی سریع‌تر + تجزیهٔ بهتر فرمان.
• حفظ ارسال رسانهٔ اصلی به مدل (همیشه).
• پشتیبانی از APIهای ارائه‌دهنده و جایگزین‌های CLI.
• اجازهٔ استفاده از چند مدل با بازگشت جایگزین ترتیبی (خطا/اندازه/مهلت زمانی).

رفتار سطح بالا

اگر فهم رسانه شکست بخورد یا غیرفعال باشد، جریان پاسخ ادامه پیدا می‌کند با بدنه + پیوست‌های اصلی.

نمای کلی پیکربندی

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

{  tools: {    media: {      models: [        /* shared list */      ],      image: {        /* optional overrides */      },      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {        /* optional overrides */      },    },  },}

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

هر ورودی models[] می‌تواند ارائه‌دهنده یا CLI باشد:

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.5",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, used for multi-modal 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"],}

پیش‌فرض‌ها و محدودیت‌ها

پیش‌فرض‌های پیشنهادی:

• maxChars: 500 برای تصویر/ویدیو (کوتاه، مناسب فرمان)
• maxChars: برای صدا تنظیم‌نشده (متن کامل پیاده‌سازی‌شده مگر اینکه حدی تعیین کنید)
• maxBytes:
  • تصویر: 10MB
  • صدا: 20MB
  • ویدیو: 50MB

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

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

برای غیرفعال کردن تشخیص خودکار، تنظیم کنید:

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

پشتیبانی از محیط پراکسی (مدل‌های ارائه‌دهنده)

وقتی فهم رسانهٔ صدا و ویدیو مبتنی بر ارائه‌دهنده فعال باشد، OpenClaw متغیرهای محیطی استاندارد پراکسی خروجی را برای فراخوانی‌های HTTP ارائه‌دهنده رعایت می‌کند:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

اگر هیچ متغیر محیطی پراکسی تنظیم نشده باشد، فهم رسانه از خروج مستقیم استفاده می‌کند. اگر مقدار پراکسی بدشکل باشد، OpenClaw هشدار ثبت می‌کند و به واکشی مستقیم بازمی‌گردد.

قابلیت‌ها (اختیاری)

اگر capabilities را تنظیم کنید، ورودی فقط برای آن نوع‌های رسانه اجرا می‌شود. برای فهرست‌های مشترک، OpenClaw می‌تواند پیش‌فرض‌ها را استنباط کند:

• openai, anthropic, minimax: تصویر
• minimax-portal: تصویر
• moonshot: تصویر + ویدیو
• openrouter: تصویر + صدا
• google (Gemini API): تصویر + صدا + ویدیو
• qwen: تصویر + ویدیو
• mistral: صدا
• zai: تصویر
• groq: صدا
• xai: صدا
• deepgram: صدا
• هر کاتالوگ models.providers.<id>.models[] با مدل دارای قابلیت تصویر: تصویر

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

ماتریس پشتیبانی ارائه‌دهنده (یکپارچه‌سازی‌های OpenClaw)

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

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

سیاست پیوست

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

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

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

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.5", 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.5" },          { provider: "anthropic", model: "claude-opus-4-6" },          {            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 شامل یک خط خلاصهٔ کوتاه است:

📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)

این، نتیجه‌ها را برای هر قابلیت و در صورت کاربرد، ارائه‌دهنده/مدل انتخاب‌شده را نشان می‌دهد.

نکته‌ها

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

مرتبط

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