Medya anlama

OpenClaw, yanıt işlem hattı çalışmadan önce gelen medyayı (görüntü/ses/video) özetleyebilir; böylece komut ayrıştırma ve yönlendirme, ham baytlar yerine kısa metin üzerinden çalışır. Anlama özelliği yerel araçları veya sağlayıcı anahtarlarını otomatik olarak algılar; ayrıca açık modeller de yapılandırabilirsiniz. Özgün medya her zaman her zamanki gibi modele iletilir; anlama başarısız olduğunda veya devre dışı bırakıldığında yanıt akışı değişmeden devam eder.

Sağlayıcı Plugin'leri yetenek meta verilerini (hangi sağlayıcının hangi medya türünü desteklediği, varsayılan model, öncelik) kaydeder. OpenClaw çekirdeği, paylaşılan tools.media yapılandırmasını, geri dönüş sırasını ve yanıt işlem hattı entegrasyonunu yönetir.

Nasıl çalışır?

Yapılandırma

tools.media, paylaşılan bir model listesinin yanı sıra yetenek başına geçersiz kılmaları içerir:

{  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 */},    },  },}

Yetenek başına (image/audio/video) anahtarlar:

Deepgram'e özgü seçenekler providerOptions.deepgram altında yer alır (üst düzey deepgram: { detectLanguage, punctuate, smartFormat } alanı kullanımdan kaldırılmıştır ancak hâlâ okunur).

Model girdileri

Her models[] girdisi bir sağlayıcı girdisi (varsayılan) veya bir CLI girdisidir:

{  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"],}

Sağlayıcı kimlik bilgileri

Sağlayıcı tabanlı medya anlama, normal model çağrılarıyla aynı kimlik doğrulama çözümlemesini kullanır: kimlik doğrulama profilleri, ortam değişkenleri ve ardından models.providers.<providerId>.apiKey. tools.media.*.models[] girdileri satır içi apiKey alanını kabul etmez.

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

Profiller, ortam değişkenleri ve özel temel URL'ler için Araçlar ve özel sağlayıcılar bölümüne bakın.

Kurallar ve davranış

• maxBytes sınırını aşan medyada bu model atlanır ve sonraki model denenir.
• 1024 bayttan küçük ses dosyaları boş/bozuk olarak değerlendirilir ve transkripsiyondan önce atlanır; temsilci bunun yerine deterministik bir yer tutucu transkript alır.
• Etkin birincil görüntü modeli zaten görsel algıyı yerel olarak destekliyorsa OpenClaw, [Görüntü] özet bloğunu atlar ve özgün görüntüyü doğrudan modele iletir. MiniMax bir istisnadır: eski MiniMax M2.x sohbet meta verileri görüntü girdisi desteklediğini belirtse bile minimax, minimax-cn, minimax-portal ve minimax-portal-cn, görüntü anlamayı her zaman Plugin'in yönettiği MiniMax-VL-01 medya sağlayıcısı üzerinden yönlendirir (yalnızca MiniMax-M3 ve sonraki sürümler yerel görsel algı yeteneğine sahip kabul edilir).
• Bir Gateway/WebChat birincil modeli yalnızca metin destekliyorsa görüntü ekleri, görüntü/PDF araçlarının veya yapılandırılmış bir görüntü modelinin eki kaybetmek yerine yine de inceleyebilmesi için dışarı aktarılan media://inbound/* başvuruları olarak korunur.
• Açık openclaw infer image describe --file <path> --model <provider/model> (takma ad: openclaw capability image describe) komutu, models.providers.ollama.models[] altında eşleşen görüntü yetenekli bir model yapılandırıldığında ollama/qwen2.5vl:7b gibi Ollama başvuruları da dahil olmak üzere bu görüntü yetenekli sağlayıcıyı/modeli doğrudan çalıştırır.
• <capability>.enabled, false değilse ancak hiçbir model yapılandırılmamışsa OpenClaw, sağlayıcısı bu yeteneği desteklediğinde etkin yanıt modelini dener.

Otomatik algılama (varsayılan)

tools.media.<capability>.enabled, false değilse ve hiçbir model yapılandırılmamışsa OpenClaw aşağıdakileri sırayla dener ve çalışan ilk seçenekte durur:

Bir yetenek için otomatik algılamayı devre dışı bırakmak üzere:

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

Proxy desteği (ses/video sağlayıcı çağrıları)

Sağlayıcı tabanlı ses ve video anlama, NO_PROXY/no_proxy atlama kuralları dahil standart giden proxy ortam değişkenlerine uyar: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Küçük harfli değişkenler büyük harfli değişkenlerden önceliklidir. Hiçbiri ayarlanmamışsa medya anlama doğrudan çıkış kullanır; proxy değeri hatalı biçimlendirilmişse OpenClaw bir uyarı kaydeder ve doğrudan getirmeye geri döner. Görüntü anlama bu proxy yolundan geçmez.

Yetenekler

Belirli medya türleriyle sınırlamak için bir models[] girdisinde capabilities değerini ayarlayın. Paylaşılan listelerde OpenClaw, paketlenmiş sağlayıcı başına varsayılanları çıkarır:

CLI girdilerinde beklenmedik eşleşmeleri önlemek için capabilities değerini açıkça ayarlayın; belirtilmezse girdi, yer aldığı her yetenek listesi için uygun kabul edilir.

Sağlayıcı destek matrisi

Model seçimi rehberi

• Kalite ve güvenliğin önemli olduğu durumlarda her medya yeteneği için mevcut neslin en güçlü modelini tercih edin.
• Güvenilmeyen girdileri işleyen araç destekli ajanlarda eski veya daha zayıf medya modellerinden kaçının.
• Kullanılabilirlik için her yetenek başına en az bir yedek tutun (kaliteli model + daha hızlı/ucuz model).
• CLI yedekleri (whisper-cli, whisper, gemini), sağlayıcı API'leri kullanılamadığında yardımcı olur.
• Bilinen dosya çıktısı kipleri belirleyicidir: çıkarıldığı varsayılan transkript dosyasının boş veya eksik olması, CLI ilerleme çıktısına geri dönmek yerine hiçbir transkript üretilmemesine neden olur.
• parakeet-mlx: --output-dir ve varsayılan {filename} çıktı şablonuyla birlikte --output-format txt (veya all) kullanın. Üst kaynaklı PARAKEET_OUTPUT_FORMAT ve PARAKEET_OUTPUT_TEMPLATE ortam değişkenleri de dikkate alınır. OpenClaw, <output-dir>/<media-basename>.txt dosyasını okur; varsayılan srt biçimi, diğer biçimler ve özel çıktı şablonları stdout'u kullanmaya devam eder.

Ek politikası

Yetenek başına attachments, hangi eklerin işleneceğini denetler:

mode: "all" olduğunda çıktılar [Görüntü 1/2], [Ses 2/2] vb. biçiminde etiketlenir.

Dosya eki ayıklama

• Ayıklanan dosya metni, medya istemine eklenmeden önce güvenilmeyen harici içerik olarak sarmalanır; bunun için <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> gibi sınır işaretleri ve bir Source: External meta veri satırı kullanılır.
• Bu yol, medya istemini kısa tutmak için uzun SECURITY NOTICE: başlığını kasıtlı olarak atlar; sınır işaretleri ve meta veriler yine uygulanır.
• Ayıklanabilir metni olmayan bir dosya [Ayıklanabilir metin yok] sonucunu alır.
• Bir PDF, oluşturulmuş sayfa görüntülerine geri dönerse OpenClaw bu görüntüleri görme yetenekli yanıt modellerine iletir ve dosya bloğunda [PDF içeriği görüntülere dönüştürüldü] yer tutucusunu korur.

Yapılandırma örnekleri

{  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"],          },        ],      },    },  },}

Durum çıktısı

Medya anlama çalıştığında /status, yetenek başına bir özet satırı içerir:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Ön kontrol envanteri için openclaw capability audio providers komutunu çalıştırın. Yerel satırlar; yerel yedek seçimini, genel sağlayıcı seçiminden ve hazırlık durumundan ayrı olarak gösterir ve yetenekli/istenen/gözlemlenen arka uç alanlarını ayrı tutar. Aynı yerel seçim, bilgilendirici bir doctor bulgusu olarak da kullanılabilir:

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

Notlar

• Anlama, mümkün olan en iyi çabayla gerçekleştirilir. Hatalar yanıtları engellemez.
• Anlama devre dışı bırakılmış olsa bile ekler modellere iletilmeye devam eder.
• Anlamanın nerede çalışacağını sınırlamak için scope kullanın (örneğin yalnızca doğrudan mesajlarda).

İlgili

• Yapılandırma
• Görüntü ve medya desteği