OpenClaw 架构全解析：本地优先的开源 AI Agent 框架

🦞 OpenClaw 架构全解析：本地优先的开源 AI Agent 框架

OpenClaw（前身 Clawdbot/Moltbot）是一个开源的、本地优先（Local-First）的 AI Agent 框架，310k+ GitHub Stars，MIT 许可证。不同于只能在网页里聊天的 ChatGPT，OpenClaw 是一个能接管你键盘和鼠标权限的超级助理，直接调用系统 API 完成复杂自动化任务。

---

一、系统分层架构：多入口、单内核

OpenClaw 的整体架构可以理解为 "多入口、单内核"的运行时模型，共分为五层：

层级	名称	职责
①	入口层 (Ingress)	WhatsApp / Telegram / Discord / iMessage / Webhook / Cron 定时任务
②	控制平面 (Control Plane)	Gateway 网关（唯一事实源）--- 会话管理、消息路由、API 接口
③	执行平面 (Execution Plane)	Pi 智能体（RPC 模式）、技能系统、Run 执行单元（含重试）
④	能力层 (Capability Layer)	浏览器自动化、Shell 执行、HTTP 调用、多模型提供商
⑤	数据层 (Data Layer)	Markdown/YAML 本地文件、日志审计追踪

┌─────────────────────────────────────────────────────────────┐
│  ① 入口层：WhatsApp / Telegram / Discord / Webhook / Cron   │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  ② 控制平面：Gateway 网关（单进程，Single Source of Truth） │
│     SessionKey 会话管理 | WebSocket :18789 | Token 认证     │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  ③ 执行平面：Pi 智能体（RPC）| Skills 技能系统 | Run 单元   │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  ④ 能力层：浏览器自动化 | Shell | HTTP | Claude/GPT/Ollama  │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  ⑤ 数据层：Markdown 对话历史 | YAML 配置 | 日志审计         │
└─────────────────────────────────────────────────────────────┘

---

二、三大核心设计哲学

OpenClaw 在 2025 年迅速走红，核心原因不在于模型本身，而在于三个关键的架构决策：

1. 💾 本地优先（Local-First）

• 所有数据（对话历史、记忆、配置）均以纯文本文件（Markdown + YAML）存储在本地机器上
• 无需云端编排，数据完全由用户控制
• 支持 Git 版本管理，可回溯任意历史状态
• 可选的"心跳"守护进程，支持定时主动唤醒 Agent

2. 💬 消息应用即界面

• 不提供独立的 Web 应用或自定义 UI
• 直接集成到用户日常使用的消息平台（WhatsApp、Telegram、Signal、Discord、Slack、iMessage）
• 用户无需学习新工具，Agent 在最熟悉的沟通环境中直接运行

3. 🔌 真正的模型无关（Model-Agnostic）

• 模型被视为可互换的商品化模块
• 支持：Claude、GPT、DeepSeek、Qwen、通过 Ollama 运行的本地 Llama 等
• 用户自带 API Key，无额外订阅费用，无供应商锁定

---

三、核心组件详解

3.1 Gateway 网关 --- 系统的心脏

Gateway 是 OpenClaw 的单一事实源（Single Source of Truth），作为单进程长期运行。

主要职责：

• 管理所有渠道连接的生命周期
• 提供 WebSocket / HTTP API 接口（默认端口：ws://127.0.0.1:18789）
• 强制执行安全边界（Token 验证、配对机制）
• 协调会话并发控制（Lane + Queue 模型）

3.2 SessionKey 会话系统 --- 并发控制核心

相同 SessionKey → 串行处理（保证顺序，避免混乱）
不同 SessionKey → 并行处理（提升吞吐，互不干扰）

SessionKey 由账户 / 群组 / 线程上下文构建，是 OpenClaw 实现精确并发控制的核心机制。

3.3 Pi 智能体 --- 执行单元

默认智能体，通过 RPC 协议与 Gateway 交互。

• 接管键盘、鼠标、系统 API 权限
• 能力：浏览器自动化、Shell 命令执行、HTTP 调用
• 支持流式输出和自动重试（Run 执行单元）
• 通过技能系统（Skills）扩展能力边界

3.4 技能系统（Skills）--- 病毒传播的秘密

技能是 OpenClaw 社区爆发的核心驱动力，本质是可重复的自动化工作流。

• 定义方式：Markdown 或 TypeScript
• 社区注册表：ClawHub
• 支持：安装、分享、自定义第三方技能
• ⚠️ 安全风险：类似 npm 供应链问题，第三方技能可能存在未授权数据外泄、提示注入等风险，且由于 Agent 能访问邮件、Shell、日历，潜在危害更大

---

四、消息处理完整流程

用户发消息（WhatsApp/Telegram）
        ↓
① Ingress --- 渠道接收消息 / Webhook / Cron 触发
        ↓
② 协议适配 --- Gateway 进行渠道协议转换
        ↓
③ 路由构建 --- 根据账户/群组/线程构建唯一 sessionKey
        ↓
④ 并发控制 --- 按 sessionKey 进入 Lane/Queue 队列
        ↓
⑤ 智能体执行 --- Pi 通过 RPC 接收，启动 Run 执行单元
               （工具调用 + 流式输出 + 自动重试）
        ↓
⑥ 结果回传 --- 经 Gateway 路由，通过原渠道返回用户

---

五、网络模型与部署策略

访问方式	说明
本地默认	ws://127.0.0.1:18789，安全隔离
LAN 局域网	同内网移动设备直接连接 Gateway IP
Tailnet	通过 Tailscale 实现跨网安全隧道（推荐）
SSH 隧道	通过 SSH 端口转发访问远程 Gateway
多实例隔离	通过环境变量 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR 区分

每台主机只部署一个 Gateway，避免多实例冲突（如 WhatsApp Web 会话独占）

---

六、安全架构

OpenClaw 采用分层安全控制：

层级	机制
入口边界	allowFrom 白名单、群聊 @mention 过滤、Token 验证
执行边界	沙箱隔离、工具策略（Tool Policy）、执行审批机制
审计能力	完整日志记录，runId 追踪完整执行链路，openclaw doctor 诊断
数据安全	所有数据本地存储，无需上传云端，用户完全掌控数据主权

---

七、核心配置示例

// ~/.openclaw/openclaw.json
{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],     // 白名单：仅接受此号码
      "groups": {
        "*": { "requireMention": true }  // 群聊需 @机器人 才响应
      }
    },
    "telegram": {
      "token": "<BOT_TOKEN>"
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  },
  "agent": {
    "model": "claude-3-5-sonnet",        // 可替换为 gpt-4o / deepseek 等
    "apiKey": "<YOUR_API_KEY>"
  }
}

---

八、快速上手

# 1. 安装（需要 Node.js ≥ 22）
npm install -g openclaw@latest

# 2. 一键初始化并注册为系统服务
openclaw onboard --install-daemon

# 3. 登录消息渠道
openclaw channels login

# 4. 手动启动 Gateway（开发调试）
openclaw gateway --port 18789

# 5. 多实例隔离运行（测试用）
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

# 6. 系统诊断
openclaw doctor

---

总结

OpenClaw 不是"更聪明的聊天工具"，而是一套消息驱动的自动化系统入口。

它的成功揭示了一个重要趋势：AI 时代，模型正在商品化，真正创造价值的是围绕模型构建的"架构套件" --- 编排层、界面层、扩展系统和信任模型。

工程价值	说明
明确的 Gateway 架构	集中管控消息流、状态和调度
本地优先设计	数据主权完全归用户所有
真正的模型无关性	无供应商锁定风险
消息应用即界面	零学习成本的交互体验
SessionKey 并发控制	相同会话串行 / 不同会话并行
技能系统生态	社区共建，但需关注供应链安全

---

参考资料：

• OpenClaw 官方文档
• OpenClaw 系统架构
• 深入OpenClaw网关：架构解析 - 腾讯云开发者社区
• OpenClaw: Anatomy of a viral open source AI agent