vision-ocr（视觉 OCR）

vision-ocr

vision-ocr 是一个用于 OpenClaw 的文档识别技能，支持图片和 PDF 输入，输出结构化 Markdown 结果，并在机器人会话中优先发送到当前飞书会话。

适用场景

• 文档截图
• 扫描件
• 表格和票据
• 技术文档
• 多页 PDF
• 手写便条和手写批注

核心能力

• 文档识别：图片默认按文档流程处理。
• PDF 处理：支持逐页识别与基础信息查看。
• Markdown 输出：尽量保留原始文档结构，复杂表格允许混合 HTML 表格。
• 多模态整合：OCR 有效时结合原图输出最终 Markdown。
• 手写优化：手写文档、手写便条和手写批注会自动启用手写优先识别策略。
• 飞书发送：默认关闭；显式开启后可发送到当前会话或指定对象，无会话上下文时保留本地结果。

触发方式

识别图片 /path/to/image.jpg
识别 PDF /path/to/file.pdf --pdf-option=ocr_full
OCR 这个截图

🚀 飞书集成场景：自动识别 + 按需发送

目标： 在飞书/集成场景下实现「发送图片/PDF → 自动识别 → 按需发送结果到当前会话」

正确操作（⚠️ 必须遵守）

为什么子会话不行？

主会话（飞书集成）
    ↓
子会话（隔离环境）
    ↓
vision-ocr 尝试获取会话上下文
    ↓
❌ 当前上下文未传入 session.chatId / session.openId
    ↓
❌ 无法确定发送目标，跳过自动发送

解决方案： 直接在主会话中调用 vision-ocr.run(context)，确保能获取到 chatId 和 openId 或 senderId。

代码示例

// ✅ 正确：在主会话中直接调用
const visionOcr = require('/home/node/.openclaw/workspace/skills/vision-ocr');

await visionOcr.run({
  session: {
    chatId: 'chat_xxx',
    openId: 'ou_xxx',
    isGroup: false
  },
  message: {
    text: '识别图片 /path/to/image.jpg'
  },
  replyText: async (msg) => {
    // 显式开启发送后，可发送到当前飞书会话
    console.log(msg);
  }
});

// ❌ 错误：通过子会话调用会丢失当前会话上下文

关键检查清单

在使用 vision-ocr 实现自动发送前，确认：

• [ ] 在主会话中直接调用（不是子会话）
• [ ] 通过 run(context) 传递会话上下文（不是命令行）
• [ ] context 中包含 session.chatId 和 session.openId / session.senderId

基本配置

推荐在技能目录 config.json 或当前进程环境变量中提供以下内容：

{
  "ocr": {
    "imageocr": {
      "token": "你的 ImageOCR Token",
      "endpoint": "你的 ImageOCR 端点"
    },
    "multimodal": {
      "baseUrl": "你的多模态 API 地址",
      "token": "你的多模态 Token",
      "model": "你的模型名称"
    }
  },
  "autoSendToFeishu": false
}

如果技能运行在 OpenClaw 会话中，并且你显式开启了飞书发送，同时运行时提供了当前群聊或私聊上下文，则发送飞书文件时会优先发到当前会话。若要发送给其他对象，可直接在对话中明确指定，例如：发给 open_id:ou_xxx 或 发给 chat:oc_xxx。

CLI 模式下，只有显式开启 --resolve-openclaw-session 或设置 VISION_RESOLVE_OPENCLAW_SESSION=true 时，技能才会尝试从 OPENCLAW_CHAT_ID、OPENCLAW_SENDER_ID、OPENCLAW_OPEN_ID 等环境变量，以及 ~/.openclaw/runtime.json 中恢复当前会话信息。机器人模式默认只信任 context.session 或消息中显式指定的接收者。

node index.js --update-config 只会把当前 shell 中的 VISION_* 环境变量写入技能目录 config.json，不会读取或改写 OpenClaw 全局配置。

如果 OpenClaw 需要发送到当前会话，必须调用导出的机器人入口 run(context) 并显式开启发送，而不是只执行命令行。例如：

const visionOcr = require('/home/node/.openclaw/workspace/skills/vision-ocr');

await visionOcr.run({
  session: {
    chatId: 'chat_xxx',
    openId: 'ou_xxx',
    isGroup: false
  },
  message: {
    text: '识别图片 /path/to/image.jpg'
  },
  replyText: async (msg) => {
    console.log(msg);
  }
});

如果仅执行 node index.js --image ...，识别会成功，但不会有当前会话信息，因此不会自动发送到当前飞书会话。

常用命令

node index.js --image /path/to/image.jpg --confirm=true
node index.js --image /path/to/file.pdf --pdf-option=ocr_full --confirm=true
node index.js --image /path/to/image.jpg --confirm=true --no-send-to-feishu
node index.js --image /path/to/image.jpg --confirm=true --send-to-feishu --resolve-openclaw-session

行为说明

• 图片默认先执行 OCR。
• OCR 有效时，会将 OCR Markdown 和原图一起交给大模型生成最终 Markdown。
• OCR 无效时，会自动切换为图片描述模式。
• 显式开启飞书发送时，优先发送到当前会话；没有会话上下文时不会自动发送。
• 只有显式开启远程输入时，技能才会下载远程附件 URL 或 token 模板资源。
• 关闭飞书发送后，结果文件会保留在临时目录，便于手动处理。

依赖

• Node.js 18+
• Python 3.8+
• PyMuPDF
• feishu-send-files 技能

隐私提示

• 默认不会发送识别结果到飞书；只有显式开启后才会发送。
• 处理敏感文档时，建议使用 --no-send-to-feishu。
• 仓库和发布包中不应包含真实凭据或本地配置文件。

版本

当前版本：1.1.2

修订说明

• 1.1.2：安全增强，远程附件下载 SSRF 过滤（禁止 localhost/私有段），新增下载超时与最大大小；PDF helper 调用加 maxBuffer 与 PYTHON_PATH 支持。
• 1.1.1：新增多模态大图自动预处理与 base64 清理，固定 PDF helper 文件，远程附件下载与 CLI OpenClaw 会话恢复改为显式开启，并同步更新文档与打包内容。