1. 从「云端知识库越用越怕」到 qmd 本地索引这篇文章在解决什么前阵子和做研发的朋友聊起文档检索大家几乎同一个状态个人笔记、团队成员的项目文档、会议记录散落在 Obsidian 和本地目录里真到要找资料的时候要么在云盘里翻半天要么怕客户信息上传到在线知识库出问题。后来社区里开始有人推 qmd 这种纯本地运行的 AI 搜索引擎它能索引本地 Markdown 文档、会议记录通过关键词搜索加语义搜索再加 LLM 重排序把结果找出来。整个过程都在本机完成断网也能跑敏感数据不出设备。这篇文章就是用 TaoToken 给 Claude Code 接入大模型通道顺着 qmd 已经建好的本地索引把「本地检索 AI 问答」跑成一条完整的 Agent 工作流。TaoToken 的统一 API 通道负责让 Claude Code 有模型可用qmd 继续做它最擅长的本地索引和混合搜索需要的 Key 在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建后面每个步骤都会具体说到。先说清楚分工免得后面绕晕qmd 管的是「文档在我这台机器上索引也在本机谁能帮我搜出相关内容」Claude Code 是「用户用自然语言提问我要根据问题决定调什么工具、看哪些文档、最后汇总回答」TaoToken 是 Claude Code 背后的大模型统一接入通道不参与索引也不碰你的文件内容。刚才提到的工作流里敏感文档还是留在本地qmd 的索引文件也在本地只有 Claude Code 向 TaoToken 发起模型推理请求时才会出网。这样既拿到了 AI 的总结和组织能力又不必把整套知识库搬上云。2. 先把 qmd 本体装好一条命令收编笔记和会议记录qmd 支持用 bun 全局安装也可以走 npm 或者 pnpm我个人习惯用 bun一条命令就能装完bun install -g https://github.com/tobi/qmd装完之后顺手确认一下版本号避免后面 MCP 插件调用时出现找不到命令的情况qmd --version如果你用的包管理器不是 bun比如 npm 全局目录存在权限问题可以考虑用 pnpm 再装一次。工具本身不大真正占地方的是后面qmd embed要下载的 embedding 模型文件那个通常几百 MB 到几个 GB需要留出磁盘空间。安装完成后把散落的文档「收编」进集合。集合Collection是 qmd 里最核心的组织单元它不是一个数据库文件而是一组对本地目录的描述。我给个人笔记、会议记录、工作文档分别建了三个集合qmd collection add ~/notes --name notes qmd collection add ~/Documents/meetings --name meetings qmd collection add ~/work/docs --name docs路径根据自己的实际情况改。这里有一点要注意qmd 索引的是目录里现有的 Markdown 文件如果以后在这个目录下新增了文档需要再跑一次增量同步它本身不会实时监听文件系统变化。为了让搜索结果的来源更可读可以给每个集合补一句上下文描述qmd context add qmd://notes Personal notes and ideas qmd context add qmd://meetings Meeting transcripts and notes qmd context add qmd://docs Work documentation这一步不是必须的但当你搜到一个结果时qmd 能告诉你这个文档属于哪个集合方便 Claude Code 在回答里带上「这段内容来自 meetings 集合的 2024-01-15.md」定位起来很快。然后生成向量索引语义搜索靠的就是这一步qmd embed第一次运行会下载 embedding 模型文件根据网络情况可能要等一阵子。之后再跑就快多了它只处理新增或变更的文件。3. 三种搜索方式里最该记住的是混合搜索索引建完之后qmd 提供三种搜索方式分别对应不同场景。我是按这个思路用的关键词搜索qmd search project timeline基于 BM25 全文检索速度快适合你记得确切关键词的情况。想拿给 AI Agent 用可以加 JSON 输出qmd search authentication --json -n 10-n 10控制返回条数--json让输出变成结构化数据Claude Code 解析起来比纯文本流畅很多。语义搜索qmd vsearch how to deploy基于向量相似度文档里没有「deploy」这个词只要语义相近也能找出来。适合只有模糊印象、记不准术语的情况。混合搜索qmd query quarterly planning process这是集大成者先用本地 LLM 把原始查询扩展成多个变体再同时跑关键词和语义搜索最后用重排序模型把结果按相关度重新排一遍。直接拿它当默认命令用就行搜索质量在这个工具里是最高的。如果只想拿路径不想要整篇内容qmd query error handling --all --files --min-score 0.4--all表示在所有集合里搜--files只返回文件路径--min-score 0.4过滤掉低分结果。这样配合 Claude Code 使用时可以先拿到一批文件路径再让模型决定读哪几个。需要读取完整内容时qmd get meetings/2024-01-15.md也可以用索引里的文档 ID 获取搜索结果里会带类似#abc123的短 IDqmd get #abc123这些命令单独用已经很顺手了但真正让它发挥价值的是下一步接到 Claude Code 里让模型在一个长会话里同时调度 qmd 搜索和语言推理。这也是为什么需要把模型通道切到 TaoToken——Claude Code 本身不自带大模型它需要一个能访问模型的 API 地址。4. Claude Code 装 qmd 插件后把模型通道指到 TaoTokenClaude Code 接 qmd 分两步第一步装 qmd 的插件第二步把模型 Base URL 指到 TaoToken。装插件用官方命令行claude marketplace add tobi/qmd claude plugin add qmdqmd装完插件之后Claude Code 会拿到一组 qmd 工具比如qmd_search、qmd_vsearch、qmd_query、qmd_get。这些工具的底层全都落在 qmd 命令上索引和文档内容仍然在本机完成。Claude Code 负责的是判断「当前这个问题该调用哪个工具、返回结果如何组织成答案」。这时候就轮到 TaoToken 登场了。Claude Code 官方默认的模型通道对国内开发者来说有配额和网络方面的门槛绕过这些限制不是本文要讲的也不该那么做更稳的做法是让 Claude Code 走一个兼容通道把模型请求发到你自己的 API 地址上。TaoToken 正好提供这种统一接入方式。打开 TaoToken 注册并创建 API Key然后配置 Claude Code 的环境变量。Claude Code 的全局配置在~/.claude/settings.json像下面这样填{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: 以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场为准 } }三个环境变量缺一不可。ANTHROPIC_BASE_URL填的是接口地址注意末尾不要加/v1TaoToken 的接入文档里对这一点有明确说明。ANTHROPIC_AUTH_TOKEN填你从控制台创建的 Key也就是上面说的YOUR_API_KEY别和官网落地页地址搞混那个是注册和创建 Key 用的填进工具的是https://taotoken.net/api。ANTHROPIC_MODEL不要拍脑袋填一个模型名去模型广场看当时提供哪些可用的 Claude 模型 ID照着列表选。这是 Claude Code 的标准环境变量配置方式不是通用 JSON是整个生态里和 Anthropic 官方客户端兼容的写法。改完之后重启 Claude Code让配置生效。顺带提一下如果你更习惯在项目级配置里区分不同项目的模型可以把这个 env 块放在项目根目录的.claude/settings.json里只对当前项目生效。平时开发我用全局配置不同客户项目需要隔离时再改成项目级。5. 验证链路让 Claude Code 去搜「数据库迁移那次会议的结论」配置保存后怎么确认两端真的打通了而不是各自跑各自的我的验证方法是给 Claude Code 提一个模糊的、没法靠模型知识回答的问题强制它去调 qmd。比如问它「去年讨论数据库迁移的会议记录结论是什么帮我列出当时提到的风险点。」如果链路正常Claude Code 会调用qmd_query做一次混合搜索返回一批会议记录文件路径再调用qmd_get读内容最后结合两份文档给出回答。回答里应该能看到类似「根据 meetings 集合的 2024-06-18.md 和 2024-06-25.md当时讨论的风险点主要有三个」这样的引用而不是模型凭自己的记忆硬编一段。这一点很重要qmd 没有搜索到内容Claude Code 就不该有对应结论。接着可以再测一个侧重点不太一样的查询「我笔记里有没有提过模糊搜索的调优思路」这个问题适合验证语义搜索因为你的笔记里可能根本没写「模糊搜索」四个字写的可能是「fuzzy match」或者「拼写纠错」。如果 qmd 能通过向量相似度把相关笔记捞回来说明 embedding 索引是真的在工作Claude Code 只是一个把结果翻译成自然语言的角色。链路通了以后再去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 看一眼这次交互有没有产生 API 调用记录。TaoToken 控制台的用量列表里能看到刚才 Claude Code 发出的请求、对应模型和 token 消耗。这一步能帮你确认问题到底出在模型通道还是出在 qmd 插件是排查问题最直接的分界点。在 TaoToken 模型对话 里也可以用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 没填错。如果这里能通而 Claude Code 里不通问题基本就在环境变量的加载路径上去检查 settings.json 的位置和 JSON 格式即可。如果这里也不通那就是 Key 或模型 ID 的问题先去 控制台 API Keys 确认 Key 的状态和额度再回到模型广场核对模型 ID。6. 只有本篇会遇到的报错逐个说清排查方向跑这套「Claude Code qmd TaoToken」的组合和纯 CLI 搜索不一样报错来源分成三层每一层的现象和修法都不同。这里只挑三个最常见的写。第一层qmd 命令本身找不到错误现象是qmd: command not found或者 Claude Code 插件报「Failed to execute qmd」之类的错。常见原因是 bun 的全局 bin 目录不在 PATH 里解决办法是把 bun 的 bin 目录加到 shell 配置里而不是重装工具。第二层模型通道报 404如果 Claude Code 启动后模型请求直接 404先检查ANTHROPIC_BASE_URL是不是被写成了https://taotoken.net/api/v1。TaoToken 的兼容地址末尾不带/v1这一点和很多 OpenAI 风格网关不一样多写一个/v1会直接导致路由对不上。另外确认ANTHROPIC_MODEL是不是填了模型广场里不存在的名字拿不准就用广场列表里显示的原始 ID。第三层插件装上了但工具调不出来claude marketplace add tobi/qmd执行成功但对话中 Claude Code 一直不调用 qmd 工具可能的原因有两个。一个是当前会话是插件安装前启动的重启会话让工具列表重新加载另一个是模型在长对话里判断「这个问题不需要外部搜索」这种情况可以主动换一种说法提示它比如「先用 qmd 搜索一下再回答」把工具调用的意图表达得更明确。另外给一个 CLI 直接验证的办法如果你机器上装了taotoken/taotoken也可以不经过 Claude Code直接确认模型通道可用npm install -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID-u后面同样不要加/v1。这条命令的作用是把模型通道这一层单独摘出来测试通过之后再去查 Claude Code 的插件问题定位会快很多。完整的 Claude Code 环境变量说明在 接入文档 里写得很细遇到不确定的字段可以直接对照文档查。7. 跑通之后这套组合实际能做什么链路验证通过后我实际用得最多的是三个场景都和本地知识库的隐私保护强相关。第一个是会议记录回顾。以前团队开完会想把某次关于备份策略的讨论找出来得按日期翻文件。现在直接问 Claude Code「6 月那几次例会里有没有讨论过备份策略把结论整理一下。」它会先让 qmd 做语义搜索定位到 meetings 集合里的几次会议记录再返回给模型汇总。整个过程不需要把会议记录传到任何云服务上。第二个是技术文档检索。查某个内部 API 的用法时Claude Code 可以先用qmd search搜出相关实现文件读完后直接基于项目里的真实代码回答而不是凭训练数据猜一段可能过时的写法。对于代码量大的仓库这个价值很快就体现出来了。第三个是写文档或周报前的资料收集。我让 Claude Code 针对某个主题先跑一轮qmd query --all --files --min-score 0.4把相关的本地文档路径全捞出来再逐个读取重点内容最后在回答里列出每份文档说了什么。这样生成的初稿每条信息都有出处不用像以前那样担心 AI 编造细节。整套方案跑顺之后你对自己的知识库会建立一种信任感文档在本地索引在本地搜索也在本地Claude Code 留在外面的只有最后那一层和模型 API 交互的内容。如果你刚装好 TaoToken 还没想好跑什么场景建议先从自己的笔记目录开始建集合。索引好之后挑一条之前死活想不起关键词的旧笔记用qmd query搜一遍再用 Claude Code 问一遍感受一下「本地检索 AI 问答」和单纯浏览器搜索的差别。之后需要长期大量调用的话可以去看看 Coding Plan 是否更贴合你的用量。