glmocr-handwriting

GLM-OCR Handwriting Recognition Skill

Recognize handwritten text from images and PDFs using the ZhiPu GLM-OCR layout parsing API.

When to Use

Extract text from handwritten notes, letters, or documents
Convert handwriting to editable text
Recognize mixed handwritten and printed content
Read handwritten formulas, labels, or annotations
User mentions "handwriting OCR", "recognize handwriting", "handwriting recognition", "handwritten OCR", "recognize handwritten characters"

Key Features

Multi-style support: Handles various handwriting styles including cursive and print
Multi-language: Supports Chinese, English, and mixed-language handwriting
Mixed content: Can recognize documents with both handwritten and printed text
Local file & URL: Supports both local files and remote URLs

Resource Links

Resource	Link
Get API Key	Zhipu Open Platform API Keys
API Docs	Layout Parsing

Prerequisites

API Key Setup (Required)

The script reads the key from the ZHIPU_API_KEY environment variable, which can be reused with other Zhipu skills using the same key. This script reads the key from the ZHIPU_API_KEY environment variable. Reusing the same key across Zhipu skills is optional.

Get Key: Visit Zhipu Open Platform API Keys to create or copy your key.

Setup options (choose any one):

Global config (recommended): Set once in openclaw.json under env.vars, all Zhipu skills will share it:

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

Skill-level config: Set for this skill only in openclaw.json:

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

Shell environment variable: Add to ~/.zshrc:
```
export ZHIPU_API_KEY="你的密钥"
```

💡 If you have already configured a key for other Zhipu skills (such as glmocr、glmv-caption、glm-image-generation), they share the same ZHIPU_API_KEY, so there is no need to configure it again.

Security & Transparency

Environment variables used:
- ZHIPU_API_KEY (required)
- GLM_OCR_TIMEOUT (optional timeout seconds)
Fixed endpoint: https://open.bigmodel.cn/api/paas/v4/layout_parsing
No custom API URL override: avoids accidental key exfiltration via redirected endpoints.
Raw upstream response is optional: use --include-raw only when needed for debugging.

⛔ MANDATORY RESTRICTIONS ⛔

ONLY use GLM-OCR API — Execute the script python scripts/glm_ocr_cli.py
NEVER parse handwriting yourself — Do NOT try to read handwritten text using built-in vision or any other method
NEVER offer alternatives — Do NOT suggest "I can try to read it" or similar
IF API fails — Display the error message and STOP immediately
NO fallback methods — Do NOT attempt handwriting recognition any other way

📋 Output Display Rules

After running the script, present the OCR result clearly and safely.

Show extracted handwritten text (text) in full
Summarization is allowed, but do not hide important extraction failures
If the result file is saved, tell the user the file path
Show raw upstream response only when explicitly requested or debugging (--include-raw)

How to Use

Recognize from URL

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

Recognize from Local File

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

Save Result to File

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

Include Raw Upstream Response (Debug Only)

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

CLI Reference

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

Parameter	Required	Description
`--file-url`	One of	URL to image/PDF
`--file`	One of	Local file path to image/PDF
`--output`, `-o`	No	Save result JSON to file
`--pretty`	No	Pretty-print JSON output
`--include-raw`	No	Include raw upstream API response in `result` field (debug only)

Response Format

{
  "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
}

Key fields:

ok — whether recognition succeeded
text — extracted text in Markdown (use this for display)
layout_details — layout analysis details
error — error details on failure

Error Handling

API key not configured:

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

→ Show exact error to user, guide them to configure

Authentication failed (401/403): API key invalid/expired → reconfigure

Rate limit (429): Quota exhausted → inform user to wait

File not found: Local file missing → check path