OpenClaw 内部架构与调用关系

多渠道 AI 助手平台的核心模块组成、数据流向、沙箱机制详解

架构设计沙箱安全多渠道

一、整体架构图

二、核心模块说明

Gateway（控制平面）

核心中枢，WebSocket 服务端口 18789。负责会话管理、配置存储、消息路由、安全认证、沙箱调度。

Channel Manager（频道管理器）

管理 20+ 消息平台连接，处理入站/出站消息，维护频道状态和凭证。

Agent Runtime（运行时）

基于 Pi Agent 的推理引擎，负责意图理解、任务规划、工具编排、上下文管理。

Sandbox Manager（沙箱管理器）

根据会话类型决定执行环境：主机执行 vs Docker 沙箱 vs SSH 远程执行。

Tools（工具集）

原子能力：文件操作、进程执行、浏览器控制、消息发送、知识库访问。

三、典型调用场景

场景 1：主会话（main）- 完全信任

1用户通过 CLI/WebChat 等客户端发起请求

2Gateway 识别为 main 会话，直接路由到主机执行环境

3Agent Runtime 调用 LLM 推理，编排工具执行

4工具直接访问主机资源，无任何限制

场景 2：群组会话（non-main）- 沙箱隔离

1消息从 Telegram/Discord 等群组渠道到达

2Gateway 识别为 non-main 会话，路由到 Docker 沙箱

3沙箱内执行工具，网络隔离、文件系统隔离

4限制爆炸半径，保护主机安全

场景 3：跨平台消息处理

1多渠道入站：WhatsApp、Discord、Telegram 同时接收消息

2Gateway 统一处理，Agent Runtime 推理响应

3多渠道出站：响应可发送到任意平台

四、沙箱决策流程

步骤1消息到达 Gateway

↓

判断会话类型（mainKey）

main 会话 → 直接主机执行，完全信任

non-main 会话 → 进入沙箱模式判断

↓

查询沙箱模式配置（sandbox.mode）

mode="off" → 全部主机执行

mode="non-main" → 群组沙箱，主会话主机（推荐）

mode="all" → 全部沙箱执行，最大安全

↓

主机执行

完全信任无任何限制

沙箱执行

Docker 隔离网络/文件限制

↓

工具策略检查（tool policy）

允许 → 执行工具操作

拒绝 → 返回错误，保护系统

五、沙箱配置对照表

六、模块调用关系总结

入站流向

用户设备/消息渠道 - Gateway - 会话管理 - 沙箱管理器 - Agent Runtime

出站流向

Agent Runtime - LLM推理 - 工具编排 - 知识库/Skills - 结果返回用户

沙箱切入时机

工具执行前检查 mode，根据 sessionKey 判断 main/non-main，选择执行环境

安全边界

频道层 DM Pairing + Allowlist，Gateway 层认证配额，沙箱层进程网络文件隔离

架构设计精髓

OpenClaw 采用"Gateway + 插件化 + 沙箱"三层架构：

1Gateway 作为统一控制平面，所有流量经过

2插件化 让 Channels/Tools/Skills 可扩展

3沙箱 在工具执行层提供安全隔离，按会话类型动态决策