1. 从 4471 个文件说起Claude Code 的 TypeScript Agent Runtime 到底长什么样Anthropic 的 Claude Code 一直给人“深不可测”的印象直到有人把anthropic-ai/claude-code2.1.88的 npm 产物拆开从package/cli.js.map里把sourcesContent还原出来我们才第一次看清这个 TypeScript Agent Runtime 的真实体量4471 个文件src目录下 1884 个 TS/TSX 源文件35 个一级子目录其中commands/86 个、tools/42 个、services/20 个。这不是一个“命令行套壳”而是一套完整的终端 Agent 运行时平台CLI 只是它的入口形态。对开发者来说真正有价值的不是围观体量而是搞清楚它的分层逻辑公共能力层负责 Git、权限、环境适配基础服务层对接模型 API、MCP 协议、代码分析工具能力层是模型真正“动手”的地方40 内置工具都遵守统一的Tool接口功能命令层是用户显式入口交互与调度层藏着QueryEngine把人类输入转成模型请求并调度工具入口层决定进 REPL 还是 Headless扩展能力层用 Skill、MCP、Plugin 横向挂载新能力。这套架构里MCP 是外部能力接入的标准接口也是我们本地复现 Agent Runtime 时最容易验证的一环。本文就沿着这条链路把 Claude Code 的 MCP 工具调用拆开再给出用 TaoToken 统一 Key 通道接入的可复制配置最后跑一次工具调用验证是否生效。适合需要在本地复现 Agent Runtime、又不想被多模型 Key 管理拖住的开发者。2. 拆解 MCP 工具调用链路Claude Code 的 Agent Runtime 工程分层与接入前置Claude Code 的 MCP 接入不是“连上就能用”的黑盒它在 Runtime 里有明确的位置。基础服务层里的 MCP 协议服务负责维护客户端连接状态工具能力层把 MCP Server 暴露的 tools 转换成符合Tool接口规范的对象交互与调度层的QueryEngine在流式响应里捕捉tool_use指令后调度对应工具执行再把tool_result回填进消息流悄悄发起下一轮 API 调用。这个循环会一直跑到拿到最终文本或强制终止。理解这条链路后接入的关键就落在两件事上一是 MCP Server 的配置要写对让 Runtime 能发现并连接二是模型通道的 Base URL 和 Key 要统一否则每个模型都要单独配一套凭证调试时很难定位问题出在 MCP 还是模型通道。TaoToken 在这里扮演的是统一 Key 通道的角色。它提供一个兼容 Anthropic 协议的 API 入口Base URL 是https://taotoken.net/api你只需要一个 Key就能在 Claude Code、Cline、Codex 等不同客户端里复用同一套凭证。对本地复现 Agent Runtime 的场景来说这能省掉大量“这个客户端配这个 Key、那个客户端配那个 Key”的切换成本。前置准备只有三步第一在 TaoToken 控制台创建一个 API Key第二确认你要接入的模型 ID比如claude-sonnet-4-5这类第三找到 Claude Code 的配置文件路径。Claude Code 的用户级配置通常在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.jsonMCP Server 配置则写在~/.claude.json或项目级.mcp.json里。不同版本路径可能略有差异以你本地实际为准。这里要提醒一点MCP Server 配置和模型通道配置是两套东西。MCP 负责“工具从哪来”模型通道负责“模型请求发到哪”。很多人接入失败是因为把两者混在一起改结果工具能发现但模型请求 401或者模型通了但工具列表为空。下面分开写。3. 可复制配置MCP Server 片段与 TaoToken Base URL 改写步骤先写 MCP Server 配置。以项目级.mcp.json为例一个标准的 stdio 类型 MCP Server 配置长这样{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/demo ], env: {} } } }这段配置告诉 Claude Code启动一个叫filesystem的 MCP Server用npx拉起modelcontextprotocol/server-filesystem允许它访问/Users/yourname/projects/demo目录。保存后Claude Code 启动时会读取这个文件并尝试连接。接下来改模型通道。Claude Code 支持通过环境变量指定 Base URL 和 Key最直接的方式是在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Claude Code 的settings.json里env字段注意 Key 的字段名是ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY写错会导致 401。Base URL 末尾不要带/v1TaoToken 的入口是https://taotoken.net/api具体路径由客户端拼接。如果你更习惯用 shell 环境变量也可以这样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey export ANTHROPIC_MODELclaude-sonnet-4-5三件套齐了Base URL、Key、Model ID。缺任何一个Runtime 都无法完成一次完整的模型请求。Cline、CC Switch 这类客户端也是同样的三件套逻辑只是配置文件的字段名不同。Cline 在 VS Code 设置里填 Base URL、API Key、Model IDCC Switch 则在它的配置界面里对应填写。核心不变通道统一到 TaoToken模型 ID 按你实际要用的填。配置写完后重启 Claude Code让它重新读取配置。如果你是在项目里用.mcp.json确保启动目录是项目根目录否则 Runtime 可能找不到这个文件。4. 验证请求跑一次 MCP 工具调用链路确认接入生效配置写完不算完要跑一次真实调用。最直接的验证方式是让 Claude Code 调用filesystemMCP Server 里的工具比如列目录。启动 Claude Code 后先输入/mcp这个命令会列出当前已连接的 MCP Server 和它们暴露的工具。如果你看到filesystem出现在列表里并且下面有read_file、list_directory这类工具说明 MCP Server 连接成功。如果列表为空说明.mcp.json没被读到或者npx拉包失败。接着发一条会触发工具调用的消息请列出 /Users/yourname/projects/demo 目录下的文件并读取 package.json 的前 20 行。正常情况下你会看到 Claude Code 的终端 UI 里出现工具调用折叠块显示它调用了list_directory和read_file然后返回结果。这个过程就是QueryEngine在流式响应里捕捉tool_use、调度 MCP 工具、回填tool_result的完整链路。如果你想更直接地验证模型通道可以发一条纯对话用一句话说明你现在使用的是哪个模型。如果返回正常文本说明 TaoToken 的 Base URL 和 Key 生效了。如果这里报 401问题在模型通道如果这里正常但/mcp列表为空问题在 MCP 配置。分开排查不要混在一起改。实测下来最容易出问题的是npx首次拉包超时。因为modelcontextprotocol/server-filesystem需要从 npm 下载网络慢的时候 Claude Code 启动会卡住。你可以先在终端手动跑一次npx -y modelcontextprotocol/server-filesystem /Users/yourname/projects/demo如果这个命令能正常启动并等待输入说明包没问题Claude Code 里也能连上。如果手动跑就报错先解决 npm 源或 Node 版本问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth接入过程中有几类报错特别常见逐个说。401 Unauthorized最常见。原因通常是 Key 写错、Key 过期、或者字段名用错。Claude Code 里必须是ANTHROPIC_AUTH_TOKEN写成ANTHROPIC_API_KEY在某些版本里不生效。另外检查 Base URL 是不是https://taotoken.net/api末尾多写/v1或/v1/messages都可能导致路径拼接错误。改完配置记得重启客户端。local proxy failed这个报错通常出现在客户端尝试走本地代理但代理没起来的时候。检查你的环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY指向一个不存在的本地端口。如果有清掉再试。另外确认 TaoToken 的 Base URL 是直连的 HTTPS 地址不需要额外代理层。reading choices 相关报错这类报错一般出现在流式响应解析阶段说明客户端收到了非预期的响应结构。常见原因是 Base URL 指向了一个不兼容 Anthropic 协议的端点或者模型 ID 填错导致服务端返回了错误格式。确认你填的 Model ID 是 TaoToken 支持的模型并且 Base URL 是https://taotoken.net/api。OAuth 相关报错Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 通道需要在配置里明确禁用 OAuth 或者忽略登录提示。检查settings.json里有没有冲突的认证字段确保只保留ANTHROPIC_AUTH_TOKEN这一套。排查顺序建议先确认模型通道能通发纯对话再确认 MCP Server 能连/mcp列表最后确认工具调用能跑发触发工具的消息。每一步单独验证比一次性改一堆配置再猜哪里错要快得多。6. 把统一 Key 通道用起来从模型对话到长期编码 Agent配置跑通之后你可以按场景分流使用。如果只是想验证模型通道是否正常或者做轻量的对话测试直接用模型对话入口就行填好 Base URL 和 Key 就能发请求。如果你要长期在 Claude Code、Cline 这类客户端里做编码或者跑多 Agent 协作任务建议用 Coding Plan把统一 Key 通道固定下来避免每次换客户端都要重新配一遍。接入文档里有各客户端的详细配置示例包括 Claude Code、Cline、Codex 的字段对照。API Keys 页面用来创建和管理你的 Key。如果你在排查过程中需要快速验证某个模型是否可用模型对话是最轻量的验证方式。回到 Claude Code 的 Agent Runtime 本身它的工程密码不在于 UI 多炫而在于 Runtime Orchestration 的严谨Tool 接口把执行逻辑、安全边界、模型可见描述、UI 呈现、持久化语义统一成一个对象QueryEngine 把一问一答变成带工具调度、预算控制、错误重试的编排循环上下文压缩用分层治理代替简单截断。你在本地复现时不需要一次还原全部 4471 个文件先把 MCP 工具调用链路和模型通道跑通就已经摸到了这套 Runtime 的骨架。剩下的就是沿着这条链路往里填你自己的工具和 Agent 逻辑。 
长河君 · 2026/10/9 19:01:50 · 阅读 1.2k 从 Anthropic 意外开源看 Claude Code 的 TypeScript Agent Runtime 工程密码：TaoToken 统一 Key 通道的 MCP 接入实践
1. 从 4471 个文件说起Claude Code 的 TypeScript Agent Runtime 到底长什么样Anthropic 的 Claude Code 一直给人“深不可测”的印象直到有人把anthropic-ai/claude-code2.1.88的 npm 产物拆开从package/cli.js.map里把sourcesContent还原出来我们才第一次看清这个 TypeScript Agent Runtime 的真实体量4471 个文件src目录下 1884 个 TS/TSX 源文件35 个一级子目录其中commands/86 个、tools/42 个、services/20 个。这不是一个“命令行套壳”而是一套完整的终端 Agent 运行时平台CLI 只是它的入口形态。对开发者来说真正有价值的不是围观体量而是搞清楚它的分层逻辑公共能力层负责 Git、权限、环境适配基础服务层对接模型 API、MCP 协议、代码分析工具能力层是模型真正“动手”的地方40 内置工具都遵守统一的Tool接口功能命令层是用户显式入口交互与调度层藏着QueryEngine把人类输入转成模型请求并调度工具入口层决定进 REPL 还是 Headless扩展能力层用 Skill、MCP、Plugin 横向挂载新能力。这套架构里MCP 是外部能力接入的标准接口也是我们本地复现 Agent Runtime 时最容易验证的一环。本文就沿着这条链路把 Claude Code 的 MCP 工具调用拆开再给出用 TaoToken 统一 Key 通道接入的可复制配置最后跑一次工具调用验证是否生效。适合需要在本地复现 Agent Runtime、又不想被多模型 Key 管理拖住的开发者。2. 拆解 MCP 工具调用链路Claude Code 的 Agent Runtime 工程分层与接入前置Claude Code 的 MCP 接入不是“连上就能用”的黑盒它在 Runtime 里有明确的位置。基础服务层里的 MCP 协议服务负责维护客户端连接状态工具能力层把 MCP Server 暴露的 tools 转换成符合Tool接口规范的对象交互与调度层的QueryEngine在流式响应里捕捉tool_use指令后调度对应工具执行再把tool_result回填进消息流悄悄发起下一轮 API 调用。这个循环会一直跑到拿到最终文本或强制终止。理解这条链路后接入的关键就落在两件事上一是 MCP Server 的配置要写对让 Runtime 能发现并连接二是模型通道的 Base URL 和 Key 要统一否则每个模型都要单独配一套凭证调试时很难定位问题出在 MCP 还是模型通道。TaoToken 在这里扮演的是统一 Key 通道的角色。它提供一个兼容 Anthropic 协议的 API 入口Base URL 是https://taotoken.net/api你只需要一个 Key就能在 Claude Code、Cline、Codex 等不同客户端里复用同一套凭证。对本地复现 Agent Runtime 的场景来说这能省掉大量“这个客户端配这个 Key、那个客户端配那个 Key”的切换成本。前置准备只有三步第一在 TaoToken 控制台创建一个 API Key第二确认你要接入的模型 ID比如claude-sonnet-4-5这类第三找到 Claude Code 的配置文件路径。Claude Code 的用户级配置通常在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.jsonMCP Server 配置则写在~/.claude.json或项目级.mcp.json里。不同版本路径可能略有差异以你本地实际为准。这里要提醒一点MCP Server 配置和模型通道配置是两套东西。MCP 负责“工具从哪来”模型通道负责“模型请求发到哪”。很多人接入失败是因为把两者混在一起改结果工具能发现但模型请求 401或者模型通了但工具列表为空。下面分开写。3. 可复制配置MCP Server 片段与 TaoToken Base URL 改写步骤先写 MCP Server 配置。以项目级.mcp.json为例一个标准的 stdio 类型 MCP Server 配置长这样{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/demo ], env: {} } } }这段配置告诉 Claude Code启动一个叫filesystem的 MCP Server用npx拉起modelcontextprotocol/server-filesystem允许它访问/Users/yourname/projects/demo目录。保存后Claude Code 启动时会读取这个文件并尝试连接。接下来改模型通道。Claude Code 支持通过环境变量指定 Base URL 和 Key最直接的方式是在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Claude Code 的settings.json里env字段注意 Key 的字段名是ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY写错会导致 401。Base URL 末尾不要带/v1TaoToken 的入口是https://taotoken.net/api具体路径由客户端拼接。如果你更习惯用 shell 环境变量也可以这样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey export ANTHROPIC_MODELclaude-sonnet-4-5三件套齐了Base URL、Key、Model ID。缺任何一个Runtime 都无法完成一次完整的模型请求。Cline、CC Switch 这类客户端也是同样的三件套逻辑只是配置文件的字段名不同。Cline 在 VS Code 设置里填 Base URL、API Key、Model IDCC Switch 则在它的配置界面里对应填写。核心不变通道统一到 TaoToken模型 ID 按你实际要用的填。配置写完后重启 Claude Code让它重新读取配置。如果你是在项目里用.mcp.json确保启动目录是项目根目录否则 Runtime 可能找不到这个文件。4. 验证请求跑一次 MCP 工具调用链路确认接入生效配置写完不算完要跑一次真实调用。最直接的验证方式是让 Claude Code 调用filesystemMCP Server 里的工具比如列目录。启动 Claude Code 后先输入/mcp这个命令会列出当前已连接的 MCP Server 和它们暴露的工具。如果你看到filesystem出现在列表里并且下面有read_file、list_directory这类工具说明 MCP Server 连接成功。如果列表为空说明.mcp.json没被读到或者npx拉包失败。接着发一条会触发工具调用的消息请列出 /Users/yourname/projects/demo 目录下的文件并读取 package.json 的前 20 行。正常情况下你会看到 Claude Code 的终端 UI 里出现工具调用折叠块显示它调用了list_directory和read_file然后返回结果。这个过程就是QueryEngine在流式响应里捕捉tool_use、调度 MCP 工具、回填tool_result的完整链路。如果你想更直接地验证模型通道可以发一条纯对话用一句话说明你现在使用的是哪个模型。如果返回正常文本说明 TaoToken 的 Base URL 和 Key 生效了。如果这里报 401问题在模型通道如果这里正常但/mcp列表为空问题在 MCP 配置。分开排查不要混在一起改。实测下来最容易出问题的是npx首次拉包超时。因为modelcontextprotocol/server-filesystem需要从 npm 下载网络慢的时候 Claude Code 启动会卡住。你可以先在终端手动跑一次npx -y modelcontextprotocol/server-filesystem /Users/yourname/projects/demo如果这个命令能正常启动并等待输入说明包没问题Claude Code 里也能连上。如果手动跑就报错先解决 npm 源或 Node 版本问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth接入过程中有几类报错特别常见逐个说。401 Unauthorized最常见。原因通常是 Key 写错、Key 过期、或者字段名用错。Claude Code 里必须是ANTHROPIC_AUTH_TOKEN写成ANTHROPIC_API_KEY在某些版本里不生效。另外检查 Base URL 是不是https://taotoken.net/api末尾多写/v1或/v1/messages都可能导致路径拼接错误。改完配置记得重启客户端。local proxy failed这个报错通常出现在客户端尝试走本地代理但代理没起来的时候。检查你的环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY指向一个不存在的本地端口。如果有清掉再试。另外确认 TaoToken 的 Base URL 是直连的 HTTPS 地址不需要额外代理层。reading choices 相关报错这类报错一般出现在流式响应解析阶段说明客户端收到了非预期的响应结构。常见原因是 Base URL 指向了一个不兼容 Anthropic 协议的端点或者模型 ID 填错导致服务端返回了错误格式。确认你填的 Model ID 是 TaoToken 支持的模型并且 Base URL 是https://taotoken.net/api。OAuth 相关报错Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 通道需要在配置里明确禁用 OAuth 或者忽略登录提示。检查settings.json里有没有冲突的认证字段确保只保留ANTHROPIC_AUTH_TOKEN这一套。排查顺序建议先确认模型通道能通发纯对话再确认 MCP Server 能连/mcp列表最后确认工具调用能跑发触发工具的消息。每一步单独验证比一次性改一堆配置再猜哪里错要快得多。6. 把统一 Key 通道用起来从模型对话到长期编码 Agent配置跑通之后你可以按场景分流使用。如果只是想验证模型通道是否正常或者做轻量的对话测试直接用模型对话入口就行填好 Base URL 和 Key 就能发请求。如果你要长期在 Claude Code、Cline 这类客户端里做编码或者跑多 Agent 协作任务建议用 Coding Plan把统一 Key 通道固定下来避免每次换客户端都要重新配一遍。接入文档里有各客户端的详细配置示例包括 Claude Code、Cline、Codex 的字段对照。API Keys 页面用来创建和管理你的 Key。如果你在排查过程中需要快速验证某个模型是否可用模型对话是最轻量的验证方式。回到 Claude Code 的 Agent Runtime 本身它的工程密码不在于 UI 多炫而在于 Runtime Orchestration 的严谨Tool 接口把执行逻辑、安全边界、模型可见描述、UI 呈现、持久化语义统一成一个对象QueryEngine 把一问一答变成带工具调度、预算控制、错误重试的编排循环上下文压缩用分层治理代替简单截断。你在本地复现时不需要一次还原全部 4471 个文件先把 MCP 工具调用链路和模型通道跑通就已经摸到了这套 Runtime 的骨架。剩下的就是沿着这条链路往里填你自己的工具和 Agent 逻辑。