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; alternatif olarak açık modeller yapılandırılabilir. Orijinal 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ın, geri dönüş sırasının ve yanıt işlem hattı entegrasyonunun sahibidir.

Nasıl çalışır?

Yapılandırma

tools.media, yetenek etiketli tek bir model listesinin yanı sıra yetenek başına küçük denetimleri içerir:

{  tools: {    media: {      concurrency: 2, // eşzamanlı maksimum yetenek çalıştırma sayısı (varsayılan)      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

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

İstemler, sınırlar, dil ipuçları, istek geçersiz kılmaları ve sağlayıcı seçenekleri yetenek varsayılanları olarak ayarlanabilir veya ayrı tools.media.models[] girdilerinde geçersiz kılınabilir. Açıkça bir model yapılandırılmadığında yetenek varsayılanları otomatik algılanan sağlayıcıları da kapsar.

Model girdileri

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

{  type: "provider", // belirtilmezse varsayılan  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Görüntüyü <= 500 karakterle açıklayın.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"],  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "{{AttachmentPath}} konumundaki medyayı okuyun ve <= {{MaxChars}} karakterle açıklayın.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

Sağlayıcı kimlik bilgileri

Sağlayıcı medya anlama özelliği, 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 medya, söz konusu modeli atlar ve sonrakini dener.
• 1024 bayttan küçük ses dosyaları boş/bozuk kabul edilir ve transkripsiyondan önce atlanır; bunun yerine aracı deterministik bir yer tutucu transkript alır.
• Etkin birincil görüntü modeli görme yeteneğini zaten yerel olarak destekliyorsa OpenClaw, [Image] özet bloğunu atlar ve orijinal görüntüyü doğrudan modele iletir. MiniMax bir istisnadır: eski MiniMax M2.x sohbet meta verileri görüntü girdisini desteklediğini iddia etse bile minimax, minimax-cn, minimax-portal ve minimax-portal-cn görüntü anlamayı her zaman Plugin'e ait MiniMax-VL-01 medya sağlayıcısı üzerinden yönlendirir (yalnızca MiniMax-M3 ve sonraki sürümler yerel görme 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ışa aktarılmış media://inbound/* referansları olarak korunur.
• Açık openclaw infer image describe --file <path> --model <provider/model> (takma ad: openclaw capability image describe), models.providers.ollama.models[] altında eşleşen, görüntü destekli bir model yapılandırıldığında ollama/qwen2.5vl:7b gibi Ollama referansları dâhil olmak üzere görüntü destekli 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ı söz konusu 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ırasıyla 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ı dâhil 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 olanlara göre önceliklidir. Hiçbiri ayarlanmamışsa medya anlama doğrudan çıkış kullanır; proxy değeri hatalı biçimlendirilmişse OpenClaw bir uyarı günlüğe 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 listeler için OpenClaw, birlikte gelen 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, göründüğü her yetenek listesi için uygun kabul edilir.

Sağlayıcı destek matrisi

Model seçimi rehberi

• Kalite ve güvenlik önemli olduğunda her medya yeteneği için mevcut neslin en güçlü modelini tercih edin.
• Güvenilmeyen girdileri işleyen araç destekli aracılarda eski veya daha zayıf medya modellerinden kaçının.
• Kullanılabilirlik için her yetenek başına en az bir yedek bulundurun (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ı modları belirleyicidir: çıkarılan transkript dosyası boşsa veya yoksa CLI ilerleme çıktısına geri dönülmez ve transkript üretilmez.
• parakeet-mlx: --output-dir ve varsayılan {filename} çıktı şablonuyla --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 değerini 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şlendiğini denetler:

mode: "all" olduğunda çıktılar [Image 1/2], [Audio 2/2] vb. olarak etiketlenir.

Dosya eki çıkarımı

• Çıkarılan 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şaretçileri 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şaretçileri ve meta veriler yine uygulanır.
• Çıkarılabilir metni olmayan bir dosya [No extractable text] alır.
• Bir PDF, oluşturulmuş sayfa görüntülerine geri dönerse OpenClaw bu görüntüleri görsel destekli yanıt modellerine iletir ve dosya bloğundaki [PDF content rendered to images] 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",            "{{AttachmentPath}} konumundaki medyayı okuyun ve <= {{MaxChars}} karakterle açıklayın.",          ],          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", "{{AttachmentPath}}"],          },        ],      },      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",              "{{AttachmentPath}} konumundaki medyayı okuyun ve <= {{MaxChars}} karakterle açıklayın.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-5" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "{{AttachmentPath}} konumundaki medyayı okuyun ve <= {{MaxChars}} karakterle açıklayın.",            ],          },        ],      },    },  },}

{  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:

📎 Medya: görüntü başarılı (openai/gpt-5.6-sol) · ses başarılı (whisper-cli gözlemlenen=metal)

Ön kontrol envanteri için openclaw capability audio providers çalıştırın. Yerel satırlar, yerel yedek kazananı genel sağlayıcı seçiminden, hazırlık durumundan ve ayrı yeterli/istenen/gözlemlenen arka uç alanlarından ayrı olarak gösterir. 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ışı 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 DM'lerde).

İlgili

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