> 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.2_control_plane.md).

# 9.2 控制平面职责与边界

Gateway 的控制平面是整个 OpenClaw 系统的“决策中枢”。本书为了分析清晰，会把策略裁决、路由、鉴权与执行效果分开讨论；但当前 Gateway 进程与 WebSocket 协议同时承载控制面、节点传输以及多类执行/查询 RPC，不能把它理解为严格的进程级或协议级隔离。本节详解这些职责的分析边界。

## 9.2.1 五大职责及其边界

控制平面的职责可归纳为五类，它们按时间顺序贯穿整个请求生命周期：

### 1. 连接认证与归属验证

**机制**：

* **认证**：通过 gateway token/password、deviceToken/bootstrapToken、trusted-proxy/Tailscale 身份头与设备签名确认“你是谁”
* **归属**：通过配对记录、设备身份、role/scopes 与 sessionKey/agent routing 映射请求到具体的用户/Agent
* **隔离**：确保租户数据严格隔离，不存在越权访问

**边界**：

* ✅ 做：验证身份、检查配对状态、映射到会话
* ❌ 不做：把模型推理、工具副作用与用户数据访问混同为认证决策本身；实际 Gateway 协议仍会承载相关 RPC 与结果上报

### 2. 路由与分发

**机制**：

* **静态路由**：基于渠道、用户属性的确定性映射（如“Slack 消息由 Slack 助手处理”）
* **动态路由**：基于消息内容、优先级、负载的智能分发（如“紧急问题转向 escalation\_agent”）
* **策略路由**：支持条件规则、优先级队列、负载均衡

**边界**：

* ✅ 做：匹配规则、选择目标 Agent、决定优先级队列
* ❌ 不做：修改消息内容、决定 Agent 的响应方式

### 3. 会话与状态管理

**机制**：

* **会话生命周期**：创建→活跃→冻结/超时→过期
* **状态持久化**：会话索引与 transcript 等关键状态写入本地 session store；不要把它理解成“每个控制平面决策都有事务日志”
* **并发控制**：同一会话的请求进行排序与互斥，避免竞态

**边界**：

* ✅ 做：管理会话生命周期、持久化状态、控制并发
* ❌ 不做：决定上下文压缩策略（由上下文平面负责）

### 4. 策略执行与约束检查

**机制**：

* **工具黑白名单**：此 Agent 允许/禁用哪些工具
* **成本预算**：当前会话是否超出 Token 预算、速率限制
* **用户同意机制**：高风险操作是否获得用户显式同意
* **HITL 门控**：某些步骤是否需要人工审批前执行

**边界**：

* ✅ 做：检查黑白名单、速率限制、成本预算、同意状态、HITL 门控
* ❌ 不做：把工具副作用写进策略判断；工具执行与结果回注仍通过运行时和 Gateway 协议协同完成

### 5. 故障恢复与熔断策略

**机制**：

* **超时与重试**：配置单步超时与重试次数
* **回退链路**：触发高成本模型失败时，切换到低成本模型
* **熔断**：连续失败超过阈值时，自动拒绝新请求，避免级联故障
* **降级策略**：当核心依赖不可用时，是否返回降级响应还是直接失败

**边界**：

* ✅ 做：决定重试策略、触发回退链路、执行熔断
* ❌ 不做：改变模型推理过程、自行执行工具（由 Agent Loop 负责）

## 9.2.2 控制平面的设计模式：分层审批

在生产环境中，控制平面的决策往往需要多层审核，以确保安全性与可追溯性。典型的分层审批模式包括：

```
请求到达
    ↓
[第一层] 认证与配对检查 ← 信任平面：密钥有效？配对有效？
    ↓
[第二层] 路由与优先级检查 ← 控制平面：这条消息应转向哪个 Agent？
    ↓
[第三层] 策略约束检查 ← 信任平面：工具黑白名单、用户同意、HITL 门控
    ↓
[第四层] 资源预算检查 ← 可观测性平面：是否超出 Token 预算、速率限制？
    ↓
[批准] → 转向 Agent Loop 执行
```

每一层都有**明确的决策规则与失败路径**，任何一层的拒绝都意味着请求被终止并返回相应的拒绝原因（供审计与调试）。

## 9.2.3 控制平面与数据平面的分析边界

为了提高系统的可维护性与安全性，本书建议在设计和排障时把控制平面的决策职责与数据平面的执行效果分开看待；这是一条工程分析边界，而不是当前实现中的硬隔离承诺。

**控制平面视角（侧重决策）**：

* 检查请求是否被允许
* 决定路由与优先级
* 触发重试/回退
* 暂停 HITL 门控

**数据平面视角（侧重执行效果）**：

* 执行工具调用
* 运行模型推理
* 处理流式输出
* 管理沙箱隔离

**通信方式**：

* Gateway WebSocket 协议承载控制面与节点传输，既有设备、日志、模型、会话等查询 RPC，也有发送消息、流式事件和运行结果上报。
* 更稳妥的说法是：策略裁决应有清晰证据链，执行结果应可审计回放；不要把“分析边界”误写成“两个独立进程或两套互不触达的协议”。

## 9.2.4 实际配置示例

在当前 OpenClaw 的 `openclaw.json` 中，控制平面更常见的是下面这种结构（根据本次审计实例整理，字段仍应以 `config.schema` 与官方文档为准）：

```jsonc
{
  "auth": {
    "profiles": {
      "openai:default": {
        "provider": "openai",
        "mode": "oauth"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/<model-id>"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "openai/<primary-model-id>",
          "fallbacks": ["openai/<fallback-model-id>"]
        },
        "tools": {
          "profile": "coding"
        }
      }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    }
  },
  "gateway": {
    "port": 18789,
    "auth": {
      "mode": "token"
    },
    "controlUi": {
      "allowedOrigins": ["http://127.0.0.1:18789", "http://localhost:18789"]
    }
  },
}
```

与早期资料常见的 `agents.default`、顶层 `policies`/`resilience` 相比，当前配置更强调：

* `auth.profiles`：认证档案与 provider 绑定。
* `agents.defaults` / `agents.list`：默认模型与特定智能体覆盖。
* `gateway.auth` / `gateway.controlUi.allowedOrigins`：控制面访问鉴权与来源校验。
* 渠道侧的 `dmPolicy` / `groupPolicy`：把入口治理直接写进渠道配置。