> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/10_agent_loop/10.1_request_lifecycle.md).

# 10.1 请求流转与分层排障

> 本节在进入 Agent Loop 内核剖析之前，先用一条真实请求的完整生命周期建立全局直觉。当系统出了问题时，这里的分层排障策略能帮你在几秒内定位到正确的层级，而不是大海捞针。

***

## 10.1.1 追踪一条消息的完整生命周期

理解 Agent Loop 最好的方式是追踪一次真实请求。下面以“用户在 Telegram 发消息，智能体查了一个网页后回复”为例，还原完整流转过程：

```mermaid
sequenceDiagram
    autonumber
    actor User as 用户
    participant Gateway
    participant Agent as Agent引擎
    participant Session
    participant Model as 大模型
    participant Tool as 工具

    User->>Gateway: 渠道适配后提交消息
    Note over Gateway: ① 权限约束点：验证与配对检查
    Gateway->>Agent: 路由分发，唤起目标 Agent
    Agent->>Session: 查找对应的 Session
    Session-->>Agent: 提取历史上下文
    Note over Agent,Model: ② 预算容错点：超时与重试控制
    Agent->>Model: 组装完整提示词后提交
    Model-->>Agent: 判定需要执行动作（如搜索网页）
    Note over Model: ③ 故障降级点：无额度时回退
    Agent->>Tool: 调用受控 Tool 执行外部操作
    Tool-->>Agent: 返回结构化回执
    Agent->>Model: 再次提交包含回执的上下文
    Model-->>Agent: 生成最终回答
    Agent->>Session: 写入工具回执与最终回答
    Agent->>Gateway: 返回处理结果
    Gateway->>User: 原路返回给用户终端
```

图 10-1：一次请求的核心流转路径（含三个关键约束点）

分步解读：

1. **步骤 ①②**：消息到达，Gateway 验证身份与配对，按路由配置把请求交给对应的 Agent。这些是第九章控制平面的职责范围。
2. **步骤 ③④⑤⑥**：Agent 从 Session 提取历史记忆，拼装提示词，发送给模型。这里有超时与重试控制——对应本章 10.3–10.4 与 10.6 的内容。
3. **步骤 ⑦⑧⑨⑩**：模型推理后决定调用工具（如搜索），执行完后把结果回传给模型。此阶段受工具策略与沙箱约束保护——对应本章 10.5 的工具执行机制。
4. **步骤 ⑪⑫⑬**：模型根据工具回执生成最终回答，并在执行过程中把部分块、工具回执和最终 payload 与 Gateway 流式输出交错推进。不要理解成“所有持久化完成后才一次性返回”。这对应本章 10.6 的流式输出。

***

## 10.1.2 分层排障：出了问题先查哪里

由于四层职责严格分离，排障可以采用“**由外到内**”策略——先检查入口层，再控制层，再执行层，最后能力层。

| 层级与对象                   | 核心职责       | 典型故障表现                         | 排查方向                                |
| ----------------------- | ---------- | ------------------------------ | ----------------------------------- |
| **入口层 (Channels)**      | 协议适配、事件统一  | 日志无任何流入记录；客户端反复“连接断开”          | Webhook 配置、网络连通性                    |
| **控制层 (Gateway)**       | 鉴权、路由、排队   | 请求被秒拒（Unauthorized），但模型没收到任何消息 | 终端配对文件、路由配置、访问限制                    |
| **执行层 (Agent/Session)** | 记忆拼接、推理、重试 | 推理时间超长、死循环、回答完全脱离上下文或偏离角色      | Context 长度、Agent 配置、Compaction 压缩参数 |
| **能力层 (Tool/Model)**    | 外部执行、模型补全  | 无动作响应、收到 429 限流、工具调用未释放        | 模型额度、工具元数据、探活探针                     |

**两个常见症状的快速定位**：

* **“间歇性回答缓慢且越来越离谱”** → 先查**执行/能力层**（上下文过长、模型降级）
* **“发消息完全没反应，或瞬间被拒”** → 先查**入口/控制层**（鉴权失败、路由配置错误）

完整的排障检查清单见[附录 C](/openclaw_guide/fu-lu/appendix/troubleshooting_checklist.md)。

***

## 10.1.3 端到端消息链路图（全局视图）

下图展示了从用户消息进入到最终回答返回的全局链路，涵盖入口、控制、执行、能力四层。

```mermaid
flowchart LR
  subgraph Inbound["入口与渠道"]
    U["用户消息"] --> CH["Channels<br/>(WhatsApp/Telegram/Feishu/...)"]
  end

  subgraph GatewayProcess["Gateway 控制平面"]
    CH --> GW["Gateway<br/>WebSocket + HTTP + Control UI"]
    GW --> ROUTE["Routing / Bindings<br/>SessionKey 决策"]
    ROUTE --> QUEUE["Command Queue<br/>按 Session 分道排队"]
    QUEUE --> RUN["Agent Runtime<br/>Prompt 装配 / 推理循环"]
    RUN --> MODEL["Model Providers<br/>(按策略选择/回退)"]
    RUN --> TOOL["Tools<br/>(受策略/沙箱/审批约束)"]
    RUN --> OUT["Reply Stream"]
    RUN --> STORE["Session Store + Transcript<br/>agents/&lt;agentId&gt;/sessions/*.jsonl"]
    GW --> LOGS["File Logs (JSONL)<br/>Control UI / CLI tail"]
  end

  OUT --> GW --> CH --> U
  TOOL --> RUN
```

图 10-2：端到端消息链路图（含存储与日志路径）

有了这张全局图，接下来 10.2 将深入 π 运行底座，解释 OpenClaw 如何通过嵌入式集成将 pi 的极简执行骨架转化为企业级智能体运行时。