# 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 的内容。
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 的极简执行骨架转化为企业级智能体运行时。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET 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?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.