解决 Claude Code 在 Windows 系统上使用 Read 工具读取 PDF 时提示 password protected 的问题

从 Claude code报错PDF受密码保护 和 CC内置read读取PDF经常提示PDF有密码保护 继续讨论

TL; DR: 下载 poppler-windows 最新发行版，并把 Library\bin 文件夹添加到 PATH 中即可

事情的起因自然是我某天在使用 cc 快乐地 vibe coding 时，发现 cc 在调用 Read 工具读取 PDF 时竟然提示这份 PDF 是 password protected 的。但其实这份 pdf 是 LaTeX 编译的产物，当然没有密码保护。搜了搜 L 站的帖子发现大家也早就发现了这个问题，但目前的解决方案主要有：

1. 使用类似 mineru, pymupdf 的工具对 PDF 文件进行识别，转换为文本文件和 md 文件


2. 使用 pdf skill - 这个方案本质上也是对 pdf 进行文件形式的转换

但一个很显然的事实是不管是转换为 md 或者使用 skill 的方法都并不本质，转换的过程一定会有文件内容的损失；最大的问题是，它们都只是绕过了 Read 工具对 PDF 无法读取的问题，并没有实际解决它（既然报错信息是 PDF 受密码保护而不是拒绝输入 PDF 文件，那就证明 Read 工具一定是有读取 PDF 的能力的）。正好前段时间 claude code 被迫开源，就研究一下这个问题吧。

在 src/tools/FileReadTool/FileReadTool.ts 中可以看出，只要 Read 工具读取 PDF，并且传入 pages 参数，就会调用 extractPDFPages():

if (isPDFExtension(ext)) {

  if (pages) {

    const parsedRange = parsePDFPageRange(pages)

    const extractResult = await extractPDFPages(...)

而 extractPDFPages() 实际上是调用 pdftoppm 把 PDF 转成若干页的图像：

// pdftoppm produces files like <prefix>-01.jpg, <prefix>-02.jpg, etc.

const prefix = join(outputDir, 'page')

const args = ['-jpeg', '-r', '100']



if (options?.firstPage) {

    args.push('-f', String(options.firstPage))

}

注意，这里的相关参数是硬编码的，这也为后文埋下了伏笔。

Read 工具对 PDF 的错误处理在 src/utils/pdf.ts 的第 236 行：

if (code !== 0) {

    if (/password/i.test(stderr)) {

    return {

        success: false,

        error: {

        reason: 'password_protected',

        message:

            'PDF is password-protected. Please provide an unprotected version.',

        },

    }

}

从这里我们可以看到，触发 PDF 是 password-protected 的条件有两个，一是 pdftoppm 非 0 退出，二是 stderr 中含有 password 字段。那现在问题就明朗了：我们只要尝试 pdftoppm -jpeg -r 100 test.pdf output/page，如果同时出现上面两种情况，那么就说明在同样的条件下，cc 调用 Read 工具读取 PDF 也一定会出现 password-protected 的问题。事实上我也确实尝试了，结果如下：

于是这里果不其然报错了！并且由于 -jpeg 参数不受支持的原因，弹出了 pdftoppm 所有的参数列表，而这里面正好就有两个参数：-opw 和 -upw 的描述中含有 password 字段，所以就导致了上面的报错。

那么这里的 pdftoppm 是从哪里来的呢？运行 Get-Command 命令可以知道 source 是 D:\texlive\2024\bin\windows\pdftoppm.exe，所以终于真相大白了：

1. 我们在配置 LaTeX 后，下载的 texlive 中是自带 pdftoppm 命令的


2. 但处于某种原因，这里附带的命令并没有开启 ENABLE_LIBJPEG 编译选项, 导致附带的 pdftoppm 命令没有 -jpeg 参数


3. 从而 cc 在调用 Read 工具时的报错会一股脑把相关参数全倒出来，而这些参数的描述中就恰好有 password 字段…

知道问题的原因后解决方法也就很简单了，正如 TL; DR 中说的那样，下载一个在 windows 上预编译的 poppler 发行版，并添加到 PATH 中就好了。

P.S. 一个很难绷的事实是 github 上虽然有非常多相关 issue：

• [BUG] Read tool reports PDF is password-protected for unprotected PDFs on Windows (additional evidence for #30819) · Issue #37681 · anthropics/claude-code · GitHub


• [BUG] bug in Claude Code's PDF parser · Issue #30819 · anthropics/claude-code · GitHub


• [BUG] Read tool falsely reports unencrypted pandoc/LaTeX PDFs as 'password-protected' · Issue #66563 · anthropics/claude-code · GitHub

但最后要么是因为 duplicate 要么是因为 not planned 关闭，总之是没有人解决：A / 果然人如其名。