Claude-code源码学习：从入口到工具调用的完整链路拆解

1. 从 npm 包里挖出 1906 个 TypeScript 文件Claude-code 源码学习第一步该看什么Claude-code 源码学习这件事很多人卡在第一步拿到源码之后不知道从哪看起。我一开始也是这样打开目录树直接懵了——1906 个 TypeScript 文件、51 万行代码光cli.js就接近 60MB。你如果按文件名顺序一个个点开大概率看三天还在utils目录里打转。先说清楚这份源码是什么。Claude Code 是通过 npm 分发的命令行工具正常情况下发布前会做压缩混淆但 2.1.88 版本打包时 Source Map 文件没有被排除于是cli.js.map被直接发到了公开仓库。Source Map 相当于一份“翻译对照表”能把压缩后的代码还原回原始 TypeScript 结构。所以你现在拿到的不是反编译产物而是接近开发态的源码树包含 Agent 循环引擎、40 多个内置工具实现、系统提示词组装逻辑、记忆系统、上下文压缩、权限管控等模块。不包含的是服务端模型训练代码和 API 后端逻辑——这部分本来就不在客户端。这份源码适合谁看三类人收益最大。第一类是想自己写 AI Agent 的开发者Claude Code 的循环引擎和工具系统是目前最完整的工程参考之一。第二类是做 AI 编程工具的产品或架构同学它的记忆分层和上下文压缩策略可以直接迁移。第三类是想理解“AI 应用到底怎么写”的入门者它用的全是并发控制、读写分离、分层缓存这些你学过的基础知识只是组合方式很讲究。源码学习的核心检索词就三个启动入口、配置加载、工具注册。把这三条链路走通整个架构的骨架就清楚了。我试过按“入口 → 配置 → 工具 → 请求编排”四条链路逐层拆比按目录树硬啃效率高很多。下面按这个顺序展开每一步都给出可复制的本地阅读路径和关键模块定位清单。先建一个本地阅读环境。把仓库克隆下来之后不要急着打开编辑器全局搜索先做两件事一是用tree -L 2 -I node_modules看顶层目录结构二是用cloc统计各目录代码量找出体量最大的几个模块。体量大的地方通常就是核心逻辑所在。比如query相关文件、Tool相关文件、memdir目录都是重点区域。git clone https://github.com/1664178416/claude-code-map-learn.git cd claude-code-map-learn tree -L 2 -I node_modules|.git cloc --exclude-dirnode_modules .跑完这两条命令你会看到类似这样的结构顶层有src、cli、tools、memory、context、permissions等目录。src下面通常放核心引擎tools下面按工具名分文件memory和context分别对应记忆系统和上下文压缩。记住这个分布后面定位模块会快很多。还有一个实用技巧用grep -rn while (true) src/直接定位 Agent 主循环。Claude Code 的核心循环就是一个while(true)找到它基本就找到了整个请求编排的起点。同理grep -rn buildTool src/能找到工具工厂函数grep -rn DYNAMIC_BOUNDARY src/能找到提示词分层标记。这几个关键词是源码里的“路标”比翻目录快得多。2. TaoToken 前置本地跑通 Claude-code 源码学习需要准备什么源码学习不只是“读”还要“跑”。你光看代码不实际发一次请求很难理解工具调用是怎么串起来的。但直接拿官方 API 跑成本和网络配置都是门槛。我的做法是先用一个兼容 Anthropic 接口的接入点把链路跑通再对照源码看每一步发生了什么。TaoToken 在这里的角色就是提供这个接入点——它兼容 Anthropic 的 Messages API 格式Claude Code 这类工具可以直接对接。先明确一点TaoToken 不是 Claude Code 的替代品也不是编辑器插件。它是一个 API 接入服务你把它当成“模型请求的出口”就行。Claude Code 负责本地循环、工具执行、上下文管理TaoToken 负责把模型请求转发出去并返回结果。两者是配合关系不是替代关系。准备工作分三步。第一步拿到 API Key。访问https://taotoken.net/api-keys注册并创建一个 Key注意保存好页面关闭后不会再显示完整 Key。第二步确认 Base URL。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。第三步确认你要用的 Model ID。Claude Code 默认走 Anthropic 的模型命名你在配置里填的 Model ID 需要和 TaoToken 支持的模型列表对齐具体可以在https://taotoken.net/doc查。这里有个容易踩的坑很多人把 Base URL 写成https://taotoken.net/api/v1或者带一堆 query 参数结果请求 404。正确做法是 Base URL 只写到/api具体路径由 Claude Code 自己拼接。另外API Key 不要硬编码在源码里提交到 Git用环境变量或者本地配置文件管理。如果你只是想先验证模型能不能通不想折腾 Claude Code 的完整配置可以直接用模型对话页面发一条测试消息https://taotoken.net/model-chat。这一步的目的是确认 Key 有效、模型可用排除账号层面的问题。等确认能通之后再回到 Claude Code 的配置环节。对于长期做源码学习和 Agent 开发的场景建议了解一下 Coding Planhttps://taotoken.net/coding-plan。它面向的是持续编码和 Agent 调用场景比按次调用更适合反复调试。不过源码学习阶段先用按量调用也完全够用等链路跑通、开始做批量实验时再考虑。还有一点要提醒Claude Code 的源码里涉及权限管控和工具执行你在本地跑的时候不要直接连生产环境的数据库或敏感服务。源码学习用的工具调用建议指向本地测试目录或者沙箱环境。这不是 TaoToken 的限制而是任何 Agent 工具本地调试都应该遵守的基本习惯。3. 可复制配置Claude-code 源码学习环境下的 settings.json 与 auth 配置这一节给可直接复制的配置片段。Claude Code 的配置分两层一层是项目级的settings.json放在项目根目录的.claude文件夹下另一层是认证信息通常通过环境变量或auth.json管理。下面分别给出。先看项目级settings.json。这个文件控制模型选择、Base URL、工具权限等。路径是你的项目/.claude/settings.json。内容如下{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, permissions: { allow: [ Read, Grep, Glob ], deny: [ Bash(rm:*), Bash(curl:*) ] } }这里三个关键字段。model填你要用的 Model ID必须和 TaoToken 支持的模型对齐。env.ANTHROPIC_BASE_URL填https://taotoken.net/api注意不要加/v1。env.ANTHROPIC_API_KEY填你的 Key。permissions是工具权限白名单和黑名单源码学习阶段建议只开只读工具把Bash里的危险命令 deny 掉。如果你用的是 Codex 系的工具认证信息走auth.json路径通常是~/.codex/auth.json。内容格式如下{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }三件套必须齐全Base URL、Key、Model ID。缺任何一个都会报认证失败或模型不存在。我见过有人只填了 Key 没填 Base URL结果请求发到默认地址去了一直 401。如果你用 Cline 或者带 MCP 的客户端配置方式类似在 MCP 配置里填 Base URL 和 KeyModel ID 在模型选择处填。CC Switch 这类切换工具也是同样的三件套逻辑只是界面不同。还有一个环境变量方式适合不想写配置文件的情况export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key这种方式在终端会话里生效关掉终端就没了。适合临时调试不适合长期使用。长期用还是写进settings.json或auth.json。配置写完记得验证一下 JSON 格式用python -m json.tool .claude/settings.json检查有没有语法错误。JSON 里多一个逗号或者少一个引号Claude Code 启动时会直接报配置解析失败而且报错信息不一定指向具体行号排查起来很烦。4. 验证请求从启动入口到工具调用的完整链路实测配置好之后跑一次完整请求对照源码看每一步。启动 Claude Code 后输入一个简单任务比如“读取当前目录下的 README.md 并总结”。观察终端输出你会看到几个阶段配置加载、系统提示词组装、模型请求、工具调用、结果回填、最终回复。第一步配置加载。Claude Code 启动时会读取.claude/settings.json和认证信息合并成运行时配置。源码里对应的是配置加载模块通常在src/config或类似目录。你可以用grep -rn settings.json src/定位具体文件。这一步的关键是看配置优先级环境变量 项目配置 全局配置。如果你发现 Base URL 没生效先检查是不是被更高优先级的配置覆盖了。第二步系统提示词组装。Claude Code 会把角色定义、行为规范、工具说明拼成静态部分把当前时间、Git 状态、CLAUDE.md 内容拼成动态部分中间用DYNAMIC_BOUNDARY标记分隔。源码里搜DYNAMIC_BOUNDARY就能找到组装逻辑。这个设计的好处是静态部分可以跨用户共享缓存节省 token。你实测的时候可以在请求日志里看到这个边界标记。第三步模型请求。Claude Code 把组装好的消息发给ANTHROPIC_BASE_URL指向的地址也就是 TaoToken 的/api。请求体是 Anthropic Messages API 格式包含model、messages、tools等字段。你可以在源码里搜messages.create或类似的调用看请求是怎么构造的。第四步工具调用解析。模型返回的响应里如果包含工具调用Claude Code 会解析出来并执行。源码里对应的是工具执行模块搜buildTool能找到工具工厂。每个工具都有isConcurrencySafe、isReadOnly、isDestructive等属性默认值都是 fail-closed——没声明安全就按危险处理。第五步结果回填。工具执行结果被追加到对话历史然后再次调用模型。这就是while(true)循环的体现。源码里搜while (true)能看到完整循环逻辑压缩上下文、调用模型、解析工具、执行工具、追加结果、判断是否继续。第六步最终回复。当模型不再返回工具调用时循环结束输出最终回复。验证成功的标志是什么终端正常输出总结内容没有报错请求日志里能看到完整的请求和响应。如果中途卡住或者报错对照下一节的排查清单。这里给一个对照官方文档验证的方法打开https://taotoken.net/doc找到 Messages API 的请求格式说明然后在你本地抓一次 Claude Code 发出的请求可以用DEBUG* claude开调试日志逐字段对比。重点看model字段是否和文档一致、tools字段格式是否正确、messages结构是否符合预期。这一步能帮你确认“源码里的请求构造”和“官方文档的格式要求”是否对齐。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错怎么解源码学习过程中最容易遇到的四类报错逐个拆。401 Unauthorized。这是最常见的。原因通常有三个Key 没填、Key 填错、Key 过期。先检查settings.json或auth.json里的 Key 是否完整注意有没有多余空格。然后确认 Base URL 是不是https://taotoken.net/api如果 Base URL 写错请求发到别的地址Key 自然不认。最后去https://taotoken.net/api-keys确认 Key 状态是否正常。如果三件套Base URL、Key、Model ID都齐了还报 401检查环境变量里有没有旧的ANTHROPIC_API_KEY覆盖了配置文件。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或者代理地址写错。Claude Code 会读取HTTP_PROXY、HTTPS_PROXY环境变量。如果你不需要代理直接unset HTTP_PROXY HTTPS_PROXY再跑。如果你确实需要走本地代理确认代理进程在运行、端口对得上。注意源码学习场景下直接连 TaoToken 的 API 地址即可不需要额外代理配置。reading choices 报错。这个通常出现在响应解析阶段模型返回的格式和 Claude Code 预期的格式不一致。原因可能是 Model ID 填错了导致返回的不是 Anthropic Messages 格式。检查settings.json里的model字段确认和 TaoToken 支持的模型列表一致。另一个可能是请求体里tools字段格式不对源码里工具定义和 API 要求的格式有差异对照https://taotoken.net/doc检查。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 流程如果你用的是 API Key 方式需要在配置里明确禁用 OAuth。源码里搜oauth能找到相关逻辑。通常设置ANTHROPIC_API_KEY之后 OAuth 流程会被跳过但如果配置里同时存在 OAuth token 和 API Key可能会冲突。清理掉 OAuth 相关缓存文件再试。排查通用步骤第一步确认三件套齐全且格式正确。第二步用curl直接测 API 是否通curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:100,messages:[{role:user,content:hi}]}如果 curl 能通但 Claude Code 不通问题在 Claude Code 配置。如果 curl 也不通问题在 Key 或 Base URL。第三步开调试日志DEBUG* claude看请求实际发到了哪个地址、带了什么 header。第四步对照源码里的请求构造逻辑逐字段核对。还有一个隐蔽的坑Claude Code 会把配置缓存到本地改了settings.json之后可能需要重启才生效。如果你改了配置但行为没变先重启再排查。6. 语义一致 CTA源码学习之后怎么继续深入四条链路走完你应该对 Claude Code 的整体架构有了基本认知。启动入口负责初始化配置加载负责合并运行时参数工具注册负责构建工具集请求编排负责驱动while(true)循环。这四块串起来就是一个完整的 AI Agent 客户端骨架。接下来深入的方向有几个。一是 Agent 循环的细节重点看上下文压缩的五级策略和断路器机制源码里搜compact和circuit breaker能找到。二是工具系统的 fail-closed 设计看TOOL_DEFAULTS里每个默认值为什么这么设。三是记忆系统的三层架构热数据MEMORY.md、温数据话题文件、冷数据.jsonl历史对话源码里搜memdir能找到。四是权限管控看classifyYoloAction怎么在 YOLO 模式下做影子审查。如果你在配置或接入环节遇到问题直接看 API Keys 页面和接入文档https://taotoken.net/api-keys、https://taotoken.net/doc。想先验证模型通不通用模型对话页面https://taotoken.net/model-chat。长期做编码和 Agent 开发看 Coding Planhttps://taotoken.net/coding-plan。源码学习最有效的方式是“读一段、跑一段、改一段”。读完工具注册逻辑就自己加一个只读工具试试读完上下文压缩就手动触发一次压缩看日志。光读不跑很多设计细节体会不到。