April 15, 2026 • バージョン: 2026.4.2

image Tool、画像入力時に設定済みOllamaモデルに対して「Unknown Model」を返す

的内蔵image toolが「Unknown model」エラーで失敗原因是model ID正規化の不一致です。設定ではmodel referenceにproviderプレフィックスがありませんが、toolは「ollama/」プレフィックスを追加するため、 설정とtool解決の間に 불일치가 발생합니다.

🔍 症状

imageツールが、正しく構成されたOllamaモデルの解決に失敗し、システム診断でモデルが有効に表示されているにもかかわらず、Unknown modelエラーを出力します。

主要なエラー現象

$ 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"
}

診断出力の矛盾

モデルは複数の診断コマンドで正しく構成されているように表示されます：

$ 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

影響を受けるモデルバリアント

複数のOllamaモデルで同様の動作が確認されています：

  • ollama/qwen3.5:397b-cloud — text+image対応
  • ollama/kimi-k2.5:cloud — text+image対応

機能的な回避策の確認

MCP Vision統合は正しく機能しており、問題が組み込みimageツールのモデル解決に限定されていることが確認されています：

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

🧠 原因

この問題は、3つの異なるコンポーネント間での双方向のモデルID正規化の不一致に起因しています：

コンポーネントの相互作用フロー

┌─────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

原因のシーケンス

  1. 設定の保存：ユーザーのopenclaw.jsonには、プロバイダープレフィックスなしでモデル参照が保存されます：
    "imageModel": {
  "primary": "qwen3.5:397b-cloud"
}
  2. 設定の取得：openclaw models statusコマンドはこの値を正しく読み取り、表示します（表示用のプロバイダープレフィックスを削除）。
  3. ツールのモデル解決：imageツールの内部ロジックは、モデルIDの構築中にプロバイダープレフィックスの挿入を実行します：
    // Pseudocode representation of the bug
const resolvedModel = `ollama/${config.imageModel.primary}`;
// Results in: "ollama/qwen3.5:397b-cloud"
  4. レジストリ検索の失敗：モデルレジストリのキーは内部的にollama/プレフィックスなしで保存されているため、検索が失敗します。

レジストリキーの構造

モデルレジストリは内部的に、プロバイダーによって異なる正規化された形式でキーを保存します：

プロバイダーレジストリキー形式例
OpenAIモデルIDのみgpt-4o
AnthropicモデルIDのみclaude-3-5-sonnet
OllamaモデルIDのみqwen3.5:397b-cloud
Geminiproviders/プレフィックスproviders/gemini/gemini-2.0-flash

コードパスの分岐

このバグは、モデルの解決を処理する2つの異なるコードパスが存在するために発生します：

  • CLI表示パス：プレフィックスなしのモデルIDを正しく処理し、ベースモデルIDと照合します。
  • ツール実行パス：プロバイダーナmspaceを正しくプレペンドし、存在しない検索キーを作成します。

🛠️ 解決手順

方法1：完全なモデルIDを使用するように設定を更新する（推奨）

openclaw.jsonを編集して、プロバイダープレフィックスを含む完全修飾モデルIDを使用します：

変更前：

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

変更後：

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

方法2：CLIコマンドによる修正

OpenClaw CLIを使用してモデル設定を更新します：

$ 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

方法3：モデルの確認と再登録（問題が持続する場合）

修正で問題が解決しない場合は、レジストリでモデルを再登録します：

# 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"

設定ファイルの場所

設定ファイルの場所はオペレーティングシステムによって異なります：

OS設定ファイルのパス
Linux~/.config/openclaw/openclaw.json
macOS~/Library/Application Support/openclaw/openclaw.json
Windows%APPDATA%\openclaw\openclaw.json

代替手段：代替プロバイダーの使用

Ollamaモデルが 계속問題を起こす場合は、代替プロバイダーを設定します：

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

🧪 検証

手順1：設定の更新を確認

設定ファイルが正しいモデルIDを反映していることを確認します：

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

手順2：モデルの状態を確認

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

手順3：モデルがリストされ、構成されていることを確認

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

configuredフラグは、モデルが正しく登録されていることを確認します。

手順4：imageツールの実行をテスト

修正された設定でimageツールを実行します：

$ 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]"
}

手順5：終了コードを確認

$ echo $?
0

正常な実行では終了コード0が返されます。エラー状態ではゼロ以外の終了コードが返されます。

手順6：JSON出力による代替確認

プログラムによる確認の場合：

$ 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
  }
}

⚠️ よくある落とし穴

落とし穴1：設定キャッシュが更新されていない

CLIは設定をキャッシュする可能性があります。強制的に更新します：

$ openclaw config reload
$ openclaw models status

落とし穴2：モデルIDの大文字小文字の区別

モデルIDは大文字と小文字が区別されます。正確な大文字小文字を確認します：

# 間違い
"ollama/Qwen3.5:397b-cloud"

# 正しい
"ollama/qwen3.5:397b-cloud"

落とし穴3：Docker環境でのモデル解決

DockerでOpenClawを実行する場合、Ollamaはコンテナ内からアクセス可能である必要があります：

# 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

落とし穴4：Ollamaサーバーが実行されていない

Ollamaサーバーが実行され、アクセス可能であることを確認します：

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

curlが失敗した場合は、Ollamaを起動します：

$ ollama serve
# In another terminal
$ ollama list

落とし穴5：モデルがダウンロードされていない

モデルがOllamaにダウンロードされていることを確認します：

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

存在しない場合は、モデルを取得します：

$ ollama pull qwen3.5:397b-cloud

落とし穴6：設定済みモデルと一時的なモデル参照の混在

ツールコールで一時的なモデル参照を使用すると、設定をバイパスできます：

# This may work if model is valid but not "configured"
$ openclaw tools run image --model "ollama/qwen3.5:397b-cloud" ...

# This uses the configured model and may fail
$ openclaw tools run image ...

落とし穴7：モデルエイリアスの競合

モデルの別名は解決の曖昧さを生じさせます：

# Alias "qwen" might resolve to different models
$ 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

落とし穴8：初回リクエスト時のネットワークタイムアウト

Ollamaがモデルレイヤーをダウンロードしている間、初回モデルリクエストがタイムアウトする可能性があります：

# Increase timeout in config
{
  "providers": {
    "ollama": {
      "timeout": 120000
    }
  }
}

🔗 関連するエラー

エラーコード：MODEL_NOT_FOUND

説明：モデルがシステムに登録されていないなど、一般的なモデル検索の失敗。

区別：この問題でのUnknown modelエラーは、モデルが登録されているが検索キーの形式が不適切な特定のケースです。

エラーコード：PROVIDER_NOT_CONFIGURED

説明：プロバイダー（例：ollama）が初期化されていないか、アクセスできません。

関連問題：Ollamaサーバーが実行されていないか、Dockerネットワークが誤って構成されている場合に表示されることが多います。

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

エラーコード：MODEL_CAPABILITY_MISMATCH

説明：モデルが必要な入力タイプをサポートしていません（例：画像分析にテキストのみ対応のモデルを使用）。

関連問題：モデルの設定に不正なinput capabilitiesが定義されている場合に発生します。

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

歴史的問題：MODEL_ID_NORMALIZATION_V1

説明：OpenClawの以前バージョン（2026.3.0以前）では、画像ツールだけでなく、すべてのツールでモデルIDの正規化が不整合でした。

解決策：2026.4.2以降にアップグレードしてください。2026.4.2の時点で、画像ツールの正規化バグは修正されていません。

関連するGitHubの問題：#1847

説明：「image tool fails with ‘Unknown model’ for ollama models」（Ollamaモデルで「不明なモデル」エラーが発生するimageツール）— これは文書化している問題の根源です。

ステータス：文書作成日の時点でのステータス：オープン。

関連する設定問題：CONFIG_MODEL_PRIMARY_AMBIGUITY

説明：imageModel.primaryが類似したベース名 인해、複数のプロバイダーにまたがる複数のモデルと一致する場合。

競合の例：

openai/gpt-4o
ollama/llama3:8b-gpt4o-compatible  # Ambiguous when searching for "gpt-4o"

エビデンスとソース

このトラブルシューティングガイドは、FixClaw Intelligence パイプラインによってコミュニティの議論から自動的に合成されました。