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

OpenClaw：基于Gateway与AI Agent的智能助手架构解析

news 2026/7/24 6:21:35

1. OpenClaw项目概述

OpenClaw是一个通过Gateway连接即时通讯平台与本地AI Agent的个人助手系统。它不仅仅是一个简单的消息转发器，而是具备完整会话管理、并发控制、记忆检索以及丰富工具支持的复杂Agent运行时环境。这个系统能够24×7持续运行，为用户提供智能化的交互体验。

从技术架构来看，OpenClaw采用了模块化设计，主要包括以下几个核心组件：

  • Gateway：作为系统的控制平面，负责与各种消息渠道建立长连接
  • Agent：执行核心智能处理功能
  • Skills：提供各种专业能力的扩展模块
  • Memory：实现短期和长期记忆管理

2. OpenClaw四大核心架构解析

2.1 Gateway架构设计

Gateway是OpenClaw系统的入口和控制中心，主要负责以下功能：

  1. 消息接入与分发：

    • 通过WebSocket与各类即时通讯平台(如Telegram、Slack等)建立连接
    • 接收用户消息并路由到相应的Agent处理
    • 将Agent的回复消息发送回原始渠道

  2. 会话状态管理：

    • 维护所有活跃会话的状态信息
    • 处理会话的生命周期(创建、维护、销毁)

  3. 定时任务调度：

    • 执行系统级的定时任务
    • 处理会话超时等事件

Gateway的核心实现是一个HTTP和WebSocket服务，启动时会加载配置并与注册的Channel建立连接。以下是简化的Gateway启动流程代码示例：

export async function startGatewayServer(port=18789, opts:GatewayServerOptions={}): Promise<GatewayServer> { // 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框架构建，但进行了深度定制。其主要特点包括：

  1. 会话管理：

    • 使用SessionKey机制唯一标识和路由会话
    • 支持私聊、群组等多种会话形式
    • 自动管理会话生命周期(每日重置、空闲归档等)

  2. 并发控制：

    • 会话级别并发控制(同一会话串行处理)
    • 全局并发控制(默认并发度4)
    • 多种队列模式处理消息竞争

  3. 故障转移机制：

    • Auth Profile轮换(当API Key遇到速率限制时自动切换)
    • 上下文溢出自动压缩
    • 思考级别降级(当模型不支持扩展思考模式时自动降级)

Agent的核心执行流程采用ReAct范式，支持工具调用和流式输出。以下是简化的Agent执行循环代码：

export async function runEmbeddedPiAgent(params: RunEmbeddedPiAgentParams): Promise<EmbeddedPiRunResult> { // 会话级别并发控制 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的记忆系统是其长期保持上下文连贯性的关键，主要包括以下组件：

  1. 记忆存储：

    • 全局长期记忆(MEMORY.md或memory.md)
    • 目录记忆(memory/*.md)
    • 额外路径配置(memorySearch.extraPaths)

  2. 记忆检索：

    • 关键词精确搜索
    • 向量语义检索
    • 混合检索策略(加权得分)

  3. 索引管理：

    • 文件分块处理
    • 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; }): Promise<MemorySearchResult[]> { // 关键词搜索 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提供了丰富的工具技能，主要包括以下几类：

  1. 核心工具：

    • 文件系统访问
    • Shell命令执行
    • webSearch工具

  2. 自感知能力：

    • 获取Gateway状态
    • 获取Session状态

  3. 插件工具：

    • bird(Twitter/X相关功能)
    • message(富消息交互)
    • browser(网页浏览)
    • 天气查询等

Skills从三个位置加载：

  1. 内置Skills(随安装包发布)
  2. 托管/本地Skills(~/.openclaw/skills)
  3. 工作区Skills( /skills)

OpenClaw支持灵活的工具策略配置，可以在多个层级进行定制：

  1. 全局策略(config.tools)
  2. 全局按提供商策略(config.tools.byProvider[providerOrModelId])
  3. Agent策略(config.agents.[agentId].tools)
  4. Agent按提供商策略(config.agents.[agentId].tools.byProvider[providerOrModelId])
  5. 群组策略(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:main
  • Telegram私聊:agent:main:telegram:default:dm:123456789
  • Telegram群组: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系统来处理消息竞争问题，支持多种队列模式：

  1. collect收集模式(默认)：

    • 将所有排队的消息合并成单个后续回复
    • 示例格式：
      [Queued messages while agent was busy] --- Queued #1 [Slack x +1s 2026-02-09 16:58 GMT+8] 算了 [slack message id: x channel: x] [message_id: x] --- Queued #2 [Slack x +4s 2026-02-09 16:58 GMT+8] 查一下天津的 [slack message id: x channel: x] [message_id: x]

  2. steer转向模式：

    • 立即注入到当前agent回合中
    • 使用pi-agent的steer能力在Agent loop中插入消息

  3. followup跟进模式：

    • 当前运行结束后，为下一个agent回合排队

  4. steer-backlog转向+积压模式：

    • 现在转向当前回合，然后保留消息用于后续回合

并发控制采用两层结构：

  1. 会话级别：同一会话内的消息串行处理
  2. 全局级别：默认并发度为4，允许最多4个会话同时处理

3.3 混合检索技术

OpenClaw的记忆检索采用混合检索方案，结合了：

  1. 关键词精确搜索
  2. 向量语义检索

对候选结果计算加权得分，返回最相关的几条。基于本地个人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支持丰富的技能扩展方式：

  1. 内置Skills：

    • 随安装包一起发布
    • 如bird、github等常用技能

  2. 托管/本地Skills：

    • 存储在~/.openclaw/skills目录
    • 可通过clawhub命令安装

  3. 工作区Skills：

    • 存储在 /skills目录
    • 支持快速开发和测试新技能

安装Skills的示例命令：

# 技能安装，以artifacts-builder为例 npm i -g clawhub clawhub install artifacts-builder # 插件安装 openclaw plugins list openclaw plugins install @openclaw/voice-call

4. OpenClaw架构设计思考

OpenClaw的架构设计体现了几个关键思想：

  1. 可靠性优先：

    • 完善的故障转移机制
    • 上下文溢出自动处理
    • 认证配置自动轮换

  2. 扩展性设计：

    • 模块化的工具技能系统
    • 多层次的配置策略
    • 支持自定义技能开发

  3. 性能考量：

    • 精细的并发控制
    • 混合检索策略
    • 本地化存储设计

  4. 用户体验：

    • 丰富的交互能力
    • 连贯的会话体验
    • 个性化的记忆系统

从技术实现来看，OpenClaw虽然基于现有的Pi-Agent框架，但通过精心的定制和扩展，打造了一个完成度极高的本地个人助手系统。其架构设计中的许多思路，特别是可靠性保障和扩展性设计，值得开发者深入研究和借鉴。

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

相关文章：

  • Google Flash模型工具：数学公式转3D打印的完整实践指南
  • MSP430 LCD_B寄存器配置与EEM高级调试实战指南
  • 劳力士中国售后服务中心｜完整热线和最新维修地址权威信息公告（2026年7月最新） - 劳力士服务中心
  • BQ41Z50高级充电算法：从参数配置到电池寿命优化的工程实践
  • 2026上海宝山区装修公司口碑评级榜 入住业主真实评价汇总表 - 资讯报道
  • 低代码IDE与生成式AI结合加速企业级AI代理开发
  • TVMSTofu视频管理平台：多光谱智能监控与AI分析实践
  • 声明：天津劳力士售后网点地址与客服电话2026年7月最新版本 - 劳力士官方服务中心
  • 原生鸿蒙像素画板实战 20：拼豆模板生成
  • Grok 4.5与Outlook集成：AI智能邮件管理与自动化实战指南
  • 外贸成交32 | 客户说要“便宜的”，其实他没说出真正想要的 - 外贸圈集团
  • 2026天津CPPM认证机构怎么选？4个核心维度帮你避坑 - 企智芯
  • YOLO11训练中NaN Loss与梯度爆炸的解决方案
  • 2026 上海宝山区环保装修公司推荐｜低甲醛材料即装即住家装排行榜 - 资讯报道
  • 深入理解C++ std::bind：从核心机制到实战应用
  • 2026年GEO监测平台：AI驱动的地理空间分析技术解析
  • 2026年7月最新卡地亚南昌万象城维修保养服务电话 - 卡地亚官方售后中心
  • AI辅助写作：智能改写工具的核心技术与应用
  • BQ41Z50电池管理芯片：智能充电算法与工程配置实战
  • BQ4050数据闪存深度解析：从架构到实战的BMS配置指南
  • 2026年7月国产口碑优选卤料包品牌推荐，商用卤料包/卤味调料包/周黑鸭调料包/卤料包/调料包，卤料包品牌推荐 - 品牌推荐师
  • Python实战全同态加密：构建隐私计算黑箱系统
  • 思维链技术：提升大模型逻辑推理能力的关键方法
  • C++计算器项目实践：从双操作数到表达式解析的编程进阶
  • CIMPro本地加载3D Tiles：数字孪生项目性能优化实战指南
  • 安徽结晶麦芽糖选购指南：兴宙医药以“3大核心优势+5项技术突破”破解行业痛点，葡萄糖酸内酯/麦芽糖，麦芽糖生产厂家推荐 - 品牌推荐师
  • 2026年最新教程：照片怎么转成PNG格式 亲测可用的免费方法 - 图片处理研究员
  • 油轮导流罩供应商选型核心指标与验证方法 - 行业深度分析
  • Domain 1 背诵
  • AI同义替换技术：高效解决写作降重难题