3 Methoden zur Behebung von Fehlern bei der Bilderkennung von Gemini durch OpenClaw: Häufige Fehlermeldungen im OpenAI-Kompatibilitätsmodus und Konfigurationsleitfaden für das native Format

Die Verwendung des OpenAI-Kompatibilitätsmodus in OpenClaw für die Bilderkennung mit Gemini-Modellen führt häufig zu Fehlermeldungen – ein bekanntes Problem für viele Entwickler, die multimodale KI-Agenten konfigurieren. Dieser Artikel analysiert die Grundursache der Fehlermeldung „Invalid JSON payload“ und bietet drei bewährte Lösungen, um Fehler bei der Gemini-Bilderkennung in OpenClaw schnell zu beheben.

Kernnutzen: Nach dem Lesen dieses Artikels verstehen Sie die entscheidenden Unterschiede zwischen dem OpenAI-Kompatibilitätsmodus und der nativen Gemini-API, beherrschen die korrekte Konfiguration und können Probleme bei der Bilderkennung dauerhaft lösen.

Fehlersymptome bei der Gemini-Bilderkennung in OpenClaw

Nach der Konfiguration des Gemini-Modells in OpenClaw treten bei der Bilderkennung im Backend-Log häufig folgende typische Fehlermeldungen auf:

Invalid JSON payload received. Unknown name "patternProperties"
at 'tools[0].function_declarations[3].parameters.properties[4].value':
Cannot find field.

Invalid JSON payload received. Unknown name "const"
at 'tools[0].function_declarations[37].parameters.properties[0].value':
Cannot find field.

Hauptmerkmale des Fehlers bei der Gemini-Bilderkennung in OpenClaw

Schnelldiagnose bei Fehlern der Gemini-Bilderkennung in OpenClaw

Ein häufiges Missverständnis ist die Annahme, dass die Bilderkennungsfähigkeit von Gemini fehlerhaft sei. Tatsächlich funktioniert die Bilderkennung einwandfrei, wenn man die offizielle visuelle Demo-API von Gemini verwendet. Das Problem liegt in der inkompatiblen Formatierung, wenn OpenClaw die Anfrage über den OpenAI-Kompatibilitätsmodus weiterleitet.

Die Überprüfung ist einfach:

# Direkter Aufruf der Gemini-API zum Testen der Bilderkennung — funktioniert einwandfrei
import google.generativeai as genai
import PIL.Image

genai.configure(api_key="YOUR_GEMINI_API_KEY")
model = genai.GenerativeModel("gemini-2.5-flash")

image = PIL.Image.open("test.jpg")
response = model.generate_content(["Beschreibe dieses Bild", image])
print(response.text)  # ✅ Korrekte Ausgabe der Bildbeschreibung

🎯 Diagnose-Empfehlung: Wenn Sie in OpenClaw Probleme mit der Gemini-Bilderkennung haben, stellen Sie zuerst mit der oben genannten Methode sicher, dass der API-Schlüssel und das Modell selbst einwandfrei funktionieren. Über die Plattform APIYI (apiyi.com) können Sie die visuelle Erkennungsfähigkeit von Gemini ebenfalls schnell testen; die Plattform kümmert sich automatisch um die Kompatibilität der Formate.

Analyse der Grundursache für das Scheitern der Bilderkennung bei OpenClaw Gemini

Um das Problem effektiv zu lösen, müssen wir zunächst die Ursache verstehen. Der Kern des Problems bei der Bilderkennung von Gemini über OpenClaw liegt in einer Inkompatibilität des JSON-Schemas.

Unterschiede im JSON-Schema bei OpenAI- und Gemini-Tool-Aufrufen

Wenn OpenClaw den OpenAI-Kompatibilitätsmodus (openai-completions) verwendet, um Gemini aufzurufen, sieht der Anforderungsprozess wie folgt aus:

OpenClaw erstellt Anfrage (OpenAI-Format)
    ↓
Enthält JSON-Schema für Tool-Definitionen
    ↓
Senden an den OpenAI-kompatiblen Endpunkt von Gemini
    ↓
Gemini analysiert function_declarations
    ↓
❌ Nicht unterstütztes Schema-Feld gefunden → 400-Fehler

Liste der von der Gemini API nicht unterstützten JSON-Schema-Felder

Dies ist der Kern des Problems. Die Unterstützung von JSON-Schemata durch die function_declarations von Gemini ist eine eingeschränkte Teilmenge. Die folgenden Felder führen direkt zu einem 400-Fehler:

Warum der Wechsel zu GPT-5.4 das Problem löst

Dies bestätigt die Analyse der Grundursache. Wenn das Modell in OpenClaw von Gemini auf GPT-5.4 umgestellt wird, funktioniert die Bilderkennung sofort wieder einwandfrei. Der Grund: Die API von GPT-5.4 unterstützt nativ die vollständige JSON-Schema-Spezifikation, wodurch das von OpenClaw generierte Schema für die Tool-Definitionen vollständig kompatibel ist.

📌 Wichtige Erkenntnis: Dies ist kein Problem der Bilderkennungsfähigkeit von Gemini, sondern liegt daran, dass das vom OpenAI-Kompatibilitätsmodus von OpenClaw gesendete Tool-Schema nicht mit den Formatvorgaben der Gemini-API übereinstimmt.

Lösung 1: Wechsel zum nativen Gemini-Format (Empfohlen)

Die gründlichste Lösung besteht darin, den API-Schnittstellentyp für Gemini in OpenClaw von openai-completions auf das native Format google-generative-ai umzustellen.

Konfigurationsschritte

Vor der Änderung (OpenAI-Kompatibilitätsmodus — fehleranfällig):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
  "api": "openai-completions",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Nach der Änderung (Gemini-natives Format — empfohlen):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
  "api": "google-generative-ai",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Kernänderungen bei der Konfiguration des nativen Formats

Schneller Wechsel über die OpenClaw CLI

# Methode 1: Gemini-Konfiguration neu initialisieren
openclaw onboard --auth-choice gemini-api-key

# Methode 2: Konfigurationsdatei manuell bearbeiten
# Speicherort der Konfigurationsdatei: ~/.openclaw/config.json
# Ändern Sie das Feld api von "openai-completions" zu "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY",
      "models": {
        "gemini-2.5-flash": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": false
        },
        "gemini-2.5-pro": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": true,
          "thinkingBudget": 8192
        }
      }
    }
  }
}

🚀 Schnellstart: Wenn Sie sich nicht manuell mit Kompatibilitätsproblemen bei der Konfiguration befassen möchten, empfehlen wir die Nutzung der einheitlichen Schnittstelle der Plattform APIYI (apiyi.com). Die Plattform konvertiert Anfragen im OpenAI-Format automatisch in das native Gemini-Format, sodass sich Entwickler nicht um Schema-Unterschiede kümmern müssen.

Lösung 2: Automatische Kompatibilitätsbehandlung über einen API-Proxy-Dienst

Wenn Sie in OpenClaw weiterhin den OpenAI-Kompatibilitätsmodus für verschiedene Modelle (einschließlich Gemini) verwenden möchten, können Sie das Problem der Formatkompatibilität über einen API-Proxy-Dienst lösen.

Funktionsweise des Proxy-Dienstes

OpenClaw (Anfrage im OpenAI-Format)
    ↓
API-Proxy-Dienst (z. B. APIYI)
    ↓ Automatische Bereinigung inkompatibler JSON-Schema-Felder
    ↓ Automatische Konvertierung des Anfrageformats
Gemini API (natives Format)
    ↓
✅ Korrekte Rückgabe der Bilderkennungsergebnisse

Konfigurationsbeispiel

# Aufruf der Gemini-Bilderkennung über den APIYI-Proxy-Dienst
import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI einheitliche Schnittstelle
)

# Bild lesen und kodieren
with open("test.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Beschreibe den Inhalt dieses Bildes"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

Vergleich: Proxy-Dienst vs. Direktverbindung

Konfiguration des APIYI-Proxys in OpenClaw:

{
  "provider": "apiyi",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://api.apiyi.com/v1",
  "api": "openai-completions",
  "apiKey": "YOUR_APIYI_KEY"
}

💡 Empfehlung: Wenn Sie in OpenClaw mehrere Modelle gleichzeitig verwenden (GPT-5.4, Claude, Gemini usw.), ist die zentrale Verwaltung der Modellaufrufe über APIYI (apiyi.com) die effizientere Wahl, um für jedes Modell unterschiedliche API-Formate zu vermeiden.

Lösung 3: Manuelle Bereinigung inkompatibler JSON-Schema-Felder

Wenn Sie Kompatibilitätsprobleme auf Code-Ebene lösen müssen, können Sie die von Gemini nicht unterstützten JSON-Schema-Felder manuell bereinigen, bevor Sie die Anfrage senden.

Funktion zur Bereinigung des JSON-Schemas

def clean_schema_for_gemini(schema: dict) -> dict:
    """Bereinigt JSON-Schema-Felder, die von Gemini nicht unterstützt werden"""
    unsupported_keys = {
        "patternProperties",
        "const",
        "additionalProperties",
        "$schema",
        "exclusiveMaximum",
        "exclusiveMinimum",
        "propertyNames",
    }

    if isinstance(schema, dict):
        return {
            k: clean_schema_for_gemini(v)
            for k, v in schema.items()
            if k not in unsupported_keys
        }
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

import openai
import json

def clean_schema_for_gemini(schema):
    """Rekursive Bereinigung von JSON-Schema-Feldern, die von Gemini nicht unterstützt werden"""
    unsupported_keys = {
        "patternProperties", "const", "additionalProperties",
        "$schema", "exclusiveMaximum", "exclusiveMinimum",
        "propertyNames", "if", "then", "else",
        "allOf", "anyOf", "oneOf", "not",
    }

    if isinstance(schema, dict):
        cleaned = {}
        for k, v in schema.items():
            if k not in unsupported_keys:
                cleaned[k] = clean_schema_for_gemini(v)
        return cleaned
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

def clean_tools_for_gemini(tools):
    """Bereinigt alle Schemas in der Tool-Liste"""
    cleaned_tools = []
    for tool in tools:
        tool_copy = json.loads(json.dumps(tool))
        if "function" in tool_copy:
            params = tool_copy["function"].get("parameters", {})
            tool_copy["function"]["parameters"] = clean_schema_for_gemini(params)
        cleaned_tools.append(tool_copy)
    return cleaned_tools

# Anwendungsbeispiel
tools = [
    {
        "type": "function",
        "function": {
            "name": "analyze_image",
            "description": "Analysiert den Bildinhalt",
            "parameters": {
                "type": "object",
                "properties": {
                    "image_url": {"type": "string"},
                    "detail": {"type": "string", "const": "high"}  # Wird von Gemini nicht unterstützt
                },
                "patternProperties": {"^x-": {"type": "string"}},  # Wird von Gemini nicht unterstützt
                "additionalProperties": False  # Wird von Gemini nicht unterstützt
            }
        }
    }
]

# Aufruf nach der Bereinigung
cleaned_tools = clean_tools_for_gemini(tools)

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello"}],
    tools=cleaned_tools
)

⚠️ Hinweis: Der Ansatz der manuellen Schema-Bereinigung erfordert, dass Sie die Parameterdefinitionen für jedes Tool einzeln bearbeiten, was mit einem hohen Wartungsaufwand verbunden ist. Wenn Sie viele Tools verwenden oder diese häufig ändern, empfehlen wir Lösung 1 (natives Format) oder Lösung 2 (API-Proxy-Dienst).

Vergleich der 3 Lösungen und Empfehlungen zur Auswahl

Entscheidungsbaum für die Auswahl

• Verwendung von Gemini nur in OpenClaw → Lösung 1 (natives Format), am stabilsten
• Mischung verschiedener Modelle in OpenClaw → Lösung 2 (APIYI-Proxy), am unkompliziertesten
• Feinsteuerung bei selbst entwickelten KI-Anwendungen → Lösung 3 (manuelle Bereinigung), am flexibelsten
• Unsicher bei der Wahl → Zuerst Lösung 2 über APIYI (apiyi.com) zur schnellen Validierung testen

Häufig gestellte Fragen

Fazit

Die grundlegende Ursache für das Scheitern der Gemini-Bilderkennung in OpenClaw ist die Inkompatibilität der JSON-Schema-Felder im OpenAI-kompatiblen Modus und nicht etwa eine Schwäche der visuellen Fähigkeiten des Gemini-Modells. Die drei Lösungsansätze haben jeweils ihre eigenen Einsatzgebiete:

• Natives Format (google-generative-ai): Die gründlichste Lösung, empfohlen für Szenarien, in denen ausschließlich Gemini verwendet wird.
• API-Proxy-Dienst: Die bequemste Lösung, empfohlen für Szenarien mit gemischten Modellen.
• Manuelle Schema-Bereinigung: Die flexibelste Lösung, empfohlen für selbst entwickelte Systeme.

Wir empfehlen, die Bilderkennungsleistung von Gemini schnell über APIYI (apiyi.com) zu testen. Die Plattform unterstützt den einheitlichen Modellaufruf für gängige Modelle wie Gemini, GPT und Claude und gleicht API-Formatunterschiede automatisch aus.

Referenzmaterialien

1. Gemini Offizielle Dokumentation – Bildverständnis: Erläuterung der visuellen Fähigkeiten von Gemini

   • Link: ai.google.dev/gemini-api/docs/image-understanding

2. Gemini Offizielle Dokumentation – OpenAI-Kompatibilität: Anleitung zum Aufruf von Gemini über das OpenAI SDK

   • Link: ai.google.dev/gemini-api/docs/openai

3. OpenClaw GitHub Issue #21172: 400-Fehler bei der Gemini-API durch patternProperties

   • Link: github.com/openclaw/openclaw/issues/21172

4. OpenClaw GitHub Issue #14456: 400-Fehler im OpenAI-Kompatibilitätsmodus mit Gemini 2.5 Flash

   • Link: github.com/openclaw/openclaw/issues/14456

5. OpenClaw Modellkonfigurations-Dokumentation: Leitfaden zur Konfiguration von Modellanbietern

   • Link: docs.openclaw.ai/concepts/model-providers

📝 Autor dieses Artikels: APIYI Team — Spezialisiert auf die Integration von KI-Großsprachmodellen und technische Analysen
🔗 Weitere Tutorials: Besuchen Sie APIYI unter apiyi.com für weitere Anleitungen zu Modellaufrufen und kostenlose Testguthaben