1. 大型仓库里 Claude Code 探索代码为什么这么慢

如果你用 Claude Code 处理过几千个文件的项目，大概率见过这个画面：让它「帮我理一下订单模块的调用链」，然后 Explore Agent 开始疯狂 grep、find、Read，进度条转一两分钟，token 消耗蹭蹭往上涨。等它终于给出答案，你发现它读了一堆无关文件，真正有用的就那几个。

这不是 Claude Code 不够聪明，而是它的工作方式决定的。默认情况下，Agent 对代码结构的理解是「按需扫描」——它不知道你的项目里有哪些函数、谁调用了谁、某个类在哪些文件里被引用。所以每次遇到探索性任务，它只能从文件系统一层层翻，靠 grep 匹配关键词，再 Read 具体文件确认。文件越多，这个暴力扫描的代价越大。

我自己的一个 TypeScript 项目，大概 1800 个文件，让 Claude Code 找「支付回调的完整处理链路」，它跑了 40 多次工具调用，耗时接近 90 秒，光读取文件就烧掉三万多 token。问题是这个任务我一周要问好几次，每次都从头扫一遍，纯属重复劳动。

CodeGraph 这个工具解决的正是这个痛点。它的思路很直接：既然 Agent 每次都要重新理解代码结构，那为什么不提前把符号关系建好索引？它扫描你的项目，提取函数、类、变量之间的调用关系，存进本地 SQLite 数据库，再通过 MCP Server 暴露给 Claude Code。Agent 需要了解结构时直接查图谱，不用再一个文件一个文件翻。

整个过程 100% 本地，不调任何外部 API，代码不出你的机器。支持 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart 等 19 种以上语言，还能识别 Django、Flask、FastAPI、Express、Laravel、Rails、Spring、Gin 这些框架的路由文件，把 URL 路径和处理函数关联起来。

适合谁用？文件数超过 100 的项目收益明显；如果你经常让 Agent 做「理解整体架构」「追踪调用链」「评估修改影响」这类探索性任务，装了会省很多时间；反过来，小脚本、小工具就没必要，Claude Code 直接扫也很快。

这篇就按我实际操作的顺序，从安装、配置 MCP、建索引，到把 endpoint 统一到 TaoToken 的 Key 通道，完整走一遍，最后用同一个仓库的前后耗时对比验证效果。

2. TaoToken 前置准备：统一 Key 通道与 MCP 接入配置

在装 CodeGraph 之前，先把模型调用这条链路理顺。Claude Code 本身要连模型，CodeGraph 的 MCP Server 是本地进程不消耗外部额度，但 Claude Code 的推理请求需要一个稳定的 endpoint。我习惯把所有 Key 统一到 TaoToken 的通道上管理，这样切换模型、查用量、控制成本都在一个地方，不用在多个平台之间来回倒腾。

TaoToken 的定位是统一的模型 API 接入层，Claude Code、Cline、Codex 这些工具都能通过它拿到兼容的接口。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api ，注意这个地址后面不加任何查询参数。

你需要先拿到一个 API Key。登录后进控制台，在 API Keys 页面创建一个，复制出来形如sk-xxxxxxxx的字符串。这个 Key 就是后面配置里的核心凭证，Claude Code 和 CodeGraph 的 MCP 配置都会用到它。

这里要区分两件事：CodeGraph 的 MCP Server 是本地 stdio 进程，它自己不联网、不调模型，只负责查本地索引；真正需要 endpoint 和 Key 的是 Claude Code 主程序。所以配置分两层——一层是 Claude Code 连 TaoToken，一层是 Claude Code 加载 CodeGraph 的 MCP Server。

先配 Claude Code 的模型通道。Claude Code 支持通过环境变量指定 Base URL 和 API Key，在~/.claude/settings.json里写：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥" } }

如果你用的是 Claude Code 的 OAuth 登录方式，也可以保留登录态，只把 Base URL 指到 TaoToken，具体看你的使用习惯。我实测下来，用 API Key 方式最省心，换机器、换项目都不用重新登录。

配完模型通道，再配 CodeGraph 的 MCP Server。这一步在~/.claude.json里加：

{ "mcpServers": { "codegraph": { "type": "stdio", "command": "codegraph", "args": ["serve", "--mcp"] } } }

注意这个配置里没有 Base URL 和 Key，因为 CodeGraph 是本地进程，不需要外部凭证。它的command是全局安装后的codegraph可执行文件，args告诉它以 MCP 模式启动。

如果你还想在 Cline 里用同一套 Key，Cline 的 MCP 配置格式类似，但字段名不同。Cline 用的是mcpServers对象，每个 server 有command、args、env三个字段。CodeGraph 在 Cline 里的配置：

{ "mcpServers": { "codegraph": { "command": "codegraph", "args": ["serve", "--mcp"], "env": {} } } }

Cline 的模型通道则在设置界面里填 Base URL 和 API Key，Base URL 同样填https://taotoken.net/api，Key 填同一个 TaoToken 密钥。这样 Claude Code 和 Cline 共用一套凭证，用量在 TaoToken 控制台统一看。

有个细节要注意：TaoToken 的 API 地址是https://taotoken.net/api，不要写成带/v1或其他路径的形式，也不要加 UTM 参数。UTM 只用在官网链接上，API 调用地址保持干净。

配好之后，先别急着建索引，验证一下 Claude Code 能不能正常连上模型。随便问一句「你好」，如果正常回复，说明模型通道通了。然后再重启 Claude Code，让它加载 CodeGraph 的 MCP Server。重启后输入/mcp命令，应该能看到 codegraph 这个 server 处于 connected 状态。如果没看到，检查~/.claude.json的 JSON 格式有没有写错，特别是逗号和引号。

这一步做完，前置准备就齐了。接下来进项目建索引。

3. 可复制配置：CodeGraph 安装、索引构建与 MCP 参数详解

安装 CodeGraph 最省事的方式是交互式安装器，一行命令：

npx @colbymchenry/codegraph

这个安装器会帮你做四件事：全局安装 codegraph 可执行文件、在~/.claude.json里写好 MCP Server 配置、设置 CodeGraph 工具的自动授权、往~/.claude/CLAUDE.md写入全局指令。如果你已经手动配过 MCP，它会提示你是否覆盖，选保留就行。

不想用交互式安装器的话，手动两步。先全局装：

npm install -g @colbymchenry/codegraph

然后按上一节的 JSON 片段手动加 MCP 配置。手动装的好处是可控，坏处是 CLAUDE.md 里的使用规则要自己补，这个后面踩坑部分会讲。

装完之后进项目目录初始化：

cd your-project codegraph init -i

-i是 interactive 的意思，会问你几个问题：要不要索引当前目录、排除哪些路径、用哪种索引模式。第一次跑建议用交互模式，看清楚它扫了哪些文件。如果项目结构固定，后续可以用非交互命令：

codegraph init --exclude "dist,build,.next,coverage" --lang typescript,python

--exclude指定跳过的目录，--lang限定要索引的语言。默认情况下 CodeGraph 会跳过node_modules、.git、dist这些常见目录，但如果你的项目有自定义构建输出目录，比如out、lib、generated，一定要手动加进排除列表，不然索引里会掺进一堆编译后的代码，查询结果会乱。

索引构建过程会打印进度，小项目几秒完事，大项目要等一会。我那个 1800 文件的 TypeScript 项目，首次索引大概 40 秒。作者测试过 Swift 编译器源码，25874 个文件、272898 个节点，索引时间不到 4 分钟。索引数据存在项目根目录的.codegraph/文件夹里，核心是index.db这个 SQLite 文件。

索引建完后，CodeGraph 会监听文件变化做增量更新。macOS 上用 FSEvents，Linux 上用 inotify，改了代码会自动同步索引，不用手动重建。如果你改了.codegraph/config.json里的排除规则，需要跑一次codegraph reindex全量重建。

配置文件.codegraph/config.json长这样：

{ "exclude": ["node_modules", ".git", "dist", "build", "coverage", "*.min.js"], "languages": ["typescript", "javascript", "python"], "maxFileSize": 1048576, "followSymlinks": false }

maxFileSize是单文件大小上限，默认 1MB，超过的文件跳过索引，避免大文件拖慢构建。followSymlinks默认 false，防止软链接导致循环扫描。

MCP Server 启动参数除了serve --mcp，还有几个可选项：

codegraph serve --mcp --db .codegraph/index.db --log-level info

--db指定索引数据库路径，默认就是.codegraph/index.db，一般不用改。--log-level控制日志详细程度，排查问题时可以调到 debug。

装完 CodeGraph 后，Claude Code 会多出这些 MCP 工具：

这里有个关键区分：codegraph_explore和codegraph_context会返回大段源代码，适合在子 agent 里用；主会话应该用codegraph_search、codegraph_callers、codegraph_callees这些轻量工具做定向查询。交互式安装器会自动在~/.claude/CLAUDE.md里写好这条规则，手动装的话要自己加：

## CodeGraph 使用规则 - 主会话只使用 codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_node - codegraph_explore 和 codegraph_context 仅在 Explore Agent 子会话中使用 - 探索代码结构时优先查索引，不要直接 grep 全仓库

这条规则很重要，不写的话主会话可能直接调codegraph_explore，一次返回几千行源码，上下文直接爆掉。

配置全部就位后，重启 Claude Code，输入/mcp确认 codegraph 已连接。然后就可以验证效果了。

4. 验证请求与成功结果：同一仓库前后耗时对比

验证分两步：先确认 MCP 工具真的被 Claude Code 调用了，再对比装前装后的耗时和 token 消耗。

先做个简单测试。在项目里问 Claude Code：「用 codegraph 查一下handlePaymentCallback这个函数被哪些地方调用」。如果配置正确，它会调用codegraph_callers，几秒内返回调用方列表，而不是去 grep 整个仓库。

我实测的输出大概是这样：

调用 codegraph_callers(symbol: "handlePaymentCallback") 返回 3 个调用点： - src/order/payment.controller.ts:47 - src/order/refund.service.ts:112 - src/webhook/stripe.handler.ts:23 耗时 1.2 秒

对比没装 CodeGraph 时，同样的查询它会先 grephandlePaymentCallback，找到文件后 Read 每个文件确认上下文，大概 8 到 12 次工具调用，耗时 15 到 25 秒。

再做个复杂点的探索任务：「梳理支付模块从接收到回调到更新订单状态的完整链路」。这个任务涉及多个文件、多层调用，最能体现索引的价值。

装 CodeGraph 前，我记录的数据：

工具调用次数：43 耗时：87 秒 读取文件数：19 token 消耗：约 32000

装 CodeGraph 后，同一个问题：

工具调用次数：4 耗时：21 秒 读取文件数：0 token 消耗：约 9000

工具调用减少 90%，耗时降到原来的四分之一左右，token 消耗降了七成。文件读取次数降到 0 是因为 Agent 直接从索引里拿到了关键代码片段，不需要再 Read 文件。

作者在 6 个真实项目上的测试数据也印证了这个趋势。VS Code 项目（TypeScript，4002 个文件）：装 CodeGraph 后 3 次工具调用、17 秒完成，没装是 52 次调用、1 分 37 秒，工具调用减少 94%，速度快 82%。Excalidraw 项目（TypeScript，626 个文件）：3 次调用、29 秒，对比 47 次调用、1 分 45 秒，减少 94%，快 72%。Alamofire 项目（Swift，102 个文件）：3 次调用、22 秒，对比 32 次调用、1 分 39 秒，减少 91%，快 78%。最夸张的是一个 Java 项目，1 次codegraph_explore调用就回答了整个问题，耗时 19 秒，没装的话要 26 次调用、1 分 22 秒。

平均下来，工具调用减少 92%，速度快 71%。这个「快 4 倍」的说法在部分项目上甚至偏保守，VS Code 那个案例快了接近 5 倍。

还有一个容易被忽略的收益是 token 消耗。装了 CodeGraph 之后文件读取次数降到 0，Agent 不再需要 Read 文件就能拿到关键代码片段。从测试数据看，token 消耗平均降了 20% 到 30%。如果你用的是按 token 计费的方案，大项目一个月下来省的钱不是小数目。

验证的时候可以用 Claude Code 的/cost命令看当前会话的 token 消耗，或者直接在 TaoToken 控制台看 API 调用量和费用。我习惯两边对照，确认 MCP 工具确实在起作用，而不是 Agent 又偷偷退回了 grep 模式。

如果发现耗时没降下来，先检查/mcp里 codegraph 是不是 connected，再看 CLAUDE.md 里的使用规则有没有生效。最常见的情况是 init 之后没重启 Claude Code，MCP Server 没加载，Agent 找不到 codegraph 工具，自然退回老模式。

5. 本篇常见错排查：401、local proxy failed、reading choices 与 OAuth

配置过程中踩的坑基本集中在几类报错上，逐个说清楚。

401 报错：invalid api key

这个通常出在 Claude Code 连 TaoToken 的环节。报错长这样：

API Error: 401 Unauthorized - invalid api key

原因有三种：Key 复制时带了空格或换行、Key 已经失效或被删除、ANTHROPIC_API_KEY环境变量没生效。排查顺序：先检查~/.claude/settings.json里的 Key 字符串有没有多余字符，再去 TaoToken 控制台确认这个 Key 还在、额度没用完，最后用echo $ANTHROPIC_API_KEY看环境变量有没有被覆盖。如果 settings.json 和 shell 环境变量同时设了，shell 的优先级更高，可能覆盖了配置文件里的值。

local proxy failed / connection refused

报错形式：

Error: local proxy failed to connect

或者：

connect ECONNREFUSED 127.0.0.1:xxxx

这个多半是 CodeGraph 的 MCP Server 没起来。检查codegraph命令能不能在终端直接跑：

codegraph --version

如果提示 command not found，说明全局安装没成功，重新跑npm install -g @colbymchenry/codegraph。如果能跑但 MCP 连不上，看~/.claude.json里的command字段是不是写成了绝对路径但路径不对，或者args里的serve --mcp拼错了。还有一种情况是端口被占用，CodeGraph 默认用 stdio 不走端口，但如果你改过配置用了 TCP 模式，检查端口冲突。

reading choices 报错

这个报错出现在模型返回格式异常时：

Error: reading 'choices' of undefined

说明 Claude Code 拿到的响应不是预期的 OpenAI 兼容格式。原因通常是 Base URL 配错了，比如写成了https://taotoken.net/api/v1或者带了多余路径。正确地址就是https://taotoken.net/api，不要加/v1、不要加斜杠结尾、不要加 UTM 参数。改完重启 Claude Code 再试。

OAuth 相关报错

如果你用 Claude Code 的 OAuth 登录而不是 API Key，可能会遇到：

OAuth token expired

或者：

Failed to refresh OAuth token

这种情况要么重新登录，要么干脆切到 API Key 方式。我实测下来 API Key 方式更稳定，不依赖登录态刷新，换机器也不用重新授权。切的方式就是在~/.claude/settings.json里设ANTHROPIC_API_KEY，然后清掉 OAuth 缓存。

CodeGraph 索引查不到结果

MCP 连上了，但codegraph_search返回空。先确认索引建了没有：

ls .codegraph/index.db

文件不存在就说明codegraph init没跑成功。文件存在但查不到，可能是语言没配对，检查.codegraph/config.json里的languages有没有包含你的项目语言。还有一种情况是文件被 exclude 规则排除了，比如你的源码放在src但 exclude 里误写了src，那就全被跳过了。

主会话上下文爆掉

如果 Claude Code 报上下文超限，多半是主会话直接调了codegraph_explore。检查~/.claude/CLAUDE.md里的使用规则有没有生效，确保主会话只用轻量工具。手动安装的话这条规则要自己加，交互式安装器会自动写。

CC Switch / Cline MCP / Codex auth.json 三件套

如果你同时用多个工具，配置要写全三件套：Base URL、Key、Model ID。以 Codex 的auth.json为例：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-20250514" }

Cline 的 MCP 配置里，CodeGraph 的 server 不需要 Key，但 Cline 本身的模型设置要填 Base URL 和 Key。CC Switch 这类工具切换配置时，确保三件套一起切，别只换了 Key 没换 Base URL，那样会 401。

排查的核心思路就一条：先确认模型通道通（能正常对话），再确认 MCP Server 连（/mcp显示 connected），最后确认索引建了（.codegraph/index.db存在）。三层都通，基本不会出问题。

6. 把 CodeGraph 用顺手：长期编码与 Agent 场景的 Key 通道建议

CodeGraph 装好之后，日常使用有几个习惯能让它发挥更大价值。

第一，探索性任务优先走索引。让 Claude Code 做「理解架构」「追踪调用链」「评估影响」这类任务时，明确在提示里说「用 codegraph 查」，比让它自己决定更可靠。比如「用 codegraph_impact 看一下改OrderService.create会影响哪些模块」，它会直接调对应工具，不走 grep。

第二，改代码前先查影响范围。codegraph_impact这个工具在重构时特别有用。改一个公共函数之前，先让它列出所有调用方，避免改完才发现漏了某个引用点。我现在的习惯是每次动核心模块前都跑一次 impact 查询，几秒钟的事，能省掉很多回归测试的麻烦。

第三，增量索引不用管。CodeGraph 监听文件变化自动更新，你正常写代码就行，不用手动 reindex。只有改了 exclude 规则或者换了语言配置才需要全量重建。

第四，多项目共用一套 Key。如果你同时维护几个仓库，每个仓库都建自己的.codegraph/index.db，但模型通道共用 TaoToken 的同一个 Key。这样用量在控制台统一看，不用每个项目单独配。Claude Code 的~/.claude/settings.json是全局的，所有项目共享；CodeGraph 的索引是项目级的，各建各的。

长期用 Claude Code 做编码和 Agent 任务的话，建议把 Key 通道固定下来。TaoToken 的 Coding Plan 适合高频编码场景，模型对话入口适合临时验证模型效果，API Keys 页面管理所有凭证。具体入口：

• 模型对话验证：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat
• Coding Plan 长期编码：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan
• API Keys 管理：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys
• 接入文档：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

最后说个实际经验：CodeGraph 的收益和项目规模正相关。文件数 100 以下的小项目，装了提升不明显，Claude Code 直接扫也很快。文件数 500 以上，收益开始显现。文件数 2000 以上，基本是刚需，不装的话每次探索任务都要等一两分钟。你可以先在自己的主力项目上装一个试试，跑几次探索任务对比一下耗时，觉得值再推广到其他仓库。

索引建好之后，.codegraph/目录建议加进.gitignore，这是本地数据，不需要提交。团队协作时每个人各自建索引就行，索引文件不大，重建也快。