> 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/09_gateway_protocol/9.1_architecture_overview.md).

# 9.1 架构全景与五平面框架

Gateway 的核心职责是通过多层次的协议与策略，把分布式的多渠道请求统一纳入可控、可审计的运行框架中。本节先用 OpenClaw 官方模块边界建立“源码里实际长什么样”的基础认知，再引入**五平面架构**（Five-Plane Harness Model）作为本书的观察视角，帮助读者从控制、数据、上下文、信任与可观测性五个维度理解系统。

> **说明：** 以下“五平面”框架是本书为便于读者理解而提出的分析模型，并非 OpenClaw 项目的官方架构术语。实际源码按模块（gateway、agents、config、hooks 等）组织，并不显式划分为五个平面；因此后文凡涉及“五平面”，都应理解为**本书的解读框架**，而不是 OpenClaw 官方文档中的固定分层。

## 9.1.1 用五平面观察 Gateway

OpenClaw 的运行时架构可从五个正交的平面来理解，每个平面负责系统的一个关键维度：

| 平面                     | 职责                     | 核心机制             |
| ---------------------- | ---------------------- | ---------------- |
| **控制平面**（Control）      | 请求编排、重试超时、步骤调度、HITL 门控 | 策略配置、故障决策、权限检查   |
| **数据平面**（Data）         | 工具执行、沙箱隔离、连接器、I/O 管理   | 副作用隔离、异步执行、流式传输  |
| **上下文平面**（Context）     | 会话状态、记忆机制、压缩总结、制品日志    | 生命周期管理、存储策略、版本控制 |
| **信任平面**（Trust）        | 认证/授权、用户同意、审计日志、策略执行   | 密钥治理、访问控制、问责链    |
| **可观测性平面**（Visibility） | 链路追踪、指标采集、评估量化、调试工具    | 遥测数据、性能分析、根因分析   |

这五个平面相互独立但紧密协作，共同确保系统的**安全性、可靠性、可审计性与可优化性**。

## 9.1.2 控制平面职责详解

**控制平面**是 Gateway 的“大脑”，负责：

1. **请求入口治理**：认证连接、归属校验、路由决策
2. **编排与调度**：决定步骤执行顺序、并发度、重试策略
3. **故障恢复**：触发超时、执行回退、决定熔断
4. **人在回路（HITL）**：在需要人工审批的步骤前设立门控，暂停执行并等待授权
5. **权限与策略**：检查请求是否被允许、受约束资源是否可达

控制平面不能理解成“纯被动路由器”。Gateway 负责路由、认证、队列与控制，并暴露一组 RPC handler / execution surface；真正的模型调用、工具副作用和节点侧执行仍由 runner、插件或 node host 等运行时处理。也就是说，控制面拥有执行入口的编排权，但不应把模型/工具工作都混写成 Gateway 本体亲自完成。

## 9.1.3 数据平面与工具执行

**数据平面**负责实际的 I/O 与副作用执行：

* **工具调用隔离**：在启用 `agents.defaults.sandbox` 或智能体级 sandbox 后，按 agent / session / shared scope 隔离高风险执行；沙箱默认不是“每个工具调用一个容器”
* **连接器管理**：通过 MCP（Model Context Protocol）或自定义连接器对接外部系统
* **流式输出**：支持流式返回大型结果（如日志、文件内容），避免内存溢出
* **异步执行**：长运行工具不阻塞控制平面，通过回调或轮询汇报结果

## 9.1.4 上下文平面与状态管理

**上下文平面**维护会话的运行状态与记忆：

* **会话状态**：为每个用户维护独立的上下文窗口，包括消息历史、工具结果、系统变量
* **压缩与总结**：当上下文超过预算时，采用 `compaction`（压缩关键信息）或 `summarization`（生成摘要）来回收空间
* **制品与日志**：存储执行过程中的中间结果与决策日志，便于复盘与审计

## 9.1.5 信任平面与安全保障

**信任平面**是安全的“根基”，包括：

* **身份认证**：验证连接身份（设备配对、Gateway token/password、deviceToken/bootstrapToken、trusted-proxy/Tailscale 身份头与设备签名）；OAuth 属于模型供应商认证，不是 Gateway WS 连接认证主路径
* **授权与访问控制**：每个操作都需检查是否被允许（工具黑白名单、模型限制等）
* **用户同意机制**：对高风险操作要求显式同意，支持条件同意（如限时、限额）
* **审计日志**：记录每个决策、允许与拒绝事件，形成完整的问责链

## 9.1.6 可观测性平面与系统诊断

**可观测性平面**为整个系统提供“透视镜”：

* **链路追踪**：从请求入口到最终响应，跟踪每一步的执行状态与耗时
* **指标与日志**：采集 Token 消耗、延迟分布、错误率等关键指标
* **根因分析**：通过关联多个平面的信息，快速定位故障点（如：控制平面超时 + 数据平面工具耗时 = 根本原因）
* **调试工具**：提供交互式诊断命令、脱敏诊断导出和状态刷新能力，帮助定位链路问题；不要把它理解成稳定的本地 replay / 场景复现协议

## 9.1.7 平面间的协作举例

以一个“获取用户信息并验证操作”的请求为例：

1. **控制平面**：检查请求来源是否认证（信任平面）→ 检查用户权限（信任平面）
2. **上下文平面**：加载该用户的会话上下文（之前的指令与结果）
3. **控制平面**：根据历史与当前请求决定是否需要人工审批（HITL 门控）
4. **数据平面**：执行“获取用户信息”工具，从外部系统拉取数据
5. **上下文平面**：将工具结果存入会话状态
6. **可观测性平面**：记录全链路耗时、Token 消耗、访问权限等

这个协作确保了请求的**可控性、可追溯性与安全性**。

## 9.1.8 为什么五平面架构重要

将系统分为五个正交的平面具有以下优势：

* **清晰职责边界**：每个平面的职责独立，便于理解与演进
* **独立扩展**：可以独立优化某个平面（如性能、安全性）而不影响其他平面
* **可组合性**：新的运行时配置或扩展可以只关注某一两个平面
* **故障隔离**：一个平面的故障不必导致整个系统的级联失败
* **审计友好**：每个平面都有清晰的输入-输出-日志，便于合规与复盘

在后续章节中，我们会深入每个平面的具体实现：

* [第 9.2 节](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/09_gateway_protocol/9.2_control_plane.md)详解控制平面的职责与设计模式
* [第 11 章](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security.md)重点关注信任平面的密钥管理与审计
* [第 14 章](/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/14_performance_cost.md)从可观测性平面出发，优化性能与成本