SmartOCR — 车辆证件与票据识别#

从图片中提取结构化信息，支持 行驶证正页、行驶证副页、收据/发票 三种类型，自动判断图片类型并返回对应字段。

Configuration#

Set the following environment variables:

• SMARTOCR_API_KEY — API Key（sk- 前缀，必填）
• SMARTOCR_API_URL — API 地址（可选，默认 https://smartocr.yunlizhi.cn）

Option 1: CLI configuration (recommended)#

bash

# Configure API Key
openclaw config set env.vars.SMARTOCR_API_KEY "sk-your-api-key"

# Configure API URL (optional)
openclaw config set env.vars.SMARTOCR_API_URL "http://localhost:5001"

Option 2: Manual configuration#

Edit ~/.openclaw/openclaw.json，在 env.vars 中添加：

json5

{
  "env": {
    "vars": {
      "SMARTOCR_API_KEY": "sk-your-api-key",
      "SMARTOCR_API_URL": "http://localhost:5001"
    }
  }
}

Usage#

bash

# 识别图片 URL
uv run python {baseDir}/scripts/smartocr.py "https://example.com/receipt.jpg"

# 识别本地文件
uv run python {baseDir}/scripts/smartocr.py /path/to/receipt.jpg

# 指定超时时间
uv run python {baseDir}/scripts/smartocr.py -t 30 "https://example.com/vehicle.jpg"

# 输出原始 JSON（不格式化）
uv run python {baseDir}/scripts/smartocr.py --raw /path/to/invoice.jpg

Options#

FlagDescriptionDefaultimage图片 URL 或本地文件路径（必填）—-t, --timeout请求超时秒数60--raw输出原始 JSON（不格式化）false

处理对话中上传的图片#

当用户在对话中（飞书、WebChat、WeCom 等）直接发送图片时，agent 无法直接获取图片的原始数据。 请改用 smartocr_from_session.py，它会直接读取当前会话的 session 文件提取图片：

bash

# 识别当前会话中最近上传的 1 张图片
uv run python {baseDir}/scripts/smartocr_from_session.py

# 识别最近 N 张图片
uv run python {baseDir}/scripts/smartocr_from_session.py -n 3

# 指定 agent ID（默认 main）
uv run python {baseDir}/scripts/smartocr_from_session.py --agent main

# 指定 session 文件路径（手动覆盖自动查找）
uv run python {baseDir}/scripts/smartocr_from_session.py --session /path/to/session.jsonl

脚本自动查找 ~/.openclaw/agents/{agent}/sessions/ 下最新的 session jsonl 文件， 从末尾向前扫描提取最近的图片 base64，直接调用 SmartOCR API 识别。

识别类型#

ocr_type说明返回字段vehicle_front行驶证正页号牌号码、车辆类型、所有人、品牌型号、车辆识别代号、发动机号码、注册日期、发证日期vehicle_rear行驶证副页号牌号码、检验有效期、核定载人数、总质量、整备质量、准牵引总质量receipt收据/票据/发票发票号码、开票日期、金额、税额、购买方、销售方、商品名称

响应格式#

json

{
  "ocr_type": "receipt",
  "content": {
    "发票号码": "12345678",
    "开票日期": "2025-06-01",
    "金额": "128.00",
    "税额": "7.68",
    "购买方": "某某公司",
    "销售方": "某某商店",
    "商品名称": "办公用品"
  }
}

无法识别的字段值返回 "无法识别"。

错误码#

状态码原因处理401缺少 X-API-Key检查 SMARTOCR_API_KEY 环境变量403Key 无效或已禁用重新配置 Key429月度额度已用完（50 次/月）等待下月重置或联系管理员502识别服务异常稍后重试，建议间隔 2-5 秒最多重试 2 次

注意事项#

• 图片清晰、光线充足时识别效果最佳
• 本地文件会自动转为 Base64 上传，URL 方式更轻量
• 超时建议设置 60 秒