درک رسانه

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

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

اهداف

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

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

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

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

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

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

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

هر ورودی models[] می‌تواند provider یا 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"],}

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

فهم رسانه توسط ارائه‌دهنده از همان resolve کردن auth ارائه‌دهنده استفاده می‌کند که در فراخوانی‌های عادی مدل استفاده می‌شود: auth profileها، متغیرهای محیطی، سپس models.providers.<providerId>.apiKey.

ورودی‌های tools.media.*.models[] فیلد inline با نام apiKey را نمی‌پذیرند. مقدار provider در ورودی مدل رسانه، مانند openai یا moonshot، باید از طریق یکی از منابع استاندارد auth ارائه‌دهنده اعتبارنامه در دسترس داشته باشد.

نمونه حداقلی:

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

برای مرجع کامل auth ارائه‌دهنده، شامل profileها، متغیرهای محیطی، و base URLهای سفارشی، ابزارها و ارائه‌دهنده‌های سفارشی را ببینید.

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

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

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

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

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

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

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

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

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

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

اگر هیچ متغیر محیطی proxy تنظیم نشده باشد، فهم رسانه از egress مستقیم استفاده می‌کند. اگر مقدار proxy malformed باشد، OpenClaw یک هشدار log می‌کند و به fetch مستقیم fallback می‌کند.

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

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

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

برای ورودی‌های CLI، برای جلوگیری از matchهای غافلگیرکننده، 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 برای محدود کردن محل اجرای درک استفاده کنید (مثلاً فقط پیام‌های خصوصی).

مرتبط

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