1. 从一次本地调用失败说起为什么要拆 Claude Code 的架构Claude Code 是 Anthropic 推出的终端编码 Agent用 TypeScript 写成跑在 Node 环境里通过 React Ink 渲染命令行界面。它能读文件、跑 Bash、搜代码、调 MCP 工具核心是一个 ReAct 循环。适合谁看适合已经会用 Claude Code、但想搞明白它内部怎么调度工具、怎么管上下文、怎么接 MCP 的开发者。我这次不是单纯读源码而是想验证一件事把 Claude Code 指向一个统一的 Key/API 通道后Agent 循环和 MCP 工具链还能不能正常跑通。第一次尝试时我在settings.json里把ANTHROPIC_BASE_URL指向了本地一个自建转发结果 Claude Code 启动后一直卡在Connecting...日志里只有一行stream ended unexpectedly。排查了半天才发现是转发层没有正确处理 SSE 流式响应tool_use的增量块被截断了。这件事让我意识到Claude Code 的 Agent 循环对 API 通道的流式协议是有硬要求的不是随便一个 HTTP 代理就能接。所以这篇拆解分两条线一条是从 TypeScript 源码结构看它的 11 个设计要点另一条是用 TaoToken 的统一通道做一次可复制的本地验证确认 Agent 循环和 MCP 工具接入都能连通。两条线交叉着讲避免只谈架构不谈落地。2. TaoToken 前置统一 Key 与 API 通道准备在拆源码之前先把验证环境搭好。Claude Code 默认走 Anthropic 官方 API但它的配置层支持通过环境变量覆盖 base URL 和认证方式。TaoToken 在这里的角色是一个统一的 Key/API 通道让你用同一个 Key 访问多个模型省去在多个平台之间切换配置的麻烦。你需要先拿到一个 API Key。打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后进控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建完 Key 后API 端点用https://taotoken.net/api注意这个地址不加 UTM 参数它是纯 API 入口。如果你后面要长期跑编码 Agent可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频编码场景做了额度优化。注意Claude Code 的配置读取优先级是 环境变量 项目级 settings.json 用户级 settings.json。验证阶段建议先用环境变量避免污染全局配置。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层settings.json管 Claude Code 自身行为config.toml管 MCP 服务器注册。下面是我实测可用的骨架你可以直接复制后改 Key。3.1 settings.json 配置骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192, MAX_MCP_OUTPUT_TOKENS: 25000 }, permissions: { allow: [ Read, Grep, Glob ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, includeCoAuthoredBy: false, cleanupPeriodDays: 30 }这里几个参数值得说明。ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口Claude Code 会把所有模型请求发到这里。ANTHROPIC_AUTH_TOKEN用你的 TaoToken Key。permissions.allow里我只放了只读工具写操作和 Bash 默认走确认流程这是 Fail-Close 思路的实践——不确定的操作先拦住。3.2 config.toml 配置骨架MCP 服务器注册在config.toml里Claude Code 启动时会读取这个文件并建立工具连接[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/projects] [mcp_servers.fetch] command npx args [-y, modelcontextprotocol/server-fetch] [mcp_servers.sqlite] command uvx args [mcp-server-sqlite, --db-path, /Users/yourname/data/dev.db]每个[mcp_servers.xxx]段对应一个 MCP 服务器。command是启动命令args是参数。Claude Code 会在启动时拉起这些进程通过 stdio 做 JSON-RPC 通信。这里我注册了三个文件系统、网络抓取、SQLite 查询。注意 SQLite 那个只连开发库不要指向生产库。提示MCP 服务器启动失败不会阻塞 Claude Code 主流程但对应工具会不可用。启动后用/mcp命令可以查看每个服务器的连接状态。4. 验证请求确认 Agent 循环与 MCP 工具链连通配置写完后跑一次最小验证。打开终端进入你的项目目录启动 Claude Codeexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 claude启动后先看 MCP 状态输入/mcp正常应该看到类似输出MCP Servers: filesystem ✓ connected (12 tools) fetch ✓ connected (1 tool) sqlite ✓ connected (6 tools)如果某个服务器显示failed先检查npx或uvx是否在 PATH 里再看命令参数路径是否存在。接着发一条会触发工具调用的请求比如帮我读一下当前目录的 package.json告诉我项目用了哪些依赖Claude Code 的 Agent 循环会这样走先发请求给模型模型返回tool_use调用Read工具Claude Code 执行读取把结果追加到对话历史再发一轮请求模型基于文件内容生成回答。整个过程在终端里能看到工具调用的折叠块。如果你想单独验证模型通道是否通可以用模型对话页面发一条测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言的调用示例。验证成功的标志有三个/mcp全部 connected、工具调用块正常展开、模型回答里引用了文件真实内容。三个都满足说明 Agent 循环和 MCP 工具链都通了。5. 源码拆解11 个设计要点逐层看验证跑通后回到源码视角。Claude Code 客户端约 51 万行 TypeScript1900 文件核心模块集中在 Agent 循环、工具系统、记忆、上下文压缩、权限五块。下面挑 11 个设计要点讲。5.1 Agent 循环一个 while(true) 撑起 ReAct核心对话循环在query.ts里简化后就是一个无限循环压缩上下文、调模型、有tool_use就执行工具并追加结果、没有就退出。这就是 ReAct 机制——思考、行动、观察、再思考。没有复杂的多 Agent 编排最朴素的循环反而最稳。5.2 工具按需加载工具多的时候Claude Code 不会把所有工具的完整定义塞进系统提示词。它先给模型一份工具名加一句话介绍的精简清单模型选了哪些再加载完整定义。这从源头省了大量 Token。5.3 Fail-Close 默认危险buildTool工厂函数里isReadOnly和isReadSafe默认都是false。开发者忘了声明只读系统就自动当危险操作处理不让并发。默认禁止比默认允许安全。5.4 读写分离的并发调度只读工具可以并发跑默认上限 10 个。遇到写操作就排队等前面批次完成。并发执行完的结果不会立刻应用先存着等一批全跑完再按顺序应用。读高并发、写严格有序。5.5 系统提示词的静态/动态分裂Anthropic API 支持 Prompt Cache。Claude Code 用动态边界把系统提示词分成两半静态部分放工具定义和基础规则全球用户共享缓存动态部分放当前时间、仓库状态、CLAUDE.md。动态内容混进静态部分缓存就废了。5.6 不用 RAG用 Grep代码检索没用向量数据库直接用 Grep 文本搜索。让模型自己决定搜什么、怎么搜。模型越强这种朴素方案效果越好还省了维护索引的工程成本。5.7 三层记忆架构第一层MEMORY.md是热记忆每次对话都加载严格限制 200 行、25KB只存指针不存内容。第二层话题文件是温记忆用小模型挑最多 5 个相关文件按需加载。第三层历史对话是冷记忆用 Grep 搜索召回。核心原则记忆不记代码只记人的偏好和判断因为代码会变。5.8 五级上下文压缩从轻到重五级裁剪旧的工具结果、微压缩大体积结果、折叠中间对话、超阈值自动压缩、API 返回 413 时应急压缩。还加了断路器连续失败 3 次就停避免无限重试烧 Token。5.9 五重安全关卡用户权限配置、工具安全属性、YOLO 模式的影子 AI 分类器、Bash 命令安全检查、文件路径校验。即使开了跳过权限确认背后还有独立分类器把关。5.10 Feature Flag 与隐藏功能源码里到处是feature_xxx判断泄露了产品路线图长期助手模式、自动整理记忆、多 Agent 协作、语音模式、浏览器操作。这些开关本身也是灰度发布的手段。5.11 反蒸馏与卧底模式往 API 请求里注入假工具定义让抓流量蒸馏的模型越训越差。内部员工往开源项目提交代码时自动启用卧底模式防止内部代号泄露。6. 本篇常见错排查配置和验证过程中最容易踩的坑集中在通道和 MCP 两块。报错一stream ended unexpectedly或一直Connecting...这是 API 通道没有正确处理 SSE 流式响应。Claude Code 依赖流式增量块来解析tool_use如果中间层做了缓冲或截断循环就卡住。检查你的ANTHROPIC_BASE_URL是否指向了支持流式的端点。用 TaoToken 的https://taotoken.net/api时确认 Key 有效且额度充足。报错二401 UnauthorizedKey 没配对或者环境变量没生效。Claude Code 读的是ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY。两个都设了的话前者优先。用echo $ANTHROPIC_AUTH_TOKEN确认当前 shell 里值正确。报错三MCP 服务器显示failed先手动跑一遍command加args看进程能不能起来。常见原因是npx首次下载包超时或者路径参数指向的目录不存在。SQLite 那个如果 db 文件不存在服务器会启动失败先手动创建空文件。报错四工具调用被拒绝permissions.deny里匹配到了。Claude Code 的权限规则支持通配符Bash(curl *)会拦掉所有 curl 命令。排查时先看终端里的拒绝提示再对照settings.json的 allow/deny 列表。报错五上下文压缩后回答质量下降这是五级压缩的正常代价。如果频繁触发 L4 自动压缩说明单次会话太长。可以主动开新会话或者把大文件读取拆成多次小范围读取减少单轮 Token 膨胀。排障时如果怀疑是 Key 或通道问题直接去 API Keys 页面重新生成一个 Key 测试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。7. 继续深入从验证到长期编码跑通一次本地验证只是起点。如果你打算把 Claude Code 当日常编码工具几个实践建议把settings.json里的permissions.allow按项目逐步放开别一上来就全允许MCP 服务器按需注册注册太多会拖慢启动长会话定期开新的避免频繁触发重压缩。想单独测某个模型的行为用模型对话页面最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。长期跑编码 Agent 的话Coding Plan 的额度模型更适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。Claude Code 的 Anthropic 兼容接入说明在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite里面有完整的 base URL 和认证配置对照。源码拆到最后会发现Claude Code 没有用什么惊天动地的新算法并发控制、读写分离、分层缓存、断路器都是程序员熟悉的基础知识。难的是把这些东西组合到 AI 场景里并且每个默认值都往安全侧偏。这套思路比任何单个设计点都值得抄。
Claude Code 架构拆解：从 TypeScript 源码看 Agent 与 MCP 的 11 个设计要点
1. 从一次本地调用失败说起为什么要拆 Claude Code 的架构Claude Code 是 Anthropic 推出的终端编码 Agent用 TypeScript 写成跑在 Node 环境里通过 React Ink 渲染命令行界面。它能读文件、跑 Bash、搜代码、调 MCP 工具核心是一个 ReAct 循环。适合谁看适合已经会用 Claude Code、但想搞明白它内部怎么调度工具、怎么管上下文、怎么接 MCP 的开发者。我这次不是单纯读源码而是想验证一件事把 Claude Code 指向一个统一的 Key/API 通道后Agent 循环和 MCP 工具链还能不能正常跑通。第一次尝试时我在settings.json里把ANTHROPIC_BASE_URL指向了本地一个自建转发结果 Claude Code 启动后一直卡在Connecting...日志里只有一行stream ended unexpectedly。排查了半天才发现是转发层没有正确处理 SSE 流式响应tool_use的增量块被截断了。这件事让我意识到Claude Code 的 Agent 循环对 API 通道的流式协议是有硬要求的不是随便一个 HTTP 代理就能接。所以这篇拆解分两条线一条是从 TypeScript 源码结构看它的 11 个设计要点另一条是用 TaoToken 的统一通道做一次可复制的本地验证确认 Agent 循环和 MCP 工具接入都能连通。两条线交叉着讲避免只谈架构不谈落地。2. TaoToken 前置统一 Key 与 API 通道准备在拆源码之前先把验证环境搭好。Claude Code 默认走 Anthropic 官方 API但它的配置层支持通过环境变量覆盖 base URL 和认证方式。TaoToken 在这里的角色是一个统一的 Key/API 通道让你用同一个 Key 访问多个模型省去在多个平台之间切换配置的麻烦。你需要先拿到一个 API Key。打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后进控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建完 Key 后API 端点用https://taotoken.net/api注意这个地址不加 UTM 参数它是纯 API 入口。如果你后面要长期跑编码 Agent可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频编码场景做了额度优化。注意Claude Code 的配置读取优先级是 环境变量 项目级 settings.json 用户级 settings.json。验证阶段建议先用环境变量避免污染全局配置。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层settings.json管 Claude Code 自身行为config.toml管 MCP 服务器注册。下面是我实测可用的骨架你可以直接复制后改 Key。3.1 settings.json 配置骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192, MAX_MCP_OUTPUT_TOKENS: 25000 }, permissions: { allow: [ Read, Grep, Glob ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, includeCoAuthoredBy: false, cleanupPeriodDays: 30 }这里几个参数值得说明。ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口Claude Code 会把所有模型请求发到这里。ANTHROPIC_AUTH_TOKEN用你的 TaoToken Key。permissions.allow里我只放了只读工具写操作和 Bash 默认走确认流程这是 Fail-Close 思路的实践——不确定的操作先拦住。3.2 config.toml 配置骨架MCP 服务器注册在config.toml里Claude Code 启动时会读取这个文件并建立工具连接[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/projects] [mcp_servers.fetch] command npx args [-y, modelcontextprotocol/server-fetch] [mcp_servers.sqlite] command uvx args [mcp-server-sqlite, --db-path, /Users/yourname/data/dev.db]每个[mcp_servers.xxx]段对应一个 MCP 服务器。command是启动命令args是参数。Claude Code 会在启动时拉起这些进程通过 stdio 做 JSON-RPC 通信。这里我注册了三个文件系统、网络抓取、SQLite 查询。注意 SQLite 那个只连开发库不要指向生产库。提示MCP 服务器启动失败不会阻塞 Claude Code 主流程但对应工具会不可用。启动后用/mcp命令可以查看每个服务器的连接状态。4. 验证请求确认 Agent 循环与 MCP 工具链连通配置写完后跑一次最小验证。打开终端进入你的项目目录启动 Claude Codeexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 claude启动后先看 MCP 状态输入/mcp正常应该看到类似输出MCP Servers: filesystem ✓ connected (12 tools) fetch ✓ connected (1 tool) sqlite ✓ connected (6 tools)如果某个服务器显示failed先检查npx或uvx是否在 PATH 里再看命令参数路径是否存在。接着发一条会触发工具调用的请求比如帮我读一下当前目录的 package.json告诉我项目用了哪些依赖Claude Code 的 Agent 循环会这样走先发请求给模型模型返回tool_use调用Read工具Claude Code 执行读取把结果追加到对话历史再发一轮请求模型基于文件内容生成回答。整个过程在终端里能看到工具调用的折叠块。如果你想单独验证模型通道是否通可以用模型对话页面发一条测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言的调用示例。验证成功的标志有三个/mcp全部 connected、工具调用块正常展开、模型回答里引用了文件真实内容。三个都满足说明 Agent 循环和 MCP 工具链都通了。5. 源码拆解11 个设计要点逐层看验证跑通后回到源码视角。Claude Code 客户端约 51 万行 TypeScript1900 文件核心模块集中在 Agent 循环、工具系统、记忆、上下文压缩、权限五块。下面挑 11 个设计要点讲。5.1 Agent 循环一个 while(true) 撑起 ReAct核心对话循环在query.ts里简化后就是一个无限循环压缩上下文、调模型、有tool_use就执行工具并追加结果、没有就退出。这就是 ReAct 机制——思考、行动、观察、再思考。没有复杂的多 Agent 编排最朴素的循环反而最稳。5.2 工具按需加载工具多的时候Claude Code 不会把所有工具的完整定义塞进系统提示词。它先给模型一份工具名加一句话介绍的精简清单模型选了哪些再加载完整定义。这从源头省了大量 Token。5.3 Fail-Close 默认危险buildTool工厂函数里isReadOnly和isReadSafe默认都是false。开发者忘了声明只读系统就自动当危险操作处理不让并发。默认禁止比默认允许安全。5.4 读写分离的并发调度只读工具可以并发跑默认上限 10 个。遇到写操作就排队等前面批次完成。并发执行完的结果不会立刻应用先存着等一批全跑完再按顺序应用。读高并发、写严格有序。5.5 系统提示词的静态/动态分裂Anthropic API 支持 Prompt Cache。Claude Code 用动态边界把系统提示词分成两半静态部分放工具定义和基础规则全球用户共享缓存动态部分放当前时间、仓库状态、CLAUDE.md。动态内容混进静态部分缓存就废了。5.6 不用 RAG用 Grep代码检索没用向量数据库直接用 Grep 文本搜索。让模型自己决定搜什么、怎么搜。模型越强这种朴素方案效果越好还省了维护索引的工程成本。5.7 三层记忆架构第一层MEMORY.md是热记忆每次对话都加载严格限制 200 行、25KB只存指针不存内容。第二层话题文件是温记忆用小模型挑最多 5 个相关文件按需加载。第三层历史对话是冷记忆用 Grep 搜索召回。核心原则记忆不记代码只记人的偏好和判断因为代码会变。5.8 五级上下文压缩从轻到重五级裁剪旧的工具结果、微压缩大体积结果、折叠中间对话、超阈值自动压缩、API 返回 413 时应急压缩。还加了断路器连续失败 3 次就停避免无限重试烧 Token。5.9 五重安全关卡用户权限配置、工具安全属性、YOLO 模式的影子 AI 分类器、Bash 命令安全检查、文件路径校验。即使开了跳过权限确认背后还有独立分类器把关。5.10 Feature Flag 与隐藏功能源码里到处是feature_xxx判断泄露了产品路线图长期助手模式、自动整理记忆、多 Agent 协作、语音模式、浏览器操作。这些开关本身也是灰度发布的手段。5.11 反蒸馏与卧底模式往 API 请求里注入假工具定义让抓流量蒸馏的模型越训越差。内部员工往开源项目提交代码时自动启用卧底模式防止内部代号泄露。6. 本篇常见错排查配置和验证过程中最容易踩的坑集中在通道和 MCP 两块。报错一stream ended unexpectedly或一直Connecting...这是 API 通道没有正确处理 SSE 流式响应。Claude Code 依赖流式增量块来解析tool_use如果中间层做了缓冲或截断循环就卡住。检查你的ANTHROPIC_BASE_URL是否指向了支持流式的端点。用 TaoToken 的https://taotoken.net/api时确认 Key 有效且额度充足。报错二401 UnauthorizedKey 没配对或者环境变量没生效。Claude Code 读的是ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY。两个都设了的话前者优先。用echo $ANTHROPIC_AUTH_TOKEN确认当前 shell 里值正确。报错三MCP 服务器显示failed先手动跑一遍command加args看进程能不能起来。常见原因是npx首次下载包超时或者路径参数指向的目录不存在。SQLite 那个如果 db 文件不存在服务器会启动失败先手动创建空文件。报错四工具调用被拒绝permissions.deny里匹配到了。Claude Code 的权限规则支持通配符Bash(curl *)会拦掉所有 curl 命令。排查时先看终端里的拒绝提示再对照settings.json的 allow/deny 列表。报错五上下文压缩后回答质量下降这是五级压缩的正常代价。如果频繁触发 L4 自动压缩说明单次会话太长。可以主动开新会话或者把大文件读取拆成多次小范围读取减少单轮 Token 膨胀。排障时如果怀疑是 Key 或通道问题直接去 API Keys 页面重新生成一个 Key 测试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。7. 继续深入从验证到长期编码跑通一次本地验证只是起点。如果你打算把 Claude Code 当日常编码工具几个实践建议把settings.json里的permissions.allow按项目逐步放开别一上来就全允许MCP 服务器按需注册注册太多会拖慢启动长会话定期开新的避免频繁触发重压缩。想单独测某个模型的行为用模型对话页面最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。长期跑编码 Agent 的话Coding Plan 的额度模型更适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。Claude Code 的 Anthropic 兼容接入说明在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite里面有完整的 base URL 和认证配置对照。源码拆到最后会发现Claude Code 没有用什么惊天动地的新算法并发控制、读写分离、分层缓存、断路器都是程序员熟悉的基础知识。难的是把这些东西组合到 AI 场景里并且每个默认值都往安全侧偏。这套思路比任何单个设计点都值得抄。
