OpenClaw Gateway 深入分析

一、Gateway 概述

Gateway 是 OpenClaw 的核心网关层，负责：

• • 客户端连接管理
• • 认证与授权
• • API 调用路由
• • 会话管理
• • 通道健康监控

二、核心文件结构

src/gateway/├── boot.ts                 # 启动引导 (读取 BOOT.md)├── call.ts                 # API 调用核心 (30KB)├── client.ts               # 客户端连接管理 (28KB)├── auth.ts                 # 认证授权 (15KB)├── auth-rate-limit.ts      # 认证速率限制├── channel-health-monitor.ts # 通道健康监控├── protocol/               # 通信协议定义│   ├── index.ts            # 方法和参数 schema│   ├── connect-error-details.ts│   └── schema/             # JSON Schema 定义├── device-auth.ts          # 设备认证├── credentials.ts          # 凭证管理├── method-scopes.ts        # 方法权限范围└── net.ts                  # 网络工具

三、核心流程

3.1 启动流程 (boot.ts)

// 1. 加载 BOOT.md 文件const result = awaitloadBootFile(workspaceDir);// 2. 构建引导提示const message = buildBootPrompt(result.content);// 3. 执行 Agent 命令awaitagentCommand({ message, sessionKey, sessionId });

BOOT.md 用途：

• • 启动时自动执行的任务
• • 系统检查、通知、状态报告

3.2 客户端连接 (client.ts)

classGatewayClient {// WebSocket 连接privatews: WebSocket;// 待处理的请求privatepending: Map<string, Pending>;// 连接到 Gatewayasyncconnect(url: string, options: ClientOptions) {// 1. 建立 WebSocket 连接// 2. 发送 Hello 消息// 3. 处理认证// 4. 开始接收事件  }// 发送请求asyncrequest(method: string, params: unknown) {// 1. 生成请求 ID// 2. 发送 RequestFrame// 3. 等待 ResponseFrame  }}

3.3 API 调用 (call.ts)

asyncfunctioncallGateway(options: CallGatewayOptions) {// 1. 解析连接参数const { url, token, password } = resolveGatewayAuth(options);// 2. 创建客户端连接const client = newGatewayClient({ url, token, password });// 3. 发送请求const response = await client.request(options.method, options.params);// 4. 返回结果return response;}

四、认证机制

4.1 认证模式

typeAuthMode =   | "token"// 静态 Token  | "password"// 密码认证  | "oauth"// OAuth 2.0  | "device"// 设备绑定认证

4.2 设备认证流程

// 1. 加载或创建设备身份const identity = awaitloadOrCreateDeviceIdentity();// 2. 构建设备认证载荷const payload = buildDeviceAuthPayloadV3({deviceId: identity.deviceId,publicKey: identity.publicKey,timestamp: Date.now()});// 3. 签名并连接const signature = awaitsignDevicePayload(payload, identity.privateKey);

4.3 速率限制

// auth-rate-limit.tsconst limits = {anonymous: { windowMs: 60000, maxAttempts: 5 },authenticated: { windowMs: 60000, maxAttempts: 100 }};

五、通信协议

5.1 协议版本

constPROTOCOL_VERSION = 3;

5.2 消息帧类型

// 连接参数typeConnectParams = {clientName: string;clientVersion: string;platform: string;instanceId: string;mode: "main" | "isolated";scopes: string[];caps: string[];};// 请求帧typeRequestFrame = {id: string;method: string;params: unknown;};// 响应帧typeResponseFrame = {id: string;result?: unknown;error?: { code: string; message: string };};// 事件帧typeEventFrame = {event: string;data: unknown;};

5.3 支持的方法 (部分)

六、方法权限范围

6.1 Operator Scopes

typeOperatorScope =   | "chat"// 对话权限  | "config"// 配置权限  | "admin"// 管理权限  | "sessions"// 会话权限  | "cron"// 定时任务权限  | "nodes"// 节点权限  | "skills"// 技能权限  | "channels"// 通道权限  ;

6.2 最小权限原则

// 为每个方法解析最小权限functionresolveLeastPrivilegeOperatorScopesForMethod(method: string): OperatorScope[] {switch (method) {case"chat.send": return ["chat"];case"config.get": return ["config"];case"admin": return ["admin"];// ...  }}

七、通道健康监控

7.1 健康检查

// channel-health-monitor.tsclassChannelHealthMonitor {// 检查间隔private intervalMs = 30000;// 健康检查asynccheckHealth(channel: ChannelPlugin) {// 1. 发送心跳// 2. 检查响应时间// 3. 更新状态  }// 故障恢复asyncrecover(channel: ChannelPlugin) {// 1. 重连// 2. 重新认证// 3. 恢复会话  }}

八、WebSocket 连接

8.1 连接 URL

ws://127.0.0.1:18789wss://gateway.example.com

8.2 TLS 指纹验证

// 支持 TLS 证书指纹验证const tlsFingerprint = awaitloadGatewayTlsRuntime();

九、错误处理

9.1 连接错误详情

typeConnectErrorDetailCode =  | "AUTH_INVALID_TOKEN"  | "AUTH_RATE_LIMITED"  | "AUTH_DEVICE_REVOKED"  | "GATEWAY_UNAVAILABLE"  | "PROTOCOL_MISMATCH"  | "SCOPE_DENIED";

9.2 恢复建议

typeConnectErrorRecoveryAdvice = {action: "retry" | "reauth" | "update" | "contact_admin";message: string;};

十、与 Agent 的交互

10.1 请求流程

客户端 → Gateway.call() → Agent Command → Agent 执行    ↓Gateway 接收响应 ← Agent 返回结果    ↓客户端收到结果

10.2 流式响应

// 支持流式事件typeAgentEvent =   | { type: "text"; content: string }  | { type: "tool_use"; name: string; input: unknown }  | { type: "tool_result"; output: unknown }  | { type: "thinking"; content: string };

十一、配置示例

{"gateway":{"bind":"loopback","port":18789,"auth":{"mode":"token","token":"your-secret-token"},"tls":{"enabled":true,"cert":"/path/to/cert.pem","key":"/path/to/key.pem"}}}

十二、总结

Gateway 是 OpenClaw 的中心枢纽：

1. 1. 连接管理：WebSocket 连接、认证、会话绑定
2. 2. API 路由：将请求分发到对应的处理器
3. 3. 安全控制：认证、授权、速率限制、权限范围
4. 4. 健康监控：通道状态检查、故障恢复
5. 5. 协议实现：帧格式、方法定义、错误处理

关键特性：

• • 支持 Token / Password / OAuth / 设备认证
• • 最小权限原则（按方法分配 scope）
• • 流式响应支持
• • TLS 加密 + 指纹验证
• • 通道健康监控

• OpenClaw 源码深入分析报告

• OpenClaw 生态产品比较分析报告

• OpenClaw 安全实战第一课：在“零信任”空环境中，手搓第一个受控文件技能

• 【基石篇】生死红线——OpenClaw 深度加固与沙箱化

• OpenClaw安全自检清单：5分钟判断你的实例是否在“裸奔”

• OpenClaw 文件体系全景指南：构建可进化的“数字生命体”

• OpenClaw 内置技能全景指南：从“只会说”到“全能做”的进化之路

• OpenClaw 安全风暴：最火 AI Agent 为什么突然变成“攻击入口”

• 企业如何落地 OpenClaw：从 0 到 1 构建 AI 开发平台

• 如何构建 OpenClaw 的 AI 开发流水线

• 如何设计 OpenClaw 的 Skill 技能体系

• 如何让 OpenClaw 24 小时自动开发？Agent 调度架构设计

• OpenClaw 架构深度解析：一个 AI 开发工厂是如何运行的

• 为什么 OpenClaw 会突然爆火？AI 编程进入 Agent 时代

• OpenClaw底层揭秘：为什么它能记住你三年前说的话？

• 完了一遍可以接单龙虾Openclaw部署了

• OpenClaw + 飞书分析Moltbook 150万 Agents 每天都在聊什么

• OpenClaw 商业化与个人创业前景深度研究报告

• 我的Openclaw AI助手