一文读懂 Claude Code 的架构设计：从 settings.json 到 TaoToken 统一 Key 的 AI Agent 配置骨架

1. 从 settings.json 看 Claude Code 的配置骨架Claude Code 是 Anthropic 推出的代理式编程工具它能代表你运行 Shell 命令、编辑文件、调用外部服务核心是一个「调用模型 → 执行工具 → 收集结果 → 再调用模型」的 while 循环。但真正决定这个循环行为边界的不是循环本身而是循环外面的配置层——settings.json就是这层配置的入口文件。如果你在用 TypeScript 构建 AI Agent或者想把 Claude Code 接入统一的 API 通道理解settings.json的结构比读源码更实用因为它直接决定了权限模式、工具白名单、Hook 触发时机和模型路由。我试过把 Claude Code 的配置层拆成三块来看第一块是权限与安全策略决定哪些工具调用需要人工确认、哪些可以自动放行第二块是扩展与工具装配决定 MCP 服务器、插件、技能如何进入工具池第三块是模型与通道配置决定请求发往哪个 API 端点、用哪个 Key 认证。这三块在settings.json里各有对应的字段而且互相之间有优先级关系——拒绝规则永远高于允许规则会话级权限不会跨恢复继承这些设计都直接体现在配置的解析顺序里。本文面向使用 TypeScript 构建 AI Agent 的开发者以settings.json为切入点梳理从配置文件到统一 Key/API 通道的完整骨架给出可复制的配置片段和验证动作。你不需要读完整个 Claude Code 源码只需要理解配置层如何影响 Agent 行为就能在自己的项目里复用这套结构。下面从实际场景出发先看配置层要解决什么问题再一步步搭出可运行的骨架。2. 配置层要解决的原问题与场景2.1 为什么 Agent 需要独立的配置层一个能自主执行 Shell 命令和编辑文件的 Agent如果没有任何配置约束行为边界完全由模型输出决定。这在演示环境里没问题但在真实项目里会出三类问题模型可能执行破坏性命令、可能把敏感文件内容发到外部服务、可能在不同会话之间继承不该继承的权限。Claude Code 的解法是把这些约束从模型推理中抽出来放到确定性的配置层里让 Harness 在模型调用前后做检查。配置层要回答的核心问题有三个哪些工具模型能看到、哪些调用需要人工批准、请求走哪条 API 通道。第一个问题影响上下文成本因为工具 Schema 会占用 token第二个问题影响安全姿态默认拒绝还是默认询问第三个问题影响可用性和成本统一 Key 通道能简化多项目多 Key 的管理。2.2 典型场景多项目共用一套 Agent 配置假设你在三个 TypeScript 项目里都用 Claude Code 做辅助开发每个项目有自己的测试命令、代码规范和目录结构。如果每个项目单独配一套 Key 和权限规则维护成本会随项目数线性增长。更合理的做法是把模型通道和基础权限规则抽到用户级配置项目级配置只覆盖差异部分。Claude Code 的配置层级正好支持这种拆分托管记忆、用户记忆、项目记忆、本地记忆四层后加载的优先级更高越接近当前目录的规则越优先。这个场景里settings.json承担的是「骨架」角色——它不写具体业务逻辑只定义 Agent 的行为边界和资源通道。你可以在用户级配置里放统一的 API 端点和 Key 引用在项目级配置里放该项目的工具白名单和 Hook本地配置放个人偏好。这样换项目时不需要重新配 Key改权限规则也不会影响其他项目。2.3 配置层与 Agent 循环的关系Claude Code 的查询循环在每次模型调用前会做上下文装配装配过程会读取配置层解析出的权限回调、工具池、模型参数。配置不是循环的一部分但循环的每一步都依赖配置的输出。比如工具调度阶段assembleToolPool()会合并内置工具和 MCP 工具合并前先做拒绝规则预过滤——被 blanket deny 的工具根本不进入模型视野。这个预过滤的规则来源就是settings.json里的权限配置。理解这层关系后你会发现配置文件的字段不是孤立的它们按固定顺序参与解析先解析系统提示和用户上下文再初始化可变状态然后装配上下文最后才进入模型调用。配置字段如果放错层级可能在解析顺序里被覆盖或忽略。下一节先讲 TaoToken 的前置准备再进入具体配置。3. TaoToken 前置统一 Key 与 API 通道准备3.1 为什么需要统一 Key 通道Claude Code 默认走 Anthropic 官方 API但在多项目、多环境场景下直接管理多个官方 Key 有几个不便Key 分散在各处容易泄露、不同项目的用量无法统一查看、切换环境时要改配置。TaoToken 提供统一的 API 通道把模型调用收敛到一个端点和一个 Key 上配置层只需要引用这个统一通道不用关心底层是哪个模型服务。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填的就是这个纯端点。统一 Key 的好处是你可以在一个地方管理所有项目的模型调用权限和用量集中可见换模型时只改通道配置不用动项目代码。3.2 获取 API Key 的步骤进入控制台后创建 API Key建议按项目或环境分开创建方便后续做用量隔离。创建时注意两点一是 Key 只在创建时完整显示一次要立即保存二是可以给 Key 设置备注比如「claude-code-dev」或「agent-test」后续排查问题时能快速定位。拿到 Key 后不要直接写进项目里的settings.json并提交到 Git。正确做法是把 Key 放在环境变量里配置文件引用环境变量名。Claude Code 的配置支持从环境变量读取认证信息这样 Key 不会进入版本历史。3.3 配置通道时的关键参数统一通道需要配三个核心参数API 端点、认证 Key、模型标识。端点是https://taotoken.net/api认证用上一步创建的 Key模型标识按你实际使用的模型填写。这三个参数在settings.json里的位置和写法下一节详细展开。注意API 端点不要带任何查询参数认证信息通过请求头传递不要拼在 URL 里。配置文件里引用环境变量时用标准的环境变量语法不同操作系统下语法一致。如果你需要查看完整的接入文档和参数说明可以访问接入文档页面里面有各语言 SDK 的配置示例。对于长期编码和 Agent 场景Coding Plan 提供了更适合持续调用的通道方案可以在控制台里查看。4. 可复制的 settings.json 配置骨架4.1 配置文件的位置与层级Claude Code 的配置按作用域分四层加载顺序从低到高托管配置系统级、用户配置~/.claude/settings.json、项目配置项目根目录.claude/settings.json、本地配置.claude/settings.local.json通常被 Git 忽略。后加载的配置覆盖先加载的同名字段但权限规则里的拒绝规则例外——拒绝规则永远优先不受加载顺序影响。实际使用时建议把模型通道和基础权限放用户级项目特有的工具白名单和 Hook 放项目级个人调试用的临时配置放本地级。这样团队协作时项目配置可以提交到 Git个人 Key 和偏好留在本地。4.2 模型通道配置片段下面是一个用户级settings.json的模型通道配置片段把 API 请求指向 TaoToken 统一通道{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${TAOTOKEN_API_KEY}, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_AUTH_TOKEN引用环境变量TAOTOKEN_API_KEY实际 Key 值放在 shell 环境里。ANTHROPIC_MODEL指定默认模型你可以按项目需要覆盖。这种写法的好处是配置文件可以安全提交Key 通过环境变量注入。设置环境变量的方式按操作系统不同Linux/macOS 下在~/.zshrc或~/.bashrc里加export TAOTOKEN_API_KEY你的KeyWindows 下用系统环境变量设置界面。设置完新开一个终端让变量生效。4.3 权限与工具配置片段权限配置决定工具调用的审批行为。下面这个片段演示了拒绝规则、允许规则和权限模式的组合{ permissions: { defaultMode: default, deny: [ Bash(rm -rf:*), Bash(curl:* | sh), Read(./.env), Read(./secrets/**) ], allow: [ Bash(npm test:*), Bash(npm run lint:*), Read(./src/**), Edit(./src/**) ] } }defaultMode设为default表示标准交互模式大多数操作需要批准。deny里的规则永远优先即使allow里有更具体的匹配。注意Bash(rm -rf:*)这种写法匹配命令前缀Read(./.env)匹配具体文件路径。拒绝规则里放的是绝对不能执行的操作允许规则里放的是高频且低风险的操作减少审批打扰。权限模式有七种可选plan要求先生成计划再执行default标准交互acceptEdits自动批准工作目录内的编辑auto启用分类器评估dontAsk不询问但仍执行拒绝规则bypassPermissions跳过多数提示但保留安全检查bubble用于子 Agent 升级权限请求。日常开发建议用default或acceptEdits自动化场景用auto。4.4 Hook 与扩展配置片段Hook 让你在工具调用的生命周期节点插入自定义逻辑。下面这个片段演示了 PreToolUse 和 PostToolUse 的配置{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node ./scripts/check-command.js } ] } ], PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATH } ] } ] } }PreToolUse在工具执行前触发可以拒绝、询问或修改工具输入。PostToolUse在工具执行后触发可以注入额外上下文或做格式化。matcher字段匹配工具名支持精确匹配和正则。Hook 命令通过标准输入输出与主进程通信退出码非零表示阻止操作。MCP 服务器配置放在mcpServers字段下每个服务器指定传输方式和启动命令。插件和技能通过各自的清单文件声明在settings.json里启用。这四类扩展机制的上下文成本不同MCP 工具 Schema 成本最高插件视组件而定技能通常只放描述Hook 默认零成本。配置时按实际需要选择不要把所有机制都打开。5. 验证请求与成功结果5.1 验证配置是否生效配置写完后先做语法检查用jq或 Node 解析一遍node -e JSON.parse(require(fs).readFileSync(process.env.HOME /.claude/settings.json, utf8)); console.log(JSON 语法正确)然后验证环境变量是否被正确读取echo $TAOTOKEN_API_KEY | head -c 8应该输出 Key 的前 8 位如果为空说明环境变量没生效检查 shell 配置文件是否 source 过。5.2 发一个最小请求验证通道用 curl 直接测试 TaoToken 通道是否可达curl -s -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回包含content字段且文本是「OK」说明通道和 Key 都正常。如果返回 401检查 Key 是否正确返回 404检查端点路径返回超时检查网络连通性。5.3 在 Claude Code 里验证权限规则启动 Claude Code 后让它执行一个被拒绝规则匹配的命令比如rm -rf /tmp/test。预期行为是直接拒绝不弹出审批提示。再执行一个允许规则里的命令比如npm test预期行为是自动放行或只弹一次确认。如果拒绝规则没生效检查规则写法是否匹配——Bash(rm -rf:*)里的冒号是分隔符前缀匹配要写对。验证 Hook 是否触发可以在 Hook 脚本里加一行日志输出到文件然后执行匹配的工具调用看日志文件是否新增记录。Hook 脚本的退出码决定是否阻止操作测试时先用exit 0确保不阻断流程。5.4 验证模型对话与 Coding Plan如果你想先验证模型对话是否正常可以打开模型对话页面直接测试不用配本地环境。对于长期编码和 Agent 场景Coding Plan 提供了更适合持续调用的方案可以在控制台里查看用量和切换。API Keys 管理页面可以创建和吊销 Key接入文档页面有各语言 SDK 的完整示例。6. 本篇常见错排查6.1 配置不生效的排查顺序配置不生效时按这个顺序查先确认文件位置对不对用户级是~/.claude/settings.json项目级是项目根目录.claude/settings.json再确认 JSON 语法有没有错用上面的 Node 命令验证然后确认字段名拼写Claude Code 的字段名区分大小写最后确认加载顺序项目级覆盖用户级但拒绝规则例外。一个常见错误是把permissions写成permission或者把defaultMode的值写成不存在的模式名。模式名是固定的七个值写错会回退到默认行为。另一个常见错误是环境变量引用语法写错${TAOTOKEN_API_KEY}是标准写法写成$TAOTOKEN_API_KEY在 JSON 里不会被解析。6.2 API 通道报错排查401 错误通常是 Key 无效或没传对。检查请求头里用的是x-api-key还是AuthorizationTaoToken 通道用x-api-key。检查 Key 有没有多余空格从控制台复制时容易带上换行符。403 错误可能是 Key 权限不足或用量超限去控制台看用量和权限设置。404 错误检查端点路径https://taotoken.net/api后面接/v1/messages是标准路径不要多加或少加斜杠。429 错误是频率限制降低请求频率或联系支持调整配额。超时错误先检查网络再检查端点是否可达用 curl 的-v参数看详细连接过程。6.3 权限规则匹配问题拒绝规则不生效最常见的原因是规则写法不匹配实际命令。Bash(rm -rf:*)匹配的是以rm -rf开头的命令如果实际命令是sudo rm -rf前缀不匹配就不会被拒绝。规则里的路径匹配是相对于当前工作目录的Read(./.env)只匹配当前目录下的.env子目录里的不匹配。允许规则被拒绝规则覆盖是预期行为拒绝优先是设计原则。如果你发现某个操作被意外拒绝先检查有没有更宽泛的拒绝规则匹配到了它。规则匹配是前缀匹配和路径匹配的组合写规则时尽量精确避免误伤。6.4 Hook 执行失败排查Hook 不触发先检查matcher是否匹配工具名工具名区分大小写Bash和bash不一样。Hook 命令的路径要写绝对路径或相对于项目根目录的路径相对路径在不同工作目录下会失效。Hook 脚本要有执行权限Linux/macOS 下用chmod x加上。Hook 脚本超时会导致主流程卡住脚本里避免长时间阻塞操作。Hook 的输出格式要符合协议标准输出会被解析为 JSON格式错误会导致解析失败。调试时先在脚本里加日志确认脚本被调用了再排查逻辑问题。6.5 会话恢复与权限继承恢复会话时权限不会继承这是安全设计。如果你恢复会话后发现之前批准过的操作又要重新批准这是预期行为。会话被视为独立信任域恢复旧授权可能把陈旧信任带入已变化的上下文。如果确实需要跨会话保持某些权限把它们写进settings.json的允许规则里而不是依赖会话级批准。分叉会话同样不继承权限。子 Agent 的权限覆盖有优先级规则父会话处于bypassPermissions、acceptEdits或auto模式时子 Agent 的权限覆盖不会取代父模式。配置子 Agent 权限时注意这个优先级避免预期外的行为。7. 配置骨架的复用与下一步把settings.json当作 Agent 的配置骨架核心思路是把模型通道、权限规则、扩展机制三块分开管理。模型通道放用户级用环境变量注入 Key指向 TaoToken 统一端点权限规则按项目差异放项目级拒绝规则写绝对禁止的操作允许规则写高频低风险操作扩展机制按上下文成本选择Hook 和技能成本低可以多用MCP 工具 Schema 成本高按需开启。这套骨架可以直接复用到你自己的 TypeScript Agent 项目里。如果你用 Agent SDK 构建配置层的解析逻辑可以复用同样的层级结构用户级配置提供默认值项目级配置覆盖差异运行时配置做最终调整。权限检查放在工具调度之前Hook 放在工具执行前后模型通道参数从配置读取而不是硬编码。下一步可以做的验证把配置片段复制到你的项目里改掉 Key 引用和路径跑一遍上面的 curl 测试和权限规则测试。如果通道正常、权限规则按预期生效说明骨架搭好了。后续要加新工具或新 Hook按同样的层级结构往里加不要把所有配置堆在一个文件里。遇到通道或接入问题去 API Keys 页面检查 Key 状态接入文档页面查参数说明验证模型行为去模型对话页面长期编码场景看 Coding Plan 的通道方案。