1. 为什么我要在 Claude Code 里折腾 PDF 和 OCR如果你平时的工作流里经常出现扫描件、图文混排 PDF、发票、合同、技术白皮书那你大概率经历过这样的循环打开某个在线转换工具把文件拖进去等它转完再手动复制粘贴最后发现表格错位、公式乱码、图片全丢。更麻烦的是有些文件涉及内部资料上传到第三方平台本身就让人不放心。Claude Code 的 Skill 机制正好切中这个痛点。它把「提取文字」「合并拆分」「OCR 识别」「填表加密」这些能力打包成可插拔模块你只需要用自然语言说一句话它就能自动匹配对应 Skill 并执行。而 PDF Skill 是其中使用频率最高的一个——提取文字、表格转 CSV、扫描件 OCR、合并拆分、加密解密、提取图片基本覆盖了日常文档处理的大部分场景。但实际落地时很多人会卡在同一个地方Skill 本身是本地运行的可一旦涉及模型推理比如 OCR 后的语义校验、表格结构理解、多页内容归纳就需要一个稳定的 API 通道。如果每个 Skill 各自配置 Key管理起来会很乱。我试过把 Key 散落在不同配置文件里结果换一次环境就要重新对一遍非常容易出错。这篇就聚焦一件事在 Claude Code 里用 TaoToken 统一 Key 和 API 通道把 PDF 解析与 OCR 配置一次性打通。配置完成后你可以在 Claude Code 内稳定调用文档 Skill批量处理扫描件和图文混排 PDF不用再为每个环节单独折腾鉴权。2. TaoToken 前置统一 Key 与 API 通道的准备TaoToken 在这里扮演的角色是「统一入口」。你不需要为每个 Skill 单独申请不同的 Key而是用一个 Key 走同一个 API 通道Claude Code 里的各个 Skill 都指向这个通道即可。这样做的好处很直接换环境时只改一处排查问题时也只盯一个地方。先做两件准备工作。第一拿到你的 API Key。访问 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite在控制台里创建一个新的 Key复制保存。注意不要把它提交到 Git 仓库后面我们会用环境变量的方式引用。第二确认 API 基础地址。TaoToken 的 API 入口是https://taotoken.net/api这个地址不加 UTM 参数直接作为 base_url 使用。如果你需要查看完整的接入说明可以参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite控制台入口在这里方便你后续查看用量和额度https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite注意Key 只保存在本地环境变量或 Claude Code 的配置文件中不要写进会被公开的代码。如果你用 dotenv记得把.env加进.gitignore。准备工作做完接下来进入配置环节。3. 可复制配置settings.json 接入统一 KeyClaude Code 的配置核心是settings.json。我们要做的是把 API 通道和 Key 写进去让 Skill 在调用模型时走 TaoToken。先确认你的 Skill 目录结构。PDF Skill 通常放在项目的.claude/skills/下目录名类似pdf。Claude Code 启动时会自动识别这个目录。如果你还没有这个 Skill可以从官方开源仓库获取后把对应目录复制进来。下面是一份可复制的settings.json骨架。把它放在项目根目录的.claude/下具体路径以你的 Claude Code 版本为准常见为.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey }, skills: { pdf: { enabled: true, path: .claude/skills/pdf } }, permissions: { allow: [ Read, Write, Bash(python:*), Bash(pdftotext:*) ] } }几个关键点说明一下。ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址这样所有模型请求都会走统一通道。ANTHROPIC_API_KEY填你刚才创建的 Key。如果你不想把 Key 明文写在 JSON 里可以改成从环境变量读取比如在 shell 里先export ANTHROPIC_API_KEYsk-xxx然后 JSON 里留空或省略该字段。skills.pdf.enabled打开 PDF Skillpath指向实际目录。permissions.allow里放行必要的读写和命令执行权限OCR 场景通常需要调用 Python 或pdftotext这类工具提前放行可以避免每次弹确认。如果你更习惯用环境变量管理也可以只保留 base_urlKey 通过 shell 注入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoTokenKey配置完成后重启 Claude Code让它重新加载 settings 和 Skill。4. 验证请求一句话触发 PDF 解析与 OCR配置对不对跑一次就知道。我们分三步验证先做纯文本提取再做扫描件 OCR最后做结果校验。4.1 纯文本 PDF 提取准备一个测试 PDF比如sample.pdf放在项目目录下。在 Claude Code 里输入帮我把 sample.pdf 里的文字提取出来保存到 sample.mdClaude Code 会自动匹配 PDF Skill调用解析能力输出 Markdown 文件。如果配置正确你会在目录下看到sample.md内容包含 PDF 的文本。这一步验证的是基础通道是否打通。如果报鉴权错误多半是 Key 或 base_url 的问题回到第 5 节排查。4.2 扫描件 OCR 提取扫描件和纯文本 PDF 的区别在于前者是图片需要 OCR。准备一个扫描版 PDF比如scan_invoice.pdf然后输入这份 PDF 是扫描的图片帮我 OCR 提取全部文字存到 invoice_note.mdSkill 会调用 OCR 流程识别图片中的文字并写入文件。实测下来清晰扫描件的识别效果比较稳定金额、日期这类结构化字段基本能正确提取。如果文件是图文混排比如一页里有表格又有说明文字可以在指令里补充这份 PDF 是图文混排帮我 OCR 提取文字并把第三页的表格单独导出成 table.csv4.3 结果校验OCR 之后不要直接信结果做一次校验更稳妥。你可以让 Claude Code 自己比对读取 invoice_note.md检查金额和日期字段是否完整如果有缺失或格式异常列出来这一步会触发模型对 OCR 结果做语义检查。因为走的是 TaoToken 统一通道模型调用和 Skill 执行在同一套配置下完成不需要额外切换。如果你还想验证模型对话能力是否正常可以到模型对话页面直接测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite在页面里发一条消息确认通道可用。这样能把「Skill 本地执行」和「模型推理」两条链路分开验证排查时更容易定位。5. 本篇常见错排查配置过程中容易踩的坑集中在几个地方我按出现频率排一下。鉴权失败401/403。最常见的原因是 Key 没生效或 base_url 写错。检查settings.json里的ANTHROPIC_BASE_URL是否为https://taotoken.net/api注意结尾不要多加斜杠。Key 是否有多余空格是否被 shell 里的旧环境变量覆盖。可以用echo $ANTHROPIC_API_KEY确认当前生效的值。Skill 未加载。Claude Code 启动时如果没识别到 PDF Skill先确认.claude/skills/pdf目录存在且settings.json里skills.pdf.enabled为true。目录名和配置里的 key 要一致。改完配置后必须重启 Claude Code热加载不一定生效。OCR 结果为空或乱码。先确认 PDF 本身是不是纯图片扫描件。如果是检查是否安装了 OCR 依赖比如 Python 的 OCR 库或系统级工具。权限方面permissions.allow里要放行对应的命令否则 Skill 执行到一半会被拦下。另外扫描件分辨率太低也会导致识别率下降可以先用图像处理工具提升清晰度再试。表格导出错位。图文混排 PDF 的表格结构比较复杂纯 OCR 可能丢失行列关系。这种情况下可以在指令里明确要求「按表格结构导出」或者先用 PDF Skill 的表格提取能力再让模型做后处理。如果表格跨页建议分页处理后再合并。请求超时。批量处理大文件时单次请求可能超时。可以把任务拆小比如按页处理或者分批提交。TaoToken 通道本身是稳定的超时多半是单次任务太重。Key 泄露风险。如果你不小心把 Key 提交到了公开仓库立刻去控制台吊销并重新生成。控制台地址在前面已经给过吊销后更新本地配置即可。排障时如果拿不准是通道问题还是 Skill 问题可以先用模型对话页面发一条简单消息。如果对话正常说明通道没问题问题在 Skill 配置如果对话也失败那就是 Key 或 base_url 的问题。6. 长期编码与 Agent 场景的配置建议如果你不只是偶尔处理几个 PDF而是要把文档 Skill 纳入长期的编码或 Agent 工作流那配置思路上可以再进一步。一方面把 Key 和 base_url 统一放在环境变量里而不是写死在多个项目的settings.json中。这样换机器或换项目时只需要维护一份环境配置。另一方面如果你经常跑批量任务或长时间运行的 Agent可以关注 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它更适合需要持续调用、批量处理的场景额度和稳定性上会比单次调用更省心。另外Claude Code 的 Skill 机制本身是本地运行的数据不出电脑这一点对处理合同、发票这类敏感文件很重要。TaoToken 在这里只承担模型推理的通道角色不改变 Skill 的本地执行逻辑。你可以在接入文档里看到更完整的配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite配置一次后面处理扫描件、图文混排 PDF、批量 OCR 都能直接复用。真正省下来的时间不是省在敲命令上而是省在不用反复切换工具、不用重复鉴权、不用把文件传到不放心的地方。