OpenClaw v2026.4.15系统级架构分析

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

版本 : 2026.4.15-beta.1
分析日期 : 2026年4月17日
项目地址: https://github.com/openclaw/openclaw

OpenClaw 是一个多通道 AI 网关系统 ，采用插件式分层架构设计。项目规模约 6900+ 文件，核心代码约 50 万行 TypeScript，支持 25+ 消息通道、40+ LLM 提供商、100+ 插件扩展。系统设计理念为"本地优先、插件驱动、安全可控"，通过统一的 Gateway 控制平面管理会话、通道、工具和事件。

核心特点

1.1 架构模式识别

OpenClaw 采用多层插件式架构 (Multi-Layer Plugin Architecture)，具有以下特征：

┌─────────────────────────────────────────────────────────┐

│ CLI & Interface Layer │

│ (entry.ts, commands, TUI, Web UI, ACP Adapter) │

├─────────────────────────────────────────────────────────┤

│ Gateway Core Layer │

│ (Server, Session, Auth, Config, Hooks, Routing) │

├─────────────────────────────────────────────────────────┤

│ Agent & AI Layer │

│ (Agent Command, Model Selection, Provider, Tools) │

├─────────────────────────────────────────────────────────┤

│ Plugin System Layer │

│ (Loader, Registry, SDK, 100+ Bundled Plugins) │

├─────────────────────────────────────────────────────────┤

│ Infrastructure Layer │

│ (Daemon, Cron, Sandbox, Security, Logging, Tasks) │

└─────────────────────────────────────────────────────────┘

1.2 设计原则

插件优先 (Plugin-First)：核心功能通过插件实现，保持核心精简
边界隔离 (Boundary Isolation)：插件只能通过 SDK 访问核心功能
延迟加载 (Lazy Loading)：重型模块按需加载，优化启动性能
渐进式暴露 (Progressive Disclosure)：从轻量元数据到完整运行时

1.3 系统架构图

系统架构图

2.1 CLI & Interface Layer (接口层)

入口模块 (src/entry.ts)

核心职责：CLI 启动入口，处理参数解析、环境初始化、进程管理

关键函数：

runMainOrRootHelp() - 主入口分发
ensureCliRespawnReady() - CLI 进程重启机制
tryHandleRootVersionFastPath() - 版本信息快速路径

调用链：

entry.ts → cli/run-main.ts → program/.ts → 具体命令处理

命令模块 (src/commands/)

规模：50+ 命令，按功能分组

TUI 模块 (src/tui/)

核心组件：

tui.ts - Terminal UI 主控制器

tui-stream-assembler.ts - 流式响应组装

gateway-chat.ts - 网关聊天交互

2.2 Gateway Core Layer (网关核心层)

网关服务器 (src/gateway/server.impl.ts)

核心职责：HTTP/WebSocket 服务器，会话管理，请求路由

关键类/函数：

class GatewayServer {

startGatewayServer(options: GatewayServerOptions): Promise

handleWebSocketConnection(socket, request): void

handleHttpRequest(request, response): void

broadcastToAll(message): void

}

服务器方法 (src/gateway/server-methods/)： - server-chat.ts - 聊天消息处理 - server-channels.ts - 通道管理 - server-cron.ts - 定时任务调度 - server-node-events.ts - 节点事件处理 - server-plugins.ts - 插件生命周期

会话管理 (src/gateway/session-utils.ts)

数据结构：

interface SessionEntry {

messages: Message[] // 对话历史

model?: string // 模型覆盖

providerOverride?: string // 提供商覆盖

authProfileOverride?: string // 认证配置覆盖

lastActive: number // 最后活跃时间

}

关键函数： - resolveSession() - 解析会话标识 - loadSessionStore() - 加载会话存储 - saveSessionStore() - 持久化会话

认证系统 (src/gateway/auth.ts)

认证模式 ： 1. 默认令牌 (Default Token) - 网关本地认证 2. 设备配对 (Device Pairing) - 移动节点配对 3. 预认证 (Pre-auth) - 外部服务认证

核心流程：

请求 → Token 验证 → 权限检查 → 方法授权 → 执行

配置系统 (src/config/)

配置层次：

openclaw.json - 主配置文件

sessions.json - 会话配置

agents/.json - Agent 工作空间配置

环境变量覆盖

关键模块：

config/io.ts - 配置读写
config/types.openclaw.ts - 类型定义
config/runtime-snapshot.ts - 运行时快照

钩子系统 (src/gateway/hooks.ts)

钩子类型：

2.3 Agent & AI Layer (智能体层)

Agent 命令处理 (src/agents/agent-command.ts)

核心流程：

runAgentCommand()

→ resolveSession() // 解析会话

→ resolveAgentRuntimeConfig() // 获取运行时配置

→ buildContext() // 构建上下文

→ runWithModelFallback() // 带回退执行

→ streamCompletion() // 流式完成

→ handleToolCalls() // 处理工具调用

关键函数： - runAgentCommand() - Agent 命令主入口 - executeWithFallback() - 带模型回退执行 - resolveAgentRuntimeConfig() - 解析运行时配置

模型选择 (src/agents/model-selection.ts)

选择优先级： 1. 会话级覆盖 (session.modelOverride) 2. Agent 配置 (agents.defaults.model) 3. 全局默认 (openclaw.model)

回退机制：

首选模型 → 失败 → 备选模型 1 → 失败 → 备选模型 2 → …

关键函数：

resolveConfiguredModelRef() - 解析配置模型
buildAllowedModelSet() - 构建允许模型集
resolveDefaultModelForAgent() - Agent 默认模型

Provider 运行时 (src/agents/provider-runtime.ts)

核心职责：统一 LLM API 调用接口，处理流式响应、工具调用、错误重试

关键函数：

async function * streamCompletion(params: {

provider: Provider

messages: Message[]

tools?: Tool[]

signal?: AbortSignal

}): AsyncGenerator

工具系统 (src/agents/bash-tools.ts)

工具类型：

审批机制：

工具调用 → 风险评估 → 需审批? → 发送审批请求 → 用户确认 → 执行

技能系统 (src/agents/skills.ts)

技能类型：

工作空间技能 (Workspace Skills) - 本地开发
打包技能 (Bundled Skills) - 系统内置
托管技能 (Managed Skills) - ClawHub 下载

技能注入：

2.4 Plugin System Layer (插件层)

插件加载器 (src/plugins/loader.ts)

加载流程：

loadPlugins()

→ discoverPlugins() // 发现插件

→ parseManifest() // 解析 manifest

→ validatePlugin() // 验证配置

→ activatePlugin() // 激活插件

→ registerCapabilities() // 注册能力

发现机制： 1. 内置插件 (extensions/ 目录) 2. 工作空间插件 (~/.openclaw/plugins/) 3. NPM 包 (@openclaw/) 4. ClawHub 托管

插件注册表 (src/plugins/registry.ts)

注册表结构：

interface PluginRegistry {

plugins: Map

capabilities: Map

channels: Map

providers: Map

}

Plugin SDK (src/plugin-sdk/)

公共 API 导出 (80+ 子路径)：

插件架构图

插件架构图

3.1 消息通道模块

核心通道 (src/channels/plugins/)

通道接口：

interface ChannelPlugin {

id: string

sendMessage(envelope: OutboundEnvelope): Promise

receiveMessage(): AsyncGenerator

validateConfig(config: any): ValidationResult

}

内置通道 (src/channels/)：

扩展通道 (extensions/)

目录结构：

extensions/telegram/

├── openclaw.plugin.json # 插件清单

├── index.ts # 入口

├── api.ts # 公共 API

├── runtime-api.ts # 运行时 API

└── src/

├── channel.ts # 通道实现

└── setup.ts # 配置向导

3.2 Provider 模块

Provider 契约 (src/plugin-sdk/provider-entry.ts)

interface ProviderPlugin

主要 Provider 实现

3.3 工具与能力模块

浏览器工具 (extensions/browser/)

功能： - CDP (Chrome DevTools Protocol) 控制 - 截图、导航、表单填写 - 多标签页管理

搜索工具 (extensions/brave/, extensions/exa/)

提供商： - Brave Search API - Exa AI Search - DuckDuckGo - Tavily

媒体生成 (extensions/comfy/, extensions/fal/)

能力： - 图像生成 (Stable Diffusion, DALL-E) - 视频生成 - 音频生成

4.1 主流程调用链

用户消息处理流程

用户输入 (CLI/Channel)

↓

CLI Entry / Channel Plugin

↓ parseMessage()

InboundEnvelope

↓ routeMessage()

Routing Engine

↓ resolveSession()

Session Manager

↓ resolveAgent()

Agent Command

↓ buildContext()

Context Engine

↓ resolveModel()

Model Selection

↓ streamCompletion()

Provider Runtime

↓ API Call

LLM Provider (Anthropic/OpenAI/…)

↓ yield chunks

Stream Response

↓ handleToolCalls()

Tool Executor

↓ executeTool()

Sandbox/Docker

↓

Tool Result

↓

Response Assembly

↓ dispatchReply()

Reply Dispatcher

↓ sendMessage()

Channel Plugin

↓

用户收到响应

4.2 模块依赖关系图

模块依赖图

4.3 数据传递结构

InboundEnvelope (入站信封)

interface InboundEnvelope {

channel: string // 通道 ID

sender: SenderIdentity // 发送者信息

content: MessageContent // 消息内容

timestamp: number // 时间戳

metadata?: Record // 元数据

}

OutboundEnvelope (出站信封)

interface OutboundEnvelope {

channel: string

recipient: RecipientIdentity

content: MessageContent

replyTo?: string // 回复的消息 ID

attachments?: Attachment[] // 附件

}

SessionEntry (会话条目)

interface SessionEntry {

messages: Message[]

model?: string

providerOverride?: string

authProfileOverride?: string

thinking?: ThinkingLevel

verbose?: VerboseLevel

lastActive: number

createdAt: number

}

5.1 延迟加载策略

目的：优化启动性能，减少内存占用

实现方式：

// 延迟导入重型模块

let runtimePromise: Promise | undefined;
function loadRuntime(): Promise {

runtimePromise ??= import(‘./runtime.js’);

return runtimePromise;

}

应用场景： - Provider 运行时（调用时加载） - 浏览器工具（需要时加载） - 技能内容（首次使用时解析）

5.2 插件边界隔离

边界规则： 1. 插件只能导入 openclaw/plugin-sdk/* 2. 禁止直接导入 src/ 核心代码 3. 通过 manifest 声明能力契约

验证机制： - 编译时：TypeScript 路径映射 - 运行时：导入守卫检查 - CI：边界测试 (extension-import-boundaries.test.ts)

5.3 安全模型

安全层级：

┌────────────────────────────────────────┐

│ DM 配对策略 │

│ (unknown → pairing code → allowlist) │

├────────────────────────────────────────┤

│ 工具审批机制 │

│ (risk assessment → approval request) │

├────────────────────────────────────────┤

│ 沙箱隔离 │

│ (Docker/Host separation) │

├────────────────────────────────────────┤

│ 配置审计 │

│ (doctor scan → security audit) │

└────────────────────────────────────────┘

5.4 高可用机制

模型回退： - 配置多认证配置 (authProfiles) - 自动轮换和冷却 - 失败时切换备用模型

会话持久化： - 自动保存到 ~/.openclaw/sessions/ - 崩溃恢复机制 - 会话压缩 (compaction.ts)

6.1 运行模式

6.2 目录结构

~/.openclaw/

├── config.json # 主配置

├── sessions/ # 会话数据

│ ├── main.json

│ └── sessions.json

├── agents/ # Agent 工作空间

│ ├── main/

│ └── work/

├── plugins/ # 安装的插件

├── skills/ # 技能包

├── auth/ # 认证存储

└── logs/ # 日志文件

6.3 服务端口

7.1 请求处理流程图

消息流程图

7.2 响应处理流程

LLM 响应 (Stream)

↓

Response Processor

├─ Text Content → 直接输出

├─ Tool Calls → Tool Executor

└─ Reasoning → 可选显示

↓

Reply Dispatcher

├─ 消息分块 (适配通道限制)

├─ 输入状态指示

└─ 媒体上传

↓

Outbound Handler

├─ 格式化 (Markdown → Channel Format)

└─ 附件处理

↓

Channel API

└─ 发送消息

8.1 架构优势

高度可扩展：插件系统支持任意通道/提供商扩展
边界清晰：SDK 层隔离核心与插件，降低耦合
性能优化：延迟加载减少启动开销
安全可控：多层安全机制保护生产环境

8.2 架构特点

8.3 学习路径建议

入门：从 src/entry.ts 开始，理解 CLI 启动流程
核心：阅读 src/gateway/server.impl.ts，理解网关架构
插件：研究 extensions/anthropic/，学习插件开发模式
进阶：分析 src/agents/agent-command.ts，理解 Agent 执行流程

A. 文件统计

B. 关键配置文件

C. 参考文档

官方文档
Plugin SDK 文档
架构设计文档

OpenClaw v2026.4.15系统级架构分析

核心特点

1.1 架构模式识别

1.2 设计原则

1.3 系统架构图

2.1 CLI & Interface Layer (接口层)

入口模块 (src/entry.ts)

命令模块 (src/commands/)

TUI 模块 (src/tui/)

2.2 Gateway Core Layer (网关核心层)

网关服务器 (src/gateway/server.impl.ts)

会话管理 (src/gateway/session-utils.ts)

认证系统 (src/gateway/auth.ts)

配置系统 (src/config/)

钩子系统 (src/gateway/hooks.ts)

2.3 Agent & AI Layer (智能体层)

Agent 命令处理 (src/agents/agent-command.ts)

模型选择 (src/agents/model-selection.ts)

Provider 运行时 (src/agents/provider-runtime.ts)

工具系统 (src/agents/bash-tools.ts)

技能系统 (src/agents/skills.ts)

2.4 Plugin System Layer (插件层)

插件加载器 (src/plugins/loader.ts)

插件注册表 (src/plugins/registry.ts)

Plugin SDK (src/plugin-sdk/)

插件架构图

3.1 消息通道模块

核心通道 (src/channels/plugins/)

扩展通道 (extensions/)

3.2 Provider 模块

Provider 契约 (src/plugin-sdk/provider-entry.ts)

主要 Provider 实现

3.3 工具与能力模块

浏览器工具 (extensions/browser/)

搜索工具 (extensions/brave/, extensions/exa/)

媒体生成 (extensions/comfy/, extensions/fal/)

4.1 主流程调用链

用户消息处理流程

4.2 模块依赖关系图

4.3 数据传递结构

InboundEnvelope (入站信封)

OutboundEnvelope (出站信封)

SessionEntry (会话条目)

5.1 延迟加载策略

5.2 插件边界隔离

5.3 安全模型

5.4 高可用机制

6.1 运行模式

6.2 目录结构

6.3 服务端口

7.1 请求处理流程图

7.2 响应处理流程

8.1 架构优势

8.2 架构特点

8.3 学习路径建议

A. 文件统计

B. 关键配置文件

C. 参考文档

相关推荐