Guide
OpenClaw + PaddleOCR: Scans and Images into Structured Text
OCR is the step people skip until a PDF turns out to be photographs of paper. PaddleOCR handles more than a hundred languages and returns document layout, not just a flat string — and it runs on your inference host, not in the bot.
When you need OCR and when you do not
A digitally generated PDF has an embedded text layer; a converter reads it directly and OCR would only add error. A scan, a photo of a receipt, or an exported image has no text layer at all — there is nothing to read until a model recognises the characters. The quick test is whether text selection works in a viewer. If it does not, you need OCR.
PaddleOCR also returns layout: which blocks are headings, which regions form a table, what reading order applies. For invoices and forms that structure is most of the value, because a flat transcription of a two-column page interleaves nonsense.
1. Deploy PaddleOCR serving
Use the official PaddleX serving path documented in the PaddleX repository to expose the PaddleOCR-VL pipeline over HTTP, pin the version, and front it with an authenticated TLS reverse proxy. Size the host for the model you chose — this is the layer that wants CPU or GPU headroom, which is precisely why it does not belong in a 4 GB agent container.
2. Connect it from Dashboard Tools
Open Dashboard Tools, select a running OpenClaw or Hermes instance, and connect the PaddleOCR card. The placeholder endpoint is https://paddleocr.example.com. The connector installs a scoped HTTP client and a managed skill describing the calls, so the agent does not have to invent request bodies. The client lives at a managed path — tools/dashboard-api-connectors/paddleocr/tool — and the examples below use tool as shorthand for it.
3. Two ways to send a page
The serving API accepts either a URL or base64 content, distinguished by a file type flag — 0 for a PDF, 1 for an image:
# A PDF reachable by URL
tool post /layout-parsing '{"file":"https://example.com/document.pdf","fileType":0}'
# An image sent inline
tool post /layout-parsing '{"file":"BASE64_IMAGE","fileType":1}'For anything larger, pipe the JSON through stdin and pass - as the final argument rather than embedding a huge base64 string in a command line. Printed responses cap at 5 MB and the client sets a 120-second socket timeout — which bounds a stalled connection rather than total runtime, so cap request duration on the serving side too and split long documents into page ranges instead of submitting a whole book.
4. Ask for the structure, then the answer
A two-step prompt beats a one-step one here: have the agent parse the document, then reason over the parsed result. "OCR this invoice, then give me the line items as a table with a total" is checkable. "What does this invoice say" invites a confident summary of a bad transcription.
OCR output is probabilistic. For numbers that matter — amounts, account identifiers, dates — ask the agent to quote the recognised text alongside its interpretation so a misread digit is visible rather than buried.
Production hardening
- Authenticate the endpoint and keep it private; an open OCR service is free compute for anyone who finds it.
- Cap request size and concurrency, and set a page limit per request.
- Give the service no retention of submitted documents unless you specifically need it.
- Log document identifiers and outcomes, never recognised contents of sensitive pages.
Pairing it with the other document tools
A practical pipeline: Stirling PDF to split a large scan into page ranges, PaddleOCR to recognise them, and MarkItDown for the documents in the same batch that already have a text layer and need no OCR at all.
Frequently asked questions
Can my agent read scanned documents?
Yes, with OCR. A scanned page contains no text layer, so a converter finds nothing to convert. PaddleOCR recognises the characters and returns text plus layout structure, which is what makes tables and multi-column pages usable.
Do the OCR models run inside my bot?
No. You connect a PaddleOCR serving deployment over HTTPS and the instance installs only a scoped client. Model weights and any GPU stay on that inference host, never inside the agent container.
How many languages does it handle?
More than one hundred, which is the main reason to pick it over a Latin-script-first OCR engine. It is a strong default for Chinese, Japanese, and Korean documents as well as mixed-script pages.