Medienverständnis

OpenClaw kann eingehende Medien zusammenfassen (Bild/Audio/Video), bevor die Antwort-Pipeline läuft. Es erkennt automatisch, wann lokale Tools oder Provider-Schlüssel verfügbar sind, und kann deaktiviert oder angepasst werden. Wenn das Verständnis deaktiviert ist, erhalten Modelle weiterhin wie üblich die ursprünglichen Dateien/URLs.

Herstellerspezifisches Medienverhalten wird von Vendor-Plugins registriert, während OpenClaw Core die gemeinsame tools.media-Konfiguration, die Fallback-Reihenfolge und die Integration in die Antwort-Pipeline verwaltet.

# Ziele

• Optional: Eingehende Medien vorab zu kurzem Text verdichten, für schnelleres Routing und bessere Befehlsanalyse.
• Ursprüngliche Medienauslieferung an das Modell beibehalten (immer).
• Provider-APIs und CLI-Fallbacks unterstützen.
• Mehrere Modelle mit geordnetem Fallback erlauben (Fehler/Größe/Timeout).

# Allgemeines Verhalten

Wenn das Verständnis fehlschlägt oder deaktiviert ist, läuft der Antwortfluss weiter mit dem ursprünglichen Body und den Anhängen.

# Konfigurationsübersicht

tools.media unterstützt gemeinsame Modelle plus Capability-spezifische Überschreibungen:

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

# Modelleinträge

Jeder models[]-Eintrag kann Provider oder CLI sein:

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

# Standardwerte und Limits

Empfohlene Standardwerte:

• maxChars: 500 für Bild/Video (kurz, befehlsfreundlich)
• maxChars: nicht gesetzt für Audio (vollständiges Transkript, sofern Sie kein Limit setzen)
• maxBytes:
  • Bild: 10MB
  • Audio: 20MB
  • Video: 50MB

# Medienverständnis automatisch erkennen (Standard)

Wenn tools.media.<capability>.enabled nicht auf false gesetzt ist und Sie keine Modelle konfiguriert haben, erkennt OpenClaw automatisch in dieser Reihenfolge und stoppt bei der ersten funktionierenden Option:

Um die automatische Erkennung zu deaktivieren, setzen Sie:

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

# Unterstützung für Proxy-Umgebungen (Provider-Modelle)

Wenn Provider-basiertes Audio- und Video-Medienverständnis aktiviert ist, berücksichtigt OpenClaw standardmäßige Umgebungsvariablen für ausgehende Proxys bei Provider-HTTP-Aufrufen:

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

Wenn keine Proxy-Umgebungsvariablen gesetzt sind, verwendet Medienverständnis direkten Egress. Wenn der Proxy-Wert fehlerhaft formatiert ist, protokolliert OpenClaw eine Warnung und fällt auf direkten Abruf zurück.

# Capabilities (optional)

Wenn Sie capabilities setzen, läuft der Eintrag nur für diese Medientypen. Für gemeinsame Listen kann OpenClaw Standardwerte ableiten:

• openai, anthropic, minimax: Bild
• minimax-portal: Bild
• moonshot: Bild + Video
• openrouter: Bild
• google (Gemini API): Bild + Audio + Video
• qwen: Bild + Video
• mistral: Audio
• zai: Bild
• groq: Audio
• xai: Audio
• deepgram: Audio
• Jeder models.providers.<id>.models[]-Katalog mit einem bildfähigen Modell: Bild

Für CLI-Einträge sollten Sie capabilities explizit setzen, um überraschende Zuordnungen zu vermeiden. Wenn Sie capabilities weglassen, ist der Eintrag für die Liste geeignet, in der er erscheint.

# Provider-Supportmatrix (OpenClaw-Integrationen)

# Anleitung zur Modellauswahl

• Bevorzugen Sie für jede Medien-Capability das stärkste verfügbare Modell der neuesten Generation, wenn Qualität und Sicherheit wichtig sind.
• Vermeiden Sie bei toolfähigen Agenten, die nicht vertrauenswürdige Eingaben verarbeiten, ältere/schwächere Medienmodelle.
• Halten Sie pro Capability mindestens einen Fallback bereit, um die Verfügbarkeit zu sichern (Qualitätsmodell + schnelleres/günstigeres Modell).
• CLI-Fallbacks (whisper-cli, whisper, gemini) sind nützlich, wenn Provider-APIs nicht verfügbar sind.
• Hinweis zu parakeet-mlx: Mit --output-dir liest OpenClaw <output-dir>/<media-basename>.txt, wenn das Ausgabeformat txt ist (oder nicht angegeben wurde); Nicht-txt-Formate fallen auf stdout zurück.

# Anhangsrichtlinie

Capability-spezifisches attachments steuert, welche Anhänge verarbeitet werden:

Bei mode: "all" werden Ausgaben mit [Image 1/2], [Audio 2/2] usw. beschriftet.

# Konfigurationsbeispiele

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

# Statusausgabe

Wenn Medienverständnis ausgeführt wird, enthält /status eine kurze Zusammenfassungszeile:

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

Dies zeigt die Ergebnisse pro Fähigkeit und gegebenenfalls den ausgewählten Provider/das ausgewählte Modell.

# Hinweise

• Das Verständnis erfolgt nach bestem Bemühen. Fehler blockieren Antworten nicht.
• Anhänge werden weiterhin an Modelle übergeben, selbst wenn das Verständnis deaktiviert ist.
• Verwenden Sie scope, um einzuschränken, wo Verständnis ausgeführt wird (z. B. nur DMs).

# Verwandte Themen

• Konfiguration
• Bild- und Medienunterstützung