Bild-Tool gibt 'Unbekanntes Modell' für konfigurierte Ollama-Modelle mit Bildeingabe zurück - image Tool Returns 'Unknown Model' for Configured Ollama Models with Image Input

Das image-Tool kann nicht ordnungsgemäß konfigurierte Ollama-Modelle auflösen und erzeugt einen Unknown model-Fehler, obwohl das Modell in den Systemdiagnosen als gültig erscheint.

Primäre Fehleräußerung

$ openclaw tools run image --prompt "Describe this image" --image "https://example.com/image.jpg"
{
  "status": "error",
  "tool": "image",
  "error": "Unknown model: ollama/qwen3.5:397b-cloud"
}

Widersprüchliche Diagnoseausgabe

Das Modell erscheint in mehreren Diagnosebefehlen korrekt konfiguriert:

$ openclaw models status
Image model   : qwen3.5:397b-cloud
Default model : gpt-4o

$ openclaw models list --all | grep qwen
ollama/qwen3.5:397b-cloud                  text+image 256k     yes   no    fallback#1,configured,alias:qwen

Betroffene Modellvarianten

Mehrere Ollama-Modelle zeigen das gleiche Verhalten:

• ollama/qwen3.5:397b-cloud — text+image fähig
• ollama/kimi-k2.5:cloud — text+image fähig

Bestätigung der funktionalen Problemumgehung

Die MCP Vision-Integration funktioniert korrekt, was bestätigt, dass das Problem auf die Modellauflösung des integrierten image-Tools beschränkt ist:

$ mcporter call gemini.analyze_media --args '{"media_source": "", "prompt": "..."}'

Das Problem stammt aus einer bidirektionalen Normalisierungsabweichung der Modell-ID zwischen drei unterschiedlichen Komponenten:

Komponenten-Interaktionsfluss

┌─────────────────────────────────────────────────────────────────┐ │ Model Resolution Pipeline │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ openclaw.json image tool │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ imageModel: { │ ──────► │ Normalizes to: │ │ │ │ primary: │ │ “ollama/qwen…"│ │ │ │ “qwen3.5…” │ │ │ │ │ └──────────────────┘ └────────┬─────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────┐ │ │ │ Model Registry Lookup │ │ │ │ Expected: “qwen3.5…” │ │ │ │ Got: “ollama/q…” │ │ │ └────────┬────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────┐ │ │ │ MISMATCH ERROR │ │ │ │ Unknown model returned │ │ │ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

Ursachenablauf

1. Konfigurationsspeicherung: Die openclaw.json des Benutzers speichert die Modellreferenz ohne das Anbieterpräfix:

   "imageModel": {
     "primary": "qwen3.5:397b-cloud"
   }

2. Konfigurationsabruf: Der Befehl openclaw models status liest und zeigt diesen Wert korrekt aus (Entfernung des Anbieterpräfix für die Anzeige).
3. Tool-Modellauflösung: Die interne Logik des image-Tools führt während der Modell-ID-Konstruktion eine Anbieterpräfix-Injektion durch:

   // Pseudocode representation of the bug
   const resolvedModel = `ollama/${config.imageModel.primary}`;
   // Results in: "ollama/qwen3.5:397b-cloud"
   

4. Registry-Lookup-Fehler: Die Modellregistrierungsschlüssel werden intern ohne das ollama/-Präfix gespeichert, wodurch das Lookup fehlschlägt.

Struktur der Registry-Schlüssel

Die Modellregistrierung speichert Schlüssel intern in einem normalisierten Format, das je nach Anbieter variiert:

Code-Pfad-Divergenz

Der Fehler tritt auf, weil zwei verschiedene Code-Pfade die Modellauflösung behandeln:

• CLI-Anzeigepfad: Behandelt unpräfixierte Modell-IDs korrekt durch Abgleich mit der Basis-Modell-ID.
• Tool-Ausführungspfad: Fügt fälschlicherweise den Provider-Namensraum voran und erstellt einen Lookup-Schlüssel, der nicht existiert.

Methode 1: Konfiguration mit vollständiger Modell-ID aktualisieren (Empfohlen)

Ändern Sie openclaw.json, um die vollständig qualifizierte Modell-ID mit dem Anbieterpräfix zu verwenden:

Vorher:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "qwen3.5:397b-cloud"
      }
    }
  }
}

Nachher:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "ollama/qwen3.5:397b-cloud"
      }
    }
  }
}

Methode 2: CLI-Befehl-Fix

Verwenden Sie die OpenClaw CLI zum Aktualisieren der Modellkonfiguration:

$ openclaw config set agents.defaults.imageModel.primary "ollama/qwen3.5:397b-cloud"
✓ Configuration updated: agents.defaults.imageModel.primary = "ollama/qwen3.5:397b-cloud"

$ openclaw models status
Image model   : ollama/qwen3.5:397b-cloud

Methode 3: Modell verifizieren und neu registrieren (falls Probleme fortbestehen)

Wenn die Lösung das Problem nicht behebt, registrieren Sie das Modell erneut in der Registry:

# Step 1: Remove existing model registration
$ openclaw models remove ollama/qwen3.5:397b-cloud

# Step 2: Re-register with explicit provider
$ openclaw models add ollama/qwen3.5:397b-cloud --input-types text,image

# Step 3: Set as primary image model
$ openclaw config set agents.defaults.imageModel.primary "ollama/qwen3.5:397b-cloud"

Speicherort der Konfigurationsdatei

Der Speicherort der Konfigurationsdatei variiert je nach Betriebssystem:

Alternative: Alternativen Anbieter verwenden

Wenn Ollama-Modelle weiterhin fehlschlagen, konfigurieren Sie einen alternativen Anbieter:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "openai/gpt-4o-mini"
      }
    }
  }
}

Schritt 1: Konfigurationsaktualisierung verifizieren

Bestätigen Sie, dass die Konfigurationsdatei die korrekte Modell-ID widerspiegelt:

$ grep -A2 "imageModel" ~/.config/openclaw/openclaw.json
"imageModel": {
  "primary": "ollama/qwen3.5:397b-cloud"
}

Schritt 2: Modellstatus verifizieren

$ openclaw models status
Default model : gpt-4o
Image model   : ollama/qwen3.5:397b-cloud

Schritt 3: Modell ist aufgelistet und konfiguriert verifizieren

$ openclaw models list --all | grep qwen
ollama/qwen3.5:397b-cloud                  text+image 256k     yes   no    fallback#1,configured,alias:qwen

Das configured-Flag bestätigt, dass das Modell korrekt registriert ist.

Schritt 4: Image-Tool-Ausführung testen

Führen Sie das Image-Tool mit der korrigierten Konfiguration aus:

$ openclaw tools run image --prompt "What is in this image?" --image "https://httpbin.org/image/jpeg"
{
  "status": "ok",
  "tool": "image",
  "model": "ollama/qwen3.5:397b-cloud",
  "result": "[Image analysis content would appear here]"
}

Schritt 5: Exit-Code verifizieren

$ echo $?
0

Eine erfolgreiche Ausführung gibt den Exit-Code 0 zurück. Fehlerbedingungen geben Nicht-Null-Exit-Codes zurück.

Schritt 6: Alternative Verifizierung mit JSON-Ausgabe

Für programmatische Verifizierung:

$ openclaw tools run image --prompt "Count the objects" --image "https://httpbin.org/image/jpeg" --output json
{
  "status": "ok",
  "tool": "image",
  "model": "ollama/qwen3.5:397b-cloud",
  "result": "...",
  "timing": {
    "total_ms": 4523
  }
}

Fehler 1: Konfigurations-Cache nicht aktualisiert

Die CLI speichert möglicherweise Konfigurationen im Cache. Erzwingen Sie eine Aktualisierung:

$ openclaw config reload
$ openclaw models status

Fehler 2: Groß-/Kleinschreibung bei Modell-IDs

Modell-IDs sind case-sensitive. Überprüfen Sie die exakte Schreibweise:

# Falsch
"ollama/Qwen3.5:397b-cloud"

# Richtig
"ollama/qwen3.5:397b-cloud"

Fehler 3: Docker-Umgebung Modellauflösung

Wenn OpenClaw in Docker läuft, muss Ollama aus dem Container heraus erreichbar sein:

# Docker run with Ollama network access
$ docker run -e OLLAMA_HOST=host.docker.internal:11434 openclaw/openclaw:latest

# Or use host network mode
$ docker run --network host openclaw/openclaw:latest

Fehler 4: Ollama-Server läuft nicht

Stellen Sie sicher, dass der Ollama-Server läuft und erreichbar ist:

$ curl http://localhost:11434/api/tags
{"models":[...]}

Wenn der curl-Befehl fehlschlägt, starten Sie Ollama:

$ ollama serve
# In another terminal
$ ollama list

Fehler 5: Modell nicht heruntergeladen

Verifizieren Sie, dass das Modell in Ollama heruntergeladen ist:

$ ollama list
NAME                            ID           SIZE      MODIFIED
qwen3.5:397b-cloud              a1b2c3d4     7.2GB     2 hours ago

Wenn nicht vorhanden, pullen Sie das Modell:

$ ollama pull qwen3.5:397b-cloud

Fehler 6: Vermischung von konfigurierten und Ad-hoc-Modellreferenzen

Die Verwendung von Ad-hoc-Modellreferenzen in Tool-Aufrufen kann die Konfiguration umgehen:

# Dies kann funktionieren, wenn das Modell gültig ist, aber nicht "konfiguriert"
$ openclaw tools run image --model "ollama/qwen3.5:397b-cloud" ...

# Dies verwendet das konfigurierte Modell und kann fehlschlagen
$ openclaw tools run image ...

Fehler 7: Modell-Alias-Konflikte

Modell-Aliase können Auflösungsmehrdeutigkeiten erzeugen:

# Alias "qwen" könnte auf verschiedene Modelle verweisen
$ openclaw models list --all | grep alias:qwen
ollama/qwen3.5:397b-cloud          text+image 256k     yes   no    configured,alias:qwen
openai/qwen-vl-max               text+image 1024k    yes   no    alias:qwen

Fehler 8: Netzwerk-Timeout bei erster Anfrage

Erstanforderungen an Modelle können timeouts verursachen, während Ollama Modell-Layer herunterlädt:

# Timeout in Konfiguration erhöhen
{
  "providers": {
    "ollama": {
      "timeout": 120000
    }
  }
}

Fehlercode: MODEL_NOT_FOUND

Beschreibung: Generischer Modell-Lookup-Fehler, oft aufgrund eines nicht im System registrierten Modells.

Unterscheidung: Der Unknown model-Fehler in diesem Problem ist eine spezifische Instanz, bei der das Modell registriert IST, aber das Lookup-Schlüsselformat falsch ist.

Fehlercode: PROVIDER_NOT_CONFIGURED

Beschreibung: Der Anbieter (z.B. ollama) ist nicht initialisiert oder nicht erreichbar.

Zugehöriges Problem: Erscheint oft, wenn der Ollama-Server nicht läuft oder die Docker-Netzwerkkonfiguration fehlerhaft ist.

{
  "error": "Provider 'ollama' not available",
  "code": "PROVIDER_NOT_CONFIGURED"
}

Fehlercode: MODEL_CAPABILITY_MISMATCH

Beschreibung: Modell unterstützt den erforderlichen Eingabetyp nicht (z.B. Verwendung eines reinen Textmodells für Bildanalyse).

Zugehöriges Problem: Kann auftreten, wenn die Modellkonfiguration falsche input-Fähigkeiten definiert hat.

{
  "error": "Model 'ollama/qwen3.5:397b-cloud' does not support image input",
  "code": "MODEL_CAPABILITY_MISMATCH"
}

Historisches Problem: MODEL_ID_NORMALIZATION_V1

Beschreibung: Frühere Versionen von OpenClaw (vor 2026.3.0) hatten inkonsistente Modell-ID-Normalisierung in allen Tools, nicht nur im Image-Tool.

Lösung: Upgrade auf 2026.4.2 oder höher, wo die Normalisierung für die meisten Tools standardisiert wurde. Der Image-Tool-Normalisierungsfehler bleibt ab 2026.4.2 ungeflickt.

Zugehöriges GitHub-Issue: #1847

Beschreibung: “image tool fails with ‘Unknown model’ for ollama models” — Dies ist das Quell-Issue, das dokumentiert wird.

Status: Offen zum Dokumentationsdatum.

Zugehöriges Konfigurationsproblem: CONFIG_MODEL_PRIMARY_AMBIGUITY

Beschreibung: Wenn imageModel.primary aufgrund ähnlicher Basisnamen auf mehrere Modelle über Anbieter hinweg passt.

Beispielkonflikt:

openai/gpt-4o
ollama/llama3:8b-gpt4o-compatible  # Mehrdeutig bei der Suche nach "gpt-4o"