1. 从源码泄漏事件说起Agent 核心循环到底长什么样Claude Code 源码泄漏这件事在开发者圈子里讨论度很高。抛开事件本身泄漏出来的query.ts、QueryEngine.ts、toolExecution.ts这些文件其实给所有在做 Agent 的团队递了一份工程化参考答案。它回答了一个很具体的问题一个能稳定跑起来的 Agent 核心循环到底该由哪些部件组成。如果你正在本地复现 Agent 循环行为大概率会遇到这几个卡点循环状态怎么存、工具调用怎么并发、上下文超了怎么压缩、API 通道怎么统一管理。Claude Code 的做法是用一个while(true)状态机驱动每次迭代走压缩管线 → 流式 API 调用 → 工具执行 → 终止/续转判定这条链路。这套骨架本身不复杂复杂的是配置和验证。这篇不打算逐行翻译源码而是把泄漏事件里暴露出来的核心循环结构落成两份你能直接复制的配置骨架settings.json和config.toml。同时给出通过 TaoToken 统一 Key/API 通道接入后的验证动作让整条循环调用链路可观测、可调试。适合已经在写 Agent、但循环跑不稳或者不好排查的开发者。2. TaoToken 前置统一 Key 与 API 通道在复现 Agent 循环之前先把 API 通道这件事理清楚。Claude Code 的queryModel()里有一整套请求构建逻辑包括 beta headers、模型解析、重试策略。本地复现时如果每个模型都单独配一套 Key 和 endpoint调试成本会很高。TaoToken 在这里的作用是提供一个统一的 Key/API 通道。你只需要一个 API Key就能在同一个通道里切换不同模型Agent 循环里的callModel层不用为每个模型改代码。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。具体操作上先去控制台创建 Key控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后先别急着写循环。建议先用模型对话页面确认通道是通的模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content这一步的意义在于把通道问题和循环逻辑问题分开。很多人调 Agent 循环调半天最后发现是 Key 或者 endpoint 配错了。先验证通道再验证循环排障路径会清晰很多。注意API 基址统一用https://taotoken.net/api不要在后面拼多余的路径。Agent 循环里的base_url配置项填这个就行。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是运行时行为配置对应settings.json一层是模型与通道配置对应config.toml。下面这两份骨架是我按泄漏出来的循环结构整理的字段命名尽量贴近源码里的概念方便你对照。3.1 settings.json循环行为骨架这份配置对应queryLoop()里的状态机参数重点是循环控制、工具并发、上下文压缩这三块。{ agent: { maxTurns: 30, loopMode: state_machine, continueOnToolError: false, streamingToolExecution: true }, context: { compactionPipeline: [ tool_result_budget, snip, microcompact, context_collapse, autocompact ], autocompactThreshold: 0.75, maxOutputTokensRecovery: 3 }, tools: { concurrencySafeMax: 10, partitionStrategy: alternating, bashErrorCascade: true }, observability: { logStreamEvents: true, logToolLifecycle: true, logCompactionSteps: true } }几个字段说明一下。loopMode设成state_machine是提醒自己用状态对象 continue而不是递归避免长对话堆栈溢出。compactionPipeline的顺序对应源码里的压缩管线从轻量到重量autocompact放最后因为它要调一次 API。autocompactThreshold是触发完整压缩的 token 占比0.75 是个比较稳的起点。bashErrorCascade对应siblingAbortController那个机制Bash 出错时取消同级工具。3.2 config.toml模型与通道骨架这份配置对应queryModel()里的请求构建层重点是模型选择、重试、降级。[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_seconds 120 [model] main claude-sonnet-4-20250514 fallback claude-haiku-3-5-20241022 max_output_tokens 8192 escalate_output_tokens 65536 [retry] max_attempts 3 backoff_base_ms 500 on_streaming_failure non_streaming_fallback [streaming] enabled true yield_partial_messages true tool_execution_during_stream trueapi_key_env指向环境变量不要把 Key 硬编码进配置文件。fallback对应源码里的模型降级逻辑主流模型过载时切到轻量模型。escalate_output_tokens对应max_output_tokens_escalate那条恢复路径输出被截断时从 8k 升到 64k 重试。on_streaming_failure设成non_streaming_fallback对应流式降级机制。3.3 环境变量与启动export TAOTOKEN_API_KEY你的Key export AGENT_CONFIG./settings.json export AGENT_PROVIDER_CONFIG./config.toml如果你用的是 Claude Code 本身的配置体系把config.toml里的base_url和api_key_env对应到它的 provider 配置即可。核心是让callModel这一层走统一通道。4. 验证请求确认循环链路可观测配置写完接下来是验证。这一步的目标不是跑通就行而是让循环的每个阶段都有可观测的输出。Claude Code 的queryLoop()会 yield 多种消息类型我们可以在本地复现一个最小验证脚本。4.1 最小循环验证脚本import os import json import httpx API_BASE https://taotoken.net/api API_KEY os.environ[TAOTOKEN_API_KEY] def call_model(messages, toolsNone, streamTrue): headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: claude-sonnet-4-20250514, max_tokens: 8192, messages: messages, stream: stream, } if tools: payload[tools] tools with httpx.Client(timeout120) as client: if stream: with client.stream(POST, f{API_BASE}/v1/messages, headersheaders, jsonpayload) as resp: for line in resp.iter_lines(): if line: yield line else: resp client.post(f{API_BASE}/v1/messages, headersheaders, jsonpayload) yield resp.text def agent_loop(user_input, max_turns5): messages [{role: user, content: user_input}] for turn in range(max_turns): print(f[turn {turn}] 调用模型...) tool_use_blocks [] assistant_text for chunk in call_model(messages): if chunk.startswith(data: ): event json.loads(chunk[6:]) if event.get(type) content_block_delta: delta event.get(delta, {}) if delta.get(type) text_delta: assistant_text delta.get(text, ) elif event.get(type) content_block_start: block event.get(content_block, {}) if block.get(type) tool_use: tool_use_blocks.append(block) print(f[turn {turn}] 文本长度{len(assistant_text)}, 工具调用{len(tool_use_blocks)}) if not tool_use_blocks: print(f[turn {turn}] 无工具调用循环终止) return assistant_text messages.append({role: assistant, content: assistant_text}) for block in tool_use_blocks: result f模拟执行 {block.get(name)} 的结果 messages.append({role: user, content: [ {type: tool_result, tool_use_id: block.get(id), content: result} ]}) return 达到 max_turns 限制 if __name__ __main__: result agent_loop(帮我读一下当前目录的文件列表) print(最终结果:, result)这个脚本复现了核心循环的骨架构建消息 → 流式调用 → 解析 tool_use → 执行工具 → 注入 tool_result → 续转。跑起来之后你能看到每一轮的文本长度和工具调用数量这就是最基本的可观测性。4.2 成功结果长什么样正常跑通的话输出类似这样[turn 0] 调用模型... [turn 0] 文本长度0, 工具调用1 [turn 1] 调用模型... [turn 1] 文本长度156, 工具调用0 [turn 1] 无工具调用循环终止 最终结果: 当前目录下有 3 个文件...关键观察点第一轮有工具调用、无文本第二轮有文本、无工具调用。这个工具调用 → 文本收尾的交替模式就是 ReAct 循环的正常形态。如果第一轮就有文本又有工具调用说明模型在边解释边调用也正常但要注意needsFollowUp的判定逻辑。4.3 用模型对话页面交叉验证如果脚本跑出来的结果和预期不符先用模型对话页面发一条同样的请求确认通道返回正常模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content页面能正常返回说明通道没问题问题在循环逻辑页面也异常说明是 Key 或 endpoint 配置问题。这个交叉验证能省掉很多来回排查的时间。5. 本篇常见错排查循环跑不起来报错信息往往指向好几个方向。下面这几个是我在复现过程中遇到频率比较高的。5.1 401 / 403Key 或通道问题最常见的就是 Key 没读到。检查TAOTOKEN_API_KEY环境变量是否真的导出了echo $TAOTOKEN_API_KEY看一下。如果 Key 没问题检查base_url是不是写成了https://taotoken.net/api/带了尾斜杠有些 HTTP 客户端会把尾斜杠拼成双斜杠导致 404。统一用https://taotoken.net/api。5.2 循环不终止needsFollowUp 判定错误如果循环一直转不进入终止分支大概率是needsFollowUp的判定逻辑写错了。源码里的判定是只要收集到 tool_use blockneedsFollowUp true。如果你在解析流式响应时漏掉了content_block_start里的 tool_use 类型就会导致工具调用没被识别模型一直等 tool_result循环卡住。排查方法是在解析层打印每个content_block_start的content_block.type。5.3 上下文超限压缩管线没生效长对话跑到一半报 prompt too long说明压缩管线没配好。检查compactionPipeline里的顺序autocompact必须在最后。另外autocompactThreshold设太高比如 0.95会导致压缩触发太晚建议 0.7 到 0.8 之间。如果用的是流式路径注意withhold逻辑PTL 错误在流循环里应该先被拦截尝试 collapse drain 和 reactive compact都失败了才 yield 给调用者。5.4 工具并发冲突分区策略问题如果多个写操作同时执行导致数据错乱检查partitionStrategy。源码里的做法是把工具调用序列分区成交替的并发批次和串行批次只读工具并发写入工具串行。如果你把所有工具都设成并发安全写操作就会互相踩。排查方法是给每个工具显式标注isConcurrencySafe只读的返回 true写入的返回 false。5.5 流式降级后状态残留流式请求失败降级到非流式时如果没清空已收集的 assistant 消息和工具状态会出现重复消息或者孤儿 tool_result。源码里的做法是收到streamingFallbackOccured后yield tombstone 消息标记需要移除的消息然后清空assistantMessages、toolResults、toolUseBlocks重建 executor。本地复现时至少要清空消息缓冲否则下一轮会把半截响应也带上。提示排障时优先看observability里的三个日志开关。logStreamEvents打开能看到每个流事件的类型logToolLifecycle能看到工具从 queued 到 completed 的状态变化logCompactionSteps能看到压缩管线每一步的触发情况。这三个日志基本能覆盖大部分循环问题。6. 接入文档与后续路径配置和验证都跑通之后如果你要把这套循环用到长期编码或者 Agent 任务里建议走 Coding Plan它更适合持续性的编码场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入过程中遇到通道层面的问题直接查接入文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你用的是 Claude Code 本身的 CLI 体系想把它接到统一通道上可以参考 ClaudeCodeAnthropic 的配置说明ClaudeCodeAnthropichttps://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后说一个实际经验复现 Agent 循环的时候别一上来就追求功能完整。先把单轮工具调用 → tool_result 注入 → 终止这条最短路径跑通确认可观测日志正常输出再往上加压缩管线和并发控制。循环这种东西链路越短越容易定位问题等最短路径稳了加什么都是增量调试。