1. 从一次“卡住”的 Agent 说起如果你正在折腾 AI Agent大概率遇到过这种场景让 Agent 帮忙改个 bug它读完文件、改完代码、跑完测试然后……就停在那里不动了。你盯着终端它盯着你谁也不知道下一步该干嘛。这不是模型笨而是驱动整个 Agent 运转的那段循环代码出了问题。Agent Loop 说白了就是一段 while 循环让 LLM 自动完成“思考 → 调用工具 → 再思考 → 再调用工具”的闭环直到任务结束。它是整个 Agent 系统的心脏。开源项目 piearendil-works/pi把这段循环做得非常干净没有动辄上万 token 的臃肿提示词特别适合拿来拆解学习。我这次就顺着 pi 的 Loop 模块源码把循环调度、工具调用链路、消息追加机制讲清楚同时用 TaoToken 的统一 Key/API 通道把本地环境跑通让你能亲手触发一次完整的 Agent Loop 并看到日志。适合谁看写过一点 Python/TypeScript、想搞明白 Agent 内部到底怎么转的人被循环中断、工具调用失败折磨过的人想用一套统一 API 通道接多个模型做验证的人。下面所有配置都可以直接复制改掉 Key 就能跑。2. TaoToken 前置统一 Key 与 API 通道pi 的 Loop 本身不绑定任何模型厂商它通过一个streamFn把 LLM 调用抽象出去。这意味着你只要提供一个兼容 OpenAI 协议的接口就能把 pi 接到任意后端。TaoToken 在这里扮演的角色就是“统一入口”一个 Key、一个 Base URL背后可以路由到不同模型省去你在 pi 里为每个厂商写一套适配。先拿到凭证。打开控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建完 Key 后在 API Keys 页面可以随时查看和轮换https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档在这里协议细节、模型列表、参数说明都在里面https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocAPI 的 Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数直接作为baseURL填进配置即可。模型对话的在线调试入口在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels注意Key 只存在本地配置文件里不要提交到 Git。建议用环境变量注入后面配置骨架里会演示。3. 可复制配置settings.json 与 config.toml 骨架pi 的配置分两层一层是 Agent 运行时的settings.json管模型、工具、循环参数另一层是config.toml管通道和凭证。下面两份骨架可以直接用。3.1 settings.json 骨架{ model: { provider: openai-compatible, baseURL: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, maxTokens: 4096, temperature: 0.2 }, loop: { maxTurns: 20, toolExecution: parallel, stream: true, stopOnNoToolCall: true }, tools: { enabled: [read_file, write_file, run_shell], sequentialTools: [run_shell] }, session: { persist: true, path: ./.pi/sessions } }几个关键字段解释一下。maxTurns是外层循环的最大轮数防止 Agent 无限转下去toolExecution设为parallel时同一轮里多个工具会并发执行但sequentialTools里声明的工具比如run_shell会强制串行避免命令互相干扰stopOnNoToolCall为 true 时LLM 不再输出工具调用就退出内层循环。3.2 config.toml 骨架[channel.default] name taotoken base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} timeout 120 [channel.default.headers] Content-Type application/json [logging] level debug loop_trace true tool_trace trueloop_trace和tool_trace打开后每次循环的进入/退出、每个工具的调用与返回都会打日志这是后面排查循环中断的关键。3.3 环境变量注入export TAOTOKEN_API_KEYsk-你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的Key。配置里用${TAOTOKEN_API_KEY}引用避免明文写死。4. 接入步骤CC Switch 与 Clinepi 本身是库实际用的时候通常挂在编辑器或客户端里。这里给两条常见路径。4.1 CC Switch 接入CC Switch 用来在多个模型通道之间切换。新建一个通道填字段值名称taotokenBase URLhttps://taotoken.net/apiAPI Key你的 TaoToken Key模型claude-sonnet-4-20250514协议OpenAI Compatible保存后设为默认通道。CC Switch 会把请求转发到 TaoTokenpi 的streamFn只管往这个通道发流式请求不关心背后是谁。4.2 Cline 接入Cline 的配置在设置里选 “OpenAI Compatible”然后{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的Key, openAiModelId: claude-sonnet-4-20250514 }填完点保存Cline 会发一个测试请求。如果返回正常说明通道通了。这一步通了pi 的 Loop 才有“后端”可用。4.3 长期编码与 Agent 场景如果你打算把 pi 当长期编码助手用或者跑多轮 Agent 任务建议走 Coding Plan额度更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan5. 验证请求触发一次完整 Agent Loop配置好了现在跑一次真实的循环。写一个最小脚本调用 pi 的agentLoopimport { agentLoop } from pi-agent-core; const context { messages: [ { role: user, content: 读取 ./demo.txt 的内容然后把里面的 hello 改成 world写回文件。 } ], tools: [ { name: read_file, executionMode: parallel }, { name: write_file, executionMode: parallel } ] }; const config { model: claude-sonnet-4-20250514, toolExecution: parallel, maxTurns: 10 }; const stream agentLoop( [{ role: user, content: context.messages[0].content }], context, config ); for await (const event of stream) { console.log(JSON.stringify(event, null, 2)); }运行后你会看到一串事件按顺序打出来。正常的时序是这样的message_start (user) assistant_start tool_call (read_file) tool_execution_start (read_file) tool_execution_end (read_file) tool_result (read_file) assistant_start tool_call (write_file) tool_execution_start (write_file) tool_execution_end (write_file) tool_result (write_file) assistant_start assistant_end (无 tool_call) loop_end关键观察点context.messages是只追加的列表。用户 prompt、assistant 响应、每个 toolResult 都按时间顺序 push 到末尾LLM 每次看到的都是完整历史。这就是为什么 Agent 不会“忘记”最初的目标。5.1 日志校验打开loop_trace后日志里会看到内层循环和外层循环的边界[loop] enter inner turn1 [loop] hasMoreToolCallstrue [loop] enter inner turn2 [loop] hasMoreToolCallstrue [loop] enter inner turn3 [loop] hasMoreToolCallsfalse [loop] inner exit [loop] check followUp queue: empty [loop] outer exit如果hasMoreToolCalls一直是 true 但轮数不涨说明工具调用结果没被正确追加如果内层退出后外层没退出检查 follow-up 队列是不是有残留消息。6. 本篇常见错排查6.1 循环中断内层退出但任务没完成最常见的原因是stopOnNoToolCall被设成 true而 LLM 某一轮恰好没输出工具调用。这时候内层循环直接退出外层看 follow-up 队列为空也退出任务就停在半路。排查方法把loop_trace打开看最后一次assistant_end里有没有toolCall。如果没有要么是提示词没让模型意识到还需要继续要么是maxTurns太小被截断。6.2 工具调用失败tool_result 没追加如果日志里看到tool_execution_end但没看到tool_result说明结果没被 push 到context.messages。检查executeToolCalls的返回处理确认每个ToolResultMessage都按顺序追加。并行模式下tool_execution_end按完成顺序发射但tool_result要等所有工具完成后按 assistant 源顺序统一发射顺序错乱会导致 LLM 对不上号。6.3 通道 401/403Key 没注入或 Base URL 写错。确认TAOTOKEN_API_KEY环境变量在当前 shell 里生效baseURL是https://taotoken.net/api不带多余路径。用模型对话页面先手动发一条消息验证通道https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels6.4 工具串行/并行冲突run_shell这类工具有副作用必须放sequentialTools。如果两个 shell 命令并行跑可能互相覆盖文件。检查settings.json里的sequentialTools数组把有状态工具都加进去。6.5 消息顺序错乱context.messages是 append-only任何“插入到中间”或“重写历史”的操作都会破坏 LLM 的上下文理解。排查时打印整个 messages 数组确认角色顺序是user → assistant → toolResult → assistant → ...没有跳位。7. 把循环跑稳的几个实操建议第一maxTurns别设太大10 到 20 足够大多数任务设太大反而掩盖了循环逻辑的问题。第二调试阶段一定开loop_trace和tool_trace日志是你唯一能看清循环内部状态的窗口。第三工具执行模式默认并行但凡是碰文件系统或网络的工具都往sequentialTools里放。第四session 持久化打开后恢复旧 session 时是把历史消息灌进context.messages再从末尾继续追加不会截断这点和 pi 的设计一致。如果你在接入过程中遇到通道问题回到 API Keys 页面确认 Key 状态https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys协议细节对不上时翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc需要长期跑 Agent 任务就上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan把上面这套配置跑通你手里就有了一台能自己转起来的 Agent 发动机。剩下的就是往工具列表里加东西让它干更多活。