跳转至

OpenClaw（小龙虾）架构与实现原理

一、整体架构概览

OpenClaw 采用从"模型中心"转向"系统中心"的架构理念，将 Agent 视为一个长期运行的操作系统，而非简单的对话机器人。

六层分层架构

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 中心架构

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:#fff

Gateway 核心特性

  • 通信协议：WebSocket 长连接，使用 TypeBox 定义严格 JSON Schema
  • 消息类型：req（请求）/ res（响应）/ event（事件推送）
  • 守护进程：通过 systemctl（Linux）或 launchctl（macOS）实现 7×24 运行
  • 默认端口：ws://127.0.0.1:18789

三、消息处理全流程

从用户发送消息到收到 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: 回复消息

路由优先级（从高到低）

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:#fff

SessionKey 格式：agent:main:telegram:dm:123456

四、Agent 运行时（Pi-Agent 框架）

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

三层容错机制

层级 机制 说明
第一层 Auth Profile 轮换 API Key 限流或失败时自动切换到备用 Key
第二层 上下文溢出压缩 会话过长时自动摘要压缩历史记录
第三层 思考级别降级 模型不支持扩展思考时自动降级处理

五、并发控制与队列系统

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

六、记忆系统

采用 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

会话生命周期

  • 每日重置：可配置每日自动清理会话
  • 空闲归档：默认 60 分钟无操作自动归档
  • 索引更新：文件变更或 Session 更新时，自动执行分块 → Embedding 计算 → 写入 SQLite

七、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

技能执行策略

场景 执行环境 说明
主会话（个人对话） 主机环境 直接执行，拥有完整权限
非主会话（群聊等） Docker 沙箱 隔离执行，防止恶意操作

八、模型抽象层

通过 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:#fff

Prompt 构造流程

模型调用时自动注入的上下文： 1. Workspace 引导文件 — Agent 角色定义与行为约束 2. 可用技能列表 — 当前 Agent 可调用的 Skills 目录 3. 会话历史记录 — 短期记忆中的对话上下文 4. 安全提示词 — 防注入和权限边界提示

九、定时任务系统

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

关键设计参数

  • 最大延迟限制：1 分钟（防止长时间挂起导致任务丢失）
  • 最小触发间隔：2 秒（防止任务风暴）
  • 失败策略：指数退避重试

十、技术栈总结

维度 技术选型
运行时 Node.js 22+
开发语言 TypeScript
前端 Lit + WebSocket
通信协议 WebSocket + JSON（TypeBox Schema）
持久化存储 本地文件系统 + SQLite + JSONL
容器化 Docker（沙箱隔离）
多端支持 macOS / iOS / Android / Headless 节点
进程管理 systemctl / launchctl 守护进程

十一、全景架构总图

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:#fff

总结

OpenClaw 本质是一个 "控制平面（Gateway）+ 智能大脑（Pi-Agent + LLM）+ 能力触角（Skills + Nodes）" 的闭环系统。它把 Agent 从"能聊天"升级为"能做事"的长期运行系统工程，通过 Gateway 统一 IM 消息接入，通过模型抽象层支持多 LLM，通过 Skills 和 Docker 沙箱实现安全可控的工具执行。

捐赠本站(Donate)

weixin_pay
如您感觉文章有用，可扫码捐赠本站！(If the article useful, you can scan the QR code to donate))