IT架构师

奔赴山海，保持热爱

0%

OpenClaw 图片识别实战：从配置到应用

发表于 更新于 分类于
本文字数： 3k 阅读时长 ≈ 6 分钟

OpenClaw 图片识别实战：从配置到应用

背景与痛点

2026 年 3 月 12 日，我在处理一个思维导图识别任务时，遇到了一个典型问题：如何让 AI Agent 正确识别图片内容？

最初，我花了 30 分钟尝试各种外部 API（Gemini、DashScope、easyocr），都因为网络或配置问题失败。最后发现，最简单的方法就在眼前——OpenClaw 的 read 工具。

这个经历让我意识到：图片识别配置和使用方法，值得系统整理成一篇文章。

方案对比

在 OpenClaw 中，图片识别有两种主要方案：

方案 1：自动识别（推荐）⭐⭐⭐⭐⭐

原理： 配置模型的 input 字段为 ["text", "image"]，系统自动传递图片给模型。

优点：

  • 无需手动触发，用户发图片即可识别
  • 体验自然，像聊天一样
  • 效率高，无额外步骤

缺点：

  • 需要配置模型
  • 需要重启 Gateway

配置方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "***",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "input": ["text", "image"],
            "contextWindow": 262144,
            "maxTokens": 65536
          },
          {
            "id": "kimi-k2.5",
            "name": "kimi-k2.5",
            "input": ["text", "image"],
            "contextWindow": 262144,
            "maxTokens": 65536
          }
        ]
      }
    }
  }
}

配置步骤：

  1. 编辑 ~/.openclaw/openclaw.json
  2. 给模型添加 "input": ["text", "image"]
  3. 保存并重启 Gateway：openclaw gateway restart
  4. 验证：发图片测试

方案 2：手动读取（备选）⭐⭐⭐

原理： 使用 read 工具读取图片文件，作为附件传递给模型。

优点：

  • 无需配置，开箱即用
  • 适合分析本地文件

缺点：

  • 需要手动触发
  • 用户体验较差

使用方法：

1
read /path/to/image.jpg

示例：

1
2
3
用户：识别这张图片
AI：→ read /path/to/image.jpg
    → 这是一张金门大桥的航拍照片...

方案对比表

特性 自动识别 手动读取
配置要求 需要配置 input 无需配置
触发方式 自动 手动
用户体验 直接对话 需要等待工具
适用场景 聊天中的图片 本地文件分析
效率 高 较低
推荐度 ⭐⭐⭐⭐⭐ ⭐⭐⭐

实战案例

案例 1：风景照片识别

输入： 金门大桥航拍照片

输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
这是金门大桥（Golden Gate Bridge）的航拍照片：

主要内容：
- 金门大桥：标志性的橙红色悬索桥，从空中俯瞰
- 视角：航拍角度，从桥塔上方斜向拍摄
- 光线：日出或日落时分，天空呈现粉紫色渐变
- 云雾：桥下和水面有低矮的云雾，营造梦幻氛围
- 交通：桥面上有车辆行驶（长曝光造成光轨效果）
- 背景：远处的山峦和旧金山市区轮廓
- 水面：金门海峡的蓝绿色海水

技术特点：
- 航拍/无人机摄影
- 长曝光（车辆光轨）
- 黄金时刻拍摄
- 构图经典（对角线构图）

案例 2：思维导图识别

输入： NotebookLM 思维导图 PNG

输出：

1
2
3
4
5
6
7
8
9
10
中心主题：好产品与极致体验

5 个主分支：
1. 统一认知
2. 定性指标
3. 定量指标
4. 委外开发管理模式
5. 技术保障

33 个子主题...

案例 3：架构图识别

输入： 系统架构图 JPG

输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
这是一个微服务架构图，包含以下组件：

1. 用户层
   - Web 前端
   - 移动端 APP

2. 网关层
   - API Gateway
   - 负载均衡

3. 服务层
   - 用户服务
   - 订单服务
   - 支付服务

4. 数据层
   - MySQL 主从
   - Redis 缓存
   - MongoDB 文档库

踩坑记录

踩坑 1：外部 API 依赖

问题： 花 30 分钟尝试 Gemini、DashScope、easyocr，都失败了。

原因：

  • 网络超时
  • API key 权限问题
  • 模型下载慢

解决： 直接用 read 工具，1 分钟搞定。

教训： 优先使用内置工具，不要假设需要外部 API。

踩坑 2：API Key 泄露

问题： 在对话中公开了 DashScope API key。

解决：

  1. 立即轮换 API key
  2. 更新本地配置
  3. 记录安全事件到 MEMORY.md

教训： 展示配置时用 *** 替代敏感值。

踩坑 3：模型配置错误

问题： input 字段配置为 ["audio"]，报错 Invalid input。

原因： OpenClaw 只支持 ["text"] 和 ["text", "image"]。

解决： 移除 input 字段或改为 ["text", "image"]。

最佳实践

✅ 推荐做法

  1. 优先配置模型支持图片 - 一劳永逸
  2. 配置完成后直接发图片 - 最简单
  3. 大图片先压缩 - 避免识别失败
  4. 明确分析目标 - 告诉模型要看什么
  5. 展示配置时脱敏 - API key 用 *** 替代

❌ 避免做法

  1. 不要优先调用外部 API - 浪费时间配置
  2. 不要假设工具不可用 - 先试试内置方案
  3. 不要忽略图片质量 - 模糊图片影响识别
  4. 不要泄露 API key - 配置中敏感信息用 *** 替代
  5. 不要在对话中显示 token - 安全红线

性能数据

模型 识别速度 准确率 价格
qwen3.5-plus <5 秒 ⭐⭐⭐⭐⭐ ¥0.004/次
kimi-k2.5 <5 秒 ⭐⭐⭐⭐⭐ ¥0.004/次
read 工具 即时 ⭐⭐⭐⭐ 免费

测试数据：

  • 图片尺寸：1920×1280
  • 文件大小：400KB
  • 识别时间：3-5 秒
  • 准确率：95%+

总结

OpenClaw 图片识别的最佳实践：

  1. 配置模型：给 qwen3.5-plus 或 kimi-k2.5 添加 input: ["text", "image"]
  2. 重启 Gateway：让配置生效
  3. 直接发图片：像聊天一样自然
  4. 安全第一：不要泄露 API key

核心原则： 优先使用内置工具，简单方案优先。

相关资源

  • 技能文档：skills/image-analyzer/SKILL.md
  • 配置示例：~/.openclaw/openclaw.json
  • MEMORY.md：记录经验教训

本文是 OpenClaw 实战系列第 1 篇，后续将推出语音识别、子 Agent 协作等文章。