知识库导入失败，数据传不进去，问题多半不在工具本身——先说个结论：大多数时候，是你给机器投喂的文档“没洗干净”。页眉页脚、扫描水印、PDF页码、参考文献附录这些东西，正在悄悄稀释知识的浓度，让QClaw根本没法提取有效文本。

上传时进度条卡住、提示“解析失败”或“向量化中断”，根本原因往往不是网络波动或软件崩溃，而是上传之前没动手清理原始文件。文档拖进上传框没反应？别急，先打开文件翻一遍。

检查文档是否被正确清洗

原始文档里那些非正文内容，会直接导致向量化失败。尤其是PDF文件，哪怕只有一处扫描噪点盖住了文字，QClaw的OCR引擎都可能整页跳过，让你哭都来不及。

打开你要上传的PDF或Word，手动翻一遍：删掉所有页眉页脚、页码、公司Logo水印、文末参考文献、致谢、版权声明、目录索引。这些东西对问答毫无价值，却会吃掉30%以上的向量空间。别嫌麻烦，这是最笨也最管用的办法。

如果是从网页保存的HTML文档，就用浏览器打开后按Ctrl+A → Ctrl+C → 新建纯文本文件 → Ctrl+V，再另存为UTF-8编码的.txt文件。这一步能彻底剥离CSS样式、广告脚本和无效标签，干净利落。

【关键前提】必须确保文档内所有文字都可被选中复制。如果鼠标划过文字却无法高亮，那说明它是图片型PDF，必须先走OCR流程，不能直接上传。这是最容易被忽视的坑。

确认上传路径与格式支持范围

QClaw目前只原生支持这些格式：.txt、.md、.pdf（文字型）、.docx、.xlsx（仅首Sheet文本内容）。其他如.epub、.rtf、.pages、.wps都不识别，上传后会静默失败，界面无报错。所以，先确认文件格式在不在支持列表里。

方法一：PDF转文字型PDF。用Adobe Acrobat Pro打开PDF → 选择“工具→增强扫描→识别文本→在本文件中” → 保存。别用在线转换工具，很多会插入不可见分页符，导致chunk切片错乱，后面更麻烦。

方法二：扫描件强制OCR。在QClaw上传界面勾选【强制OCR】选项后再拖入图片型PDF或JPG/PNG文件。注意：单张图片分辨率不得低于300dpi，否则OCR准确率骤降，错字连成句，知识库就变成“猜谜库”了。

方法三：Excel内容提纯。打开.xlsx文件 → 删除除第一张工作表外的所有Sheet → 清空所有公式，只保留结果值 → 将含标题的首行设为列名 → 复制整表 → 粘贴到新.txt文件中，用Tab键分隔字段 → 保存为UTF-8无BOM格式。这样提取出来的文本最干净。

验证知识库是否真正完成向量化

做完上面这些，不等于就万事大吉了。你得确认机器确实帮你把文档吃进去了、消化了，而不是只打了个饱嗝。

第一步：发送微信指令“查询USER.md中‘行业’字段值”。如果返回空或默认值，说明用户画像没加载，知识库底层索引根本没启动。别被上传成功的假象骗了。

第二步：打开本地QClaw安装目录 → 进入knowledge/文件夹 → 查找与你上传文件同名的.chunk.json文件。没有这个文件，代表文档尚未开始向量化；有但体积小于3KB，说明解析过程被截断——必须重新上传，并【务必勾选‘强制OCR’】。

第三步：在微信中发送“检索知识库中关于‘ISO 13485条款7.5.2’的内容”。观察返回结果是否包含原文段落、页码标识及引用来源。如果只输出概括性描述，说明原始文档中该条款被页眉/水印/扫描噪点干扰，文本提取已经失败了。这时候就得回去重新清洗文档，没什么捷径。