glmocr-handwriting

GLM-OCR 手写识别技能 / GLM-OCR 手写体识别技能

使用智谱 GLM-OCR 版面解析 API 识别图像和 PDF 中的手写文字。

使用场景 / 使用场景

• 从手写笔记、信件或文档中提取文字 / 从手写笔记、信件或文档中提取文字
• 将手写内容转换为可编辑文本 / 将手写内容转为可编辑文本
• 识别手写和印刷混排内容 / 识别手写和印刷混排内容
• 读取手写公式、标签或批注 / 读取手写公式、标签或批注
• 用户提到“手写 OCR”“识别手写”“手写识别”“手写体 OCR”“识别手写字”

核心特性 / 核心特性

• 支持多种风格：可处理草书、印刷体等各种手写风格
• 支持多种语言：支持中文、英文和混合语言手写内容
• 支持混合内容：可识别同时包含手写和印刷文字的文档
• 支持本地文件和 URL：支持本地文件和远程 URL

资源链接 / 资源链接

资源	链接
获取 API Key	智谱开放平台 API Keys
API 文档	版面解析 / 版面解析

前置条件 / 前置条件

API Key 配置（必需）/ API Key 配置（必需）

脚本通过 ZHIPU_API_KEY 环境变量获取密钥，可与其他智谱技能复用同一个 key。 此脚本从 ZHIPU_API_KEY 环境变量读取密钥。是否在智谱技能之间复用同一个 key，由你自行决定。

获取 Key / 获取 Key： 访问 智谱开放平台 API Keys 创建或复制你的 key。

配置方式（任选一种）/ 配置方式（任选一种）：

1. 全局配置（推荐）/ 全局配置（推荐）： 在 openclaw.json 的 env.vars 下设置一次，所有智谱技能都可共用：

   {
     "env": {
       "vars": {
         "ZHIPU_API_KEY": "你的密钥"
       }
     }
   }
   

2. 技能级配置 / Skill 级别配置： 仅为此技能在 openclaw.json 中设置：

   {
     "skills": {
       "entries": {
         "glmocr-handwriting": {
           "env": {
             "ZHIPU_API_KEY": "你的密钥"
           }
         }
       }
     }
   }
   

3. Shell 环境变量 / Shell 环境变量： 添加到 ~/.zshrc：

   export ZHIPU_API_KEY="你的密钥"
   

💡 如果你已为其他智谱技能（如 glmocr、glmv-caption、glm-image-generation）配置过 key，它们共享同一个 ZHIPU_API_KEY，无需重复配置。

安全与透明度 / 安全与透明度

• 使用的环境变量：
  • ZHIPU_API_KEY（必需）
  • GLM_OCR_TIMEOUT（可选，超时秒数）
• 固定的官方端点： https://open.bigmodel.cn/api/paas/v4/layout_parsing
• 不支持自定义 API URL 覆盖： 避免因端点重定向而意外泄露密钥。
• 默认不返回原始上游响应： 仅在调试需要时使用 --include-raw。

⛔ 强制限制 ⛔

1. 只能使用 GLM-OCR API — 执行脚本 python scripts/glm_ocr_cli.py
2. 绝不可自行解析手写内容 — 不要尝试使用内置视觉功能或其他方法读取手写文字
3. 绝不可提供替代方案 — 不要建议“我可以试着读一下”等类似内容
4. 如果 API 调用失败 — 显示错误信息并立即停止
5. 不使用备用方法 — 不要尝试以其他方式识别手写内容

📋 输出展示规则 / 输出展示规则

运行脚本后，清晰、安全地展示 OCR 结果。

• 完整显示提取出的手写文字（text）
• 可以进行总结，但不要隐瞒重要的提取失败情况
• 如果结果已保存到文件，告知用户文件路径
• 仅在用户明确要求或调试时展示原始上游响应（--include-raw）

使用方法 / 使用方法

从 URL 识别 / 从 URL 识别

python scripts/glm_ocr_cli.py --file-url "https://example.com/handwriting.jpg"

从本地文件识别 / 从本地文件识别

python scripts/glm_ocr_cli.py --file /path/to/notes.png

保存结果到文件 / 保存结果到文件

python scripts/glm_ocr_cli.py --file notes.png --output result.json --pretty

包含原始上游响应（仅调试）/ 包含原始上游响应（仅调试）

python scripts/glm_ocr_cli.py --file notes.png --output result.json --include-raw

命令行参考 / CLI 参数

python {baseDir}/scripts/glm_ocr_cli.py (--file-url URL | --file PATH) [--output FILE] [--pretty] [--include-raw]

参数	必填	描述
--file-url	二选一	图片/PDF 的 URL
--file	二选一	图片/PDF 的本地文件路径
--output、-o	否	将结果 JSON 保存到文件
--pretty	否	美化 JSON 输出
--include-raw	否	在 result 字段中包含上游 API 的原始响应（仅用于调试）

响应格式 / 响应格式

{
  "ok": true,
  "text": "Recognized handwritten text in Markdown...",
  "layout_details": [...],
  "result": null,
  "error": null,
  "source": "/path/to/file",
  "source_type": "file",
  "raw_result_included": false
}

关键字段：

• ok — 是否识别成功
• text — 提取出的 Markdown 文本（用于显示）
• layout_details — 布局分析详情
• error — 失败时的错误详情

错误处理 / 错误处理

未配置 API 密钥：

ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys

→ 向用户显示确切错误，并指导其进行配置

身份验证失败（401/403）： API 密钥无效/已过期 → 重新配置

速率限制（429）： 配额已用尽 → 告知用户等待

未找到文件： 本地文件缺失 → 检查路径