1. 从一次 Agent Loop 卡死说起Claude Code 的 Agent Loop 是什么简单说它是 Claude Code 从接收用户输入到完成任务之间反复执行的“推理—工具调用—结果回流”循环。QueryEngine 则是驱动这个循环的核心引擎负责组装 Prompt、管理消息历史、分发 tool_use、回写工具结果。适合谁看正在本地搭 Claude Code 调试环境、想搞清楚 Agent Loop 触发条件、准备接 MCP 和 Skills 的开发者。我第一次搭本地环境时输入一句“帮我看看这个项目的入口文件”终端转了两圈就停了没有任何工具调用记录。当时以为是模型没返回 tool_use后来把日志级别调高才发现QueryEngine 根本没进入循环卡在启动装配阶段——MCP server 配置写错了一个字段整个运行时初始化直接中断。这个坑让我意识到Claude Code 的 Agent Loop 不是“发消息就有响应”那么简单它依赖一套完整的配置骨架settings.json 决定运行时行为config.toml 决定模型通道MCP 和 Skills 决定能力边界。任何一个环节配置不对QueryEngine 就不会正常触发。这篇文章按运行链路拆先讲 Agent Loop 和 QueryEngine 各自管什么再给一份可复制的 settings.json 与 config.toml 骨架然后接 MCP 与 Skills最后给验证 Agent Loop 是否正常触发的具体动作和常见报错排查。全程用统一 Key/API 通道做示例你可以直接替换成自己的配置。2. Agent Loop 与 QueryEngine 的职责边界2.1 Agent Loop 到底循环什么Agent Loop 的本质是一个“模型推理 → 判断是否调用工具 → 执行工具 → 结果回写 → 再推理”的闭环。它循环的不是网络请求而是任务状态。每一轮循环里QueryEngine 会把当前的消息历史、系统提示词、上下文、可用工具定义组装成模型输入模型返回普通文本或 tool_use如果是 tool_use就交给 Tool Runtime 执行执行结果再写回消息历史进入下一轮。这个循环什么时候结束两种情况模型返回纯文本且没有 tool_use或者任务被显式中断。理解这一点很关键——如果你发现 Claude Code 只回了一句话就停了说明它认为任务已完成而不是 Agent Loop 坏了。2.2 QueryEngine 在链路中做什么QueryEngine 是 Agent Loop 的实现载体。它管的事情比“调模型”多得多维护 Message History包括用户输入、历史 assistant 回复、历史 tool_use 和 tool_result读取 Memory 和项目规则比如 CLAUDE.md收集当前环境上下文包括工作目录、Git 状态、项目结构判断是否需要上下文压缩加载当前可用 Tool 定义组装 Prompt 并调用模型识别 tool_use 并分发到 Tool Runtime处理权限拒绝、错误和中断把工具结果写回消息历史和上下文。一句话概括QueryEngine 管的是整个任务循环不是单次模型调用。这也是为什么配置骨架里模型通道和工具注册必须同时正确否则 QueryEngine 要么起不来要么起来了但调不动工具。2.3 MCP 与 Skills 在链路中的位置MCP 解决的是“我还能接入谁”。内置工具是 Claude Code 自己会的能力MCP 让它接入外部工具、外部资源和外部服务比如数据库查询、内部文档系统、工单系统。MCP server 在启动装配阶段注册QueryEngine 在加载 Tool 定义时会把 MCP 工具一起纳入可用工具列表。Skills 解决的是“这类任务该怎么做”。一个 Skill 通常是一个 SKILL.md 文件YAML frontmatter 里写 name、description、allowedTools正文写适用场景、执行步骤和注意事项。启动时 Claude Code 只读取 YAML 元数据做索引不把正文全部塞进上下文等模型判断任务需要某个 Skill 时再按需展开正文。这种“轻量索引 按需展开”的设计是为了控制上下文占用。3. 统一 Key/API 通道的前置准备3.1 为什么需要统一通道Claude Code 默认走 Anthropic 官方通道但在本地调试和多模型对比场景下统一 Key/API 通道能让你用一套配置切换模型、统一管理配额、集中看请求日志。TaoToken 提供的就是这样一个通道一个 API Key 覆盖模型对话、Coding Plan 和 API 调用配置方式兼容 Anthropic 的接口格式。你需要先拿到 API Key。打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建注意 Key 只在创建时显示一次复制后存到环境变量里不要直接写进配置文件提交到 Git。3.2 环境变量与目录约定Claude Code 读取配置的优先级是项目级配置 用户级配置 环境变量。建议把敏感信息放环境变量把行为配置放项目级文件。目录约定如下# 用户级配置目录 ~/.claude/ ├── settings.json # 用户级运行时配置 └── config.toml # 模型通道配置 # 项目级配置目录 project/.claude/ ├── settings.json # 项目级运行时配置优先级更高 ├── mcp.json # MCP server 注册 └── skills/ # 项目级 Skills └── my-skill/ └── SKILL.md环境变量建议这样设export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key注意ANTHROPIC_BASE_URL 不要加 UTM 参数API 调用地址保持干净。如果你用的是 Claude Code 的 Anthropic 兼容模式这两个变量会被自动读取。4. 可复制的 settings.json 与 config.toml 骨架4.1 settings.json 骨架settings.json 控制 Claude Code 的运行时行为包括权限策略、工具白名单、MCP 开关、Skills 加载路径。下面是一份可直接复制的最小骨架{ model: claude-sonnet-4-20250514, permissions: { allow: [ Read, Glob, Grep, Bash(git status), Bash(git diff), Bash(npm test) ], deny: [ Bash(rm -rf *), Bash(curl *), Write(.env) ], ask: [ Bash(git push), Write(src/**) ] }, mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./src], enabled: true } }, skills: { enabled: true, paths: [./.claude/skills, ~/.claude/skills] }, context: { autoCompact: true, compactThreshold: 0.8 }, logging: { level: debug, file: ./.claude/logs/agent-loop.log } }几个关键字段说明。permissions.allow 里的工具不需要确认就能执行deny 里的直接拦截ask 里的每次都要用户确认。mcpServers 注册 MCP servercommand 和 args 决定怎么启动。skills.paths 告诉 Claude Code 去哪扫描 SKILL.md。logging.level 设成 debug 才能在排查 Agent Loop 时看到 QueryEngine 的循环日志。4.2 config.toml 骨架config.toml 控制模型通道和请求参数。如果你用统一 Key/API 通道配置如下[api] base_url https://taotoken.net/api api_key_env ANTHROPIC_API_KEY timeout_seconds 120 max_retries 3 [model] default claude-sonnet-4-20250514 fallback claude-haiku-3-5-20241022 max_tokens 8192 temperature 0.2 [agent] max_loop_iterations 50 tool_result_max_chars 20000 enable_sub_agent true [context] enable_compaction true tool_result_budget 15000[api] 段里 base_url 指向统一通道api_key_env 指定从哪个环境变量读 Key这样 Key 不会出现在配置文件里。[agent] 段的 max_loop_iterations 限制单次任务最多循环多少轮防止死循环tool_result_max_chars 控制单个工具结果的最大字符数超过就触发裁剪。[context] 段控制上下文压缩策略。4.3 MCP 注册与 Skills 目录MCP server 除了写在 settings.json 的 mcpServers 里也可以单独放 mcp.json适合团队共享{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./src] }, sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, ./data/dev.db] } } }Skills 目录结构--- name: code-review description: 对指定文件做代码审查检查命名、边界条件和错误处理 allowedTools: - Read - Grep - Bash(git diff) --- ## 适用场景 当用户要求审查代码、检查 PR 或排查潜在 bug 时使用。 ## 执行步骤 1. 用 Read 读取目标文件 2. 用 Grep 搜索相关调用点 3. 用 git diff 查看最近改动 4. 按命名、边界、错误处理三个维度输出问题列表 ## 注意事项 不要直接修改代码只输出审查意见。YAML frontmatter 里的 allowedTools 限制这个 Skill 能用哪些工具正文里的执行步骤是模型按需展开后才看到的。5. 验证 Agent Loop 是否正常触发5.1 用日志确认循环启动配置好之后第一件事是确认 QueryEngine 进入了循环。把 logging.level 设成 debug然后启动 Claude Code输入一个必然触发工具调用的请求claude 读取 package.json 并告诉我项目名称和依赖数量观察日志文件 .claude/logs/agent-loop.log正常触发时你会看到类似这样的序列[QueryEngine] loop iteration1 [QueryEngine] assembling prompt: messages1 tools12 [QueryEngine] model response: tool_use nameRead [ToolRuntime] executing Read pathpackage.json [ToolRuntime] result: success chars842 [QueryEngine] loop iteration2 [QueryEngine] model response: text [QueryEngine] task completed如果只看到 loop iteration1 然后没有下文说明模型没返回 tool_use可能是工具定义没注册成功。如果连 loop iteration1 都没有说明启动装配阶段就失败了检查 MCP server 配置和 API Key。5.2 用最小请求验证工具调用更精确的验证方式是发一个只可能用工具完成的请求。比如让 Claude Code 统计当前目录下有多少个 .ts 文件claude 统计当前目录下 .ts 文件的数量只告诉我数字这个请求模型无法凭记忆回答必须调用 Glob 或 Bash。如果 Agent Loop 正常日志里会出现 tool_use最终输出一个数字。如果模型直接编了一个数字说明工具没注册进可用列表QueryEngine 组装 Prompt 时没带上工具定义。5.3 验证 MCP 与 Skills 是否生效验证 MCP在 settings.json 里注册 filesystem server 后发一个需要读文件的请求日志里应该出现 mcp__filesystem__read_file 这样的工具名。如果没出现检查 MCP server 是否启动成功可以在终端手动跑一遍 command 和 args 看报错。验证 Skills发一个匹配 Skill description 的请求比如“帮我审查一下 src/index.ts”日志里应该出现 skill 加载记录然后模型按 SKILL.md 里的步骤执行。如果 Skill 没被加载检查 skills.paths 路径是否正确以及 SKILL.md 的 YAML 格式是否合法。6. 本篇常见报错排查6.1 QueryEngine 不进入循环现象输入请求后没有任何工具调用日志停在启动阶段。排查顺序先确认 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 是否设置正确可以用 curl 手动测一下通道连通性再检查 settings.json 的 JSON 格式是否合法一个多余的逗号就会导致整个配置解析失败最后看 MCP server 是否启动超时某个 server 卡住会阻塞整个装配流程。6.2 tool_use 返回但工具执行失败现象日志里有 tool_use但 ToolRuntime 报权限拒绝或参数校验失败。排查检查 permissions.allow 里是否包含该工具注意 Bash 工具的匹配是前缀匹配Bash(git status) 不会匹配 git status --short。参数校验失败通常是模型生成的参数不符合 schema可以在日志里看具体是哪个字段。6.3 上下文压缩导致任务中断现象长任务执行到一半模型突然“忘记”了之前的步骤。排查这是上下文压缩触发了但摘要没保留关键状态。检查 config.toml 里的 tool_result_budget 是否设得太小导致工具结果被裁得太狠。可以适当调大或者在 CLAUDE.md 里显式要求保留任务状态。6.4 MCP 工具不出现现象MCP server 配置了但模型从不调用 MCP 工具。排查先确认 server 进程是否真的起来了在终端手动执行 command 看输出再检查 settings.json 里 mcpServers 的 enabled 是否为 true最后看日志里工具注册列表是否包含 MCP 工具如果注册了但模型不调用可能是工具 description 写得太模糊模型判断不出什么时候该用。6.5 Skills 加载但步骤不执行现象日志显示 Skill 被加载但模型没按 SKILL.md 的步骤走。排查Skills 的正文是按需展开的如果模型只读了 YAML 元数据就自己发挥了说明 description 没有足够明确地指向正文。把 description 写得更具体明确触发条件模型才会去展开正文。排障和接入相关的配置细节可以参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你需要长期跑编码任务或 Agent 流程Coding 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 。