OpenClaw imageModel 配置指南

OpenClaw imageModel 配置指南

一、什么是 imageModel

简单来说，imageModel 就是 OpenClaw 里专门负责“看图说话”的那套配置。它和负责日常聊天的那个主模型（model）是分开的。一旦对话里出现了图片或者需要视觉分析的内容，系统就会自动切换到这个专门的视觉模型来处理，整个过程对用户是无感的。

二、为什么需要单独配置

这里有个关键点：并不是所有的大语言模型都“长着眼睛”。有的模型专攻文本，速度飞快，但对图片束手无策。比如，MiniMax-M2.5-highspeed 就是一个纯文本模型，你发张图给它，它根本“看”不到。

而像 moonshot/kimi-k2.5 这类模型，则是真正的“多面手”，既能处理文字，也能理解图像。

所以，单独配置 imageModel 的精妙之处就在这里：日常纯文本对话，交给速度快、成本低的文本模型；一旦涉及图片，立刻无缝切换到支持多模态的视觉模型。这样一来，既能保证日常交互的效率，又能在需要时获得强大的视觉理解能力，可谓鱼与熊掌兼得。

三、配置方式

配置都在 OpenClaw 的主配置文件里进行，通过命令 openclaw config edit 就能打开。核心就是 agents.defaults 这个部分。

{
  "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 管理命令

除了直接编辑配置文件，OpenClaw 还提供了一套直观的命令行工具来管理 imageModel，对于喜欢敲命令的开发者来说尤其顺手。

# 查看当前 imageModel 的运行状态
openclaw models status

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

# 以下是管理回退链的一系列命令
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

五、触发场景

那么，具体在哪些情况下会触发这个视觉模型呢？主要有以下四类场景：

六、回退逻辑

为了保证服务的可用性，imageModel 配置了清晰的故障转移链，也就是回退逻辑。整个调用顺序是这样的：

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

系统会从主模型开始逐个尝试，只要有一个模型调用成功，就会立刻返回结果。如果配置链上的所有模型都尝试失败了，那么系统会抛出一个明确的错误提示：

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

七、与 pdfModel 的关系

这里需要注意一下处理 PDF 文件时的模型优先级，它们之间是有调用顺序的：

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

换句话说，当处理 PDF 时，系统会首先使用你专门为 PDF 配置的 pdfModel。只有当你没有配置 pdfModel 时，PDF 处理工具才会自动回退，去使用 imageModel 的配置链。这是一个很重要的设计，让你可以分别为图文 PDF 和纯图像分析指定最合适的模型。

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

如果你图省事，完全没有配置 imageModel，OpenClaw 也不会罢工。当系统检测到需要处理图片，且识别出你配置了某个供应商的 API Key 时，它会自动启用一套内置的默认模型。这套默认配置是：

九、完整配置示例

最后，让我们来看一个综合性的配置示例，把主模型、视觉模型、PDF模型以及模型别名都放在一起，这样能更清楚地理解它们是如何协同工作的：

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

通过这样分层、分场景的配置，整个系统的资源利用和任务分配就达到了一个非常理想的平衡状态。