OpenClaw架构详解

作者：CSDN博客
OpenClaw 是一个本地优先、分布式、常驻运行的 AI Agent 框架，核心是 Gateway 控制平面 + Agent Runtime 执行平面 的双进程/分层架构。本文将从架构总览、分层拆解、核心组件、分布式机制等维度，清晰解析其整体设计与运行逻辑。
一、架构总览与定位

1.1 核心定位

OpenClaw = 常驻 Gateway（控制中枢） + 分布式 Agent Runtime（执行引擎） + 全渠道接入 + 本地优先存储
1.2 架构哲学

控制平面与执行平面分离：Gateway 负责路由、会话、状态管理；Agent Runtime 负责推理、工具调度与执行。本地优先（Local-First）：数据、记忆、配置均存储在本地，不依赖云端，保障隐私与断网可用性。微内核 + 插件化 + 分布式：核心轻量，渠道、技能、模型可插拔，支持多设备/多节点协同。

1.3 物理部署：双进程模型

OpenClaw 物理上仅包含两个独立进程，职责清晰、低耦合：

• Gateway 进程（核心守护进程）
  包含组件：接入层、网关层、Agent Runtime、本地节点（Local Node）核心特性：单端口（默认 127.0.0.1:18789）统一提供所有服务
  
  
  
• Remote Node 进程（可选，分布式节点）
  部署位置：手机、服务器、边缘设备等通信方式：通过 WebSocket 与 Gateway 长连接核心职责：执行远程工具（如手机截图、远程文件操作）
  
  
  

二、五层逻辑架构（从外到内）

OpenClaw 采用标准五层分层设计，各层级职责明确、低耦合，确保系统可扩展、易维护，具体如下表所示：

层级	名称	核心组件	核心职责
1	接入层（Ingress/Channel）	渠道适配器（Channels）	多平台消息接入、协议转换、格式标准化
2	控制平面（Control Plane）	Gateway 网关	路由、会话管理、认证、状态同步、API 服务
3	执行平面（Execution Plane）	Agent Runtime、Run 单元	ReAct 推理循环、工具调度、任务执行、重试
4	能力层（Capability）	Skills、Tools、LLM Providers	工具集、模型适配、浏览器/Shell/HTTP 等能力
5	数据层（Data）	Workspace、Memory、Config	本地文件存储、记忆、日志、审计、配置

三、各层级深度拆解

3.1 接入层（Ingress/Channel Layer）

核心作用：将外部平台的消息“翻译”为 OpenClaw 内部统一格式，实现多渠道统一接入。
核心组件：渠道适配器（Channels）

支持渠道：WhatsApp、Telegram、Discord、iMessage、WebChat、Webhook、Cron 定时任务

• 核心功能（每个渠道为独立插件）：
  
  与对应 IM 平台建立连接接收外部消息 → 转换为内部 Message 对象将内部回复 → 转换为对应平台原生格式并发送
  
  
  

统一入口：所有渠道最终均接入 Gateway，由 Gateway 统一调度管理，避免多渠道混乱。
3.2 控制平面（Control Plane）：Gateway 网关

核心定位：整个系统的“心脏”，作为唯一事实源（Single Source of Truth），统筹所有核心流程。
核心能力

消息路由：根据用户、会话、渠道信息，将消息精准分发到对应 Agent 与 Run 单元。

• 会话管理：
  维护每个用户的独立会话状态将会话历史持久化到本地文件支持跨设备会话同步，保障多端一致体验
  
  
  
• 认证与安全：
  支持 API Key / Token 认证机制禁止无认证公网暴露，保障系统安全提供工具调用审批机制，管控权限风险
  
  
  
• 单端口复用服务：
  WebSocket RPC：负责客户端、节点间的实时通信OpenAI 兼容 HTTP API：方便与各类 LLM 客户端集成Control UI：内置 Web 管理界面，用于配置、监控与调试Webhook 端点：支持外部系统集成与自动化触发
  
  
  
• 技能注册中心（Skill Registry）：
  统一管理所有可用技能（本地/远程）实现技能发现、权限校验、参数校验功能
  
  上下文引擎（Context Engine）：动态组装 LLM 上下文，包含基础提示、技能列表、历史记忆、当前输入等内容。
  

3.3 执行平面（Execution Plane）：Agent Runtime

核心定位：系统的“大脑”，是真正执行“思考 + 行动”的核心模块，基于 ReAct 模式（Reason + Act）运行。
核心流程：Agentic Loop（智能体循环）

一次完整的任务执行流程如下：

1. 用户输入 → 上下文组装 → LLM 推理 → 工具调用/纯文本回复 → 流式输出 → 持久化

复制代码

• 上下文组装（Context Assembly）：
  基础提示（Base Prompt）：来自 soul.md，定义 Agent 人格与规则技能提示（Skills Prompt）：当前可用的工具列表引导上下文：工作区环境信息历史记忆：短期会话历史与长期沉淀知识当前输入：用户最新发送的消息
  
  
  
• LLM 推理：
  调用配置的模型（本地 Llama / 云端 GPT/Claude 等）输出结果：要么是纯文本回复，要么是结构化工具调用请求
  
  
  
• 工具执行（Tool Execution）：
  若输出工具调用请求：Gateway 校验权限 → 转发到对应 Node（本地/远程）→ Node 执行工具 → 返回结果 → 结果回传给 Agent 进入新一轮推理若输出纯文本：直接回复用户，本次循环结束
  
  
  
• Run 单元与 Lane 机制：
  Run 单元：一次完整的任务执行单元，包含重试、超时、日志等信息，确保任务可追溯、可中断Lane 机制：串行执行队列，每个会话/任务独占一个 Lane，避免并发状态冲突（如保证“下载 → 解压 → 处理”严格按顺序执行）
  
  
  

3.4 能力层（Capability Layer）

核心定位：系统的“手脚”，为 Agent 提供可执行的各类能力，支撑任务落地。
核心组件

• Skills（技能）：
  定义：即插即用的工具集，官方提供 60+ 技能（文件操作、搜索、浏览器、Shell、天气查询等）
  
  • 分类：
    
    本地技能：在 Gateway 所在主机执行（如文件读写、命令行操作）远程技能：在 Remote Node 执行（如手机截图、远程文件操作）
    
    
    
  
  
• Tools（底层工具）：最基础的原子能力，是 Skills 的组成单元，包括：
  浏览器自动化（Playwright）Shell 命令执行HTTP/API 调用文件系统操作
  
  
  
• LLM Providers：
  统一适配各类模型：OpenAI、Anthropic、本地 Llama/Ollama、通义千问等灵活配置：每个 Node 可独立配置模型（轻任务用本地小模型，重任务用云端大模型）
  
  
  

3.5 数据层（Data Layer）

核心定位：系统的“记忆与存储中心”，遵循本地优先原则，所有数据均存储在用户本地主机。
核心组件

• Workspace（工作区）：
  默认路径：~/.openclaw/核心结构：config/（配置文件）、memory/（记忆数据）、logs/（日志）、channels/（渠道配置）、skills/（技能文件）
  
  
  
• Memory（记忆）：分为短期记忆与长期记忆，支撑 Agent 的“记忆能力”：
  短期记忆：当前会话的历史记录，格式为 Markdown/JSON，供 LLM 实时调用长期记忆：跨会话保存的信息，包括用户偏好、重要结论、任务结果、知识库片段等，支持检索复用
  
  
  
• Config（配置）：
  openclaw.json：全局配置文件，包含模型选择、端口设置、渠道凭证、安全策略等soul.md：定义 Agent 的人格、规则与行为边界
  
  
  
• 日志与审计：
  全链路日志：记录消息流转、LLM 推理、工具调用、错误信息等核心特性：可追溯、可审计，便于问题排查与系统运维
  
  
  

四、分布式节点架构（Gateway + Nodes）

OpenClaw 支持一 Gateway + 多 Nodes 的分布式部署模式，实现跨设备协同与能力扩展，具体架构如下：
4.1 各节点角色

Gateway：整个分布式系统的控制中心，所有流量的统一入口，负责调度、路由与管理。Local Node：与 Gateway 运行在同一台机器上，负责执行本地工具，无需额外部署。

• Remote Node：
  部署位置：手机（iOS/Android）、服务器、边缘设备等通信方式：通过 WebSocket 与 Gateway 建立长连接核心职责：执行远程工具（如手机拍照、远程服务器命令）灵活配置：每个 Remote Node 可独立配置模型、技能与权限
  
  
  

4.2 分布式核心逻辑

一句话总结

OpenClaw 分布式 = 一个中央 Gateway + 多个执行节点（Node），工具可在任意设备上执行，实现“思考与执行分离”。
分布式部署的意义

适配不同工具的运行环境：部分工具仅能在特定设备执行（如手机拍照、服务器大数据处理）。保障隐私安全：数据不出设备，每个节点的本地数据仅在自身存储，避免隐私泄露。灵活扩展：可随时新增节点，提升系统执行能力，无需修改 Gateway 核心配置。

分布式执行流程（示例）

用户发送指令：“帮我截一张手机屏幕”Gateway 接收消息，转发给 Agent 进行推理Agent 推理后，确定需要调用手机截图工具Gateway 查找所有在线 Node，定位到手机上的 Remote NodeGateway 将工具调用指令转发给手机 Remote Node手机 Remote Node 执行截图操作，将截图结果返回给 GatewayGateway 将结果整理后，回复给用户

核心优势：Gateway 不触碰设备底层，手机不直接连接模型服务，兼顾安全、隐私与跨设备协同。
五、完整消息数据流

以用户通过 Telegram 发送消息为例，完整数据流如下，清晰呈现各组件的协同逻辑：

用户在 Telegram 发送消息 → Telegram 渠道适配器接收渠道适配器将消息转换为内部 Message 对象 → 发送给 GatewayGateway 执行流程：认证 → 查找对应会话 → 将消息路由到指定 Agent → 组装上下文（历史记忆 + 技能 + 当前消息）Gateway 将组装好的上下文交给 Agent Runtime，启动一个 Run 单元执行任务Agent Runtime 执行流程：调用 LLM 推理 → 输出工具调用请求（如“调用文件搜索工具”）Gateway 校验工具调用权限 → 将请求转发给 Local NodeLocal Node 执行文件搜索工具 → 返回结果列表结果回传给 Agent Runtime → Agent 进行新一轮推理，生成总结文本Agent 将总结文本流式回复给 GatewayGateway 将回复转发给 Telegram 渠道适配器 → 适配器转换为 Telegram 原生格式，推送给用户全程日志与会话历史自动持久化到本地工作区

六、架构核心优势

常驻运行（Always-On）：Gateway 作为守护进程，7×24 小时在线，支持主动消息推送、定时任务执行。本地优先：所有数据存储在本地，数据不出域，保障隐私安全，断网状态下仍可正常使用。分布式协同：一中心多节点架构，实现跨设备工具执行，灵活扩展系统能力。控制与执行分离：Gateway 管调度，Node 管执行，提升系统稳定性、可扩展性与可运维性。插件化设计：渠道、技能、模型均支持插拔，可根据需求灵活定制，降低二次开发成本。有状态特性：支持长期记忆与会话上下文持久化，实现真正的“智能体”，而非一次性执行脚本。

七、与传统 Agent 框架的区别

特性	OpenClaw	传统单进程 CLI Agent
运行模式	常驻 Gateway 守护进程	一次性脚本/无状态
架构	控制平面 + 执行平面 + 分布式	单进程、无分层
接入能力	全渠道 IM + Webhook + Cron	仅 CLI/简单 Web
工具执行	本地 + 远程多节点	仅本地
状态管理	持久化会话 + 长期记忆	无状态/临时内存
并发	Lane 串行 + 多会话并行	单线程/简单并发

八、OpenClaw 整体架构图（清晰可绘制版）

1. ┌─────────────────────────────────────────────────────────────────────┐
2. │                         外部用户与渠道                               │
3. │  ┌───────┐  ┌──────────┐  ┌─────────┐  ┌────────┐  ┌─────────────┐  │
4. │  │ 微信   │  │Telegram │  │Discord │  │Web UI │  │API / 第三方客户端 │ │
5. │  └───┬───┘  └────┬─────┘  └────┬────┘  └───┬────┘  └───────┬───────┘  │
6. └──────┼────────────┼────────────┼────────────┼────────────────┼───────┘
7.        │            │            │            │                │
8.        ▼            ▼            ▼            ▼                ▼
9. ┌─────────────────────────────────────────────────────────────────────┐
10. │                       Gateway（网关 / 控制平面）                       │
11. │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
12. │  │  接入层     │  │ 会话&路由    │  │ 安全&认证    │  │ Web/API服务 │ │
13. │  │ (Channels)  │  │             │  │             │  │            │ │
14. │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  │
15. └─────────┼────────────────┼────────────────┼────────────────┼─────────┘
16.           │                │                │                │
17.           ▼                ▼                ▼                ▼
18. ┌─────────────────────────────────────────────────────────────────────┐
19. │                       Agent Runtime（执行平面）                       │
20. │  ┌───────────────────────────────────────────────────────────────┐  │
21. │  │                     Agent 智能体循环                           │  │
22. │  │  接收消息 → 组装上下文 → LLM 推理 → 决定是否调用工具 → 回复     │  │
23. │  └───────────────────────────┬───────────────────────────────────┘  │
24. └───────────────────────────────┼───────────────────────────────────────┘
25.                                 │
26.           ┌─────────────────────┴─────────────────────┐
27.           │                                           │
28.           ▼                                           ▼
29. ┌─────────────────────┐                     ┌─────────────────────┐
30. │    Skills / Tools   │                     │    数据与记忆层      │
31. │ （文件、搜索、浏览器、 │                     │ 会话历史、长期记忆  │
32. │   Shell、API 等）    │                     │ 配置、日志、工作区  │
33. └──────────┬───────────┘                     └─────────────────────┘
34.            │
35.            │ （工具可以分发到不同设备执行）
36.            ▼
37. ┌─────────────────────────────────────────────────────────────────────┐
38. │                           分布式节点层                               │
39. │   ┌───────────────┐    ┌───────────────┐    ┌───────────────────┐   │
40. │   │  Local Node  │    │ Remote Node 1 │    │ Remote Node 2 …   │   │
41. │   │（本机执行）   │    │（手机/服务器） │    │（其他设备/边缘设备）│   │
42. │   └───────────────┘    └───────────────┘    └───────────────────┘   │
43. └─────────────────────────────────────────────────────────────────────┘

复制代码

架构总结：用户 → 渠道 → Gateway（大脑中枢） → Agent Runtime（思考） → 调用 Skills/Tools → 在本地或远程 Node 执行 → 结果返回用户
九、核心名词解释

为便于理解，对 OpenClaw 核心名词进行精准定义，明确其角色与功能：
9.1 用户（User）

即使用 OpenClaw 的人，核心特点：

可通过 Web、App、微信、Telegram 等多种渠道发送指令每个用户拥有独立身份、独立对话记录与独立权限Gateway 通过用户 ID 区分不同会话，避免消息串聊

9.2 Run 单元

定义：一次完整的“思考+做事”任务包，核心特性：

对应关系：一次用户输入 = 一个 Run 单元包含内容：上下文、LLM 调用、工具调用、重试机制、超时控制、执行日志、最终回复核心作用：让任务可追踪、可重试、可中断，避免多个任务互相干扰，保证“思考→行动”的原子性

9.3 Skills vs Tools（技能 vs 工具）

两者层级不同、职责不同，是“组合与被组合”的关系：

Tools（底层工具）：最基础的原子能力，是构成 Skills 的基础，如文件读写、Shell 执行、网络请求、截图、搜索等。Skills（高级技能）：由多个 Tools 组合而成，面向具体任务，如总结文件、下载网页并分析、定时备份、自动写周报、控制智能家居等。

通俗记忆：Tools = 手脚，Skills = 经过训练的动作组合
9.4 历史记忆

分为短期记忆与长期记忆，支撑 Agent 的“记忆能力”，实现跨会话连贯交互：

短期记忆（会话历史）：当前一轮对话的上下文，LLM 每次推理时都会读取，确保对话连贯性。长期记忆：跨会话保存的核心信息，包括用户偏好、重要结论、任务结果、知识库片段等，支持语义检索，让 Agent 即使关闭对话也能“记住”关键信息。

9.5 Node（节点）

定义：可以执行工具的设备/环境，分为两种类型，各司其职：

Local Node（本地节点）：与 Gateway 运行在同一台机器上，负责执行本地工具，无需额外部署。Remote Node（远程节点）：运行在其他设备上（手机、另一台服务器、家里的电脑、树莓派等），核心职责：接收 Gateway 指令 → 执行工具 → 返回结果。

原文地址：https://blog.csdn.net/weixin_43904304/article/details/159651250