OpenClaw视觉能力配置指南

配置 OpenClaw 图片理解能力，遇到图片输入时自动切换到视觉模型。

OpenClaw 视觉能力配置指南

我们介绍如何在 OpenClaw 中配置图片理解能力，使文本请求继续使用常规推理模型，而遇到图片输入时自动切换到视觉模型进行图片理解。示例场景为：

  • 文本主模型：sjtu/claw
  • 图片理解模型：sjtu/qwen3.6-27b

1. 配置目标

OpenClaw 处理图片时，核心会经历两层判断：

  1. 选择图片理解模型：通过 agents.defaults.imageModel.primary 指定。
  2. 校验模型是否支持图片：通过 models.providers.<provider>.models[].input 判断是否包含 "image"。

2. 推荐配置模板

登录云主机，编辑 OpenClaw 配置文件：

vim ~/.openclaw/openclaw.json

参考配置如下：

{
  agents: {
    defaults: {
      // 普通文本对话使用的主模型
      model: {
        primary: "sjtu/claw"
      },

      // 当输入包含图片，且需要图片理解时使用的模型
      imageModel: {
        primary: "sjtu/qwen3.6-27b"
      },

      // 当前 agent 允许使用的模型列表
      models: {
        "sjtu/claw": {},
        "sjtu/qwen3.6-27b": {}
      }
    }
  },

  models: {
    mode: "merge",
    providers: {
      sjtu: {
        baseUrl: "https://models.sjtu.edu.cn/api/v1",
        apiKey: "${SJTU_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "claw",
            name: "ClawModel",
            input: ["text"],
            reasoning: true,
            contextWindow: 256000,
            maxTokens: 128000
          },
          {
            id: "qwen3.6-27b",
            name: "qwen3.6-27b",
            input: ["text", "image"],
            reasoning: false,
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

3. 关键字段说明

3.1 agents.defaults.model

这是默认文本模型。普通文本输入会走这里：

model: {
  primary: "sjtu/claw"
}

建议主模型保持为文本模型，避免图片输入被主模型直接接收，从而绕过 imageModel 路由。

3.2 agents.defaults.imageModel

这是图片理解模型：

imageModel: {
  primary: "sjtu/qwen3.6-27b"
}

注意：imageModel 负责模型选择，但不负责声明模型能力。能力声明仍然要写在 provider 的模型元数据中。

3.4 models.providers.sjtu.models[].input

这是最容易漏掉、也最关键的配置：

{
  id: "qwen3.6-27b",
  input: ["text", "image"]
}

OpenClaw 会根据这里的 input 判断模型是否支持图片。如果只写成：

input: ["text"]

或者没有覆盖默认模型元数据，就会导致图片调用被拒绝。

4. 生效步骤

保存配置后，重启 OpenClaw gateway：

openclaw gateway restart

检查模型状态：

openclaw models status
openclaw models list --provider sjtu

期望看到：

Image model: sjtu/qwen3.6-27b
sjtu/qwen3.6-27b input: text,image

如果仍显示：

sjtu/qwen3.6-27b input: text

说明同名模型元数据没有被正确覆盖，或者其他配置源中还有旧的 text-only 条目。

5. 验证图片能力

可以上传一张图片并提问：

请详细描述这张图片的内容，包括其中的文字、物体、场景等所有可见信息。

正常情况下，OpenClaw 应该自动调用 sjtu/qwen3.6-27b 进行图片理解，然后把识别结果交给对话流程。

如果需要进一步确认后端模型本身支持图片，可以直接用 OpenAI-compatible API 测试该 endpoint，但 OpenClaw 内部仍然必须配置 input: ["text", "image"]。

6. 常见问题

6.1 报错：Model does not support images

完整报错示例：

error [tools] image failed: Model does not support images: sjtu/qwen3.6-27b
resolved sjtu/qwen3.6-27b input: text

原因：

OpenClaw 解析到的模型能力是 input: text，所以在本地能力检查阶段拒绝图片输入。

修复：

确认 provider 模型元数据中有：

{
  id: "qwen3.6-27b",
  input: ["text", "image"]
}

同时确认模型 ID 与调用名完全一致：

sjtu/qwen3.6-27b

6.2 配置后仍未切换到图片模型

排查顺序：

  1. agents.defaults.imageModel.primary 是否为 sjtu/qwen3.6-27b。
  2. agents.defaults.models 是否允许 sjtu/qwen3.6-27b。
  3. models.providers.sjtu.models[] 中是否有同名模型。
  4. openclaw gateway restart重启网关以生效配置
  5. 在飞书中使用/new创建新会话测试

7. 参考资料