1. 从一次真实卡点说起claud-code 源码到底该怎么读claud-code 源码分析这件事很多人第一次打开仓库都会懵根目录没有熟悉的src/而是一堆平铺的域模块entrypoints/、tools/、commands/、services/、skills/、plugins/全在顶层main.tsx和setup.ts直接躺在根上。它本质上是一个以 TypeScript Bun bundling 为核心的 CLI/TUI 应用围绕“对话主循环 工具调用 Slash 命令 配置/权限/遥测/插件/技能”构建。适合谁读适合已经能用 claud-code 跑通日常编码、但想搞清楚“我敲下回车之后到底发生了什么”的开发者也适合准备给它接统一 API 通道、做二次封装或排查配置不生效的人。我试过最笨的办法——从main.tsx一行行往下读结果两小时还在 import 里打转。后来换成“先看入口分流再看初始化最后追主循环”的路径结构一下就清楚了。这篇就按这个顺序拆先讲代码架构的分层与调用链再落到可复制的settings.json/config.toml配置骨架把 TaoToken 统一 Key/API 通道接进去最后给出验证配置生效的具体命令和排错清单。读完你应该能画出自己的架构图并且知道改哪个文件会影响哪条链路。2. claud-code 代码架构逐层拆解2.1 入口层entrypoints/cli.tsx 的 fast-path 分流entrypoints/cli.tsx是轻量启动分发器它的设计目标是“能不进主程序就不进”。逻辑可以概括成三步解析 argv命中 fast-path 就地执行并返回否则动态import(../main.js)再调用main()。fast-path 覆盖--version、--dump-system-prompt以及若干内部 server/worker 模式这些路径只做极少 import避免把整个 TUI 依赖树拉起来。这里有个关键机制是 feature gate 驱动的 DCEdead code elimination。源码里大量feature(...)条件块在 Bun 打包阶段就能裁剪掉不参与构建的分支。所以你读源码时看到某个工具“明明写了却好像没生效”第一反应应该是去查它外层的 feature gate而不是怀疑自己看漏了。// entrypoints/cli.tsx 结构示意简化 async function bootstrap() { const argv process.argv.slice(2); if (argv.includes(--version)) return printVersion(); if (argv.includes(--dump-system-prompt)) return dumpSystemPrompt(); // feature gate 包裹的内部模式 if (feature(MCP_SERVER) argv.includes(--mcp-server)) return runMcpServer(); const { main } await import(../main.js); return main(); }2.2 初始化层init.ts 与 setup.ts 的分工这两个文件最容易混。entrypoints/init.ts是全局一次性初始化用memoize(async () ...)包住整个进程只跑一次负责enableConfigs()启用配置系统、应用 TLS/网络相关环境变量、为 remote managed settings 和 policy limits 建立 loading promise、延迟加载 OpenTelemetry 并在“信任后”初始化遥测以及 API preconnect、OAuth 信息补齐这类后台预热。setup.ts则贴近单次 session 的运行时准备校验 Node 版本要求 18、setCwd()与setProjectRoot()、切换 session id、捕获 hooks 配置快照、启动文件变更 watcher、在--worktree时创建 worktree 并可拉起 tmux session还有插件 hooks 预加载、会话内存、启动 sinks 等。一句话区分init 管“进程级的一次性”setup 管“会话级的每次”。2.3 核心层QueryEngine 主循环与上下文注入QueryEngine.ts是对话生命周期的核心抽象管理一次 conversation 的多轮 turn 状态包括 messages、usage、file cache、权限拒绝记录、plugin/skill 发现等。它的输入是用户 prompt文本或内容块外加工具集合、命令集合、MCP client、权限回调、状态读写函数输出是以AsyncGenerator形式逐步 yield 的SDKMessage这也是流式输出的来源。下游通过query()与services/api/claude完成模型调用和 usage 累积通过工具池执行工具通过命令解析把/xxx映射成 prompt 或动作。context.ts负责把系统上下文和用户上下文组织成对话前置内容。system context 可能包含 git status可被 remote/配置禁用和 cache breaker injectionuser context 默认会收集 ClaudeMd/memory files在--bare或显式禁用时跳过。它用 memoize 缓存避免每 turn 重复 I/O并在 injection 变化时主动清缓存——这点很重要你改了 memory 文件却感觉没生效往往就是缓存没被正确失效。2.4 扩展层tools.ts、commands.ts、skills 与 pluginstools.ts是所有工具的事实来源getAllBaseTools()返回当前环境下可能存在的全部工具集合再按isEnabled()、权限 deny rules、工具池策略过滤。工具覆盖文件类读/写/编辑、glob、grep、notebook、shell 类Bash、可选 PowerShell、web 类fetch/search、可选 browser、任务编排类Task create/get/update/list、TaskOutput、TodoWrite、Plan mode、Agent/Skill 以及 MCP resource 读/list。commands.ts是 Slash 命令的聚合注册点把commands/*下的实现组装成可用列表同样受 feature gate 与环境变量条件加载。扩展模型基本固定新增命令就在commands/下实现并在commands.ts注册新增工具就在tools/下实现 Tool 并加入getAllBaseTools()同时考虑权限与 feature gate新增技能或插件走skills/*、plugins/*的加载路径并确保与 policy/setting/telemetry 约束一致。模块职责关键文件入口分流argv 解析与 fast-pathentrypoints/cli.tsx全局初始化配置/遥测/网络一次性初始化entrypoints/init.ts会话准备cwd/worktree/hooks/watchersetup.ts上下文注入system/user context 组装与缓存context.ts对话主循环多轮 turn 状态与流式输出QueryEngine.ts工具事实来源工具集合与过滤tools.ts命令聚合Slash 命令注册commands.ts3. TaoToken 前置统一 Key 与 API 通道在动配置之前先把通道准备好。TaoToken 在这里扮演的是统一 Key/API 通道的角色把模型调用收敛到一个入口这样你在 claud-code 里只需要维护一份凭据和 base URL不用在多个 provider 之间来回切。你需要准备两样东西一个可用的 API Key以及对应的 API 接入地址。Key 在控制台的 API Keys 页面创建接入方式和参数说明看接入文档两处入口分别是API Keyshttps://taotoken.net/console/api-key?utm_sourcetaotoken_aicg_blog_end接入文档https://taotoken.net/docs?utm_sourcetaotoken_aicg_blog_end如果你只是想先验证模型能不能通、对话是否正常用模型对话页面直接试最省事https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_end 。如果你打算长期在 claud-code 里做编码和 Agent 任务建议直接上 Coding Plan额度与通道更匹配https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_end 。注意Key 只放在本地配置或环境变量里不要提交进 git也不要写进任何会随仓库分发的文件。轮换 Key 时优先改环境变量避免逐个改配置文件。4. 可复制配置settings.json 与 config.toml 骨架claud-code 的配置分两层一层是应用级 settings一层是模型通道级 config。下面这份骨架可以直接抄把占位符替换成你自己的值即可。先看settings.json{ model: claude-sonnet-4-5, apiProvider: custom, apiKeyEnv: TAOTOKEN_API_KEY, baseUrl: https://taotoken.net/api, permissions: { allow: [Read, Glob, Grep], deny: [Bash(rm -rf *)] }, context: { includeGitStatus: true, memoryFiles: [CLAUDE.md] }, telemetry: { enabled: false } }再看config.toml它更适合放通道与超时这类偏基础设施的参数[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_ms 60000 max_retries 3 [model] default claude-sonnet-4-5 max_tokens 8192 [network] preconnect true环境变量这样设Linux/macOS 写进 shell 配置Windows 用系统环境变量界面export TAOTOKEN_API_KEYsk-你的Key export CLAUDE_CODE_SETTINGS$HOME/.claude/settings.json参数对照表方便你按需改参数作用建议值baseUrl / base_url统一 API 通道地址https://taotoken.net/apiapiKeyEnv从哪个环境变量读 KeyTAOTOKEN_API_KEYtimeout_ms单次请求超时60000max_retries失败重试次数3includeGitStatus是否注入 git statustruememoryFiles注入的上下文文件CLAUDE.md5. 验证请求确认配置真的生效配置写完不代表生效必须验证。第一步确认环境变量被正确读取echo $TAOTOKEN_API_KEY | head -c 8能打印出 Key 前 8 位说明变量存在。第二步用 curl 直接打通道排除 claud-code 本身的干扰curl -s -X POST https://taotoken.net/api/v1/messages \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 只回复 ok}] }返回体里出现正常的 content 字段说明 Key 和通道都没问题。第三步回到 claud-code 里跑一次最小会话观察它是否走了你配置的 base URL。可以在启动时打开调试输出确认请求地址和模型名claude --dump-system-prompt | grep -i base_url\|model如果这里打印的还是默认地址说明 settings 没被加载回到第 4 节检查CLAUDE_CODE_SETTINGS路径。第四步验证上下文注入是否生效在项目根放一个CLAUDE.md写入一句特征字符串然后发起一次对话问它“我的项目约定是什么”能答出来就说明context.ts的注入链路通了。6. 本篇常见错排查配置不生效九成出在加载顺序上。init.ts里enableConfigs()在建立信任前只应用“安全环境变量”如果你把 Key 写在一个需要信任后才读的配置项里早期请求就会拿不到凭据。解决办法是把 Key 放环境变量配置里只写apiKeyEnv引用。第二个高频问题是 Node 版本。setup.ts明确要求 18低于这个版本会在会话准备阶段直接失败报错信息不一定直白。先跑node -v确认。第三个是 feature gate 误判。你按源码加了个工具结果没出现多半是外层feature(...)在构建时被裁掉了。检查构建配置里该 feature 是否开启而不是改运行期代码。第四个是上下文缓存。改了CLAUDE.md但对话里没体现是context.ts的 memoize 缓存还在。重启会话或触发一次 injection 变化让缓存失效。第五个是超时与重试。长上下文请求在默认超时下容易断把timeout_ms提到 60000 以上max_retries设 3能覆盖大部分网络抖动。现象可能原因处理请求打到默认地址settings 未加载检查 CLAUDE_CODE_SETTINGS启动即失败Node 18升级 Node工具不出现feature gate 裁剪检查构建配置上下文不更新memoize 缓存重启会话长请求中断超时过短提高 timeout_ms7. 继续往下走把通道固定成长期方案架构拆到这一步你应该能说清 claud-code 从cli.tsx分流、init.ts初始化、setup.ts准备会话到QueryEngine驱动主循环、tools.ts提供工具、context.ts注入上下文的完整链路。配置侧settings.json管应用行为config.toml管通道参数Key 走环境变量验证靠 curl 加最小会话两步。如果你准备把它用在日常编码和 Agent 任务上建议把通道固定下来用 Coding Plan 承接长期调用避免每次临时找 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_end 。接入过程中遇到参数对不上、报错定位不了直接翻接入文档对照字段https://taotoken.net/docs?utm_sourcetaotoken_aicg_blog_end 。想先确认某个模型在当前通道下的实际表现用模型对话跑一轮最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_end 。下一篇我会接着拆QueryEngine的多轮状态管理和工具调用的权限判定路径把主循环里的分支逐个走一遍。