درک رسانه‌ها

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[] می‌تواند ارائه‌دهنده یا 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: برای صدا تنظیم‌نشده (transcript کامل مگر اینکه محدودیت تعیین کنید)
• maxBytes:
  • تصویر: 10MB
  • صدا: 20MB
  • ویدئو: 50MB

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# policy پیوست

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

# مرتبط

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