【OpenClaw 架构设计】2-OpenClaw 系统架构

1. 概述

OpenClaw 采用分层架构设计,以 Gateway 为核心控制平面,实现了消息渠道、AI 代理、工具系统和客户端应用的完整集成。系统架构设计遵循”本地优先”原则,确保用户数据的安全性和隐私保护。

2. 系统架构总览

2.1 分层架构图

2.2 核心设计原则

1. 本地优先
   
   所有数据和计算都在本地进行
2. 模块化
   
   各层职责明确,松耦合设计
3. 可扩展
   
   支持插件和扩展机制
4. 安全第一
   
   多层安全防护机制
5. 高性能
   
   异步处理和缓存优化

3. Gateway 控制平面

3.1 Gateway 架构

Gateway 是 OpenClaw 的核心组件,负责协调所有子系统:

// src/gateway/index.tsexport class Gateway {  private wsServer: WebSocket.Server  private sessionManager: SessionManager  private channelManager: ChannelManager  private toolRegistry: ToolRegistry  private configManager: ConfigManager  private cronScheduler: CronScheduler  private webhookManager: WebhookManager  async start(): Promise<void> {    // 1. 加载配置    await this.configManager.load()    // 2. 初始化会话管理器    await this.sessionManager.initialize()    // 3. 加载渠道适配器    await this.channelManager.loadChannels()    // 4. 注册工具    await this.toolRegistry.registerTools()    // 5. 启动 Cron 调度器    await this.cronScheduler.start()    // 6. 启动 Webhook 管理器    await this.webhookManager.start()    // 7. 启动 WebSocket 服务器    await this.startWebSocketServer()  }}

3.2 WebSocket 协议

Gateway 使用 WebSocket 协议与客户端通信:

// src/gateway/protocol/schema.tsexport interface GatewayFrame {  type: 'req' | 'res' | 'event'  id?: string  method?: string  params?: any  ok?: boolean  payload?: any  error?: any  event?: string  seq?: number}// 连接流程Client                    Gateway  |                          |  |---- req:connect -------->|  |<------ res (ok) ---------|  |                          |  |<------ event:tick -------|  |<------ event:presence ---|  |                          |  |------- req:agent ------->|  |<------ res:agent --------|  |<------ event:agent ------|  |                          |

3.3 请求处理

Gateway 处理客户端请求:

// src/gateway/server.tsexport class GatewayServer {  private methods: Map<string, MethodHandler>  async handleRequest(frame: RequestFrame): Promise<ResponseFrame> {    const handler = this.methods.get(frame.method)    if (!handler) {      return {        id: frame.id,        ok: false,        error: { message: `Unknown method: ${frame.method}` }      }    }    try {      const result = await handler(frame.params)      return {        id: frame.id,        ok: true,        payload: result      }    } catch (error) {      return {        id: frame.id,        ok: false,        error: { message: error.message }      }    }  }}

3.4 事件推送

Gateway 向客户端推送事件:

// src/gateway/events.tsexport class EventEmitter {  private clients: Set<WebSocket>  emit(event: string, payload: any): void {    const frame: EventFrame = {      type: 'event',      event,      payload,      timestamp: Date.now()    }    this.clients.forEach(client => {      if (client.readyState === WebSocket.OPEN) {        client.send(JSON.stringify(frame))      }    })  }}

支持的事件类型:

• tick
  
  心跳事件
• presence
  
  在线状态事件
• agent
  
  AI 代理事件
• chat
  
  聊天消息事件
• health
  
  健康状态事件
• shutdown
  
  关闭事件

4. 客户端架构

4.1 macOS 应用

macOS 应用是主要的控制界面:

// apps/macos/Sources/OpenClaw/AppDelegate.swiftclass AppDelegate: NSObject, NSApplicationDelegate {  var statusItem: NSStatusItem!  var gatewayConnection: GatewayConnection!  func applicationDidFinishLaunching(_ notification: Notification) {    // 1. 创建菜单栏图标    setupStatusBar()    // 2. 连接 Gateway    connectToGateway()    // 3. 启动 Voice Wake    startVoiceWake()    // 4. 初始化 Canvas    initializeCanvas()  }}

主要功能:

• 菜单栏控制
  
  快速访问常用功能
• Voice Wake
  
  语音唤醒和 PTT
• Talk Mode
  
  语音对话覆盖层
• WebChat
  
  内置聊天界面
• 调试工具
  
  日志查看和诊断

4.2 iOS 节点

iOS 节点提供移动端功能:

// apps/ios/Sources/OpenClaw/App.swift@mainstruct OpenClawApp: App {  var body: some Scene {    WindowGroup {      ContentView()        .onAppear {          // 1. 连接 Gateway          connectToGateway()          // 2. 注册节点能力          registerNodeCapabilities()        }    }  }}

节点能力:

• Canvas
  
  渲染 AI 生成的可视化内容
• Voice Wake
  
  语音唤醒
• Talk Mode
  
  语音对话
• 摄像头
  
  拍照和录像
• 屏幕录制
  
  录制屏幕内容
• 位置
  
  获取设备位置

4.3 Android 节点

Android 节点提供类似 iOS 的功能:

// apps/android/app/src/main/java/ai/openclaw/android/MainActivity.ktclass MainActivity : AppCompatActivity() {  private lateinit var gatewayConnection: GatewayConnection  override fun onCreate(savedInstanceState: Bundle?) {    super.onCreate(savedInstanceState)    setContentView(R.layout.activity_main)    // 1. 连接 Gateway    connectToGateway()    // 2. 注册节点能力    registerNodeCapabilities()  }}

4.4 WebChat UI

WebChat 是基于 Web 的聊天界面:

// src/web/webchat/index.tsexport class WebChatUI {  private wsClient: WebSocketClient  private messageStore: MessageStore  async initialize(): Promise<void> {    // 1. 连接 Gateway    await this.wsClient.connect()    // 2. 加载聊天历史    await this.loadChatHistory()    // 3. 订阅消息事件    this.subscribeToMessages()  }}

4.5 CLI 客户端

CLI 提供命令行界面:

// src/cli/index.tsexport class CLI {  async run(): Promise<void> {    const program = new Command()    program      .name('openclaw')      .description('Personal AI Assistant CLI')      .version(version)    // 添加命令    program      .command('gateway')      .description('Start the gateway')      .action(this.startGateway)    program      .command('agent')      .description('Run an agent')      .action(this.runAgent)    program      .command('send')      .description('Send a message')      .action(this.sendMessage)    await program.parseAsync(process.argv)  }}

5. 处理层架构

5.1 Pi Agent 运行时

Pi Agent 是 AI 代理的核心运行时:

// src/agents/pi-embedded.tsexport class PiEmbeddedAgent {  private modelProvider: ModelProvider  private toolExecutor: ToolExecutor  private sessionManager: SessionManager  async processMessage(    message: ChatMessage,    sessionKey: string,    workspace: string  ): Promise<AgentResponse> {    // 1. 加载会话    const session = await this.sessionManager.load(sessionKey, workspace)    // 2. 构建上下文    const context = await this.buildContext(message, session)    // 3. 准备工具    const tools = await this.prepareTools(context)    // 4. 调用模型    const response = await this.callModel(context, tools)    // 5. 执行工具    if (response.toolCalls) {      const toolResults = await this.toolExecutor.execute(        response.toolCalls,        context      )      // 6. 处理工具结果      return await this.processToolResults(response, toolResults)    }    // 7. 保存会话    await this.sessionManager.save(sessionKey, session)    return response  }}

5.2 自动回复引擎

自动回复引擎处理消息回复:

// src/auto-reply/reply.tsexport class AutoReplyEngine {  private chunker: Chunker  private dispatcher: Dispatcher  private templater: Templater  async process(message: ChatMessage): Promise<ReplyResult> {    // 1. 分块处理    const chunks = await this.chunker.chunk(message)    // 2. 模板处理    const templated = await this.templater.process(chunks)    // 3. 分发回复    const result = await this.dispatcher.dispatch(templated)    return result  }}

5.3 渠道适配器

渠道适配器处理不同渠道的消息:

// src/channels/adapter.tsexport abstract class ChannelAdapter {  abstract async connect(): Promise<void>  abstract async disconnect(): Promise<void>  abstract async sendMessage(to: string, message: FormattedMessage): Promise<void>  abstract async handleMessage(rawMessage: any): Promise<ChatMessage>}// WhatsApp 适配器export class WhatsAppAdapter extends ChannelAdapter {  private sock: WASocket  async connect(): Promise<void> {    const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys')    this.sock = makeWASocket({ auth: state })    this.sock.ev.on('messages.upsert', this.handleMessage)  }}// Telegram 适配器export class TelegramAdapter extends ChannelAdapter {  private bot: Bot  async connect(): Promise<void> {    this.bot = new Bot(this.config.token)    this.bot.on('message', this.handleMessage)    await this.bot.start()  }}

6. 数据层架构

6.1 会话存储

会话存储使用 SQLite 数据库:

// src/sessions/store.tsexport class SessionStore {  private db: Database  constructor(dbPath: string) {    this.db = new Database(dbPath)    this.initializeTables()  }  private initializeTables(): void {    this.db.exec(`      CREATE TABLE IF NOT EXISTS sessions (        session_key TEXT PRIMARY KEY,        agent_id TEXT NOT NULL,        workspace TEXT NOT NULL,        data TEXT NOT NULL,        created_at INTEGER NOT NULL,        updated_at INTEGER NOT NULL      )    `)  }  async load(sessionKey: string): Promise<Session> {    const row = this.db.prepare(      'SELECT data FROM sessions WHERE session_key = ?'    ).get(sessionKey)    if (!row) {      return this.createNewSession(sessionKey)    }    return JSON.parse(row.data)  }  async save(sessionKey: string, session: Session): Promise<void> {    const data = JSON.stringify(session)    this.db.prepare(`      INSERT OR REPLACE INTO sessions       (session_key, agent_id, workspace, data, created_at, updated_at)      VALUES (?, ?, ?, ?, ?, ?)    `).run(      sessionKey,      session.agentId,      session.workspace,      data,      session.createdAt,      Date.now()    )  }}

6.2 内存存储

内存存储支持向量搜索:

// src/memory/store.tsexport class MemoryStore {  private vectorStore: VectorStore  async store(memory: Memory): Promise<void> {    // 1. 向量化内容    const embedding = await this.embed(memory.content)    // 2. 存储向量    await this.vectorStore.add({      id: memory.id,      vector: embedding,      metadata: memory.metadata    })  }  async search(query: string, limit: number = 10): Promise<Memory[]> {    // 1. 向量化查询    const queryEmbedding = await this.embed(query)    // 2. 向量搜索    const results = await this.vectorStore.search(queryEmbedding, limit)    // 3. 返回结果    return results.map(r => ({      id: r.id,      content: r.metadata.content,      score: r.score    }))  }}

6.3 配置存储

配置存储使用 JSON 文件:

// src/config/store.tsexport class ConfigStore {  private configPath: string  private config: any  async load(): Promise<void> {    const content = await fs.readFile(this.configPath, 'utf-8')    this.config = JSON.parse(content)  }  async save(): Promise<void> {    const content = JSON.stringify(this.config, null, 2)    await fs.writeFile(this.configPath, content, 'utf-8')  }  get(key: string): any {    return this.config[key]  }  set(key: string, value: any): void {    this.config[key] = value  }}

6.4 凭证存储

凭证存储使用加密存储:

// src/credentials/store.tsexport class CredentialStore {  private encryptionKey: Buffer  async store(key: string, value: string): Promise<void> {    const encrypted = await this.encrypt(value)    await this.saveToKeychain(key, encrypted)  }  async retrieve(key: string): Promise<string> {    const encrypted = await this.loadFromKeychain(key)    return await this.decrypt(encrypted)  }  private async encrypt(data: string): Promise<Buffer> {    // 使用 AES-256-GCM 加密    const iv = crypto.randomBytes(16)    const cipher = crypto.createCipheriv(      'aes-256-gcm',      this.encryptionKey,      iv    )    const encrypted = Buffer.concat([      cipher.update(data, 'utf8'),      cipher.final()    ])    const authTag = cipher.getAuthTag()    return Buffer.concat([iv, authTag, encrypted])  }  private async decrypt(data: Buffer): Promise<string> {    const iv = data.slice(0, 16)    const authTag = data.slice(16, 32)    const encrypted = data.slice(32)    const decipher = crypto.createDecipheriv(      'aes-256-gcm',      this.encryptionKey,      iv    )    decipher.setAuthTag(authTag)    const decrypted = Buffer.concat([      decipher.update(encrypted),      decipher.final()    ])    return decrypted.toString('utf8')  }}

7. 工具层架构

7.1 浏览器控制

浏览器控制工具提供 Web 自动化能力:

// src/tools/browser/index.tsexport class BrowserTool {  private page: Page  async navigate(url: string): Promise<void> {    await this.page.goto(url)  }  async screenshot(): Promise<Buffer> {    return await this.page.screenshot()  }  async click(selector: string): Promise<void> {    await this.page.click(selector)  }  async type(selector: string, text: string): Promise<void> {    await this.page.type(selector, text)  }}

7.2 Canvas 渲染

Canvas 渲染工具提供可视化能力:

// src/tools/canvas/index.tsexport class CanvasTool {  private canvasHost: CanvasHost  async render(component: string, data: any): Promise<void> {    await this.canvasHost.render({      component,      data,      timestamp: Date.now()    })  }  async update(id: string, data: any): Promise<void> {    await this.canvasHost.update(id, data)  }  async clear(): Promise<void> {    await this.canvasHost.clear()  }}

7.3 节点控制

节点控制工具提供设备控制能力:

// src/tools/node/index.tsexport class NodeTool {  async getCamera(): Promise<Camera> {    return await this.requestCapability('camera')  }  async getScreenRecording(): Promise<ScreenRecording> {    return await this.requestCapability('screen-recording')  }  async getLocation(): Promise<Location> {    return await this.requestCapability('location')  }  async sendNotification(title: string, body: string): Promise<void> {    await this.requestCapability('notification', { title, body })  }}

8. 安全架构

8.1 本地优先原则

OpenClaw 采用”本地优先”原则,确保用户数据的安全性和隐私保护:

• 所有数据存储在本地设备
• 敏感信息使用端到端加密
• API 密钥存储在系统密钥链中
• 会话数据使用 SQLite 本地存储

8.2 加密机制

系统使用多层加密机制:

• 传输加密
  
  所有 WebSocket 连接使用 TLS
• 存储加密
  
  敏感数据使用 AES-256-GCM 加密
• 密钥管理
  
  使用系统密钥链管理加密密钥

8.3 访问控制

系统实施严格的访问控制:

• 配对机制
  
  只有配对的设备才能连接
• 白名单
  
  可配置允许的用户白名单
• 权限验证
  
  每个工具调用都需要权限验证

9. 性能优化

9.1 异步处理

系统使用异步处理提高性能:

• 所有 I/O 操作都是异步的
• 使用消息队列处理并发请求
• 工具执行使用工作线程池

9.2 缓存机制

系统使用多层缓存:

• 会话缓存
  
  热会话保存在内存中
• 向量缓存
  
  向量搜索结果缓存
• 配置缓存
  
  配置文件缓存

9.3 资源管理

系统实施有效的资源管理:

• 会话压缩减少内存占用
• 连接池管理数据库连接
• 定期清理过期数据

10. 扩展机制

10.1 插件系统

OpenClaw 支持插件扩展:

// src/plugins/manager.tsexport class PluginManager {  private plugins: Map<string, Plugin>  async load(pluginPath: string): Promise<void> {    const plugin = await import(pluginPath)    await plugin.initialize()    this.plugins.set(plugin.name, plugin)  }  async unload(pluginName: string): Promise<void> {    const plugin = this.plugins.get(pluginName)    if (plugin) {      await plugin.shutdown()      this.plugins.delete(pluginName)    }  }}

10.2 工具注册

开发者可以注册自定义工具:

// src/tools/registry.tsexport class ToolRegistry {  private tools: Map<string, Tool>  register(tool: Tool): void {    this.tools.set(tool.name, tool)  }  get(name: string): Tool | undefined {    return this.tools.get(name)  }  list(): Tool[] {    return Array.from(this.tools.values())  }}

10.3 渠道适配器

开发者可以实现自定义渠道适配器:

// src/channels/adapter.tsexport interface ChannelAdapter {  name: string  connect(): Promise<void>  disconnect(): Promise<void>  sendMessage(to: string, message: FormattedMessage): Promise<void>  handleMessage(rawMessage: any): Promise<ChatMessage>}

11. 总结

OpenClaw 的系统架构具有以下特点:

1. 分层设计
   
   清晰的分层架构,职责明确
2. Gateway 核心
   
   以 Gateway 为控制平面,协调所有子系统
3. 多客户端支持
   
   支持 macOS、iOS、Android、Web、CLI 等多种客户端
4. 灵活的数据层
   
   支持会话存储、内存存储、配置存储等多种存储方式
5. 丰富的工具层
   
   提供浏览器、Canvas、节点、自动化等多种工具
6. 多层安全
   
   从网络层到工具层的多层安全防护
7. 高性能设计
   
   支持缓存、异步处理等性能优化
8. 可扩展性
   
   支持插件和扩展机制

这种架构设计确保了 OpenClaw 能够作为一个功能强大、安全可靠、易于扩展的个人 AI 助手平台运行。