OpenClaw：基于Gateway与AI Agent的智能助手架构解析 1. OpenClaw项目概述OpenClaw是一个通过Gateway连接即时通讯平台与本地AI Agent的个人助手系统。它不仅仅是一个简单的消息转发器而是具备完整会话管理、并发控制、记忆检索以及丰富工具支持的复杂Agent运行时环境。这个系统能够24×7持续运行为用户提供智能化的交互体验。从技术架构来看OpenClaw采用了模块化设计主要包括以下几个核心组件Gateway作为系统的控制平面负责与各种消息渠道建立长连接Agent执行核心智能处理功能Skills提供各种专业能力的扩展模块Memory实现短期和长期记忆管理2. OpenClaw四大核心架构解析2.1 Gateway架构设计Gateway是OpenClaw系统的入口和控制中心主要负责以下功能消息接入与分发通过WebSocket与各类即时通讯平台(如Telegram、Slack等)建立连接接收用户消息并路由到相应的Agent处理将Agent的回复消息发送回原始渠道会话状态管理维护所有活跃会话的状态信息处理会话的生命周期(创建、维护、销毁)定时任务调度执行系统级的定时任务处理会话超时等事件Gateway的核心实现是一个HTTP和WebSocket服务启动时会加载配置并与注册的Channel建立连接。以下是简化的Gateway启动流程代码示例export async function startGatewayServer(port18789, opts:GatewayServerOptions{}): PromiseGatewayServer { // 1. 设置端口环境变量 process.env.OPENCLAW_GATEWAY_PORT String(port); // 2. 加载并验证配置 let configSnapshot await readConfigFileSnapshot(); // 3. 创建WebSocket服务器 const wsServer new WebSocket.Server({port, host}); // 4. 注册核心处理器 const channelManager createChannelManager(configSnapshot.config); const agentEventHandler createAgentEventHandler(configSnapshot.config); const cronService buildGatewayCronService(configSnapshot.config); // 5. 启动通道连接 await channelManager.startAll(); // 6. 返回close方法用于优雅关闭 return { close: (opts) shutdownGateway(opts), }; }Gateway通过系统服务管理保持24×7运行在macOS上使用launchctl在Linux上使用systemctl进行管理。2.2 Agent核心架构Agent是OpenClaw系统的智能处理核心基于开源的Pi-Agent框架构建但进行了深度定制。其主要特点包括会话管理使用SessionKey机制唯一标识和路由会话支持私聊、群组等多种会话形式自动管理会话生命周期(每日重置、空闲归档等)并发控制会话级别并发控制(同一会话串行处理)全局并发控制(默认并发度4)多种队列模式处理消息竞争故障转移机制Auth Profile轮换(当API Key遇到速率限制时自动切换)上下文溢出自动压缩思考级别降级(当模型不支持扩展思考模式时自动降级)Agent的核心执行流程采用ReAct范式支持工具调用和流式输出。以下是简化的Agent执行循环代码export async function runEmbeddedPiAgent(params: RunEmbeddedPiAgentParams): PromiseEmbeddedPiRunResult { // 会话级别并发控制 const sessionLane resolveSessionLane(params.sessionKey?.trim() || params.sessionId); // 全局并发控制 const globalLane resolveGlobalLane(params.lane); return enqueueSession(() enqueueGlobal(async () { const started Date.now(); // 模型解析和上下文窗口验证 const {model, error, authStorage, modelRegistry} resolveModel(provider, modelId, agentDir, params.config); // 认证配置管理和故障转移 const profileOrder resolveAuthProfileOrder({ cfg: params.config, store: authStore, provider, preferredProfile: preferredProfileId, }); // 主执行循环支持故障转移 while (true) { const attempt await runEmbeddedAttempt({ sessionId: params.sessionId, sessionKey: params.sessionKey, // ... 大量参数 }); // 处理上下文溢出自动压缩 if (isContextOverflowError(errorText)) { const compactResult await compactEmbeddedPiSessionDirect({ sessionId: params.sessionId, sessionKey: params.sessionKey, // ... }); if (compactResult.compacted) continue; } // 处理认证/速率限制故障转移 if (shouldRotate) { const rotated await advanceAuthProfile(); if (rotated) continue; } return { payloads: payloads.length ? payloads : undefined, meta: { durationMs: Date.now() - started, // ... }, }; } })); }2.3 Memory记忆系统OpenClaw的记忆系统是其长期保持上下文连贯性的关键主要包括以下组件记忆存储全局长期记忆(MEMORY.md或memory.md)目录记忆(memory/*.md)额外路径配置(memorySearch.extraPaths)记忆检索关键词精确搜索向量语义检索混合检索策略(加权得分)索引管理文件分块处理Embedding计算和缓存本地数据库写入记忆系统使用Sqlite作为存储后端支持高效的混合检索。以下是记忆检索工具的示例实现export function createMemorySearchTool(options: { config?: OpenClawConfig; agentSessionKey?: string; }): AnyAgentTool | null { return { label: Memory Search, name: memory_search, description: Mandatory recall step: semantically search MEMORY.md memory/*.md (and optional session transcripts) before answering questions about prior work, decisions, dates, people, preferences, or todos; returns top snippets with path lines., parameters: MemorySearchSchema, execute: async (_toolCallId, params) { const query readStringParam(params, query, {required: true}); const maxResults readNumberParam(params, maxResults); const minScore readNumberParam(params, minScore); const {manager, error} await getMemorySearchManager({cfg, agentId}); if (!manager) { return jsonResult({results: [], disabled: true, error}); } const results await manager.search(query, { maxResults, minScore, sessionKey: options.agentSessionKey, }); return jsonResult({results, provider: status.provider, model: status.model}); }, }; }记忆管理器执行混合检索的核心逻辑如下export class MemoryIndexManager { async search(query: string, opts?: { maxResults?: number; minScore?: number; sessionKey?: string; }): PromiseMemorySearchResult[] { // 关键词搜索 const keywordResults hybrid.enabled ? await this.searchKeyword(cleaned, candidates).catch(() []) : []; // 向量搜索 const queryVec await this.embedQueryWithTimeout(cleaned); const vectorResults hasVector ? await this.searchVector(queryVec, candidates).catch(() []) : []; // 合并结果 if (!hybrid.enabled) { return vectorResults .filter((entry) entry.score minScore) .slice(0, maxResults); } const merged this.mergeHybridResults({ vector: vectorResults, keyword: keywordResults, vectorWeight: hybrid.vectorWeight, textWeight: hybrid.textWeight, }); return merged .filter((entry) entry.score minScore) .slice(0, maxResults); } }2.4 Skills工具技能系统OpenClaw提供了丰富的工具技能主要包括以下几类核心工具文件系统访问Shell命令执行webSearch工具自感知能力获取Gateway状态获取Session状态插件工具bird(Twitter/X相关功能)message(富消息交互)browser(网页浏览)天气查询等Skills从三个位置加载内置Skills(随安装包发布)托管/本地Skills(~/.openclaw/skills)工作区Skills( /skills)OpenClaw支持灵活的工具策略配置可以在多个层级进行定制全局策略(config.tools)全局按提供商策略(config.tools.byProvider[providerOrModelId])Agent策略(config.agents.[agentId].tools)Agent按提供商策略(config.agents.[agentId].tools.byProvider[providerOrModelId])群组策略(config.groups.[groupId].tools)message工具是OpenClaw的特色功能之一支持以下高级交互发送多条消息(在最终回复前后发送图片、文件等)富文本与复杂交互(按钮、卡片、投票等)精准引用与回复(回复特定消息ID)以下是message工具调用的JSON示例{ action: send, buttons: [[{\text\:\A. 下午好\, \callback_data\:\n5_quiz_wrong\}, {\text\:\B. 再见\, \callback_data\:\n5_quiz_correct\}], [{\text\:\C. 谢谢\, \callback_data\:\n5_quiz_wrong\}, {\text\:\D. 早上好\, \callback_data\:\n5_quiz_wrong\}]], channel: telegram, message: **日语N5练习题**\n\n**さようなら** 的中文意思是什么, target: 123456 }3. OpenClaw架构设计亮点3.1 会话管理机制OpenClaw的会话管理采用SessionKey机制能够唯一标识各种复杂的会话场景。SessionKey的格式示例如下主会话:agent:main:mainTelegram私聊:agent:main:telegram:default:dm:123456789Telegram群组:agent:main:telegram:group:1001234567890会话数据存储在本地文件系统中路径结构为~/.openclaw/agents/agentId/sessions/ session.json # 记录所有Session的元数据映射 sessionId.jsonl # 存储具体的对话日志(JSON Lines格式)会话生命周期管理包括每日自动生成新的SessionId(通过检测日期变化)默认60分钟无交互后归档当前Session子Agent的Session同样遵循60分钟自动归档策略3.2 队列与并发控制OpenClaw设计了精密的Queue系统来处理消息竞争问题支持多种队列模式collect收集模式(默认)将所有排队的消息合并成单个后续回复示例格式[Queued messages while agent was busy] --- Queued #1 [Slack x 1s 2026-02-09 16:58 GMT8] 算了 [slack message id: x channel: x] [message_id: x] --- Queued #2 [Slack x 4s 2026-02-09 16:58 GMT8] 查一下天津的 [slack message id: x channel: x] [message_id: x]steer转向模式立即注入到当前agent回合中使用pi-agent的steer能力在Agent loop中插入消息followup跟进模式当前运行结束后为下一个agent回合排队steer-backlog转向积压模式现在转向当前回合然后保留消息用于后续回合并发控制采用两层结构会话级别同一会话内的消息串行处理全局级别默认并发度为4允许最多4个会话同时处理3.3 混合检索技术OpenClaw的记忆检索采用混合检索方案结合了关键词精确搜索向量语义检索对候选结果计算加权得分返回最相关的几条。基于本地个人Agent的定位默认使用Sqlite作为数据库存储(agents.sqlite文件)。向量检索使用Sqlite-vec扩展执行KNN搜索示例代码如下// 创建向量表 db.exec(CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[4])); // 插入数据 const insert db.prepare(INSERT INTO vec_items(rowid, embedding) VALUES (?, ?)); const data [ [1, [0.1, 0.1, 0.1, 0.1]], [2, [0.2, 0.2, 0.2, 0.2]] ]; for (const [id, vec] of data) { insert.run(BigInt(id), new Float32Array(vec)); } // KNN搜索 const query new Float32Array([0.15, 0.15, 0.15, 0.15]); const rows db.prepare( SELECT rowid, distance FROM vec_items WHERE embedding MATCH ? ORDER BY distance LIMIT 3 ).all(query);3.4 工具技能扩展性OpenClaw支持丰富的技能扩展方式内置Skills随安装包一起发布如bird、github等常用技能托管/本地Skills存储在~/.openclaw/skills目录可通过clawhub命令安装工作区Skills存储在 /skills目录支持快速开发和测试新技能安装Skills的示例命令# 技能安装以artifacts-builder为例 npm i -g clawhub clawhub install artifacts-builder # 插件安装 openclaw plugins list openclaw plugins install openclaw/voice-call4. OpenClaw架构设计思考OpenClaw的架构设计体现了几个关键思想可靠性优先完善的故障转移机制上下文溢出自动处理认证配置自动轮换扩展性设计模块化的工具技能系统多层次的配置策略支持自定义技能开发性能考量精细的并发控制混合检索策略本地化存储设计用户体验丰富的交互能力连贯的会话体验个性化的记忆系统从技术实现来看OpenClaw虽然基于现有的Pi-Agent框架但通过精心的定制和扩展打造了一个完成度极高的本地个人助手系统。其架构设计中的许多思路特别是可靠性保障和扩展性设计值得开发者深入研究和借鉴。