OpenClaw imageModel 配置指南

一、什么是 imageModel

imageModel 是 OpenClaw 中专门用于视觉理解 的模型配置，独立于主对话模型（model）。当对话涉及图片或视觉内容时，OpenClaw 会自动切换到 imageModel 指定的模型来处理。

二、为什么需要单独配置

主模型（model.primary）不一定支持视觉输入。例如：

MiniMax-M2.5-highspeed 是纯文本模型，无法处理图片
moonshot/kimi-k2.5 支持多模态（文本+图片）

单独配置 imageModel 可以做到：文本走快模型，图片走多模态模型，兼顾速度和能力。

三、配置方式

在 OpenClaw 配置文件中（openclaw config edit）：

json5 复制代码

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax-portal/MiniMax-M2.5-highspeed",
        "fallbacks": ["moonshot/kimi-k2.5", "anthropic/claude-opus-4-6"]
      },
      "imageModel": {
        "primary": "moonshot/kimi-k2.5",
        "fallbacks": ["openrouter/qwen/qwen-2.5-vl-72b-instruct:free"]
      }
    }
  }
}

两种写法都支持：

json5 复制代码

// 简写（只设主模型，无回退）
"imageModel": "moonshot/kimi-k2.5"

// 完整写法（主模型 + 回退链）
"imageModel": {
  "primary": "moonshot/kimi-k2.5",
  "fallbacks": ["openrouter/google/gemini-2.0-flash-vision:free"]
}

四、CLI 管理命令

bash 复制代码

# 查看当前 imageModel 状态
openclaw models status

# 设置 imageModel 主模型
openclaw models set-image moonshot/kimi-k2.5

# 管理 imageModel 回退链
openclaw models image-fallbacks list
openclaw models image-fallbacks add openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-fallbacks remove openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-fallbacks clear

五、触发场景

场景	说明
用户发送图片	照片、截图等图片附件，agent 需要"看图说话"时
用户发送 PDF	PDF 含扫描页/图片，需视觉分析时（先查 `pdfModel`，未配则回退到 `imageModel`）
媒体理解管线	收到的图片/视频截帧经过自动媒体理解流程时
agent 工具调用	agent 使用内置的 `image` 工具分析图片时

六、回退逻辑

复制代码

imageModel.primary  →  imageModel.fallbacks[0]  →  fallbacks[1]  →  ...

逐个尝试，第一个成功即返回。全部失败则报错：

"No image model configured. Set agents.defaults.imageModel.primary or agents.defaults.imageModel.fallbacks."

七、与 pdfModel 的关系

复制代码

PDF 处理优先级：pdfModel → imageModel → 内置 provider 默认值

如果没有配置 pdfModel，PDF 工具会自动回退到 imageModel 的配置。

八、内置默认图像模型（无配置时）

当未配置 imageModel 且系统检测到对应 provider 的 API key 时，会使用内置默认：

Provider	默认模型
OpenAI	`gpt-5-mini`
Anthropic	`claude-opus-4-6`
Google	`gemini-3-flash-preview`
MiniMax	`MiniMax-VL-01`
ZAI	`glm-4.6v`

九、完整配置示例

json5 复制代码

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax-portal/MiniMax-M2.5-highspeed",
        "fallbacks": ["moonshot/kimi-k2.5", "anthropic/claude-opus-4-6"]
      },
      "imageModel": {
        "primary": "moonshot/kimi-k2.5",
        "fallbacks": ["openrouter/google/gemini-2.0-flash-vision:free"]
      },
      "pdfModel": {
        "primary": "anthropic/claude-opus-4-6"
      },
      "models": {
        "moonshot/kimi-k2.5": { "alias": "kimi" },
        "minimax-portal/MiniMax-M2.5-highspeed": { "alias": "mm" }
      }
    }
  }
}

效果：

纯文本对话 → MiniMax-M2.5-highspeed
发图片 → moonshot/kimi-k2.5，失败则 → gemini-2.0-flash-vision
发 PDF → claude-opus-4-6，未配则回退到 imageModel 链