视觉

视觉与图像描述¶

捆绑的 Ollama 插件将 Ollama 注册为支持图像的媒体理解提供商，因此 OpenClaw 可以将显式的图像描述请求以及已配置的图像模型默认值路由到本地或托管的 Ollama 视觉模型。

ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json

--model 必须是完整的 <provider/model> 引用；设置后，infer image describe 会优先尝试该模型，而不是跳过描述那些已经支持原生视觉的模型。如果调用失败，OpenClaw 可以继续通过 agents.defaults.imageModel.fallbacks；文件/URL 准备错误会在尝试回退之前使操作失败。对于 OpenClaw 的图像理解流程和已配置的 imageModel，请使用 infer image describe；对于使用自定义提示词的原始多模态探测，请使用 infer model run --file。

要让 Ollama 成为入站媒体的默认图像理解提供商：

{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}

优先使用完整的 ollama/<model> 引用。像 qwen2.5vl:7b 这样的裸 imageModel 引用，只有当该确切模型列在 models.providers.ollama.models 下，并且 input: ["text", "image"]，且没有其他已配置的图像提供商公开相同的裸 id 时，才会规范化为 ollama/qwen2.5vl:7b；否则请显式使用提供商前缀。

较慢的本地视觉模型可能需要比云模型更长的图像理解超时时间，并且在 Ollama 尝试分配模型完整标称视觉上下文时，可能在受限硬件上崩溃。设置能力超时并限制 num_ctx：

{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      models: [
        {
          provider: "ollama",
          model: "qwen2.5vl:7b",
          timeoutSeconds: 300,
          capabilities: ["image"],
        },
      ],
      image: {
        timeoutSeconds: 180,
      },
    },
  },
}

此超时适用于入站图像理解以及显式的 view_image 工具。models.providers.ollama.timeoutSeconds 仍然控制普通模型调用底层 Ollama HTTP 请求保护。

实时验证：

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts

如果你手动定义 models.providers.ollama.models，请显式标记视觉模型：

{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}

OpenClaw 会拒绝针对未标记为支持图像的模型的图像描述请求。在隐式发现中，这来自 /api/show 的视觉能力。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw