OpenClaw 基础架构详解

OpenClaw 是一款 MIT 开源、本地优先（Local-First） 的 AI Agent 执行网关与运行时操作系统，其核心定位是为 AI Agent 提供完整的、自托管的执行环境 ——LLM 提供智能，OpenClaw 提供调度、隔离、持久化与扩展能力，将 “对话式 AI” 升级为 “可执行的 AI Agent”。

其基础架构遵循中心辐射式（Hub-Spoke） 核心范式，以 Gateway 网关为唯一的控制中枢与事实来源，所有子系统、扩展能力、交互入口均作为分支节点通过标准化接口与 Gateway 通信，实现了交互渠道、AI 推理、任务执行、能力扩展的完全解耦，同时严格遵循本地优先、沙箱执行、模型无关三大设计哲学。

一、核心分层架构（官方标准架构）

OpenClaw 整体架构从外到内可分为 5 个核心层级，每层职责单一、边界清晰，通过标准化的 WebSocket/HTTP 接口通信，层间严格遵循依赖倒置原则，保证核心稳定的同时实现无侵入式扩展。

1. 接入层：系统与外界的交互入口

接入层是用户、设备与 OpenClaw 交互的唯一入口，分为渠道适配器和控制接口两大模块，核心职责是屏蔽底层差异，实现消息与指令的标准化输入输出。

（1）渠道适配器（Channels Adapter）

负责对接各类通讯平台，将不同平台的消息协议、格式、认证体系标准化，让上层系统无需关心消息来源。

核心能力：认证鉴权、入站消息解析、访问控制、出站消息格式化

原生支持：WhatsApp、Telegram、Discord、Slack、iMessage、飞书、企业微信等 50 + 主流通讯平台

扩展方式：通过渠道插件新增自定义平台，无需修改核心代码

（2）控制接口（Control Interfaces）

提供多种 Gateway 管控方式，适配不同使用场景，所有控制指令均通过 WebSocket 与 Gateway 通信，核心包括：

Web UI：默认监听127.0.0.1:18789，提供聊天、配置管理、会话检查、健康监控等可视化能力

CLI：命令行工具，覆盖 Gateway 启停、Agent 调用、渠道配对、健康诊断等全生命周期操作

桌面 / 移动端应用：macOS 菜单栏应用、iOS/Android 移动端节点，提供 Gateway 生命周期管理、设备能力扩展（摄像头、位置、屏幕录制等）

2. Gateway 核心控制平面层：系统的神经中枢

Gateway 是 OpenClaw 架构的唯一 Hub 核心，基于 Node.js 构建，默认绑定127.0.0.1:18789，是整个系统的唯一事实来源与全局调度中心，所有消息、指令、事件都必须经过 Gateway 流转。

其核心职责包括：

连接管理：维护所有渠道、控制接口、Agent 运行时、节点的 WebSocket 长连接，管理连接生命周期

消息路由与调度：入站消息经过访问控制校验后，解析归属会话，精准分派到对应的 Agent Runtime，同时管理事件分发与重试

会话与状态管理：持有全量会话状态，管理会话隔离、上下文持久化、在线状态、定时任务等，是系统状态的唯一可信源

权限与安全管控：实现接入认证、IP 白名单、渠道级访问控制、操作幂等性保障，防止重复执行与越权操作

配置热重载：支持配置动态更新，无需重启 Gateway 即可生效，同时管理全系统的配置分发

3. Agent Runtime 智能体运行时层：AI 决策的执行引擎

Agent Runtime 是 OpenClaw 的 AI 核心，基于 Pi Agent Core 库实现，是端到端运行 Agent 智能循环的执行引擎，负责将用户指令转化为模型推理与工具执行动作。

其核心执行流程（单轮循环）分为 4 步：

会话解析：根据消息来源，映射到对应会话（个人主会话、DM 会话、群聊会话），加载会话权限与沙箱规则，会话是系统的核心安全边界

上下文组装：动态拼接系统提示、会话历史、技能说明、内存检索结果、工具定义，构建完整的模型输入上下文，避免提示词膨胀

模型推理与工具执行：流式调用配置的 LLM（支持 OpenAI、Anthropic、Gemini、DeepSeek 等 40 + 模型 / 自托管模型），拦截并执行模型发起的工具调用，将工具结果流式回传给模型，完成多轮推理

状态持久化：对话轮次完成后，将更新后的会话历史、工具调用记录、状态数据持久化到磁盘，保证会话连续性

系统提示架构（可组合式设计）

OpenClaw 采用分层可组合的提示词体系，无需修改核心代码，仅通过编辑工作区文件即可定制 Agent 行为：

核心基线：AGENTS.md（全局规则、权限边界）、SOUL.md（个性语气）、TOOLS.md（工具使用约定）

动态注入：会话历史、相关技能说明、语义检索的内存片段、自动生成的工具定义

基础底座：Pi Agent Core 内置的基础指令

4. 能力执行层：Agent 的行动与记忆底座

该层是 Agent 能力的最终载体，负责工具执行、记忆持久化、安全隔离，核心分为三大模块：

（1）工具 / 技能系统（Tools & Skills）

工具（Tools）：原子化的执行能力，内置 bash 终端、浏览器自动化、文件操作、Canvas 渲染等核心能力，可通过工具插件无限扩展，所有工具调用均受沙箱规则管控

技能（Skills）：结构化的任务执行 SOP，基于工具组合实现复杂场景能力（如网页调研、报表生成、邮件自动化），运行时仅注入与当前任务相关的技能，避免提示词冗余

（2）内存系统（Memory）

负责 Agent 的长期记忆与上下文管理，默认基于 SQLite 实现本地持久化，支持通过内存插件替换为向量数据库、知识图谱等存储后端。

核心能力：会话历史持久化、语义记忆检索、用户偏好存储、跨会话上下文继承

设计特点：内存与模型解耦，记忆检索在运行时本地完成，仅相关片段注入模型上下文，兼顾隐私与上下文窗口效率

（3）沙箱执行环境（Sandbox）

OpenClaw 安全架构的核心，基于 Docker 实现工具执行的强隔离，避免 Agent 直接操作主机系统。

可配置隔离规则：不同会话可设置不同的沙箱权限，如个人主会话可开放主机权限，群聊 / DM 会话默认严格隔离

执行管控：所有工具调用均经过权限校验，高危操作需用户二次确认，执行日志全量留存

5. 插件扩展层：无侵入式能力扩展

OpenClaw 采用全插件化设计，无需修改核心代码即可扩展系统能力，插件通过标准化 API 注册到系统，由 Gateway 统一管理生命周期，支持热加载。

官方原生支持四大类插件：

表格

插件类型 核心作用 扩展场景

渠道插件 新增通讯平台适配 对接企业微信、钉钉、自定义 IM 系统

模型 Provider 插件 新增 LLM 接入能力 对接自托管模型、国产大模型

工具插件 新增原子执行能力 对接企业内部系统、第三方 API、自定义工具

内存插件 替换 / 扩展内存存储 对接向量数据库、知识图谱、企业知识库

二、核心架构设计亮点

严格的控制与执行分离：Gateway 作为唯一控制平面，不执行 AI 推理与工具调用；Agent Runtime 作为执行平面，无状态、可隔离，两者解耦保证了系统的稳定性与安全性

会话级安全边界：以会话为核心权限单元，不同渠道、不同用户、不同群聊的会话完全隔离，可独立配置权限、模型、工作区，避免权限泄露

本地优先的隐私设计：对话历史、会话状态、工具执行全流程在用户自有基础设施上完成，仅模型 API 调用发送到 LLM 服务商，数据主权完全归用户所有

模型无关的兼容性：Agent Runtime 与 LLM 完全解耦，可无缝切换不同模型，同时支持多模型降级、负载均衡，不绑定任何 AI 厂商

事件驱动的异步架构：全系统基于事件驱动设计，无轮询开销，客户端通过订阅事件获取状态更新，响应延迟低，资源占用少

三、完整请求处理工作流

一条用户消息从发送到得到响应，完整的架构流转流程如下：

用户通过 WhatsApp/Telegram 等渠道发送消息，对应渠道适配器接收消息，完成认证、格式解析、访问控制校验，将消息标准化后发送到 Gateway

Gateway 接收消息，解析消息归属的会话 ID，校验会话权限，将消息分派到对应的 Agent Runtime

Agent Runtime 加载会话上下文，拼接系统提示、历史消息、相关技能、内存片段，构建完整的模型输入

Agent Runtime 流式调用 LLM，拦截模型发起的工具调用请求，根据会话沙箱规则，在 Docker 隔离环境中执行工具

工具执行结果流式回传给 LLM，模型完成多轮推理与内容生成

Agent Runtime 将生成的响应内容发送给 Gateway，同时持久化更新会话状态

Gateway 将响应内容路由回对应的渠道适配器，适配器完成平台格式转换，发送给用户

整个流程中，Gateway 全程管控事件流转、状态更新、权限校验，保证全链路可追溯、可管控