OpenClaw imageModel 配置指南

目录

• 一、什么是 imageModel
• 二、为什么需要单独配置
• 三、配置方式
• 四、CLI 管理命令
• 五、触发场景
• 六、回退逻辑
• 七、与 pdfModel 的关系
• 八、内置默认图像模型（无配置时）
• 九、完整配置示例

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

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

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

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

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

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

两种写法都支持：

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

# 查看当前 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.”

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

{
  "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 链

到此这篇关于OpenClaw imageModel 配置指南的文章就介绍到这了,更多相关OpenClaw imageModel 配置内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！