PaddleOCR Text Recognition Skill

---

name: paddleocr-text-recognition

description: Extracts text (with locations) from images and PDF documents using PaddleOCR.

metadata:

openclaw:

requires:

env:

- PADDLEOCR_OCR_API_URL

- PADDLEOCR_ACCESS_TOKEN

- PADDLEOCR_OCR_TIMEOUT

bins:

- python

primaryEnv: PADDLEOCR_ACCESS_TOKEN

emoji: "🔤"

homepage: https://github.com/PaddlePaddle/PaddleOCR/tree/main/skills/paddleocr-text-recognition

---

# PaddleOCR Text Recognition Skill

When to Use This Skill

Invoke this skill in the following situations:

Do not use this skill in the following situations:

Installation

Install Python dependencies before using this skill. From the skill directory (`skills/paddleocr-text-recognition`):

pip install -r scripts/requirements.txt

How to Use This Skill

**⛔ MANDATORY RESTRICTIONS - DO NOT VIOLATE ⛔**

1. **ONLY use PaddleOCR Text Recognition API** - Execute the script `python scripts/ocr_caller.py`

2. **NEVER read images directly** - Do NOT read images yourself

3. **NEVER offer alternatives** - Do NOT suggest "I can try to read it" or similar

4. **IF API fails** - Display the error message and STOP immediately

5. **NO fallback methods** - Do NOT attempt OCR any other way

If the script execution fails (API not configured, network error, etc.):

Basic Workflow

1. **Identify the input source**:

- User provides URL: Use the `--file-url` parameter

- User provides local file path: Use the `--file-path` parameter

- User uploads image: Save it first, then use `--file-path`

**Input type note**:

- Supported file types depend on the model and endpoint configuration.

- Follow the official endpoint/API documentation for the exact supported formats.

2. **Execute OCR**:

```bash

python scripts/ocr_caller.py --file-url "URL provided by user" --pretty

```

Or for local files:

```bash

python scripts/ocr_caller.py --file-path "file path" --pretty

```

**Default behavior: save raw JSON to a temp file**:

- If `--output` is omitted, the script saves automatically under the system temp directory

- Default path pattern: `<system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json`

- If `--output` is provided, it overrides the default temp-file destination

- If `--stdout` is provided, JSON is printed to stdout and no file is saved

- In save mode, the script prints the absolute saved path on stderr: `Result saved to: /absolute/path/...`

- In default/custom save mode, read and parse the saved JSON file before responding

- Use `--stdout` only when you explicitly want to skip file persistence

3. **Parse JSON response**:

- In default/custom save mode, load JSON from the saved file path shown by the script

- Check the `ok` field: `true` means success, `false` means error

- Extract text: `text` field contains all recognized text

- If `--stdout` is used, parse the stdout JSON directly

- Handle errors: If `ok` is false, display `error.message`

4. **Present results to user**:

- Display extracted text in a readable format

- If the text is empty, the image may contain no text

- In save mode, always tell the user the saved file path and that full raw JSON is available there

IMPORTANT: Complete Output Display

**CRITICAL**: Always display the COMPLETE recognized text to the user. Do NOT truncate or summarize the OCR results.

**Correct approach**:

I've extracted the text from the image. Here's the complete content:

[Display the entire text here]

**Incorrect approach**:

I found some text in the image. Here's a preview:
"The quick brown fox..." (truncated)

Usage Examples

**Example 1: URL OCR**:

python scripts/ocr_caller.py --file-url "https://example.com/invoice.jpg" --pretty

**Example 2: Local File OCR**:

python scripts/ocr_caller.py --file-path "./document.pdf" --pretty

**Example 3: OCR With Explicit File Type**:

python scripts/ocr_caller.py --file-url "https://example.com/input" --file-type 1 --pretty

**Example 4: Print JSON Without Saving**:

python scripts/ocr_caller.py --file-url "https://example.com/input" --stdout --pretty

Understanding the Output

The output JSON structure is as follows:

{
  "ok": true,
  "text": "All recognized text here...",
  "result": { ... },
  "error": null
}

**Key fields**:

> Raw result location (default): the temp-file path printed by the script on stderr

First-Time Configuration

**When API is not configured**:

The error will show:

CONFIG_ERROR: PADDLEOCR_OCR_API_URL not configured. Get your API at: https://paddleocr.com

**Configuration workflow**:

1. **Show the exact error message** to the user (including the URL).

2. **Guide the user to configure securely**:

- Instruct the user to visit the [PaddleOCR website](https://www.paddleocr.com), click **API**, select the model you need, then copy the `API_URL` and `Token`. They correspond to the API URL (`PADDLEOCR_OCR_API_URL`) and access token (`PADDLEOCR_ACCESS_TOKEN`) used for authentication. Supported model: `PP-OCRv5`.

- Optionally, ask the user to configure the request timeout via `PADDLEOCR_OCR_TIMEOUT`.

- Recommend configuring through the host application's standard method (e.g., settings file, environment variable UI) rather than pasting credentials in chat. For example, in OpenClaw, environment variables can be set in `~/.openclaw/openclaw.json`.

3. **If the user provides credentials in chat anyway** (accept any reasonable format), for example:

- `PADDLEOCR_OCR_API_URL=https://xxx.paddleocr.com/ocr, PADDLEOCR_ACCESS_TOKEN=abc123...`

- `Here's my API: https://xxx and token: abc123`

- Copy-pasted code format

Warn the user that credentials shared in chat may be stored in conversation history. Recommend setting them through the host application's configuration instead when possible.

Then parse and validate the values:

- Extract `PADDLEOCR_OCR_API_URL` (look for URLs with `paddleocr.com` or similar)

- Confirm `PADDLEOCR_OCR_API_URL` is a full endpoint ending with `/ocr`

- Extract `PADDLEOCR_ACCESS_TOKEN` (long alphanumeric string, usually 40+ chars)

4. **Ask the user to confirm the environment is configured**.

5. **Retry only after confirmation**:

- Once the user confirms the environment variables are available, retry the original OCR task

Error Handling

**Authentication failed**:

API_ERROR: Authentication failed (403). Check your token.

**Quota exceeded**:

API_ERROR: API rate limit exceeded (429)

**No text detected**:

Tips for Better Results

If recognition quality is poor, suggest:

Reference Documentation

For in-depth understanding of the OCR system, refer to:

> **Note**: Model version, capabilities, and supported file formats are determined by your API endpoint (`PADDLEOCR_OCR_API_URL`) and its official API documentation.

Testing the Skill

To verify the skill is working properly:

python scripts/smoke_test.py

This tests configuration and API connectivity.