vision

name	vision
description	识别图片内容、提取文字、分析图表。使用时需提供本地图片路径或图片URL。适用于"识别/查看/读取/分析/描述图片"等场景。不处理纯文本或音频文件。
user-invocable	true
metadata	{"openclaw":{"requires":{"bins":["python3"]},"primaryEnv":"VISION_API_KEY"}}

多模态识图 Skill

角色与能力

你是一名图像分析专家，能够准确理解图像内容，并根据用户需求进行分析或信息提取。

前置条件

• Python 3.10+ 环境

首次使用配置检查

首次调用 /vision 时，检查以下环境变量是否已设置：

VISION_API_KEY=<your-api-key>       # 必需 - API 密钥
VISION_API_URL=<your-api-endpoint>/v1/chat/completions  # 必需 - API 地址
VISION_MODEL=<首选模型名称>           # 必需 - 模型名称
VISION_FALLBACK=<备选模型名称>        # 可选 - 首选失败时回退
VISION_FALLBACK_API_URL=<备选API地址>  # 可选 - 不同厂商的 API 地址，空则使用 VISION_API_URL
VISION_FALLBACK_API_KEY=<备选API密钥>  # 可选 - 不同厂商的 API 密钥，空则使用 VISION_API_KEY

如未设置，提示用户按上方格式配置后再使用。

💡 备选模型可以是不同厂商的模型（如首选 MiMo，备选 GPT-4o-mini），只需设置对应的 FALLBACK_API_URL 和 FALLBACK_API_KEY。（base64 编码必需）

• 有效的 API Key（配置在 openclaw.json 的 VISION_API_KEY 中）
• 支持的图片格式：.jpg .jpeg .png .webp .bmp

核心工作流

用户提供图片路径/URL → 解析参数 → 调用 {baseDir}/scripts/vision_api.py → 格式化输出

调用方式

# 本地图片
python3 {baseDir}/scripts/vision_api.py /path/to/image.jpg "这张图里有什么？"

# 网络图片
python3 {baseDir}/scripts/vision_api.py https://example.com/photo.png "描述一下"

# 默认问题
python3 {baseDir}/scripts/vision_api.py /path/to/image.jpg

脚本返回 JSON：

{
  "success": true,
  "model": "<首选模型名称>",
  "description": "图片描述内容...",
  "usage": {"prompt_tokens": 1000, "completion_tokens": 200, "total_tokens": 1200}
}

参数解析

格式	示例
竖线分隔	`/path/img.jpg
JSON	{"image":"path","question":"描述"}
纯路径	/path/img.jpg

问题默认为 "请详细描述这张图片中的内容"

环境变量配置

在 openclaw.json 中配置：

{
  "skills": {
    "entries": {
      "vision": {
        "enabled": true,
        "apiKey": { "source": "env", "provider": "default", "id": "VISION_API_KEY" }
      }
    }
  }
}

可选环境变量（不配置则使用脚本默认值）：

变量	说明	默认值
VISION_API_URL	API 地址	`/v1/chat/completions

例如: https://token-plan-cn.xiaomimimo.com/v1/chat/completions` | | VISION_MODEL | 首选模型 | <首选模型名称> | | VISION_FALLBACK | 备选模型 | <备选模型名称> | | VISION_MAX_TOKENS | 最大 Token | 3000 | | VISION_TIMEOUT | 超时秒数 | 120 |

错误处理

现象	处理方式
API Key 无效	提示检查 VISION_API_KEY 配置
请求超时	图片可能过大，建议压缩后重试
模型不可用	自动回退到备选模型
图片格式不支持	提示支持的格式列表

参考

• API 文档
• 故障排查
• 通用分析模板
• OCR 提取模板