当前位置：首页 > news >正文

【openclaw】OpenClaw v2026.4.15系统级架构分析

news 2026/4/20 10:39:08

一、项目整体架构

1.1 项目概述

OpenClaw是一个多通道AI网关（Multi-Channel AI Gateway），通过可扩展的插件式架构将70+个消息通道（Slack、Discord、Telegram、WhatsApp、飞书、Signal、iMessage、IRC、Matrix、MS Teams等）与22+个LLM Provider（Anthropic、OpenAI、Google、Bedrock、DeepSeek、Groq、Mistral、Ollama、vLLM、OpenRouter等）连接，提供统一的Agent编排、工具执行、会话管理、安全审计和子Agent调度能力。

项目名称: openclaw
版本: 2026.4.15-beta.1
语言: TypeScript (ESM)
包管理: pnpm workspaces
总源文件: 6624+ 个 .ts 文件 (核心) + 867+ 个 (扩展插件)
扩展插件: 80+ 个（通道、Provider、工具、媒体等）
技能: 50+ 个（1password、github、slack、weather等）

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

设计原则

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

1.2 架构模式：分层插件式网关架构

OpenClaw 采用六层 + 插件式架构模式，自顶向下：

层级	名称	核心组件	职责
L1	客户端/UI层	CLI、TUI、Web UI、Mobile Apps、MCP/ACP	用户交互入口
L2	通道插件层	70+ Channel Plugins	消息平台适配与双向通信
L3	网关核心层	GatewayServer、SessionManager、Auth、PluginEngine	请求路由、会话管理、安全控制
L4	Agent引擎层	AgentRunner、ModelConfig、ToolSystem、SubagentReg	LLM调用循环、工具执行、上下文管理
L5	Provider插件层	22+ LLM Provider Plugins	多模型统一流式API
L6	基础设施层	Daemon、Security、Secrets、Process、Memory、Logging	系统级支撑服务

跨切关注点：Config（Zod Schema）、Hooks（生命周期钩子）、Media Understanding、Image/Video Generation、TTS、Node Host、Pairing

1.3 整体运行流程

用户消息 → Channel Plugin (L2) → GatewayServer (L3) [认证/路由/会话] → AgentRunner (L4) [system prompt构建 + 上下文加载] → LLM Provider (L5) [stream调用] → Tool Execution (L4) [bash/read/write/edit + 审批] → Reply Delivery (L3→L2) [流式回复→通道] → Session Persistence (L3) [JSONL写入]

核心循环：Agent Loop 驱动 prompt → LLM stream → toolCall 检测 → 工具执行 → 结果回注 → 再次调用 LLM，直到 stopReason 终止。

二、子模块详细分析

2.1 Gateway Core — 网关核心

核心作用：OpenClaw 的中枢神经系统，处理HTTP/WS连接、消息路由、会话生命周期、认证授权、插件调度和定时任务。

关键模块：

模块	文件	核心作用	关键函数/类
GatewayServer	server.impl.ts	HTTP/WS服务器主类	`startGatewayServer()`, 生命周期管理
启动流程	server-startup.ts	启动序列：配置→认证→插件→路由	`startup()`阶段化初始化
运行时配置	server-runtime-config.ts	热重载配置，无需重启	`reloadConfig()`, runtime overrides
插件引导	server-startup-plugins.ts	插件加载后激活	`bootstrapPlugins()`
聊天处理	server-chat.ts	消息入站→Agent分发→回复投递	`handleChat()`, 流式回复
会话管理	session-utils.ts	JSONL持久化，历史查询	`loadSession()`,`addEntry()`
会话归档	session-archive.ts	导入/导出/压缩	`archiveSession()`,`importSession()`
认证	auth.ts	Token验证、设备认证、API Key	`validateAuth()`,`resolveCredentials()`
角色策略	role-policy.ts	RBAC权限执行	`checkPermission()`, scope验证
速率限制	auth-rate-limit.ts	每方法限流	`checkRateLimit()`, 滑动窗口
设备认证	device-auth.ts	移动端/Node配对与授权	`pairDevice()`,`validateDeviceToken()`
节点注册	node-registry.ts	连接节点追踪与能力查询	`registerNode()`,`getNodeCapabilities()`
插件服务	server-plugins.ts	插件生命周期、激活、运行时	`activatePlugin()`,`reloadPlugin()`
Cron调度	server-cron.ts	定时任务调度与执行	`scheduleCron()`,`fireJob()`
执行审批	exec-approval-manager.ts	命令审批流程	`requestApproval()`,`respondToApproval()`
配置重载	config-reload.ts	热配置变更与路由更新	`reload()`, diff plan
健康监控	channel-health-monitor.ts	通道连通性与健康检查	`checkHealth()`, alerting
模型目录	server-model-catalog.ts	可用模型索引	`getModelCatalog()`, filter by provider
挂钩映射	hooks-mapping.ts	Gateway hook 绑定	`mapHooks()`, lifecycle→handler
MCP HTTP	mcp-http.ts	MCP协议HTTP端点	`handleMcpRequest()`
OpenAI兼容	openai-http.ts	OpenAI API兼容层	`/v1/chat/completions`endpoint
Open Responses	openresponses-http.ts	OpenAI Responses API	`/v1/responses`endpoint

数据流：WebSocket连接 → 消息反序列化 → 认证检查 → Session解析 → Channel绑定 → Agent分发 → 流式回复 → Session持久化

2.2 Channel Plugins — 通道插件系统

核心作用：统一70+个消息平台的适配层，处理消息收发、会话绑定、触发检测、状态反应和流式回复。

关键模块：

模块	文件	核心作用	关键函数/类
通道注册	registry.ts	插件注册与查找	`registerChannel()`,`getChannel()`
通道配置	channel-config.ts	每通道配置验证与默认值	`validateConfig()`,`applyDefaults()`
目录扫描	bundled-channel-catalog-read.ts	内置通道元数据扫描	`scanCatalog()`,`readMetadata()`
配置验证	channel-validation.ts	Schema验证	`validateChannelConfig()`
会话绑定	session.ts	通道→会话绑定、线程追踪	`resolveSession()`, thread binding
对话绑定	conversation-binding.ts	DM/群/话题路由	`bindConversation()`,`resolveTarget()`
线程策略	thread-bindings-policy.ts	线程所有权与绑定规则	`enforcePolicy()`, ownership check
消息信封	session-envelope.ts	消息信封构建	`buildEnvelope()`, metadata attach
允许来源	allow-from.ts	发送者白名单/黑名单	`checkAllowFrom()`,`isAllowed()`
提及门控	mention-gating.ts	@提及/关键词触发	`shouldRespond()`,`matchMention()`
去抖策略	inbound-debounce-policy.ts	消息去重与节流	`debounce()`,`isDuplicate()`
运行状态机	run-state-machine.ts	通道运行状态转换	`transition()`, idle→running→done
状态反应	status-reactions.ts	Emoji反应生命周期	`addReaction()`,`removeReaction()`
打字指示	typing-lifecycle.ts	typing start/stop管理	`startTyping()`,`stopTyping()`
回复前缀	reply-prefix.ts	通道特定回复格式	`formatReply()`, channel prefix
草稿流控	draft-stream-controls.ts	流式回复分块与节流	`chunk()`,`throttle()`

已支持的通道（70+）：Slack、Discord、Telegram、WhatsApp、Feishu、Signal、iMessage、IRC、Matrix、MS Teams、Google Chat、LINE、QQ Bot、Nostr、Nextcloud Talk、Synology Chat、Zalo、BlueBubbles、Twitch等。

2.3 Agent Engine — Agent引擎

核心作用：OpenClaw的"大脑"，驱动LLM调用循环、工具执行、上下文管理、模型选择、子Agent调度和技能执行。

关键模块：

模块	文件	核心作用	关键函数/类
Agent循环	pi-embedded-runner.ts	主Agent循环：prompt→LLM→tool→reply	`runEmbeddedPiSession()`
流订阅	pi-embedded-subscribe.ts	流事件处理，block reply，压缩	`subscribeEmbeddedPiSession()`
上下文管理	context.ts	上下文窗口管理，消息裁剪	`loadContext()`,`pruneHistory()`
系统提示	system-prompt.ts	动态系统提示组合	`buildSystemPrompt()`, skill injection
模型配置	models-config.ts	Provider/model配置加载与合并	`loadModelsConfig()`,`mergeProviders()`
模型目录	model-catalog.ts	模型发现与能力索引	`discoverModels()`,`getModelCapabilities()`
模型选择	model-selection.ts	模型解析（别名/允许列表/覆盖）	`resolveModel()`,`selectModel()`
认证轮换	model-auth.ts	Auth Profile轮换，故障转移，冷却	`rotateAuthProfile()`,`cooldown()`
故障转移	model-fallback.ts	Provider故障转移与重试	`tryNextProvider()`,`handleError()`
工具注册	openclaw-tools.ts	内置工具（read/write/edit/bash…）	`registerTools()`, tool definitions
Bash执行	bash-tools.ts	Shell命令执行，PTY，审批流	`execCommand()`,`requestApproval()`
工具策略	tool-policy.ts	工具允许/拒绝策略	`isToolAllowed()`, allowlist enforcement
工具目录	tool-catalog.ts	可用工具枚举	`listTools()`,`getToolSchema()`
子Agent注册	subagent-registry.ts	子Agent生命周期与状态追踪	`spawn()`,`steer()`,`kill()`,`list()`
上下文压缩	compaction.ts	上下文溢出→摘要压缩	`compact()`,`shouldCompact()`,`summarize()`
技能引擎	skills.ts	Markdown技能加载与提示注入	`loadSkills()`,`buildSkillsPrompt()`
工作空间	workspace.ts	工作空间引导，文件模板	`bootstrapWorkspace()`, template init

Agent Loop 详细流程：

buildSystemPrompt()— 组合identity + skills + tools + bootstrap
loadContext()— SessionManager加载历史消息
resolveModel()— 按优先级选择provider+model
stream()— 调用LLM provider流式API
检测toolCall→resolveTool()→execTool()→ 结果回注
shouldCompact()— 上下文溢出时触发压缩
重复3-6直到stopReason终止
saveSession()— 持久化到JSONL

2.4 Plugin System — 插件系统

核心作用：OpenClaw的扩展骨架，支持Provider注册、通道集成、Hook绑定、内存提供者和交互绑定的统一插件框架。

关键模块：

模块	文件	核心作用	关键函数/类
插件加载	loader.ts	扫描、解析manifest、加载代码	`loadPlugin()`,`scanPlugins()`
插件注册	registry.ts	注册、状态管理、激活	`register()`,`activate()`,`deactivate()`
运行时	runtime.ts	插件运行时边界，沙箱执行	`runInBoundary()`, error isolation
安装/卸载	install.ts / uninstall.ts	npm/路径安装与清理	`installPlugin()`,`uninstallPlugin()`
Provider运行时	provider-runtime.ts	Provider激活、模型注册、stream()	`activateProvider()`,`registerModels()`
Provider发现	provider-discovery.ts	从Provider API自动发现模型	`discoverModels()`
Provider认证	provider-auth-choice.ts	API Key/OAuth认证选择	`selectAuthMode()`,`configureAuth()`
Provider目录	provider-catalog.ts	Provider元数据、能力、默认值	`getProviderInfo()`, capabilities
Hook系统	hooks.ts	生命周期钩子：beforeAgentStart等	`fireHook()`, hook registry
Hook调度	hook-runner-global.ts	Hook调度与错误隔离	`runHook()`, error boundary
预绑定Hook	wired-hooks-*.ts	核心流程预绑定Hook	message/reply/tool/session hooks
对话绑定	conversation-binding.ts	通道↔插件对话绑定	`bindConversation()`, routing
通道运行时	bundled-channel-runtime.ts	内置通道插件激活	`activateBundledChannel()`
内存运行时	memory-runtime.ts	内存Provider（嵌入/搜索/存储）	`activateMemory()`, embedding
嵌入Provider	memory-embedding-provider-runtime.ts	嵌入模型集成	`computeEmbedding()`
交互绑定	interactive-binding-helpers.ts	交互CLI↔插件绑定	`bindInteractive()`

插件生命周期：

scanPlugins()— 扫描extensions/目录和node_modules
loadPlugin()— 解析manifest.json5，加载代码模块
register()— 注册到Registry，记录capabilities
activate()— 按依赖顺序激活，注册Provider/Channel/Hook
fireHook()— 在对应生命周期触发Hook回调
deactivate()/uninstall()— 清理与卸载

2.5 Config & Schema — 配置与Schema

核心作用：OpenClaw的配置中枢，使用Zod Schema定义和验证所有配置项（agents、channels、providers、plugins、hooks、secrets），支持热重载和环境变量替换。

关键模块：

模块	文件	核心作用	关键函数/类
配置IO	io.ts	配置文件读写、验证、备份	`readConfig()`,`writeConfig()`,`validate()`
变更审计	io.audit.ts	配置变更审计轨迹	`auditChange()`, diff log
原子写入	io.write-prepare.ts	带备份轮换的原子写入	`prepareWrite()`, backup rotation
主配置	config.ts	配置对象：agents/channels/providers/plugins	`loadConfig()`,`resolveConfig()`
根Schema	schema.ts	Zod根Schema定义	`ConfigSchema`, nested schemas
Provider Schema	zod-schema.providers.ts	22+ Provider配置Schema	`ProviderSchema`, per-provider validation
Channel Schema	zod-schema.channels.ts	通道配置Schema	`ChannelSchema`, Slack/Discord/TG…
Agent Schema	zod-schema.agents.ts	Agent配置Schema	`AgentSchema`, model/tools/sandbox
Hook Schema	zod-schema.hooks.ts	Hook配置Schema	`HookSchema`, lifecycle bindings
运行时Schema	runtime-schema.ts	运行时验证的配置快照	`validateRuntime()`, snapshot
运行时覆盖	runtime-overrides.ts	热重载覆盖无需重启	`applyOverrides()`, diff merge
运行时快照	runtime-snapshot.ts	不可变配置快照	`createSnapshot()`, immutability
配置具化	materialize.ts	配置解析：默认值→Schema→运行时	`materializeConfig()`, layered resolution
Secret解析	secrets/resolve.ts	Secret解析：env/file/inline	`resolveSecret()`, secret ref
环境替换	env-substitution.ts	${VAR}变量替换	`substitute()`, env var interpolation
Secret脱敏	redact-snapshot.ts	日志/显示用Secret脱敏	`redact()`, mask sensitive values

配置层级：

Defaults (code) → Schema (Zod) → Config File (JSON) → Runtime Overrides (hot) → Env Vars

2.6 CLI & Commands — 命令行接口

核心作用：用户与OpenClaw交互的主要入口，基于Commander.js实现的CLI，提供gateway/daemon/config/models/plugins/sessions/doctor等30+子命令。

关键模块：

模块	文件	核心作用	关键函数/类
根程序	program.ts	Commander.js根程序，子命令注册	`createProgram()`, subcommand dispatch
参数解析	argv.ts	Argv解析，全局选项转发	`parseArgv()`, option forwarding
主入口	run-main.ts	入口分发：daemon/gateway/agent	`runMain()`, mode selection
命令引导	command-bootstrap.ts	插件命令注册	`registerPluginCommands()`
Gateway命令	gateway-cli.ts	openclaw gateway start/stop/restart	`startGateway()`,`stopGateway()`
Daemon命令	daemon-cli.ts	openclaw daemon install/uninstall/status	`installDaemon()`, cross-platform
Config命令	config-cli.ts	openclaw config set/get/edit	`setConfig()`,`getConfig()`
Models命令	models-cli.ts	openclaw models list/set	`listModels()`,`setModel()`
Plugins命令	plugins-cli.ts	openclaw plugins install/list/update	`installPlugin()`,`updatePlugin()`
Agent命令	agent-command.ts	openclaw agent 交互	`runAgent()`, interactive session
Sessions命令	sessions.ts (commands)	openclaw sessions list/kill/clean	`listSessions()`,`killSession()`
Channels命令	channels-cli.ts	openclaw channels add/remove/status	`addChannel()`,`removeChannel()`
Skills命令	skills-cli.ts	openclaw skills install/list	`installSkill()`,`listSkills()`
Doctor命令	doctor.ts	openclaw doctor 综合健康检查	`runDoctor()`, diagnostics + repair
Status命令	status.ts (commands)	openclaw status 系统概览	`showStatus()`, comprehensive view
Security命令	security-cli.ts	openclaw security audit	`auditSecurity()`
Secrets命令	secrets-cli.ts	openclaw secrets configure	`configureSecrets()`

2.7 Security & Infrastructure — 安全与基础设施

核心作用：系统级安全保障和运行时基础设施，包括安全审计、命令审批、Daemon管理、进程控制和Node/设备配对。

关键模块：

模块	文件	核心作用	关键函数/类
安全审计	audit.ts	全量配置+运行时安全审计	`runAudit()`, comprehensive scan
Gateway审计	audit-gateway.ts	网关暴露与认证审计	`auditGatewayExposure()`
通道审计	audit-channel.ts	通道白名单/命令安全审计	`auditChannelSecurity()`
执行面审计	audit-exec-surface.ts	命令攻击面分析	`auditExecSurface()`
插件代码审计	audit-plugin-code-safety.ts	插件代码静态分析	`scanPluginCode()`
自动修复	fix.ts	自动修复安全问题	`fixIssues()`, auto-remediation
审批存储	exec-approvals.ts	审批存储、白名单、信任级别	`requestApproval()`,`isAutoApproved()`
安全二进制	exec-safe-bin-policy.ts	安全二进制白名单	`isSafeBin()`, whitelist enforcement
审批处理	approval-handler-runtime.ts	审批请求→通道投递	`handleApproval()`, delivery
审批绑定	system-run-approval-binding.ts	Gateway↔Agent审批绑定	`bindApproval()`, gateway routing
Daemon服务	service.ts	跨平台Daemon：systemd/launchd/schtasks	`install()`,`start()`,`stop()`
优雅重启	restart.ts	Sentinel/deferral保护重启	`restart()`, graceful drain
进程清理	process/kill-tree.ts	关闭时进程树清理	`killTree()`, signal propagation
网关进程	gateway-processes.ts	Gateway进程管理	`spawnGateway()`, health monitoring
Node调用	node-host/invoke.ts	Node命令执行（沙箱化）	`invokeCommand()`, sandboxed exec
配对存储	pairing-store.ts	设备配对状态持久化	`storePairing()`,`loadPairing()`
设备认证	device-auth-store.ts	设备Token管理	`registerDevice()`,`rotateToken()`
Node配对	node-pairing.ts	QR/Setup Code配对流程	`startPairing()`, QR generation

三、模块调用关系与数据流

3.1 核心依赖关系

CLI/TUI (L1) → Channel Plugins (L2) → Gateway Core (L3) → Agent Engine (L4) → Providers (L5) ↕ ↕ Plugin System Tool System / Subagent ↕ ↕ Config/Schema Skills / Workspace ↕ Security / Daemon (L6)

具体调用链：

调用方	被调用方	调用方式
CLI (L1)	Gateway Core (L3)	HTTP/WS连接
Channel Plugin (L2)	Gateway Core (L3)	Plugin API接口
Gateway Core (L3)	Agent Engine (L4)	函数调用（pi-embedded-runner）
Gateway Core (L3)	Plugin System	registry/runtime API
Gateway Core (L3)	Config/Schema	loadConfig(), runtime-snapshot
Agent Engine (L4)	Provider Plugins (L5)	provider.stream()
Agent Engine (L4)	Tool System	tool execution dispatch
Agent Engine (L4)	Subagent Registry	spawn/steer/kill
Plugin System	Config/Schema	manifest validation
Security (L6)	Gateway/Auth	audit scan

3.2 核心请求链路

链路1：Slack消息处理

SlackBot.onMessage() → Channel Plugin (allow-from, mention-gating) → GatewayServer.handleChat() → Auth.checkPermission() → SessionManager.resolveSession() → PluginHooks.fire("beforeAgentStart") → AgentRunner.runEmbeddedPiSession() → buildSystemPrompt() (identity + skills + tools) → ModelConfig.resolveModel() → Provider.stream() → ToolDispatch (toolCall → exec → result) → Compaction (if overflow) → SessionManager.persist() → Channel Plugin.sendReply() → SlackBot.postMessage()

链路2：CLI交互

openclaw gateway start → Daemon.install() / GatewayServer.start() → WebSocket connection from TUI/CLI → TUI.submitMessage() → GatewayServer.handleChat() → (同链路1的Agent流程)

链路3：Web UI交互

Web UI (React/Lit) → HTTP/WS to GatewayServer → Control UI (config/status management) → Chat → handleChat() → (同链路1)

链路4：Cron定时任务

CronService.fireJob() → SessionResolver.resolveTarget() → AgentRunner.runEmbeddedPiSession() → DeliveryPlan.execute() → Channel Plugin.deliver()

3.3 关键数据传递

数据	来源	目标	传递方式
InboundMessage	Channel Plugin	GatewayServer	Plugin API callback
SessionKey	GatewayServer	SessionManager	字符串键（agent+channel+target）
AuthToken	客户端/设备	Auth模块	HTTP header / WS handshake
AgentContext	AgentRunner	LLM Provider	函数参数（messages+tools+model）
ToolCall	LLM响应	ToolDispatch	content block解析
ToolResult	Tool执行器	Agent上下文	消息追加
AgentEvent	Agent Loop	GatewayServer	EventStream订阅
ReplyChunk	Agent	Channel Plugin	Draft stream分块
ConfigSnapshot	Config	Gateway/Agent	runtime-snapshot对象
ApprovalRequest	Agent	Gateway	审批通道投递
SubagentSpawn	Agent	SubagentRegistry	spawn()调用

3.4 状态管理

会话状态：SessionManager 维护每会话JSONL文件，支持：

历史消息查询与窗口裁剪
上下文压缩（compaction）防止溢出
会话归档与导入
分支对话（branching）
子Agent会话隔离

配置状态：

不可变快照（runtime-snapshot）保证一致性
热重载覆盖（runtime-overrides）无需重启
变更审计（io.audit）追踪所有修改
备份轮换（backup-rotation）防止丢失

认证状态：

Auth Profile轮换与冷却机制
设备Token自动轮换
API Key来源优先级（config > env > store）

安全状态：

Exec审批白名单与信任级别
通道Allow-from策略
工具Allow/Deny策略

四、架构特点总结

4.1 设计优势

极致插件化：70+通道 + 22+Provider + 50+技能均为独立插件，新增通道/Provider只需创建扩展目录
六层清晰分层：从客户端到基础设施，每层职责明确，依赖方向单一
多通道统一：一套Agent核心服务所有通道，消息格式统一转换
热重载设计：配置/插件/模型均支持运行时更新，无需重启
安全纵深防御：Auth→RBAC→Allow-from→Tool Policy→Exec Approval→Security Audit 六层安全
子Agent编排：支持嵌套spawn、深度限制、模型隔离、生命周期管理
多Provider故障转移：Auth Profile轮换 + Provider failover + cooldown机制

4.2 架构模式

模式	应用位置
插件式架构	通道、Provider、技能、Hook全部插件化
分层架构	L1-L6六层，单向依赖
网关模式	GatewayServer作为中心路由器
观察者模式	Hook系统（lifecycle hooks）
策略模式	Auth/Tool/Exec策略可插拔
命令模式	CLI子命令统一注册与分发
事件驱动	AgentEvent, SessionEvent, HookEvent
工厂模式	createDefaultDeps, plugin activation
快照模式	Config runtime-snapshot不可变

4.3 规模指标

指标	数值
源文件数	7,500+
通道插件数	70+
Provider插件数	22+
CLI子命令数	30+
内置工具数	15+
测试文件数	2,000+
配置Schema项	500+
安全审计检查项	50+

4.4 技术债务与改进方向

Gateway Server 单体：server.impl.ts 超过数千行，建议拆分为独立的微服务（Chat Service、Auth Service、Plugin Service）
Agent模块膨胀：agents/目录文件过多（200+），pi-embedded-* 系列可提取为独立包
配置Schema耦合：所有Provider Schema在一个文件中，新增Provider需修改核心代码
测试覆盖不均：gateway和agents有大量测试，但部分通道插件测试较少
TypeScript编译性能：6624+文件的增量编译较慢，建议项目分区编译

查看全文

http://www.jsqmd.com/news/670776/