Mediabegrip

OpenClaw kan inkomende media samenvatten (afbeelding/audio/video) voordat de antwoordpipeline wordt uitgevoerd. Het detecteert automatisch wanneer lokale tools of providersleutels beschikbaar zijn, en kan worden uitgeschakeld of aangepast. Als begrip is uitgeschakeld, ontvangen modellen nog steeds de oorspronkelijke bestanden/URL's zoals gebruikelijk.

Leveranciersspecifiek mediagedrag wordt geregistreerd door vendor plugins, terwijl OpenClaw core de gedeelde tools.media-configuratie, fallbackvolgorde en integratie met de antwoordpipeline beheert.

# Doelen

• Optioneel: inkomende media vooraf verwerken tot korte tekst voor snellere routering en betere opdrachtparsing.
• Oorspronkelijke medialevering aan het model behouden (altijd).
• Provider-API's en CLI-fallbacks ondersteunen.
• Meerdere modellen met geordende fallback toestaan (fout/grootte/time-out).

# Gedrag op hoog niveau

Als begrip faalt of is uitgeschakeld, gaat de antwoordstroom door met de oorspronkelijke body + bijlagen.

# Configuratieoverzicht

tools.media ondersteunt gedeelde modellen plus overrides per mogelijkheid:

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

# Modelvermeldingen

Elke models[]-vermelding kan provider of CLI zijn:

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

# Standaardwaarden en limieten

Aanbevolen standaardwaarden:

• maxChars: 500 voor afbeelding/video (kort, opdrachtvriendelijk)
• maxChars: niet ingesteld voor audio (volledig transcript tenzij je een limiet instelt)
• maxBytes:
  • afbeelding: 10MB
  • audio: 20MB
  • video: 50MB

# Mediabegrip automatisch detecteren (standaard)

Als tools.media.<capability>.enabled niet op false is gezet en je geen modellen hebt geconfigureerd, detecteert OpenClaw automatisch in deze volgorde en stopt bij de eerste werkende optie:

Stel het volgende in om automatische detectie uit te schakelen:

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

# Ondersteuning voor proxy-omgeving (providermodellen)

Wanneer providergebaseerd audio- en video-mediabegrip is ingeschakeld, respecteert OpenClaw standaard uitgaande proxy-omgevingsvariabelen voor provider-HTTP-aanroepen:

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

Als er geen proxy-env-vars zijn ingesteld, gebruikt mediabegrip directe egress. Als de proxywaarde ongeldig is gevormd, logt OpenClaw een waarschuwing en valt het terug op direct ophalen.

# Mogelijkheden (optioneel)

Als je capabilities instelt, draait de vermelding alleen voor die mediatypen. Voor gedeelde lijsten kan OpenClaw standaardwaarden afleiden:

• openai, anthropic, minimax: afbeelding
• minimax-portal: afbeelding
• moonshot: afbeelding + video
• openrouter: afbeelding
• google (Gemini API): afbeelding + audio + video
• qwen: afbeelding + video
• mistral: audio
• zai: afbeelding
• groq: audio
• xai: audio
• deepgram: audio
• Elke models.providers.<id>.models[]-catalogus met een afbeeldingsgeschikt model: afbeelding

Stel voor CLI-vermeldingen capabilities expliciet in om verrassende matches te voorkomen. Als je capabilities weglaat, is de vermelding geschikt voor de lijst waarin deze voorkomt.

# Matrix voor providerondersteuning (OpenClaw-integraties)

# Richtlijnen voor modelselectie

• Geef de voorkeur aan het sterkste beschikbare model van de nieuwste generatie voor elke mediamogelijkheid wanneer kwaliteit en veiligheid belangrijk zijn.
• Vermijd oudere/zwakkere mediamodellen voor tool-enabled agents die niet-vertrouwde invoer verwerken.
• Houd ten minste één fallback per mogelijkheid aan voor beschikbaarheid (kwaliteitsmodel + sneller/goedkoper model).
• CLI-fallbacks (whisper-cli, whisper, gemini) zijn nuttig wanneer provider-API's niet beschikbaar zijn.
• parakeet-mlx-opmerking: met --output-dir leest OpenClaw <output-dir>/<media-basename>.txt wanneer het uitvoerformaat txt is (of niet is opgegeven); niet-txt-formaten vallen terug op stdout.

# Bijlagebeleid

attachments per mogelijkheid bepaalt welke bijlagen worden verwerkt:

Wanneer mode: "all" is, worden uitvoerresultaten gelabeld als [Image 1/2], [Audio 2/2], enzovoort.

# Configuratievoorbeelden

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

# Statusuitvoer

Wanneer mediabegrip wordt uitgevoerd, bevat /status een korte samenvattingsregel:

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

Dit toont resultaten per mogelijkheid en, waar van toepassing, de gekozen provider/het gekozen model.

# Opmerkingen

• Begrip is best-effort. Fouten blokkeren antwoorden niet.
• Bijlagen worden nog steeds aan modellen doorgegeven, zelfs wanneer begrip is uitgeschakeld.
• Gebruik scope om te beperken waar begrip wordt uitgevoerd (bijvoorbeeld alleen DM's).

# Gerelateerd

• Configuratie
• Ondersteuning voor afbeeldingen en media