OpenClaw imageModel 配置指南
张成AI
一、什么是 imageModel
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"]
}四、CLI 管理命令
# 查看当前 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 |
| 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 配置内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！