10.1 请求流转与分层排障
本节在进入 Agent Loop 内核剖析之前，先用一条真实请求的完整生命周期建立全局直觉。当系统出了问题时，这里的分层排障策略能帮你在几秒内定位到正确的层级，而不是大海捞针。
10.1.1 追踪一条消息的完整生命周期
理解 Agent Loop 最好的方式是追踪一次真实请求。下面以“用户在 Telegram 发消息，智能体查了一个网页后回复”为例，还原完整流转过程：
图 10-1：一次请求的核心流转路径（含三个关键约束点）
分步解读：
步骤 ①②：消息到达，Gateway 验证身份与配对，按路由配置把请求交给对应的 Agent。这些是第九章控制平面的职责范围。
步骤 ③④⑤⑥：Agent 从 Session 提取历史记忆，拼装提示词，发送给模型。这里有超时与重试控制——对应本章 10.3–10.4 的内容。
步骤 ⑦⑧⑨⑩：模型推理后决定调用工具（如搜索），执行完后把结果回传给模型。此阶段受工具策略与沙箱约束保护——对应本章 10.5 的工具执行机制。
步骤 ⑪⑫⑬⑭：模型根据工具回执生成最终回答，写入 Session，通过 Gateway 返回给用户——对应本章 10.6 的流式输出。
10.1.2 分层排障：出了问题先查哪里
由于四层职责严格分离，排障可以采用“由外到内”策略——先检查入口层，再控制层，再执行层，最后能力层。
入口层 (Channels)
协议适配、事件统一
日志无任何流入记录；客户端反复“连接断开”
Webhook 配置、网络连通性
控制层 (Gateway)
鉴权、路由、排队
请求被秒拒（Unauthorized），但模型没收到任何消息
终端配对文件、路由配置、访问限制
执行层 (Agent/Session)
记忆拼接、推理、重试
推理时间超长、死循环、回答完全脱离上下文或偏离角色
Context 长度、Agent 配置、Compaction 压缩参数
能力层 (Tool/Model)
外部执行、模型补全
无动作响应、收到 429 限流、工具调用未释放
模型额度、工具元数据、探活探针
两个常见症状的快速定位：
“间歇性回答缓慢且越来越离谱” → 先查执行/能力层（上下文过长、模型降级）
“发消息完全没反应，或瞬间被拒” → 先查入口/控制层（鉴权失败、路由配置错误）
完整的排障检查清单见附录 C。
10.1.3 端到端消息链路图（全局视图）
图 10-2：端到端消息链路图（含存储与日志路径）
有了这张全局图，接下来 10.2 将深入 π 运行底座，解释 OpenClaw 如何通过嵌入式集成将 pi 的极简执行骨架转化为企业级智能体运行时。
最后更新于