OpenClaw多模态和视觉模型配置教程

前言

多模态能力让 AI 不再局限于文本，可以"看见"和理解图片、文档甚至视频。在 OpenClaw 中，你可以通过 WhatsApp、Telegram 等频道发送图片，AI 助手会自动识别和分析图像内容。本教程将详细介绍多模态视觉模型的配置和使用。

支持视觉能力的模型

目前 OpenClaw 支持的主要视觉模型：

第一步：基础配置

1.1 使用云端视觉模型

以 Claude Sonnet 4 为例，配置视觉能力：

{
  models: {
    vision: {
      provider: "anthropic",
      apiKey: "${ANTHROPIC_API_KEY}",
      defaultModel: "claude-sonnet-4",
      capabilities: {
        vision: true,          // 启用图像理解
        maxImageSize: 20,      // 最大图片大小 (MB)
        maxImagesPerMessage: 5, // 每条消息最多图片数
      },
      parameters: {
        temperature: 0.3,       // 视觉任务建议用较低温度
        maxTokens: 4096,
      }
    }
  }
}

1.2 使用 GPT-4o 视觉

{
  models: {
    vision: {
      provider: "openai",
      apiKey: "${OPENAI_API_KEY}",
      defaultModel: "gpt-4o",
      capabilities: {
        vision: true,
        imageDetail: "high",     // high 或 low，high 更精确但更贵
      }
    }
  }
}

1.3 使用 Gemini 视觉

{
  models: {
    vision: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      capabilities: {
        vision: true,
        pdf: true,               // Gemini 原生支持 PDF
        video: true,             // 支持视频理解
      }
    }
  }
}

1.4 使用本地视觉模型

# 下载支持视觉的本地模型
ollama pull llava:13b
# 或更强的 Qwen VL
ollama pull qwen2.5-vl:72b   # 需要较大显存

配置 OpenClaw：

{
  models: {
    "local-vision": {
      provider: "ollama",
      baseUrl: "http://localhost:11434",
      defaultModel: "llava:13b",
      capabilities: {
        vision: true,
      }
    }
  }
}

第二步：频道集成配置

2.1 Telegram 图片处理

Telegram 支持直接发送图片。配置方法：

{
  channels: {
    telegram: {
      token: "${TELEGRAM_BOT_TOKEN}",
      model: "vision",             // 指向上面配置的视觉模型
      mediaHandling: {
        images: true,              // 接收并处理图片
        documents: true,           // 接收文档（PDF等）
        maxFileSize: 20,           // 最大文件大小 (MB)
        compressImages: true,      // 压缩大图以节省 token
        compressionQuality: 85,    // 压缩质量 (0-100)
      }
    }
  }
}

2.2 WhatsApp 图片处理

{
  channels: {
    whatsapp: {
      model: "vision",
      mediaHandling: {
        images: true,
        documents: true,
        stickers: false,            // 贴纸通常不需要分析
      }
    }
  }
}

2.3 Discord 图片处理

{
  channels: {
    discord: {
      token: "${DISCORD_BOT_TOKEN}",
      model: "vision",
      mediaHandling: {
        images: true,
        attachments: true,          // 处理消息附件
      }
    }
  }
}

第三步：使用场景详解

3.1 OCR 文字识别

在聊天中发送包含文字的图片，AI 会自动识别文字内容：

用户：[发送一张菜单照片]
用户：帮我翻译这个菜单

AI：我看到这是一家日料店的菜单，以下是翻译：
    - 刺身盛り合わせ → 刺身拼盘
    - 焼き鳥 → 烤鸡肉串
    - 天ぷら盛り合わせ → 天妇罗拼盘
    ...

优化 OCR 的系统提示词：

{
  models: {
    vision: {
      provider: "anthropic",
      defaultModel: "claude-sonnet-4",
      systemPrompt: "当用户发送图片时，首先仔细识别图中所有文字内容，然后根据用户的要求进行处理。对于模糊或不确定的文字，用 [?] 标记。",
      capabilities: {
        vision: true,
      }
    }
  }
}

3.2 图表和数据分析

发送图表、表格截图，AI 可以解读数据：

用户：[发送一张销售数据折线图]
用户：分析一下这个趋势

AI：根据图表分析：
    1. 整体趋势：Q1-Q3 销售额稳步上升，Q4 出现回落
    2. 峰值出现在 9 月，约 $450K
    3. 同比增长约 23%
    4. Q4 下降可能与季节性因素有关
    建议关注 Q4 下降原因，提前布局下一年度策略。

3.3 文档和截图理解

发送 UI 截图、代码截图、文档照片等：

用户：[发送一张报错截图]
用户：这个错误怎么解决？

AI：我看到错误信息是 "TypeError: Cannot read property 'map' of undefined"。
    这说明你尝试对一个 undefined 值调用 .map() 方法。
    可能的原因：
    1. API 返回的数据格式与预期不同
    2. 数据还未加载就尝试渲染
    建议在调用 .map() 前添加空值检查：
    data?.items?.map(...) 或 (data.items || []).map(...)

3.4 图片比较

发送多张图片进行比较分析：

用户：[发送两张装修效果图]
用户：帮我比较这两个方案的优缺点

AI：方案 A（第一张图）：
    - 优点：空间感强，采光好，现代简约风格
    - 缺点：储物空间有限，色调偏冷

    方案 B（第二张图）：
    - 优点：储物空间充足，暖色调温馨
    - 缺点：空间显得紧凑，家具摆放较密

    建议：如果注重舒适感选方案 B，注重空间感选方案 A。

第四步：图片处理优化

4.1 控制图片分辨率和成本

高分辨率图片会消耗更多 token（尤其是 OpenAI 模型）。合理配置可以节省费用：

{
  models: {
    vision: {
      provider: "openai",
      defaultModel: "gpt-4o",
      capabilities: {
        vision: true,
        imageDetail: "low",       // low: 固定 85 token
                                   // high: 根据分辨率计算，可能数千 token
        imageResize: {
          maxWidth: 1024,          // 自动缩放大图
          maxHeight: 1024,
        }
      }
    }
  }
}

4.2 Token 消耗参考

4.3 图片缓存

对于经常分析相同类型图片的场景，启用缓存可以减少重复处理：

{
  models: {
    vision: {
      provider: "anthropic",
      defaultModel: "claude-sonnet-4",
      capabilities: {
        vision: true,
      },
      cache: {
        enabled: true,
        imageHashCache: true,     // 缓存相同图片的分析结果
        ttl: 3600,                // 缓存有效期（秒）
      }
    }
  }
}

第五步：视觉模型对比评测

实际场景测试结果

推荐选择

• 最佳质量： Claude Sonnet 4（全面表现最优）
• 最佳性价比： Gemini 2.5 Flash（免费额度 + 质量不错）
• 完全免费： Llava 13B 本地部署（质量有限但够用）
• PDF 处理： Gemini 2.5 Pro（原生 PDF 支持最好）

常见问题

图片无法识别

确认配置中已启用 vision: true，并检查日志：

openclaw logs | grep -i "vision\|image\|media"

图片太大导致超时

capabilities: {
  vision: true,
  imageResize: {
    maxWidth: 1024,
    maxHeight: 1024,
  }
}

本地视觉模型效果差

Llava 等本地视觉模型在复杂场景下表现有限。建议对精度要求高的任务使用云端模型。

视频发送后无响应

目前仅 Gemini 系列支持视频理解。其他模型收到视频会忽略或报错，可以在配置中设置提示：

mediaHandling: {
  video: false,
  unsupportedMediaReply: "抱歉，我目前不支持视频分析，请发送截图或图片。",
}

小结

多模态视觉能力大大扩展了 OpenClaw 的使用场景。从日常的 OCR 识别到专业的图表分析，视觉模型让聊天机器人变得更加实用。推荐使用 Claude Sonnet 4 或 GPT-4o 获得最佳视觉理解效果，使用 Gemini 2.5 Flash 在免费额度内体验视觉功能，或者使用 Llava/Qwen VL 在本地免费运行。根据你的实际需求和预算，选择最合适的方案。