如何把 PaddleOCR Agent Skills 装进 AI 应用：一句话文字识别与文档解析完整指南

如何把 PaddleOCR Agent Skills 装进 AI 应用：一句话文字识别与文档解析完整指南

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

把 PaddleOCR Agent Skills 装进 Claude Code、OpenClaw 这类支持 Skills 的 AI 应用后，一句自然语言就能完成 PaddleOCR 文字识别或文档解析，全程不写代码。从环境准备到验收，我们一次跑通。

一、是什么、怎么选：两个 Skill 各管一件事

Skill 可以把一项任务的触发规则、调用步骤、配置要求和结果处理实践打包成一个模块，AI 应用按需加载它，自己就知道该调什么命令、怎么报错了。PaddleOCR 官方目前提供两个，分工如下：

判断标准很直接：目标是纯文本，走文字识别；文档里含表格、公式、图表或多栏版面，走文档解析。前者相当于"把字读给我"，后者相当于"把这份文档还给我"。

二、动手前的环境清单：三件事先备好

所有操作都在同一台设备完成，开工前把下面三条勾掉即可：

1. Python 版本 ≥ 3.9：运行python3 --version确认一下。
2. 装好 PaddleOCR 3.7.0 及以上：pip install "paddleocr>=3.7.0"。
3. 拿到 access token：登录百度 AI Studio，在账户设置里的 Access Token 页面复制。后面要配给它。

可以放心的是，Skill 背后调用的paddleocr api是把文件提交到官方托管服务、等它跑完再取结果的子命令，不做本地推理，所以既不需要 GPU，也不用装额外依赖组。

三、把 Skill 装进 AI 应用：按顺序试三条路

两条 Skill 的源码都在仓库的 skills 目录，规则细节可看文字识别 Skill 规则文件和文档解析 Skill 规则文件。安装按下面顺序来，任一条走通即可停。

路线 1：skillsCLI（需要先装 Node.js）

npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y

这条方式会把 Skill 全局装到设备上，装完各 AI 应用都能用。因为 PaddleOCR 仓库体积较大，网络慢时命令可能超时，此时先把仓库克隆下来，再从本地路径安装：

git clone https://gitcode.com/GitHub_Trending/pa/PaddleOCR npx skills add ./PaddleOCR/skills/paddleocr-text-recognition npx skills add ./PaddleOCR/skills/paddleocr-doc-parsing

路线 2：clawhub（OpenClaw 用户）

clawhub install paddleocr-text-recognition clawhub install paddleocr-doc-parsing

路线 3：手动拷贝（兜底）

克隆仓库后，把PaddleOCR/skills下你要的那个 Skill 目录，拷到你 AI 应用指定的 Skills 位置。拷到哪里，以 Claude Code、claude.ai、OpenClaw 各自的安装说明为准。只装一个 Skill 时，上面所有命令也只保留对应那一条。

四、把 token 交给你的应用：PADDLEOCR_ACCESS_TOKEN 配置方法

核心就是一个环境变量：PADDLEOCR_ACCESS_TOKEN（必填）；另有PADDLEOCR_BASE_URL（可选，API 服务地址，不填就用官方服务）。

Claude Code

在项目根目录的.claude/settings.local.json里加env字段，把<ACCESS_TOKEN>换成你的 token：

{ "env": { "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>" } }

OpenClaw

在~/.openclaw/openclaw.json里给对应 Skill 加上配置，enabled置true，token 填进env：

{ "skills": { "entries": { "paddleocr-text-recognition": { "enabled": true, "env": { "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>" } }, "paddleocr-doc-parsing": { "enabled": true, "env": { "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>" } } } } }

其他应用

直接把 token 以PADDLEOCR_ACCESS_TOKEN环境变量的形式提供给应用即可；也可以不用环境变量，在单次调用时用--token参数显式传入。

五、第一次触发与验收：提示词、关键参数和成功输出

配置完就可以开口了。直接用自然语言描述任务，再附上文件 URL 或本地路径，AI 应用会自己挑对应的 Skill。下面四种说法都管用：

• "帮我把这张截图里的文字认出来，逐行列出来：<你的图片链接>"
• "把这个本地 PDF 里的文本都取出来：C:\docs\invoice.pdf"
• "解析这份 PDF，我要标题、正文和里面所有表格：<你的 PDF 链接>"
• "解析本地文件 C:\docs\report.pdf，给我完整的结构化结果。"

Skill 实际执行的是paddleocr api命令。--model_type必填（取值ocr或doc_parsing），--file_url与--file_path二选一，手动验证时可以直接跑：

paddleocr api \ --model_type ocr \ --file_path "./document.pdf"

完整参数见 官方 API CLI 文档 或执行paddleocr api --help。

成功时你会得到一段格式化 JSON（未指定--output时打印到标准输出）。文字识别结果重点看这几个字段：

{ "jobId": "job-xxx", "pages": [ { "prunedResult": { "rec_texts": ["Line 1", "Line 2"], "rec_scores": [0.98, 0.95] }, "ocrImageUrl": "https://..." } ] }

验收就看两点：pages是否覆盖目标页码、rec_texts内容是否与文档实际内容一致。文档解析（--model_type doc_parsing）的 JSON 结构不同，每页带markdownText、markdownImages、outputImages，验收时主要比对markdownText里的 Markdown 正文。

六、排错、边界与提速：失败输出怎么判断

失败输出怎么判断

命令出错时，信息打到标准错误流（stderr）且退出码非零，凭这两点就能判定失败。常见三类：

• 认证错误：PADDLEOCR_ACCESS_TOKEN缺失或无效。先确认环境变量配没配、token 是否来自 AI Studio 且未过期。
• 配额错误：API 限流或配额用完，稍后重试。
• 未检测到内容：输入是空白页，或图里压根没有文字。

SKILL.md 的要求是：CLI 报错时向用户说明具体问题，不要静默失败，也不要悄悄回退到应用自身的视觉能力。

两个 Skill 的适用范围

paddleocr-text-recognition明确不接含表格、公式、图表或复杂版面的文档，这类任务交给paddleocr-doc-parsing：

另一条展示规则：结果要完整呈现给用户，只有内容超过 10,000 字符时才允许省略。

预处理开关何时关、何时留

API 默认开着扭曲矫正（use_doc_unwarping）和方向分类（use_doc_orientation_classify）两项预处理。截图、扫描规范的文档这类平整且方向正确的输入，可以直接关掉提速：

paddleocr api --model_type ocr --file_path "./document.pdf" \ --use_doc_unwarping False --use_doc_orientation_classify False

反过来，文档照片弯曲折叠、透视变形明显，或页面转了 90、180、270 度时，预处理要保留，别关。

收尾：拿真实文件跑一遍就通了

到这里，安装、token 配置、调用方式就都齐了。验收动作很简单：从手头挑一份真实 PDF 或图片，用上面任一句提示词发给你装好 Skill 的 AI 应用。输出 JSON 里的rec_texts或markdownText和文档实际内容对得上，说明整条链路已经打通，之后一句话就能出结果。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR