版本 : 2026.4.15-beta.1
分析日期 : 2026年4月17日
项目地址: https://github.com/openclaw/openclaw
执行摘要
OpenClaw 是一个多通道 AI 网关系统 ，采用插件式分层架构设计。项目规模约 6900+ 文件，核心代码约 50 万行 TypeScript，支持 25+ 消息通道、40+ LLM 提供商、100+ 插件扩展。系统设计理念为"本地优先、插件驱动、安全可控"，通过统一的 Gateway 控制平面管理会话、通道、工具和事件。
核心特点
|-------------|----------------------------------------------------------|
| 特性 | 描述 |
| 架构模式 | 插件式分层架构 (Plugin-based Layered Architecture) |
| 核心语言 | TypeScript (Node.js 24+) |
| 消息通道 | WhatsApp, Telegram, Discord, Slack, Matrix, Feishu 等 25+ |
| LLM 提供商 | Anthropic, OpenAI, Google, DeepSeek, Groq 等 40+ |
| 扩展机制 | Plugin SDK (80+ 子路径导出) |
| 部署方式 | 本地网关 + 可选云端/远程 |
一、整体架构设计
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+ 命令，按功能分组
|------|-----------------------------------|---------------|
| 命令组 | 文件 | 功能 |
| 核心命令 | agent.ts, gateway.ts, config.ts | AI 交互、网关管理、配置 |
| 会话命令 | sessions.ts, reset.ts, compact.ts | 会话历史、重置、压缩 |
| 插件命令 | plugins.ts, skills.ts | 插件/技能管理 |
| 通道命令 | pairing.ts, channels.ts | 配对、通道管理 |
| 自动化 | cron.ts, hooks.ts | 定时任务、钩子 |
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<void>
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<CompletionChunk>
工具系统 (src/agents/bash-tools.ts)
工具类型：
审批机制：
工具调用 → 风险评估 → 需审批? → 发送审批请求 → 用户确认 → 执行
技能系统 (src/agents/skills.ts)
技能类型：
-
工作空间技能 (Workspace Skills) - 本地开发
-
打包技能 (Bundled Skills) - 系统内置
-
托管技能 (Managed Skills) - ClawHub 下载
技能注入：
buildWorkspaceSkillSnapshot(): SkillSnapshot
resolveSkillsPromptForRun(): string // 注入到系统提示
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<string, PluginDescriptor>
capabilities: Map<string, CapabilityProvider[]>
channels: Map<string, ChannelPlugin>
providers: Map<string, ProviderPlugin>
}
Plugin SDK (src/plugin-sdk/)
公共 API 导出 (80+ 子路径)：
|-----------------------------|---------|
| 子路径 | 功能 |
| plugin-sdk | 主入口 |
| plugin-sdk/core | 核心类型 |
| plugin-sdk/provider-entry | 提供商插件入口 |
| plugin-sdk/channel-contract | 通道契约 |
| plugin-sdk/runtime | 运行时上下文 |
| plugin-sdk/setup | 配置向导 |
| plugin-sdk/approval-* | 审批流程 |
| plugin-sdk/config-* | 配置辅助 |
插件架构图
插件架构图
三、子模块详细分析
3.1 消息通道模块
核心通道 (src/channels/plugins/)
通道接口：
interface ChannelPlugin {
id: string
sendMessage(envelope: OutboundEnvelope): Promise<void>
receiveMessage(): AsyncGenerator<InboundEnvelope>
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 {
id: string
streamCompletion(params): AsyncGenerator<CompletionChunk>
resolveAuth(config): AuthConfig
getModels(): ModelCatalog
validateRequest(params): ValidationResult
}
主要 Provider 实现
|-----------|-----------------------|----------------|
| Provider | 文件位置 | 特性 |
| Anthropic | extensions/anthropic/ | Claude 系列 |
| OpenAI | extensions/openai/ | GPT 系列 + Codex |
| Google | extensions/google/ | Gemini 系列 |
| Groq | extensions/groq/ | 高速推理 |
| DeepSeek | extensions/deepseek/ | 推理模型 |
| vLLM | extensions/vllm/ | 本地部署 |
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<string, any> // 元数据
}
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<RuntimeModule> | undefined;
function loadRuntime(): Promise<RuntimeModule> {
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 运行模式
|--------|------------------------------|--------------------|
| 模式 | 命令 | 说明 |
| 前台模式 | openclaw gateway | 直接运行网关 |
| 守护进程 | openclaw gateway --daemon | launchd/systemd 服务 |
| Docker | docker run openclaw/openclaw | 容器化部署 |
6.2 目录结构
~/.openclaw/
├── config.json # 主配置
├── sessions/ # 会话数据
│ ├── main.json
│ └── sessions.json
├── agents/ # Agent 工作空间
│ ├── main/
│ └── work/
├── plugins/ # 安装的插件
├── skills/ # 技能包
├── auth/ # 认证存储
└── logs/ # 日志文件
6.3 服务端口
|-------------------|-------|----------|
| 服务 | 默认端口 | 说明 |
| Gateway HTTP | 18789 | REST API |
| Gateway WebSocket | 18789 | 实时通信 |
| Control UI | 18789 | Web 管理界面 |
七、消息处理流程
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 架构特点
|------|------------------|
| 方面 | 设计 |
| 扩展性 | 插件式架构，100+ 内置插件 |
| 性能 | 延迟加载，按需激活 |
| 安全 | 配对策略 + 审批机制 + 沙箱 |
| 可维护性 | 清晰分层，边界测试 |
8.3 学习路径建议
- 入门：从 src/entry.ts 开始，理解 CLI 启动流程
- 核心：阅读 src/gateway/server.impl.ts，理解网关架构
- 插件：研究 extensions/anthropic/，学习插件开发模式
- 进阶：分析 src/agents/agent-command.ts，理解 Agent 执行流程
附录
A. 文件统计
|-------------|-------|------|
| 目录 | 文件数 | 主要内容 |
| src/ | 2000+ | 核心源码 |
| extensions/ | 100+ | 打包插件 |
| docs/ | 150+ | 文档 |
| test/ | 300+ | 测试 |
| skills/ | 50+ | 技能包 |
B. 关键配置文件
|----------------------|-------------------|
| 文件 | 用途 |
| package.json | NPM 配置，80+ SDK 导出 |
| tsconfig.json | TypeScript 配置 |
| vitest.config.ts | 测试配置 |
| openclaw.plugin.json | 插件清单模板 |