Claude Code 源码解剖：终端里的 AI 操作系统是怎么建起来的

1. 终端里跑 AI 操作系统到底难在哪Claude Code 是一个跑在终端里的 AI 编程工具能读文件、改代码、执行命令、并发调度多个工具还能 spawn 子代理协同干活。适合谁看正在做 AI CLI 工具的开发者、对「终端里跑 React」感到困惑的人、想从顶级产品实现里提炼可复用工程模式的人。我第一次认真用它的时候注意到一件奇怪的事屏幕上同时显示「正在读取文件」和「正在搜索调用方」两个进度条AI 的流式文字还在旁边继续输出。这在普通 CLI 里几乎不可能——你试试在 shell 里同时跑两个tail -f输出会互相覆盖。没有浏览器没有 WebSocket没有 Electron它是怎么做到的答案不在某个技巧里而在整套架构的选择上。Claude Code 的源码可以分成五层用户交互层REPL.tsx、会话编排层QueryEngine.ts、核心循环层query.ts、工具执行层StreamingToolExecutor Bash/Read/Edit/MCP/Sub-Agent、外部服务层Anthropic API。所有并发复杂度都汇聚在 query.ts 这个 async generator 里。技术选型上每个决定都是被逼出来的运行时选 Bun 是为了极快冷启动终端 UI 选 React Ink 是因为它是唯一能解决多并发输出源竞态问题的方案CLI 解析选 Commander.js 是因为大量子命令需要内联注册Schema 校验选 Zod v4 是因为 AI 函数调用的参数类型在运行时才确定代码搜索内置 ripgrep 是为了跨平台零配置。最反直觉的是 React Ink。终端本质是单向字节流三个并发任务同时往屏幕写内容时传统process.stdout.write()是无状态的谁最后写谁覆盖别人。Ink 的解法是把终端渲染变成统一的 diff patch 过程每个并发任务只更新自己 React 组件的 stateInk 的 reconciler 负责把所有状态合并成一次屏幕更新。这不是把前端技术生硬嫁接是在终端物理约束下唯一能优雅处理并发渲染的方案。理解这套架构之后我想在自己的终端里复现类似的 AI 编程体验。但直接调 Anthropic API 有几个现实问题网络稳定性、Key 管理、多模型切换。我试过用 TaoToken 做统一通道把 Key 和 API 入口收敛到一处终端工具只认一个 base_url配置量小很多。下面把可复制的配置骨架和接入步骤拆开讲。2. TaoToken 前置统一 Key 与 API 通道在动手改 Claude Code 配置之前先把 TaoToken 这边的准备工作做完。这一步的目标是拿到一个可用的 API Key并确认 API 入口地址。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址不带 UTMhttps://taotoken.net/api具体操作路径第一步打开官网注册并登录账号。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite第二步进入 API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建一个新的 Key复制保存。这个 Key 后面会写进 Claude Code 的环境变量或 settings.json。第三步如果你只是想先验证模型能不能通可以用模型对话页快速测一条请求https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite第四步如果你打算长期用 Claude Code 做编码或跑 Agent建议看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频编码场景做了额度规划比按量零散调用更省心。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定的时候翻一下。注意Key 只创建一次就够不要在每个终端窗口里重复生成。多个工具共用同一个 Key方便统一管理和排查。3. 可复制配置settings.json 骨架与启动链路Claude Code 的配置核心是settings.json它决定了模型走哪个 API 入口、用哪个 Key、启用哪些工具。下面给一份可以直接改的骨架。先确认 Claude Code 已安装。如果你用的是 Anthropic 官方 CLI 形态配置目录通常在~/.claude/下。创建或编辑~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(git status), Bash(git diff), Read, Edit ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, includeCoAuthoredBy: false, cleanupPeriodDays: 30 }几个关键字段说明ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口这样 Claude Code 的所有请求都走统一通道不用改源码。ANTHROPIC_API_KEY填你在上一步创建的 Key。注意不要把这个文件提交到 git建议加进.gitignore。ANTHROPIC_MODEL指定默认模型。如果你在 TaoToken 控制台看到其他可用模型名替换这里即可。permissions.allow和permissions.deny是工具权限白名单和黑名单。Claude Code 在执行 Bash 命令前会检查这里deny 里的模式会直接拦截。生产环境建议把危险命令都放进 deny。如果你不想把 Key 写进文件可以用环境变量方式。在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoTokenKey export ANTHROPIC_MODELclaude-sonnet-4-20250514然后source ~/.zshrc生效。环境变量优先级高于 settings.json适合临时切换 Key 的场景。启动链路是这样的终端执行claude命令 → 入口文件cli.tsx解析参数 →main.tsx注册 Commander 命令并初始化 → 读取 settings.json 和环境变量 → 启动 REPL.tsx 渲染主界面 → 用户输入触发 query.ts 的 turn 循环 → 请求发往 ANTHROPIC_BASE_URL 指向的 TaoToken API。提示如果你同时装了多个 AI CLI 工具建议每个工具用独立的 settings 文件避免 Key 和 base_url 互相覆盖。Claude Code 的配置目录可以用CLAUDE_CONFIG_DIR环境变量指定。4. 验证请求终端启动与成功结果确认配置写完之后不要急着写代码先验证请求能不能通。分三步走。第一步检查环境变量是否生效echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8预期输出应该是https://taotoken.net/api和 Key 的前 8 位。如果为空说明 shell 配置没 source 或者写错了文件。第二步直接用 curl 测一条最小请求确认 TaoToken 通道可用curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回 JSON 里包含content字段和文本内容说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了或少了/v1。第三步启动 Claude Code 本体claude进入 REPL 后输入一句简单指令比如「列出当前目录的文件」。观察终端输出如果能看到流式文字逐步出现并且工具调用Read/Bash的进度条正常显示说明整条链路打通了。成功结果的特征有三个AI 回复是流式逐字出现的不是等全部生成完才一次性刷出工具调用有独立的进度指示多个工具并发时互不覆盖输入/status能看到当前模型和 API 入口信息。注意第一次启动可能会提示你确认权限或登录。如果它试图跳转到 Anthropic 官方登录页说明ANTHROPIC_BASE_URL没生效回到第一步检查环境变量。5. 本篇常见错排查配置过程中最容易踩的坑集中在几个地方逐个说。报错401 UnauthorizedKey 不对或没传进去。先echo $ANTHROPIC_API_KEY确认非空再检查 settings.json 里有没有拼写错误。注意 Key 前缀通常是sk-复制时不要带空格或换行。报错404 Not Foundbase_url 路径不对。TaoToken 的 API 入口是https://taotoken.net/api不要自己加/v1或/messagesClaude Code 内部会拼接。如果你用 curl 手动测才需要补全/v1/messages。终端输出交错、进度条互相覆盖这不是配置问题是终端本身不支持 Ink 的 diff patch 渲染。检查你的终端模拟器是否支持 ANSI 转义序列Windows 下建议用 Windows Terminal 而不是老版 cmd。另外确认 Claude Code 版本不是过旧的。模型名报错model not foundANTHROPIC_MODEL填的模型名在 TaoToken 通道里不可用。去控制台的模型列表页确认可用模型名或者先用默认模型跑通再换。settings.json 改了不生效Claude Code 启动时读一次配置改完要重启进程。另外检查是否有多个配置文件冲突比如项目目录下的.claude/settings.json会覆盖全局的~/.claude/settings.json。工具调用被拦截检查permissions.deny里有没有误伤。比如你 deny 了Bash(curl *)那所有 curl 命令都会被拦。调试阶段可以先把 deny 清空跑通后再逐步加回。流式输出卡住不动可能是网络到 TaoToken 的链路不稳定。先用 curl 测一条请求看响应时间如果 curl 也慢换网络环境再试。如果 curl 快但 Claude Code 慢检查是不是模型名指向了一个响应较慢的模型。排障时优先看 API Keys 和接入文档两个页面大部分参数问题那里都有说明API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite6. 把终端 AI 操作系统跑起来之后配置跑通只是起点。Claude Code 真正有意思的地方在于它的核心循环 query.ts——一个 async generator负责在 AI 回复、工具结果、用户中断之间协调节拍。你可以在自己的项目里观察这个循环的行为一次用户输入可能触发多个 turn工具调用是并发的而不是串行的UI 更新是实时的而不是等所有工具完成后一次性刷新。如果你想深入源码建议从这五个文件按顺序读src/entrypoints/cli.tsx找入口src/main.tsx扫 Commander 命令注册点src/screens/REPL.tsx理解 React 组件结构src/QueryEngine.ts找 turn 循环入口src/query.ts读懂 async generator。读的时候带着同一个问题这个设计决策解决了什么在「CLI AI 实时 I/O」交叉点上才会出现的问题。如果你打算长期用这套组合做编码或跑 AgentCoding Plan 比零散调用更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite想快速验证模型对话效果用这个页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite需要管理多个 Key 或查看用量进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后说一个我踩过的坑不要把所有工具的 base_url 都指向同一个 Key 却不做额度隔离。跑 Agent 的时候 token 消耗比聊天大得多建议给编码工具单独建一个 Key方便在控制台看用量和设限额。配置骨架里的cleanupPeriodDays也建议保留它会定期清理本地会话缓存避免长跑之后磁盘被日志撑满。