# OpenClaw 源码解读（2）：Gateway 控制

> OpenClaw 的 Gateway 是整个系统唯一的控制平面。本篇深入源码，拆解这个「万物互联中枢」如何通过优雅的架构设计，实现对海量设备、会话与工具的全局调度。

- 原文链接: https://laojin.blog/blog/20260305_openclaw_source_code_2
- 作者: 老金
- 发布日期: 2026-03-05
- 标签: OpenClaw, 源码解读, AI Agent, 开源项目

---

在上一篇文章[《OpenClaw 源码解读（1）：项目概览与快速上手》](/post/20260304_openclaw_source_code_1)中，我们鸟瞰了 OpenClaw 的整体架构与设计哲学。作为一款全平台运行的个人 AI 助手，OpenClaw 能够无缝穿梭于 20 多种通讯软件与底层系统硬件之间。那么，究竟是什么在背后有条不紊地指挥着这一切？

答案就是：**OpenClaw Gateway（网关）**。本篇我们将深入源码的底层逻辑，为你拆解这个作为"万物互联中枢"的控制平面，看看它是如何通过优雅的架构设计，实现对海量设备、会话与工具的全局调度的。

## 唯一控制平面的艺术

OpenClaw 的 Gateway 设计理念非常清晰：**它是一个本地优先（Local-first）的守护进程，也是整个系统唯一的控制平面**。

在源码中，Gateway 被实现为一个基于单一 WebSocket 网络的控制中枢。这种设计模式带来了极大的架构优势：

**1. 全局解耦与统一调度**：

无论是你的 macOS 伴随应用、WebChat 前端、CLI 终端，还是负责执行操作的节点（Nodes）和自动化工具（Tools），所有客户端和事件都必须通过 Gateway WebSocket 网络进行接入与通信。

**2. 中心化与安全性**：

网关通常被绑定在本地回环地址（Loopback）上运行，只有通过类似 Tailscale Serve/Funnel 或 SSH 隧道进行安全穿透后，外部请求才能访问它。这种设计确保了你的 AI 助手在拥有强大互联能力的同时，数据和控制权依然牢牢掌握在自己手中。

简单来说，Gateway 就像是 OpenClaw 的"脑干"，所有来自外部环境的刺激（消息、事件）和发往外部的指令（执行工具、回复消息），都在这里交汇和流转。

我们可以从 `~/.openclaw/openclaw.json` 的网关配置片段中窥探其网络暴露的设计：

```json
{
  "gateway": {
    "bind": "127.0.0.1",
    "tailscale": {
      "mode": "serve", 
      "resetOnExit": true
    },
    "auth": {
      "mode": "password",
      "allowTailscale": false
    }
  }
}
```

## 状态、会话与定时调度模块

Gateway 不仅仅是一个网络中转站，它内部维护了极其丰富的核心业务模块。通过源码结构，我们可以清晰地看到它的三大核心职责：

### 状态与配置管理 (Presence & Config)
Gateway 负责维护整个 AI 网络的实时状态。它追踪用户的在线状态（Presence）、输入指示器（Typing indicators）以及各个底层大模型 Token 的使用情况（Usage tracking）。此外，网关还内置了强大的仪表盘（Control UI），直接为用户提供动态配置下发与状态监控的能力。

### 精密复杂的会话调度 (Session Model)
OpenClaw 支持在同一个底层节点上运行多个相对独立的对话，这就高度依赖网关内部的**会话模型（Session model）**。网关针对不同场景采取了严格的隔离策略：

*   **主会话（Main session）**：

专门用于你与助手的私聊（Direct chats）。在主会话中，助手默认直接在宿主机（Host）上运行工具，拥有最高的设备控制权限。

*   **非主会话（Non-main sessions / 群组隔离）**：

当助手被拉入 WhatsApp 或 Slack 群组时，网关会启用群组隔离（Group isolation）。为了安全起见，源码中甚至允许通过配置 `agents.defaults.sandbox.mode: "non-main"`，将这些非主会话的脚本运行环境丢入隔离的 Docker 沙箱（Docker sandboxes）中执行，从而彻底隔绝潜在的恶意输入。

可以看一下安全沙箱的配置源码注入方式：

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}
```

*源码解析*：当 `sandbox.mode` 设置为 `"non-main"` 时，针对群组的请求，Gateway 会把执行环境隔离到 Docker 容器中。此时，系统仅允许执行安全的工具（如 `bash`、`read`、`write`、`sessions_send`），并严格拉黑（denylist）提权操作（如 `browser`、`gateway`、`canvas` 等），彻底阻断了未授权的设备越权控制。

*   **会话队列与激活策略**：

针对群组的高频聊天，Gateway 设计了精细的队列模式（Queue modes）、群组激活规则（如 Mention 提及激活）以及回复追踪（Reply-back）机制，确保 AI 既不会"插不上话"，也不会"过度刷屏"。

### 定时任务与事件唤醒 (Cron & Wakeups)
作为一个"永远在线"的管家，AI 必须具备自主发起任务的能力。Gateway 内部集成了一套完整的 Cron 定时与唤醒机制。结合外部 Webhook 接口甚至 Gmail 的 Pub/Sub 订阅，网关能够在特定时间点或收到特定邮件事件时，主动唤醒 Agent 去执行特定的工作流。

## Pi 运行时与流式传输

当用户的消息通过通道（Channel）进入网关后，Gateway 最终需要将任务交由 Agent 处理。在 OpenClaw 中，Agent 的执行依赖于一个极其关键的底层机制：**处于 RPC（远程过程调用）模式下的 Pi Agent Runtime**。

### Pi Agent Runtime 与 RPC 架构
OpenClaw 并不是将所有 AI 逻辑都直接硬编码在网关中，而是通过 RPC 适配器（RPC adapters）将大语言模型（LLM）的思考过程抽象为了独立的运行时（Pi agent runtime）。

在执行过程中，网关（Gateway）作为服务端，Agent 作为客户端。当 Agent 判断需要调用系统操作时（例如读取文件或控制浏览器），它通过 RPC 向网关发出请求，网关校验权限后在宿主机或沙箱中执行，再将结果返回给 Agent。这种进程分离的思想，是保证多节点并发与系统稳定性的关键。

### 工具与区块的流式传输 (Tool & Block Streaming)
对于现代 AI 助手而言，响应延迟是致命的体验缺陷。为了实现"丝滑"的交互体验，OpenClaw 在数据流控制上实现了高级的**流式传输（Tool & block streaming）**。

*   **Block Streaming**：

AI 生成的文本不是等整段话全部生成完毕才发送，而是以流（Stream）或区块（Block）的形式实时推送到前端（如 WebChat 或伴随 UI）。

*   **Tool Streaming**：

在调用复杂工具（例如浏览器快照、Canvas 绘图）时，网关不需要等待工具执行完毕。工具的状态变化和部分执行结果可以被实时"流"回客户端，这使得像 Live Canvas 这样复杂的 Agent 驱动型视觉工作区能够顺畅运作，做到真正意义上的"边想边画、边做边聊"。

---

## 本篇总结

透过 Gateway WebSocket 网络的底层代码，我们看到了 OpenClaw 是如何以一个轻量级的 Node.js 守护进程为支点，优雅地撬动起了庞大的设备网络与多会话 Agent 体系的。它不仅通过会话模型与沙箱机制保障了交互的安全，更利用 Pi RPC 运行时与流式传输榨干了 LLM 响应的性能。

但在 Gateway 完成请求调度之后，这些请求又是如何精准落在不同的 Agent 实例中，并注入不同 Prompt 记忆的呢？在下一篇 **Workspaces 与多智能体路由**中，我们将带你走进 OpenClaw 的"大脑"深处，解密其强大的工作流机制。