1. 从源码视角拆 Claude Code 的 Agent 骨架Claude Code 是 Anthropic 推出的终端编码 Agent能读文件、跑命令、调工具、维护记忆适合想搞懂 Agent 架构的开发者本地复现。很多人第一次翻它的源码会懵Query Loop、Tool 协议、Skill 展开、上下文压缩全缠在一起光看调用栈根本理不清谁先谁后。我这次换个思路不逐行读源码而是把 Agent 架构、Tool、Skill 三块拆成可配置的骨架用 settings.json 和 config.toml 把关键参数落到本地再通过统一 API 通道跑通验证。这样你既能对照源码定位调用链又能马上动手复现。核心检索词先摆清楚Claude Code 的 Agent 架构本质是 ReAct 范式的工程化实现主查询循环负责「想—做—看结果」的迭代Tool 是统一协议包装的外部能力Skill 是用 tool 协议包装的上下文变换器。理解这三层源码里那些 QueryEngine、streamedCheckPermissionsAndCallTool、SkillTool 就不再是黑盒。本文面向本地复现与调试场景交付可复制的配置骨架和逐步验证动作。所有模型请求走 TaoToken 统一 Key/API 通道官网入口 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址 https://taotoken.net/api 。下面从问题场景开始一层层把骨架搭起来。2. 原问题与场景源码读不懂配置跑不通读 Claude Code 源码时最常卡在三个地方。第一Query 进来之后到底经过哪些模块SystemPrompt、UserContext、SystemContext 怎么拼消息顺序为什么是[meta UserContext, ...业务消息]。第二Tool 调用时权限校验、PreHook、Permission Decision 的执行顺序allow/deny/ask 三态怎么合并。第三Skill 展开后为什么 tool_result 只是表层真正重要的是它往消息流里塞了新的 prompt 片段。光看代码不够因为很多行为依赖运行时配置。比如上下文压缩阈值、工具池筛选规则、Skill 的 command_permissions这些在源码里是常量或默认值但实际调试时需要能改。所以正确姿势是先搭一个最小可跑的配置骨架让 Agent 循环转起来再对照源码看每一步的输入输出。本地复现的典型场景是这样你在终端里输入一个 promptAgent 判断是否需要调工具调完把结果回传再决定是否结束。这个循环里模型请求需要一个稳定的 API 通道。我用 TaoToken 做统一入口好处是 Key 和 Base URL 一套配置Claude Code、Cline、CC Switch 都能复用调试时不用来回换。3. TaoToken 前置统一 Key 与 API 通道在动手配 Claude Code 之前先把 API 通道准备好。TaoToken 提供兼容 Anthropic 和 OpenAI 风格的接口Claude Code 走 Anthropic 协议Cline 走 OpenAI 兼容协议两者可以共用同一个 Key。第一步登录控制台创建 API Key。入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后复制保存后面配置里要用。第二步确认 API Base URL。Claude Code 的 Anthropic 兼容端点是https://taotoken.net/api注意这个地址不加 UTM 参数直接写进配置即可。第三步如果你要长期跑编码任务或 Agent 循环建议看下 Coding Plan入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对高频编码场景做了额度优化比按次调用更划算。Key 和 Base URL 拿到后先别急着配 Claude Code用模型对话页面快速验证一下通道是否通。入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个 Claude 系列模型发一句话能正常返回就说明 Key 有效。这一步能省掉后面很多「配置写了但请求 401」的排查时间。4. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是 Agent 行为配置通常放在项目根的.claude/settings.json另一层是模型通道配置可以用config.toml或环境变量。下面给一份最小骨架你可以直接复制改。4.1 settings.jsonAgent 与 Tool 骨架{ model: claude-sonnet-4-20250514, apiBaseUrl: https://taotoken.net/api, maxTokens: 8192, temperature: 0.2, tools: { enabled: [Read, Write, Bash, Skill], permissionMode: ask, preHookTimeoutMs: 3000 }, context: { collapseThreshold: 0.75, autocompactThreshold: 0.9, keepRecentMessages: 6 }, memory: { enableExtraction: true, sessionSummaryThreshold: 20 } }这份配置对应源码里的几个关键点。tools.enabled就是工具池筛选只有列出的工具会进当前轮次的 Tool Schema。permissionMode对应 Permission Decision 的全局模式ask表示需要确认调试时可以临时改allow减少打断。context.collapseThreshold是 Context Collapse 的触发比例超过 75% 先折叠旧上下文超过 90% 走 Autocompact。4.2 config.toml模型通道与 CC Switch如果你用 CC Switch 管理多个通道可以写一份config.toml[provider.taotoken] name TaoToken base_url https://taotoken.net/api api_key sk-你的Key protocol anthropic [agent.claude_code] provider taotoken model claude-sonnet-4-20250514 max_tokens 8192 [agent.cline] provider taotoken model claude-sonnet-4-20250514 protocol openaiCC Switch 的作用是在多个 provider 之间切换把 TaoToken 配成一个 provider 后Claude Code 和 Cline 都能指向它。注意protocol字段Claude Code 用anthropicCline 用openai同一个 Base URL 和 Key 可以复用。4.3 Skill 配置骨架Skill 在源码里是通过 SkillTool 展开的配置上体现为 skill 目录和 command_permissions。最小结构{ skills: { dir: .claude/skills, autoLoad: [code-review, refactor], commandPermissions: { code-review: [Read, Bash], refactor: [Read, Write] } } }autoLoad里的 skill 会在会话启动时把描述注入上下文模型据此判断用哪个。commandPermissions对应源码里 SkillTool 返回的command_permissions它决定了 skill 展开后能调哪些工具。这就是「渐进式披露」的配置层体现先给描述再按需展开正文和权限。5. 验证请求与成功结果配置写完后按顺序验证三层通道通、Agent 循环转、Skill 展开生效。5.1 验证 API 通道先用 curl 打一次 Anthropic 兼容端点curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK}] }返回里能看到content数组和stop_reason就说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 Base URL 是否多了斜杠或路径。5.2 验证 Agent 循环启动 Claude Code 后输入一个需要调工具的 prompt比如「读一下当前目录的 README.md 并总结」。观察终端输出正常流程是模型先产出 tool_useAgent 执行 Read把 tool_result 回传模型再产出文本总结。这个过程对应源码里的 Query Loop LLM Loop如果只输出文本没调工具说明工具池没生效回去检查tools.enabled。5.3 验证 Skill 展开在会话里输入/code-review或触发对应 skill观察是否注入了新的 meta user message。成功标志是模型开始按 skill 里定义的 SOP 执行比如先列检查项再逐条读文件。如果 skill 没触发检查skills.dir路径和autoLoad名称是否匹配。6. 本篇常见错排查配置跑不通时按下面顺序排查基本能覆盖 90% 的问题。报错一401 Unauthorized。最常见是 Key 没带对。Claude Code 用x-api-key头Cline 用Authorization: Bearer两者别混。另外确认 Base URL 是https://taotoken.net/api不要写成带 UTM 的官网地址。报错二tool_use 和 tool_result 配对失败。源码里有一步「修复 tool_use/tool_result 配对」如果你手动构造消息或用了不兼容的中间层可能触发这个错误。排查方法是看消息序列里每个 tool_use 是否有对应的 tool_result顺序是否一致。报错三上下文压缩后行为异常。压缩后的消息顺序是boundaryMarker → summaryMessages → messagesToKeep → attachments → hookResults。如果messagesToKeep配得太少关键上下文丢失模型会「失忆」。调试时把keepRecentMessages调大或临时关掉 Autocompact。报错四Skill 展开后权限被拒。SkillTool 返回的command_permissions如果和全局permissionMode冲突会走 deny。检查 skill 配置里的commandPermissions是否包含它实际要用的工具比如 code-review 要读文件就得有Read。报错五CC Switch 切换后 Cline 报协议错。Cline 走 OpenAI 兼容协议protocol必须写openai模型名也要用对应格式。如果混用 Anthropic 协议会返回格式解析错误。排查时建议开 debug 日志把每轮请求的 messages 和 tools 打出来对照源码里的标准化阶段看哪一步被改写。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各协议的字段说明卡住时翻一下比猜快。7. 继续深入从骨架到调用链把上面三层跑通后你手里就有了一份可调试的 Agent 骨架。接下来读源码会顺很多QueryEngine 对应你的入口配置streamedCheckPermissionsAndCallTool 对应tools.permissionMode和 PreHookSkillTool 对应skills.commandPermissions。每个源码模块都能在配置里找到对应开关改一个参数就能观察行为变化。如果你要长期跑编码任务或 Agent 循环建议把 Key 和通道固定下来用 Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 管理额度。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建和轮换Claude Code 专用接入说明在 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。下一篇我会展开 Prompt 和记忆管理模块把 SystemPrompt 拼接、记忆检索、session summary 的配置也落到骨架里。
【图解】Claude Code 源码解析｜Agent 架构、Tool、Skill 的配置骨架与验证（一）
1. 从源码视角拆 Claude Code 的 Agent 骨架Claude Code 是 Anthropic 推出的终端编码 Agent能读文件、跑命令、调工具、维护记忆适合想搞懂 Agent 架构的开发者本地复现。很多人第一次翻它的源码会懵Query Loop、Tool 协议、Skill 展开、上下文压缩全缠在一起光看调用栈根本理不清谁先谁后。我这次换个思路不逐行读源码而是把 Agent 架构、Tool、Skill 三块拆成可配置的骨架用 settings.json 和 config.toml 把关键参数落到本地再通过统一 API 通道跑通验证。这样你既能对照源码定位调用链又能马上动手复现。核心检索词先摆清楚Claude Code 的 Agent 架构本质是 ReAct 范式的工程化实现主查询循环负责「想—做—看结果」的迭代Tool 是统一协议包装的外部能力Skill 是用 tool 协议包装的上下文变换器。理解这三层源码里那些 QueryEngine、streamedCheckPermissionsAndCallTool、SkillTool 就不再是黑盒。本文面向本地复现与调试场景交付可复制的配置骨架和逐步验证动作。所有模型请求走 TaoToken 统一 Key/API 通道官网入口 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址 https://taotoken.net/api 。下面从问题场景开始一层层把骨架搭起来。2. 原问题与场景源码读不懂配置跑不通读 Claude Code 源码时最常卡在三个地方。第一Query 进来之后到底经过哪些模块SystemPrompt、UserContext、SystemContext 怎么拼消息顺序为什么是[meta UserContext, ...业务消息]。第二Tool 调用时权限校验、PreHook、Permission Decision 的执行顺序allow/deny/ask 三态怎么合并。第三Skill 展开后为什么 tool_result 只是表层真正重要的是它往消息流里塞了新的 prompt 片段。光看代码不够因为很多行为依赖运行时配置。比如上下文压缩阈值、工具池筛选规则、Skill 的 command_permissions这些在源码里是常量或默认值但实际调试时需要能改。所以正确姿势是先搭一个最小可跑的配置骨架让 Agent 循环转起来再对照源码看每一步的输入输出。本地复现的典型场景是这样你在终端里输入一个 promptAgent 判断是否需要调工具调完把结果回传再决定是否结束。这个循环里模型请求需要一个稳定的 API 通道。我用 TaoToken 做统一入口好处是 Key 和 Base URL 一套配置Claude Code、Cline、CC Switch 都能复用调试时不用来回换。3. TaoToken 前置统一 Key 与 API 通道在动手配 Claude Code 之前先把 API 通道准备好。TaoToken 提供兼容 Anthropic 和 OpenAI 风格的接口Claude Code 走 Anthropic 协议Cline 走 OpenAI 兼容协议两者可以共用同一个 Key。第一步登录控制台创建 API Key。入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后复制保存后面配置里要用。第二步确认 API Base URL。Claude Code 的 Anthropic 兼容端点是https://taotoken.net/api注意这个地址不加 UTM 参数直接写进配置即可。第三步如果你要长期跑编码任务或 Agent 循环建议看下 Coding Plan入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对高频编码场景做了额度优化比按次调用更划算。Key 和 Base URL 拿到后先别急着配 Claude Code用模型对话页面快速验证一下通道是否通。入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个 Claude 系列模型发一句话能正常返回就说明 Key 有效。这一步能省掉后面很多「配置写了但请求 401」的排查时间。4. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是 Agent 行为配置通常放在项目根的.claude/settings.json另一层是模型通道配置可以用config.toml或环境变量。下面给一份最小骨架你可以直接复制改。4.1 settings.jsonAgent 与 Tool 骨架{ model: claude-sonnet-4-20250514, apiBaseUrl: https://taotoken.net/api, maxTokens: 8192, temperature: 0.2, tools: { enabled: [Read, Write, Bash, Skill], permissionMode: ask, preHookTimeoutMs: 3000 }, context: { collapseThreshold: 0.75, autocompactThreshold: 0.9, keepRecentMessages: 6 }, memory: { enableExtraction: true, sessionSummaryThreshold: 20 } }这份配置对应源码里的几个关键点。tools.enabled就是工具池筛选只有列出的工具会进当前轮次的 Tool Schema。permissionMode对应 Permission Decision 的全局模式ask表示需要确认调试时可以临时改allow减少打断。context.collapseThreshold是 Context Collapse 的触发比例超过 75% 先折叠旧上下文超过 90% 走 Autocompact。4.2 config.toml模型通道与 CC Switch如果你用 CC Switch 管理多个通道可以写一份config.toml[provider.taotoken] name TaoToken base_url https://taotoken.net/api api_key sk-你的Key protocol anthropic [agent.claude_code] provider taotoken model claude-sonnet-4-20250514 max_tokens 8192 [agent.cline] provider taotoken model claude-sonnet-4-20250514 protocol openaiCC Switch 的作用是在多个 provider 之间切换把 TaoToken 配成一个 provider 后Claude Code 和 Cline 都能指向它。注意protocol字段Claude Code 用anthropicCline 用openai同一个 Base URL 和 Key 可以复用。4.3 Skill 配置骨架Skill 在源码里是通过 SkillTool 展开的配置上体现为 skill 目录和 command_permissions。最小结构{ skills: { dir: .claude/skills, autoLoad: [code-review, refactor], commandPermissions: { code-review: [Read, Bash], refactor: [Read, Write] } } }autoLoad里的 skill 会在会话启动时把描述注入上下文模型据此判断用哪个。commandPermissions对应源码里 SkillTool 返回的command_permissions它决定了 skill 展开后能调哪些工具。这就是「渐进式披露」的配置层体现先给描述再按需展开正文和权限。5. 验证请求与成功结果配置写完后按顺序验证三层通道通、Agent 循环转、Skill 展开生效。5.1 验证 API 通道先用 curl 打一次 Anthropic 兼容端点curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK}] }返回里能看到content数组和stop_reason就说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 Base URL 是否多了斜杠或路径。5.2 验证 Agent 循环启动 Claude Code 后输入一个需要调工具的 prompt比如「读一下当前目录的 README.md 并总结」。观察终端输出正常流程是模型先产出 tool_useAgent 执行 Read把 tool_result 回传模型再产出文本总结。这个过程对应源码里的 Query Loop LLM Loop如果只输出文本没调工具说明工具池没生效回去检查tools.enabled。5.3 验证 Skill 展开在会话里输入/code-review或触发对应 skill观察是否注入了新的 meta user message。成功标志是模型开始按 skill 里定义的 SOP 执行比如先列检查项再逐条读文件。如果 skill 没触发检查skills.dir路径和autoLoad名称是否匹配。6. 本篇常见错排查配置跑不通时按下面顺序排查基本能覆盖 90% 的问题。报错一401 Unauthorized。最常见是 Key 没带对。Claude Code 用x-api-key头Cline 用Authorization: Bearer两者别混。另外确认 Base URL 是https://taotoken.net/api不要写成带 UTM 的官网地址。报错二tool_use 和 tool_result 配对失败。源码里有一步「修复 tool_use/tool_result 配对」如果你手动构造消息或用了不兼容的中间层可能触发这个错误。排查方法是看消息序列里每个 tool_use 是否有对应的 tool_result顺序是否一致。报错三上下文压缩后行为异常。压缩后的消息顺序是boundaryMarker → summaryMessages → messagesToKeep → attachments → hookResults。如果messagesToKeep配得太少关键上下文丢失模型会「失忆」。调试时把keepRecentMessages调大或临时关掉 Autocompact。报错四Skill 展开后权限被拒。SkillTool 返回的command_permissions如果和全局permissionMode冲突会走 deny。检查 skill 配置里的commandPermissions是否包含它实际要用的工具比如 code-review 要读文件就得有Read。报错五CC Switch 切换后 Cline 报协议错。Cline 走 OpenAI 兼容协议protocol必须写openai模型名也要用对应格式。如果混用 Anthropic 协议会返回格式解析错误。排查时建议开 debug 日志把每轮请求的 messages 和 tools 打出来对照源码里的标准化阶段看哪一步被改写。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各协议的字段说明卡住时翻一下比猜快。7. 继续深入从骨架到调用链把上面三层跑通后你手里就有了一份可调试的 Agent 骨架。接下来读源码会顺很多QueryEngine 对应你的入口配置streamedCheckPermissionsAndCallTool 对应tools.permissionMode和 PreHookSkillTool 对应skills.commandPermissions。每个源码模块都能在配置里找到对应开关改一个参数就能观察行为变化。如果你要长期跑编码任务或 Agent 循环建议把 Key 和通道固定下来用 Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 管理额度。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建和轮换Claude Code 专用接入说明在 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。下一篇我会展开 Prompt 和记忆管理模块把 SystemPrompt 拼接、记忆检索、session summary 的配置也落到骨架里。
