用 OpenClaw 用得越久，越会遇到一个高频场景：你把一个文件丢给 Agent——一份 PDF 合同、一张 Excel 报价表、一张拍下来的纸质单据——然后说「帮我整理一下」。结果要么它回你「我读不了这个文件」，要么读出来的内容乱七八糟：表格串行、文字变乱码、扫描件一个字都提取不出来。
问题大多不是 Agent 笨，而是文件读取这件事本身有门槛：不同格式有不同的读法，PDF 还分「有文字层」和「纯扫描」两种完全不同的情况。这篇教程把 OpenClaw 读文件这件事按类型拆开讲：每种文件怎么喂给它、用什么方式读、常见坑在哪，让你把文件丢给它时心里有底。
第 0 步：先搞清文件的「读法」分两种
所有文件读取，本质上分两条路：文本提取和视觉识别（OCR）。文本提取是把文件里存的文字直接抽出来——Word、Excel、CSV 以及有文字层的 PDF 走这条路，又快又准。视觉识别是让模型「看」图像、把图像里的字认出来——图片、截图、扫描版 PDF 走这条路，速度慢一些、准确率受清晰度影响，但没有文字层时它是唯一的路。
判断文件走哪条路，最笨也最有效的办法是问一句：这个文件能选中里面的字吗？能复制就是有文字层，不能复制（扫描件或图片）就得走 OCR。很多人在扫描 PDF 上硬走文本提取，什么都提不出来，还以为 Agent 坏了——其实是路走错了。
给文件的三种姿势，先让 Agent「看一眼」
OpenClaw 里把文件交给 Agent 通常有三种方式：直接作为附件拖进对话、给本地文件路径让它读、给它一个 URL 让它自己下载。三种都行，但建议养成一个习惯：先让 Agent 确认文件的基本信息再动手——文件名、格式、大小、大概多少页。一个 200MB 的视频和一个 2MB 的 PDF，处理方式天差地别；先摸清底细，能避免它傻乎乎地去「读」一个根本不是文本的东西。
按类型拆：每种文件的正确读法
PDF。先分文字层还是扫描件：文字层 PDF 直接提取文本，又快又准；扫描版 PDF 先转成图片再走 OCR。PDF 里的表格是重灾区——直接提取文本时表格会变成一堆没规律的文字，要保住表格结构，得用专门的解析工具按表格模式提取，或者干脆把那一页转成图片让模型看。老达的建议：合同、论文这类以文字为主的 PDF 用文本提取；带大量表格的报表型 PDF 转图让模型看，结构反而更准。
Word / PPT。这俩本质是打包的 XML，用现成解析库转成纯文本或 Markdown 最省事。可以把这一步做成一个 OpenClaw 自定义技能：丢进来一个 .docx，技能自动转文本、保留标题层级，Agent 拿到的就是干净的结构化内容。注意 .doc 老格式和 .docx 不一样，很多解析库只支持新格式，老文件先转一下格式再喂。
Excel / CSV。表格文件别让 Agent「读文字」，要让它「读结构」。正确姿势是用解析库把每个 Sheet 读成结构化的行列表（或转成 CSV/JSON），表头、行号、单元格都清清楚楚，Agent 再基于这些数据干活——AI Agent 结构化输出 讲过：机器能用的数据要先结构化，别让模型面对一团乱麻的文字。多级表头和合并单元格是 Excel 解析最常见的坑，解析后最好让 Agent 先复述一遍它理解的结构（「这个表有三列：产品、单价、数量，第一行是表头」），确认理解对了再往下做。
图片 / 截图 / 纸质单据。走 OCR 或视觉模型。选型分两种：只想要「把图里的字抠出来」，用 OCR 工具（本地有 tesseract 这类，云端有各家 OCR API）；想「看懂图里发生了什么」（比如界面截图、数据图表），用带视觉能力的大模型直接看——OpenClaw 接本地模型 提过的视觉模型方案就能干这事，敏感单据不出网也能识别。
压缩包。先解压，再按里面文件的类型分别处理。注意压缩包可能套娃、可能带密码、可能解压出可执行文件——让 Agent 解压前先列一遍包内文件清单，确认没有可疑文件再解，更别让它顺手执行里面的东西。
长文档：别一口气全塞进上下文
几百页的 PDF、几十万字的资料，一股脑读进来会把上下文塞爆，前面的内容被冲掉，Agent 开始「失忆」——AI Agent 上下文管理 讲过的窗口问题在这里最容易爆发。处理长文档的正确姿势是分块：先读目录或前几页搞清结构，再按章节分批读，读完一块总结一块，最后汇总。这样即使文档很长，每时每刻上下文里只有当前需要的那一块，Agent 不会读到后面忘了前面。
分块读还有个附带好处：让 Agent 每读完一章就标出「这部分讲了什么、有哪些关键数字」，读完直接得到一份带页码的摘要——比一次性读完再凭印象总结可靠得多，也方便你抽查它对没对。
读完之后：结果去哪，决定这套流程值不值
文件读出来只是第一步，真正值钱的是结果怎么处理。建议按用途分流：需要长期引用的资料，让 Agent 把要点结构化后写进数据库或知识库，下次直接检索、不用重读——OpenClaw 接数据库 正好承接这一步；需要跨会话记住的结论，存进长期记忆——OpenClaw 长期记忆 开启后，昨天读的合同要点今天还能直接引用；一次性的活，读完用完就行，别什么都往记忆里塞，塞多了就是污染。
常见坑与排查清单
把高频翻车点列成一张单子：扫描件当文字层读——提取出来全是空的或乱码，先确认有没有文字层；中文乱码——多数是编码问题，让 Agent 换 UTF-8 等编码重试，或用支持中文识别的解析参数；表格串行——别用纯文本提取读表格，换结构化解析或转图看；加密文件——有密码的 PDF 和压缩包要先要密码，别硬猜；超大文件——先看大小，超限就分块或让用户先拆分；读出来但内容对不上——让 Agent 标出「这段没把握」，而不是硬编一个通顺的版本。排错时先看它到底卡在哪一步，按日志定位的方法参考 OpenClaw 日志与排错 的流程，比瞎猜快得多。
优缺点与适合人群
好处：把「下载文件—打开—复制—整理」的人工环节省掉，批量处理一堆文件时效率提升最明显；配合定时任务，还能做「每天自动读新到的报表并汇总」这类持续活。代价：文件解析的坑比想象中多（格式千奇百怪、扫描件质量参差），头几次调试要花时间；OCR 对清晰度敏感，手写体和模糊单据别抱太高期望；涉及敏感文件记得优先本地模型，别把机密文档送云端。
适合：经常和 PDF、Excel、扫描件打交道的运营、财务、行政、法务类场景，以及想用 Agent 做批量文档处理的人。不适合：纯图片内容为主、几乎不碰文本文件的场景（那是图像处理的活，不是文档读取）；以及文件本身质量太差（模糊扫描、拍照歪斜）还想 100% 识别的情况——工具能提升上限，但救不了糊成一团的图。
总结
OpenClaw 读文件，记住五条：先分清文件走「文本提取」还是「视觉识别」，扫描件别硬走文字层；PDF 按文字版还是表格版选不同读法，Word/PPT 转文本、Excel 读结构、图片单据走 OCR；长文档分块读，别一口气塞爆上下文；读出来的结果按用途落进数据库或长期记忆，别只停留在对话里；出问题先确认卡在哪一步，再按日志定位。核心心法一句话：让 Agent 读文件，不是把文件丢给它就完事，而是先想清楚这份文件该怎么读、读哪部分、读完放哪——这三件事想明白了，Agent 读文件基本不会翻车。
