OpenClaw(小龙虾)架构与实现原理
一、整体架构概览
Section titled “一、整体架构概览”OpenClaw 采用从”模型中心”转向”系统中心”的架构理念,将 Agent 视为一个长期运行的操作系统,而非简单的对话机器人。
六层分层架构
Section titled “六层分层架构”graph TB subgraph "OpenClaw 六层架构" L1["🖥️ 接口层<br/>Web UI · IM 渠道 · CLI · 移动端"] L2["👁️ 感知与理解层<br/>多模态输入 → 标准化感知事件"] L3["🧠 认知与决策层<br/>Planner 任务拆解 · Reasoner 推理决策"] L4["⚙️ 执行与工具层<br/>CLI 命令 · 子进程 · Function Calling"] L5["💾 记忆与状态层<br/>短期/中期/长期记忆 · RAG 检索"] L6["🔐 治理与安全层<br/>Docker 沙箱 · 白名单 · 权限审计"] end
L1 --> L2 L2 --> L3 L3 --> L4 L4 --> L5 L5 --> L6
style L1 fill:#1e3a5f,stroke:#3b82f6,color:#f0f6ff style L2 fill:#1e3a5f,stroke:#06b6d4,color:#f0f6ff style L3 fill:#1e3a5f,stroke:#8b5cf6,color:#f0f6ff style L4 fill:#1e3a5f,stroke:#f59e0b,color:#f0f6ff style L5 fill:#1e3a5f,stroke:#10b981,color:#f0f6ff style L6 fill:#1e3a5f,stroke:#ec4899,color:#f0f6ff| 层级 | 职责 | 关键机制 |
|---|---|---|
| 接口层 | 多端入口抽象(Web UI、IM、CLI) | WebSocket + JSON-RPC |
| 感知与理解层 | 多模态输入 → 标准化感知事件 | 意图识别、上下文建模、去 Prompt 依赖 |
| 认知与决策层 | 任务拆解、路径规划、推理决策 | Planner + Reasoner,支持 Re-plan |
| 执行与工具层 | 工具调用、CLI 命令、子进程执行 | CLI 优先 + 子进程 stdio 管道 |
| 记忆与状态层 | 短/中/长期记忆 + 状态机管理 | RAG 检索 + SQLite + JSONL 持久化 |
| 治理与安全层 | 权限、审计、沙箱隔离 | Docker 沙箱 + 白名单 + 执行审批 |
二、核心组件:Gateway 中心架构
Section titled “二、核心组件:Gateway 中心架构”Gateway 是整个系统的控制平面,相当于”大脑中枢”,负责一切 I/O、会话管理和路由调度。
graph LR subgraph "IM 渠道" T["Telegram"] D["Discord"] S["Slack"] WX["企业微信"] DD["钉钉"] FS["飞书"] WA["WhatsApp"] MS["Teams"] end
subgraph "Gateway 控制平面" GW["⚙️ Gateway<br/>ws://127.0.0.1:18789"] RT["路由引擎<br/>resolveAgentRoute()"] SM["会话管理<br/>SessionKey"] QM["队列管理<br/>并发控制"] CR["定时任务<br/>CronService"] end
subgraph "Agent Runtime" PA["Pi-Agent 框架<br/>ReAct 循环"] ML["模型抽象层<br/>Claude / GPT / Ollama"] end
subgraph "能力触角" SK["Skills 技能系统<br/>5000+ 插件"] ND["Nodes 节点<br/>macOS / iOS / Android"] DC["Docker 沙箱<br/>隔离执行"] MEM["记忆系统<br/>RAG + SQLite"] end
T & D & S & WX & DD & FS & WA & MS --> GW GW --> RT --> SM --> QM GW --> CR QM --> PA --> ML PA --> SK & ND & DC PA --> MEM
style GW fill:#1e3a8f,stroke:#3b82f6,color:#fff,stroke-width:3px style PA fill:#4c1d95,stroke:#8b5cf6,color:#fff style ML fill:#065f46,stroke:#10b981,color:#fffGateway 核心特性
Section titled “Gateway 核心特性”- 通信协议:WebSocket 长连接,使用 TypeBox 定义严格 JSON Schema
- 消息类型:
req(请求)/res(响应)/event(事件推送) - 守护进程:通过
systemctl(Linux)或launchctl(macOS)实现 7×24 运行 - 默认端口:
ws://127.0.0.1:18789
三、消息处理全流程
Section titled “三、消息处理全流程”从用户发送消息到收到 AI 回复的完整链路:
sequenceDiagram participant U as 👤 用户 participant IM as 💬 IM 平台 participant GW as ⚙️ Gateway participant RT as 🔀 路由引擎 participant AG as 🤖 Pi-Agent participant LLM as 🧠 AI 模型 participant TL as 🔧 工具/Skills
U->>IM: 发送消息 IM->>GW: 渠道监听器捕获 GW->>GW: dispatchInboundMessage() GW->>RT: resolveAgentRoute() RT->>RT: 匹配路由规则<br/>生成 SessionKey RT->>AG: 分配 Agent 实例
loop ReAct 循环 AG->>LLM: 构造 Prompt + 调用模型 LLM->>AG: 返回思考结果 / 工具调用指令 opt 需要工具调用 AG->>TL: 执行 Function Calling TL->>AG: 返回执行结果 end end
AG->>GW: 生成最终回复 GW->>GW: deliver.ts 格式化 GW->>IM: 调用渠道 API IM->>U: 回复消息路由优先级(从高到低)
Section titled “路由优先级(从高到低)”graph LR P1["peer<br/>指定用户"] --> P2["peer.parent<br/>父线程继承"] P2 --> P3["guild+roles<br/>服务器角色"] P3 --> P4["guild<br/>服务器"] P4 --> P5["team<br/>团队"] P5 --> P6["account<br/>账户"] P6 --> P7["channel<br/>渠道"] P7 --> P8["default<br/>默认"]
style P1 fill:#dc2626,stroke:#fca5a5,color:#fff style P8 fill:#6b7280,stroke:#9ca3af,color:#fffSessionKey 格式:agent:main:telegram:dm:123456
四、Agent 运行时(Pi-Agent 框架)
Section titled “四、Agent 运行时(Pi-Agent 框架)”ReAct 循环机制
Section titled “ReAct 循环机制”graph TD START["📥 接收用户消息"] --> THINK["🧠 思考<br/>分析意图 + 规划行动"] THINK --> DECIDE{需要工具调用?} DECIDE -->|是| ACTION["⚡ 行动<br/>执行工具 / CLI / API"] ACTION --> OBSERVE["👁️ 观察<br/>收集执行结果"] OBSERVE --> THINK DECIDE -->|否| REPLY["✅ 生成最终回复"] REPLY --> END["📤 返回 Gateway"]
style START fill:#1e3a5f,stroke:#3b82f6,color:#fff style THINK fill:#4c1d95,stroke:#8b5cf6,color:#fff style ACTION fill:#92400e,stroke:#f59e0b,color:#fff style OBSERVE fill:#065f46,stroke:#10b981,color:#fff style REPLY fill:#166534,stroke:#22c55e,color:#fff三层容错机制
Section titled “三层容错机制”| 层级 | 机制 | 说明 |
|---|---|---|
| 第一层 | Auth Profile 轮换 | API Key 限流或失败时自动切换到备用 Key |
| 第二层 | 上下文溢出压缩 | 会话过长时自动摘要压缩历史记录 |
| 第三层 | 思考级别降级 | 模型不支持扩展思考时自动降级处理 |
五、并发控制与队列系统
Section titled “五、并发控制与队列系统”graph TB subgraph "并发控制 — 两层设计" direction TB GL["🌐 全局级别<br/>默认并发度 = 4<br/>限制同时处理的会话数"] SL["💬 会话级别<br/>同一会话内消息串行处理"] end
subgraph "队列模式" direction TB C["📦 collect 收集模式<br/>合并排队消息为单次回复"] S["🔀 steer 转向模式<br/>立即注入当前 Agent 回合"] F["📋 followup 跟进模式<br/>当前回合结束后排队处理"] end
GL --> SL SL --> C & S & F
style GL fill:#1e3a5f,stroke:#3b82f6,color:#fff style SL fill:#1e3a5f,stroke:#06b6d4,color:#fff style C fill:#065f46,stroke:#10b981,color:#fff style S fill:#92400e,stroke:#f59e0b,color:#fff style F fill:#4c1d95,stroke:#8b5cf6,color:#fff六、记忆系统
Section titled “六、记忆系统”采用 RAG(检索增强生成) 范式的混合检索架构:
graph TB subgraph "记忆分层" ST["🕐 短期记忆<br/>当前对话 Context<br/>sessionId.jsonl"] MT["🕑 中期记忆<br/>任务步骤 · 失败原因<br/>session.json"] LT["🕒 长期记忆<br/>用户偏好 · 知识图谱<br/>MEMORY.md"] end
subgraph "检索引擎" KW["🔍 关键词精确搜索"] VS["🧲 向量语义检索"] DB["💾 SQLite 索引存储"] end
subgraph "存储路径" PATH["~/.openclaw/agents/<br/> └── agentId/<br/> └── sessions/<br/> ├── session.json<br/> └── sessionId.jsonl"] end
ST & MT & LT --> KW & VS KW & VS --> DB DB --> PATH
style ST fill:#1e3a5f,stroke:#3b82f6,color:#fff style MT fill:#1e3a5f,stroke:#f59e0b,color:#fff style LT fill:#1e3a5f,stroke:#10b981,color:#fff会话生命周期
Section titled “会话生命周期”- 每日重置:可配置每日自动清理会话
- 空闲归档:默认 60 分钟无操作自动归档
- 索引更新:文件变更或 Session 更新时,自动执行分块 → Embedding 计算 → 写入 SQLite
七、Skills 技能系统
Section titled “七、Skills 技能系统”graph TB subgraph "技能加载层级(优先级从高到低)" S1["④ ClawHub 在线仓库<br/>类似插件市场"] S2["③ Agent Workspace<br/>agents/workspace/skills/"] S3["② 本地目录<br/>~/.openclaw/skills/"] S4["① 系统内置<br/>核心默认技能"] end
subgraph "技能定义" DEF["📄 SKILL.md<br/>YAML frontmatter 元数据<br/>+ 实现文件 (JS/TS)"] end
subgraph "执行环境" MAIN["🖥️ 主会话<br/>主机环境直接执行"] SANDBOX["🐳 非主会话<br/>Docker 沙箱隔离执行"] end
S4 --> S3 --> S2 --> S1 DEF --> MAIN & SANDBOX
style S4 fill:#166534,stroke:#22c55e,color:#fff style S1 fill:#7c2d12,stroke:#f97316,color:#fff style SANDBOX fill:#991b1b,stroke:#ef4444,color:#fff技能执行策略
Section titled “技能执行策略”| 场景 | 执行环境 | 说明 |
|---|---|---|
| 主会话(个人对话) | 主机环境 | 直接执行,拥有完整权限 |
| 非主会话(群聊等) | Docker 沙箱 | 隔离执行,防止恶意操作 |
八、模型抽象层
Section titled “八、模型抽象层”通过 models config + providers 双层抽象屏蔽底层差异:
graph LR subgraph "Agent Runtime" AR["Pi-Agent<br/>统一调用接口"] end
subgraph "模型抽象层" MA["Models Config<br/>模型配置"] PV["Providers<br/>提供商适配"] end
subgraph "云端模型" CL["Anthropic<br/>Claude 3.5/4"] GP["OpenAI<br/>GPT-4o / o1"] OR["OpenRouter<br/>聚合平台"] QW["通义千问"] DS["DeepSeek"] end
subgraph "本地模型" OL["Ollama<br/>本地运行时"] LM["LLaMA / Qwen<br/>开源模型"] end
AR --> MA --> PV PV --> CL & GP & OR & QW & DS PV --> OL --> LM
style AR fill:#4c1d95,stroke:#8b5cf6,color:#fff style MA fill:#1e3a5f,stroke:#3b82f6,color:#fff style PV fill:#1e3a5f,stroke:#06b6d4,color:#fffPrompt 构造流程
Section titled “Prompt 构造流程”模型调用时自动注入的上下文:
- Workspace 引导文件 — Agent 角色定义与行为约束
- 可用技能列表 — 当前 Agent 可调用的 Skills 目录
- 会话历史记录 — 短期记忆中的对话上下文
- 安全提示词 — 防注入和权限边界提示
九、定时任务系统
Section titled “九、定时任务系统”graph LR subgraph "任务类型" AT["⏰ at<br/>一次性任务<br/>指定时间点"] EV["🔄 every<br/>周期性任务<br/>按间隔执行"] CN["📅 cron<br/>表达式任务<br/>标准 Cron"] end
subgraph "生命周期" C1["创建"] --> C2["存储<br/>~/.openclaw/cron/"] C2 --> C3["调度<br/>计算 nextAt"] C3 --> C4["触发<br/>onTimer"] C4 --> C5["执行<br/>executeJobCore"] C5 --> C6["结果处理"] C6 --> C7["更新/删除"] C7 --> C8["清理"] end
AT & EV & CN --> C1
style AT fill:#1e3a5f,stroke:#3b82f6,color:#fff style EV fill:#1e3a5f,stroke:#f59e0b,color:#fff style CN fill:#1e3a5f,stroke:#10b981,color:#fff关键设计参数
Section titled “关键设计参数”- 最大延迟限制:1 分钟(防止长时间挂起导致任务丢失)
- 最小触发间隔:2 秒(防止任务风暴)
- 失败策略:指数退避重试
十、技术栈总结
Section titled “十、技术栈总结”| 维度 | 技术选型 |
|---|---|
| 运行时 | Node.js 22+ |
| 开发语言 | TypeScript |
| 前端 | Lit + WebSocket |
| 通信协议 | WebSocket + JSON(TypeBox Schema) |
| 持久化存储 | 本地文件系统 + SQLite + JSONL |
| 容器化 | Docker(沙箱隔离) |
| 多端支持 | macOS / iOS / Android / Headless 节点 |
| 进程管理 | systemctl / launchctl 守护进程 |
十一、全景架构总图
Section titled “十一、全景架构总图”graph TB subgraph "用户端" U1["👤 Web UI"] U2["💬 IM 平台"] U3["⌨️ CLI"] U4["📱 移动端"] end
subgraph "Gateway 控制平面" GW["⚙️ Gateway<br/>WebSocket + JSON-RPC"] RT["🔀 路由引擎"] SM["📋 会话管理"] QM["📦 队列系统"] CR["⏰ 定时任务"] end
subgraph "Agent Runtime" PA["🤖 Pi-Agent<br/>ReAct 循环"] FC["🔧 Function Calling"] end
subgraph "模型层" MA["模型抽象层"] CL["Claude"] GP["GPT"] OL["Ollama"] end
subgraph "能力层" SK["🧩 Skills<br/>5000+ 插件"] ND["🖥️ Nodes<br/>多设备节点"] DC["🐳 Docker<br/>沙箱隔离"] CLI["⌨️ CLI 工具<br/>系统命令"] end
subgraph "记忆层" MEM["💾 记忆系统"] RAG["🔍 RAG 检索"] DB["📊 SQLite"] end
U1 & U2 & U3 & U4 --> GW GW --> RT --> SM --> QM GW --> CR QM --> PA --> FC PA --> MA --> CL & GP & OL FC --> SK & ND & DC & CLI PA --> MEM --> RAG --> DB
style GW fill:#1e3a8f,stroke:#3b82f6,color:#fff,stroke-width:3px style PA fill:#4c1d95,stroke:#8b5cf6,color:#fff,stroke-width:2px style MA fill:#065f46,stroke:#10b981,color:#fff style MEM fill:#92400e,stroke:#f59e0b,color:#fffOpenClaw 本质是一个 “控制平面(Gateway)+ 智能大脑(Pi-Agent + LLM)+ 能力触角(Skills + Nodes)” 的闭环系统。它把 Agent 从”能聊天”升级为”能做事”的长期运行系统工程,通过 Gateway 统一 IM 消息接入,通过模型抽象层支持多 LLM,通过 Skills 和 Docker 沙箱实现安全可控的工具执行。