老周虾扯：OpenClaw 架构原理与核心机制深度解析

前言

OpenClaw 是一款运行在个人设备上的开源 AI 助手框架，支持 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等 20+ 主流消息平台。本文基于其源码（openclaw-main）对其整体架构、核心子系统及关键设计原理进行深度解析。

一、整体架构概览

OpenClaw 采用本地优先（Local-First）的 Gateway 控制平面架构，核心思想是：所有消息渠道、AI 会话、工具调用都通过一个统一的本地 WebSocket 服务（Gateway）进行调度。

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / ...
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (控制平面 / Control Plane) │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi Agent（嵌入式 AI 运行时，RPC 模式）
               ├─ CLI（openclaw 命令行）
               ├─ WebChat UI（内置 Web 界面）
               ├─ macOS 菜单栏 App
               └─ iOS / Android 节点（Nodes）

设计哲学：

• Gateway 只是控制平面，不是产品本身
• 产品是 AI 助手体验，Gateway 负责把所有渠道、工具、会话串联起来
• 默认绑定本地回环地址（127.0.0.1），安全优先

二、核心目录结构

openclaw-main/
├── src/                    # 核心源码
│   ├── gateway/            # Gateway 服务（WebSocket 控制平面）
│   ├── agents/             # Agent 运行时（Pi 嵌入式 Runner）
│   ├── sessions/           # 会话管理
│   ├── channels/           # 消息渠道适配器
│   ├── providers/          # AI 模型提供商
│   ├── skills/             # Skills 平台
│   ├── browser/            # 浏览器控制工具
│   ├── canvas-host/        # Canvas 可视化工作区
│   └── ...
├── extensions/             # 扩展插件（Discord、Feishu、Matrix 等）
├── skills/                 # 内置 Skills 目录
├── ui/                     # WebChat 前端（TypeScript + Vite）
├── apps/                   # 平台 App（macOS、iOS、Android）
└── packages/               # 共享包

三、Gateway：WebSocket 控制平面

3.1 核心职责

Gateway 是整个系统的神经中枢，负责：

1. WebSocket 连接管理：所有客户端（CLI、App、WebChat）通过 WS 连接到 Gateway
2. 消息路由：将来自各渠道的消息路由到对应的 Agent 会话
3. 工具调用代理：浏览器控制、文件操作、Shell 执行等工具调用均通过 Gateway 分发
4. 配置热重载：支持运行时配置变更，无需重启
5. Cron 调度：内置定时任务调度器
6. 健康监控：渠道健康检查、连接状态监控

3.2 服务启动流程

源码 src/gateway/server-startup.ts 揭示了启动序列：

1. 加载配置（openclaw.json）
2. 初始化认证模块（auth.ts）
3. 启动 HTTP 服务（server-http.ts）
4. 升级 WebSocket 连接（server-ws-runtime.ts）
5. 初始化渠道连接（server-channels.ts）
6. 启动 Cron 调度器（server-cron.ts）
7. 注册工具目录（tool-catalog.ts）
8. 加载 Skills（skills.ts）
9. 启动内存服务（server-startup-memory.ts）

3.3 WebSocket 协议设计

Gateway 使用自定义 WS 协议，核心方法分为：

• 控制平面方法：sessions.list、sessions.patch、config.get、config.patch
• 聊天方法：chat.send、chat.abort、chat.compact
• 工具方法：tools.invoke、node.invoke、browser.action
• 事件推送：agent.text、agent.tool_call、session.update

方法权限通过 method-scopes.ts 进行细粒度控制，不同角色（owner/user/guest）拥有不同的方法访问权限。

四、Pi Agent：嵌入式 AI 运行时

4.1 架构设计

Pi Agent 是 OpenClaw 的 AI 执行引擎，采用嵌入式 RPC 模式运行，与 Gateway 通过内部 RPC 通信，而非外部 HTTP 调用。

核心文件：

• src/agents/pi-embedded-runner.ts：主运行循环
• src/agents/pi-embedded-subscribe.ts：流式响应订阅处理
• src/agents/pi-embedded-helpers.ts：辅助工具函数

4.2 Agent 运行循环

用户消息到达
    │
    ▼
构建 System Prompt（SOUL.md + AGENTS.md + Skills + 上下文）
    │
    ▼
调用 AI 模型 API（支持 Anthropic / OpenAI / Gemini / Ollama 等）
    │
    ▼
流式接收响应（pi-embedded-subscribe.ts）
    │
    ├─ 文本块 → 实时推送到渠道
    ├─ 工具调用 → 执行工具 → 结果注入上下文
    └─ 思考块（Reasoning）→ 可选显示
    │
    ▼
会话历史持久化（session-utils.fs.ts）

4.3 工具执行机制

工具调用采用策略管道（Policy Pipeline）设计：

工具调用请求
    │
    ▼
tool-policy-pipeline.ts（策略检查）
    ├─ 沙箱策略（sandbox-tool-policy.ts）
    ├─ 文件系统策略（tool-fs-policy.ts）
    ├─ 路径策略（path-policy.ts）
    └─ 自定义策略
    │
    ▼
工具执行（bash-tools.exec.ts / browser / canvas 等）
    │
    ▼
结果返回 + 持久化（session-tool-result-guard.ts）

4.4 上下文压缩（Compaction）

当会话历史超过模型上下文窗口时，自动触发压缩：

• src/agents/compaction.ts：压缩主逻辑
• 保留关键标识符（compaction.identifier-preservation.ts）
• 支持重试机制（compaction.retry.ts）
• Token 清理（compaction.token-sanitize.ts）

五、会话模型（Session Model）

5.1 会话类型

OpenClaw 的会话分为两类：

5.2 会话隔离与沙箱

非 main 会话（群组、陌生人 DM）可运行在 Docker 沙箱中：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

沙箱内默认：

• 允许：bash、read、write、edit、sessions_*
• 禁止：browser、canvas、nodes、cron

5.3 会话持久化

会话数据存储在文件系统：

• 会话目录：~/.openclaw/sessions/<session-key>/
• 消息历史：JSON 格式，支持修复（session-transcript-repair.ts）
• 写锁机制：session-write-lock.ts 防止并发写入冲突

六、多渠道架构

6.1 渠道适配器设计

每个渠道（WhatsApp、Telegram、Discord 等）实现统一的渠道接口，核心职责：

1. 连接管理：维持与平台的长连接
2. 消息标准化：将平台消息转换为 OpenClaw 内部格式
3. 媒体处理：图片、音频、视频的下载与上传
4. 发送策略：消息分块、重试、限速

6.2 消息路由

入站消息
    │
    ▼
渠道适配器（解析 + 标准化）
    │
    ▼
routing/（路由决策）
    ├─ 确定目标 Agent（基于 sender/group 配置）
    ├─ 安全检查（allowFrom / dmPolicy）
    └─ 会话键生成（session-key-utils.ts）
    │
    ▼
会话队列（lanes.ts）
    │
    ▼
Pi Agent 处理
    │
    ▼
回复分块（streaming/chunking）→ 发送回渠道

6.3 安全模型

• DM 配对策略（dmPolicy）：默认要求配对码验证，防止陌生人滥用
• allowFrom 白名单：精确控制哪些用户/群组可以触发 Agent
• Doctor 检查：openclaw doctor 自动检测危险配置

七、模型管理与故障转移

7.1 多模型支持

OpenClaw 支持几乎所有主流 AI 提供商：

• Anthropic（Claude 系列）
• OpenAI（GPT / o 系列 / Codex）
• Google（Gemini 系列）
• 本地模型（Ollama 自动发现）
• 国内模型（MiniMax、Moonshot、BytePlus/Doubao、Qianfan 等）

7.2 Auth Profile 轮换

src/agents/auth-profiles.ts 实现了多 API Key 的智能轮换：

请求到来
    │
    ▼
resolve-auth-profile-order.ts（排序策略）
    ├─ 按 lastUsed 时间排序（避免单 Key 过热）
    ├─ 跳过冷却中的 Key（rate limit 后自动冷却）
    └─ 优先使用 lastGood Key
    │
    ▼
执行请求
    │
    ├─ 成功 → 更新 lastUsed
    └─ 失败 → 标记冷却 → 自动切换下一个 Key

7.3 模型故障转移

src/agents/model-fallback.ts 实现了模型级别的故障转移：

• 主模型失败时自动切换到备用模型
• 支持配置 fallback 链
• 错误分类（账单错误、限速错误、模型不可用等）

八、Skills 平台

8.1 Skills 架构

Skills 是 OpenClaw 的扩展机制，本质是注入到 System Prompt 的指令文件（SKILL.md）+ 可选的脚本/工具。

三种 Skills 类型：

8.2 Skills 加载流程

启动时扫描 Skills 目录
    │
    ▼
解析 SKILL.md（提取 description、触发条件）
    │
    ▼
构建 Skills 快照（buildworkspaceskillsnapshot.ts）
    │
    ▼
注入 System Prompt（build-workspace-skills-prompt.ts）
    │
    ▼
Agent 根据用户意图选择并加载对应 Skill

8.3 Skills 安装

支持从 ClawHub（clawhub.com）在线安装：

• 下载 tar 包（skills-install-download.ts）
• 解压验证（skills-install-extract.ts）
• 安全审查（skill-vetter 内置 Skill）

九、工具系统

9.1 核心工具集

OpenClaw 内置了丰富的工具：

9.2 Bash 工具深度解析

bash-tools.exec.ts 是最复杂的工具之一：

• PTY 支持：通过伪终端运行交互式命令
• 后台进程：支持 background: true 异步执行
• 审批机制：危险命令可配置人工审批（exec-approval-manager.ts）
• 沙箱隔离：非 main 会话在 Docker 容器内执行
• 进程注册表：bash-process-registry.ts 管理所有后台进程生命周期

9.3 浏览器控制

基于 Chrome DevTools Protocol（CDP）：

• 支持 OpenClaw 托管的独立 Chrome 实例
• 支持通过 Browser Relay 扩展接管用户现有 Chrome 标签页
• 快照（Snapshot）+ 动作（Act）的 UI 自动化模式

十、子 Agent 系统（Multi-Agent）

10.1 设计理念

OpenClaw 支持 Agent 间协作，主 Agent 可以 spawn 子 Agent 执行并行任务：

主 Agent
    │
    ├─ sessions_spawn() → 子 Agent A（独立会话）
    ├─ sessions_spawn() → 子 Agent B（独立会话）
    └─ sessions_send() → 向其他会话发消息

10.2 子 Agent 注册表

src/agents/subagent-registry.ts 管理所有子 Agent 的生命周期：

• 深度限制（subagent-depth.ts）：防止无限递归 spawn
• 完成通知（subagent-announce.ts）：子 Agent 完成后自动通知父 Agent
• 清理机制（subagent-registry-cleanup.ts）：超时或失败的子 Agent 自动清理
• 持久化：子 Agent 状态持久化，支持 Gateway 重启后恢复

10.3 ACP（Agent Coding Protocol）

src/acp/ 实现了与外部编码 Agent（Codex、Claude Code 等）的集成协议，支持：

• 线程绑定的持久会话
• 流式输出到父会话
• 工具调用代理

十一、内存与记忆系统

11.1 文件系统记忆

OpenClaw 的记忆系统基于文件：

• MEMORY.md：长期记忆（主会话专用）
• memory/YYYY-MM-DD.md：每日日志
• SOUL.md、AGENTS.md、USER.md：身份与行为定义

11.2 语义搜索

src/agents/memory-search.ts 实现了向量语义搜索：

• 支持 LanceDB 后端（extensions/memory-lancedb/）
• 支持内存核心（extensions/memory-core/）
• 通过 memory_search 工具暴露给 Agent

十二、安全架构

12.1 多层安全防护

外部请求
    │
    ▼
网络层：默认绑定 127.0.0.1（不暴露公网）
    │
    ▼
认证层：Token / Password / Tailscale 身份
    │
    ▼
授权层：角色权限（owner/user/guest）+ 方法作用域
    │
    ▼
渠道层：allowFrom 白名单 + dmPolicy 配对
    │
    ▼
工具层：沙箱隔离 + 路径策略 + 审批机制
    │
    ▼
Agent 层：Prompt 注入防护 + 内容清理

12.2 Docker 沙箱

非 main 会话可在 Docker 容器中运行：

• Dockerfile.sandbox：基础沙箱镜像
• Dockerfile.sandbox-browser：含浏览器的沙箱镜像
• 工具调用通过 bash-tools.exec-host-gateway.ts 代理到容器内执行

十三、配置系统

13.1 配置文件

主配置文件：~/.openclaw/openclaw.json（JSON5 格式）

核心配置项：

{
  agent: {
    model: "anthropic/claude-opus-4-6",  // 默认模型
  },
  gateway: {
    bind: "loopback",  // 绑定地址
    port: 18789,
  },
  channels: {
    telegram: { botToken: "..." },
    discord: { token: "..." },
    whatsapp: { allowFrom: ["..."] },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      sandbox: { mode: "non-main" },
    }
  }
}

13.2 热重载机制

src/gateway/config-reload.ts 实现配置热重载：

• 监听配置文件变化
• 计算变更计划（config-reload-plan.ts）
• 最小化重启影响（只重启受影响的渠道/组件）

十四、总结

OpenClaw 的架构设计体现了以下核心理念：

1. 本地优先：Gateway 运行在用户设备上，数据不经过第三方服务器
2. 渠道无关：统一的内部消息格式，轻松接入任意平台
3. 安全默认：多层防护，最小权限原则，沙箱隔离
4. 可扩展性：Skills 平台 + 插件系统，功能无限扩展
5. 多 Agent 协作：内置子 Agent 系统，支持复杂任务分解
6. 模型无关：支持几乎所有主流 AI 提供商，智能故障转移

对于想深入研究 AI Agent 框架设计的开发者，OpenClaw 的源码是一份极具价值的参考实现，涵盖了从 WebSocket 协议设计、流式响应处理、工具安全策略到多 Agent 协作的完整工程实践。