OpenClaw 架构概述

OpenClaw 架构概述 🏗️

本文档帮助您理解 OpenClaw 的核心组件和它们如何协同工作。

🎯 什么是 OpenClaw？

OpenClaw 是一个本地优先的 AI 网关，它充当了消息平台（如 WhatsApp、Telegram）和 AI 代理之间的桥梁。

┌─────────────────────────────────────────────────────────────┐
│                      OpenClaw 网关                           │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────────┐ │
│  │  消息频道    │◄──►│   核心引擎    │◄──►│   AI 代理      │ │
│  │  WhatsApp   │    │   网关服务    │    │   Pi Agent    │ │
│  │  Telegram   │    │              │    │   Claude      │ │
│  │  Discord    │    │              │    │   GPT-4       │ │
│  │  iMessage   │    │              │    │               │ │
│  └─────────────┘    └──────────────┘    └────────────────┘ │
│           ▲                ▲                     ▲         │
└───────────┼────────────────┼─────────────────────┼─────────┘
            │                │                     │
     用户消息          控制界面              AI 响应
    (WhatsApp)       (浏览器)            (智能回复)

🧩 核心组件

1. 网关服务 (Gateway)

网关是 OpenClaw 的核心进程，负责：

🔄 管理所有消息频道的连接
🧠 协调 AI 代理的调用
🌐 提供 Web 控制界面
📊 处理消息路由和会话管理

技术细节：

监听端口：默认 18789
协议：WebSocket + HTTP
自动重连：支持连接断开自动恢复

2. 消息频道 (Channels)

频道是 OpenClaw 与外部消息平台的连接：

频道	协议	特点
WhatsApp	Baileys	网页版连接，支持多媒体
Telegram	Bot API	稳定的机器人接口
Discord	Bot API	丰富的富文本支持
iMessage	imsg CLI	macOS 原生集成

频道工作原理：

用户发送消息 → 频道接收 → 网关处理 → AI 生成回复 → 频道发送

3. AI 代理 (Agents)

代理是实际处理消息的 AI 大脑：

Pi Agent：默认代理，基于 Claude/GPT
自定义代理：可接入其他 AI 模型
多代理路由：根据场景选择不同代理

代理配置示例：

{
  agents: {
    default: {
      type: "pi",
      model: "claude-3.5-sonnet",
      temperature: 0.7
    }
  }
}

4. 会话管理 (Sessions)

会话跟踪对话上下文：

私信会话：一对一对话
群组会话：多人对话，支持提及触发
上下文保持：记住对话历史

会话隔离：

每个用户/群组有独立会话
防止信息泄露
支持会话重置

5. 工作空间 (Workspace)

工作空间是代理的工作目录：

~/.openclaw/workspace/
├── canvas/          # 画布文件
├── memory/          # 记忆存储
├── skills/          # 技能脚本
└── logs/            # 运行日志

🔧 数据流

消息处理流程

1. 用户发送消息 (WhatsApp/Telegram/Discord)
         ↓
2. 频道接收并解析消息
         ↓
3. 网关路由到合适的代理
         ↓
4. 代理处理并生成回复
         ↓
5. 网关发送回复到原频道
         ↓
6. 用户收到 AI 回复

配置加载流程

1. 读取 ~/.openclaw/openclaw.json
         ↓
2. 验证配置格式
         ↓
3. 加载频道配置
         ↓
4. 初始化代理
         ↓
5. 启动网关服务
         ↓
6. 开放 Web 界面

🛡️ 安全架构

1. 本地优先设计

✅ 数据不离开本地机器
✅ 无需云端 API（可选）
✅ 完全离线运行

2. 认证机制

┌─────────────┐
│   用户请求   │
└──────┬──────┘
       ↓
┌─────────────┐
│  Token 验证  │
└──────┬──────┘
       ↓
┌─────────────┐
│  权限检查    │
└──────┬──────┘
       ↓
┌─────────────┐
│  处理请求    │
└─────────────┘

3. 沙箱隔离

代理运行在隔离环境
限制文件系统访问
网络访问控制

🚀 扩展性

插件系统

核心网关
   ↓
插件管理器
   ↓
┌─────────┬─────────┬─────────┐
│WhatsApp │Telegram │ Matter- │
│ 插件    │ 插件    │ most    │
│         │         │ 插件    │
└─────────┴─────────┴─────────┘

自定义工具

代理可以调用各种工具：

🌐 网页浏览
🖼️ 图像生成
📁 文件操作
⏰ 定时任务

📊 性能特点

1. 低延迟

本地处理，无网络延迟
平均响应时间 < 100ms
流式输出，即时显示

2. 高并发

支持多频道同时连接
异步消息处理
连接池管理

3. 资源占用

内存：约 200-500MB
CPU：空闲时接近 0%
存储：配置 + 日志约 100MB

🔄 生命周期

启动流程

openclaw gateway start
    ↓
读取配置
    ↓
初始化频道
    ↓
连接消息平台
    ↓
启动代理
    ↓
开放 Web 界面
    ↓
✅ 就绪

关闭流程

Ctrl+C 或 openclaw gateway stop
    ↓
停止接受新消息
    ↓
等待处理中的消息完成
    ↓
断开频道连接
    ↓
保存会话状态
    ↓
关闭代理
    ↓
✅ 已停止