image Tool 对已配置的 Ollama 模型使用 Image Input 时返回 'Unknown Model'

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": "..."}'

问题源于三个不同组件之间的双向模型 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/ 前缀，导致查找失败。

注册表键结构

模型注册表在内部以规范化格式存储键，该格式因提供商而异：

代码路径分歧

问题之所以出现，是因为两个不同的代码路径处理模型解析：

• CLI 显示路径: 通过匹配基础模型 ID 正确处理无前缀的模型 ID。
• 工具执行路径: 错误地添加了提供商命名空间前缀，创建了一个不存在的查找键。

方法 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：验证并重新注册模型（如果问题仍然存在）

如果修复未能解决问题，请在注册表中重新注册模型：

# 步骤 1: 移除现有的模型注册
$ openclaw models remove ollama/qwen3.5:397b-cloud

# 步骤 2: 使用显式提供商重新注册
$ openclaw models add ollama/qwen3.5:397b-cloud --input-types text,image

# 步骤 3: 设置为主要图像模型
$ openclaw config set agents.defaults.imageModel.primary "ollama/qwen3.5:397b-cloud"

配置文件位置

配置文件位置因操作系统而异：

备选方案：使用替代提供商

如果 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: 测试图像工具执行

使用修正后的配置执行图像工具：

$ 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 必须可从容器内访问：

# 使用 Ollama 网络访问的 Docker 运行
$ docker run -e OLLAMA_HOST=host.docker.internal:11434 openclaw/openclaw:latest

# 或使用主机网络模式
$ docker run --network host openclaw/openclaw:latest

陷阱 4: Ollama 服务器未运行

确保 Ollama 服务器正在运行且可访问：

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

如果 curl 失败，请启动 Ollama：

$ ollama serve
# 在另一个终端
$ 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: 混用配置和临时模型引用

在工具调用中使用临时模型引用可能会绕过配置：

# 如果模型有效但未"配置"，这可能会工作
$ openclaw tools run image --model "ollama/qwen3.5:397b-cloud" ...

# 这使用配置的模型，可能会失败
$ openclaw tools run image ...

陷阱 7: 模型别名冲突

模型别名可能产生解析歧义：

# 别名 "qwen" 可能解析到不同的模型
$ 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 下载模型层可能会超时：

# 在配置中增加超时时间
{
  "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 功能定义不正确，可能会发生。

{
  "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 规范化不一致，不仅限于 image 工具。

解决方案: 升级到 2026.4.2 或更高版本，其中大部分工具的规范化已标准化。截至 2026.4.2，image 工具的规范化错误仍未修复。

相关 GitHub 问题: #1847

描述: “image tool fails with ‘Unknown model’ for ollama models” — 这是正在记录的问题的来源。

状态: 截至文档日期为开放状态。

相关配置问题: CONFIG_MODEL_PRIMARY_AMBIGUITY

描述: 当 imageModel.primary 由于相似的基础名称而跨提供商匹配多个模型时。

冲突示例:

openai/gpt-4o
ollama/llama3:8b-gpt4o-compatible  # 搜索 "gpt-4o" 时会产生歧义