QClaw知识库导入失败的根本原因是原始文档未清洗，含页眉页脚、水印、扫描噪点等非正文内容，导致OCR失败或向量化中断；需手动清理、确保文字可选、转为支持格式并验证.chunk.json文件及微信指令响应。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
QClaw知识库导入失败时，文档明明拖进上传框却没反应、进度条卡住不动、或提示“解析失败”“向量化中断”，根本原因往往不是网络或软件崩溃，而是你上传前没动过原始文件——页眉页脚、扫描水印、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’的内容”
观察返回结果是否包含原文段落、页码标识及引用来源。若仅输出概括性描述，说明原始文档中该条款被页眉/水印/扫描噪点干扰，文本提取已失败。
