OpenClaw 架构剖析：Gateway-first 的 AI 代理平台

AI 代理技术栈深度解析 · 第二篇

上一篇我们深入剖析了 Hermes Agent 的自学习架构，本篇将视角转向另一个主流框架——OpenClaw，揭示其 Gateway-first 设计哲学的技术实现与工程权衡。

📚 关于本系列

「AI 代理技术栈深度解析」 是一个专注于剖析现代 AI Agent 架构、实现原理与生态系统的技术专栏。

本系列其他文章：

• 📝 第一篇：Hermes Agent 深度解析（已完成）
• 📝 第二篇：OpenClaw 架构剖析（本文）
• 🔜 第三篇：Agent 安全与隔离机制（筹备中）
• 🔜 第四篇：从单代理到多代理联邦（筹备中）

一、OpenClaw 简介与发展历程

1.1 OpenClaw 的起源

OpenClaw 的故事始于一个简单而深刻的问题：如何让 AI 代理真正"可用"？

在 AI 代理技术蓬勃发展的今天，大部分方案仍停留在实验性质——要么是云端托管服务，用户数据被锁在围墙花园；要么是本地运行，但需要复杂的配置和缺乏持久化的会话管理。

Peter Steinberger（@steipete），一位深耕移动开发多年的技术专家，在 2026 年初发布了 OpenClaw。其核心理念源于一个关键洞察：

"AI 代理需要一个 Gateway——就像 Web 服务需要一个服务器。"

项目名称 "OpenClaw" 是 CLAW + TARDIS 的组合——"每一只太空龙虾都需要一个时空机器"。这个幽默的命名背后，隐藏着严肃的技术野心：构建一个能够连接时空（即时通讯历史与会话持久化）、跨越平台（多渠道统一接入）的 AI 代理控制平面。

1.2 核心定位：Gateway-first 的 AI 代理平台

OpenClaw 的核心定位可以用一句话概括：

"一个自托管的 Gateway，连接你最常用的聊天应用和 AI 代理。"

这个设计哲学包含三个关键原则：

1. Gateway-first（控制平面优先）

传统 AI 代理方案往往将"模型调用"作为核心，而忽视了连接、路由、会话管理等基础设施。OpenClaw 反转了这个优先级：

用户消息 → [Gateway] → Agent Runtime → Model Provider
                    ↓
              会话管理/路由/工具调度

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

• 多渠道消息接入（WhatsApp、Telegram、Discord、Slack 等 20+ 平台）
• 会话生命周期管理（创建、持久化、重置、清理）
• 多代理路由（按发送者、渠道、工作区隔离）
• 工具调度与审批流
• 安全边界与访问控制

2. Self-hosted（自托管）

"你的硬件，你的规则"——OpenClaw 强调数据主权和隐私控制：

• 运行在用户自有设备（本地服务器、VPS、甚至 Raspberry Pi）
• 不依赖云端托管服务
• 会话数据存储在本地文件系统
• 支持 Tailscale/VPN 安全远程访问

3. Agent-native（代理原生）

OpenClaw 专为 AI 代理设计，而非通用聊天机器人：

• 内置工具系统（浏览器控制、文件操作、代码执行等）
• 会话记忆与持久化
• 多代理协同与子代理调度
• Hooks 机制（事件驱动扩展）
• Skills 平台（技能包管理）

1.3 架构概览

┌─────────────────────────────────────────────────────────────┐
│                    消息渠道层                                │
│  WhatsApp | Telegram | Discord | Slack | Signal | iMessage  │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    Gateway (控制平面)                        │
│  WebSocket Server @ 127.0.0.1:18789                         │
│  ├─ 消息路由    ├─ 会话管理    ├─ 工具调度    ├─ 安全控制   │
│  └─ HTTP API (OpenAI Compatible)                            │
└────────────────────────────┬────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Pi Agent      │ │   Control UI    │ │   Nodes         │
│   Runtime       │ │   (Web Dashboard)│ │   (iOS/Android) │
│   ├─ Model Call │ │                 │ │   ├─ Canvas     │
│   ├─ Tool Exec  │ │                 │ │   ├─ Camera     │
│   └─ Streaming  │ │                 │ │   └─ Voice      │
└─────────────────┘ └─────────────────┘ └─────────────────┘

1.4 发展历程与重要版本

OpenClaw 采用日期式版本命名（vYYYY.M.D），反映其快速迭代节奏：

项目维护三个发布渠道：

• stable（latest）：稳定版本，推荐生产使用
• beta：预发布版本，包含新功能
• dev：开发版本，main 分支最新提交

二、Gateway 控制平面架构详解

2.1 Gateway 的核心职责

Gateway 是 OpenClaw 的"心脏"，承担以下核心职责：

2.1.1 WebSocket 服务器

Gateway 默认在 127.0.0.1:18789 启动 WebSocket 服务器，处理所有客户端连接：

• Operator Clients：CLI、Control UI、macOS App
• Nodes：iOS、Android、headless nodes
• Channels：内置渠道插件连接
• Automations：Cron jobs、Webhooks

端口配置优先级：

--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 (default)

绑定模式：

安全警告：非 loopback 绑定必须配置有效的认证路径。

2.1.2 消息路由

Gateway 实现多层级消息路由：

1. 渠道级路由

{
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: { dmPolicy: "pairing" },
    discord: { groups: { "*": { requireMention: true } } },
  },
}

2. 会话级路由

3. 代理级路由

{
  agents: {
    routing: {
      work: { channels: ["slack"], workspace: "~/.openclaw-work" },
      personal: { channels: ["telegram"], workspace: "~/.openclaw-personal" },
    },
  },
}

2.1.3 会话管理

Gateway 负责会话的完整生命周期：

会话存储路径：

~/.openclaw/agents/<agentId>/sessions/sessions.json  # 会话索引
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl  # 会话日志

会话生命周期：

1. 创建：首次消息触发，或手动创建
2. 持久化：实时写入 transcript（jsonl 格式）
3. 重置：Daily Reset（每日 4:00 AM）、Idle Reset、Manual Reset（/new 命令）
4. 清理：维护模式自动清理过期会话

2.2 三层架构：Gateway → Agent Runtime → Tools

OpenClaw 采用清晰的三层架构：

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Gateway (Control Plane)                            │
│ ├─ WebSocket Server  ├─ Session Manager  ├─ Channel Plugins │
│ ├─ HTTP API          └─ Security & Auth                     │
└────────────────────────────┬────────────────────────────────┘
                             │ RPC (Pi Protocol)
                             ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Agent Runtime (Pi)                                 │
│ ├─ Model Provider Client  ├─ Prompt Assembly                │
│ ├─ Tool Execution         ├─ Streaming & Compaction         │
│ └─ Memory & Context                                         │
└────────────────────────────┬────────────────────────────────┘
                             │ Tool Calls
                             ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Tools                                              │
│ ├─ Core: read, write, exec, canvas, browser                 │
│ ├─ Node: camera, screen.record, location.get                │
│ ├─ Channel: message.send, reactions                         │
│ ├─ Plugin: custom extensions                                │
│ └─ Skills: packaged workflows                               │
└─────────────────────────────────────────────────────────────┘

2.2.1 Layer 1: Gateway（控制平面）

Gateway 作为控制平面，不直接执行 AI 模型调用，而是协调所有组件：

进程模型：Gateway 是单进程、长生命周期服务

• 启动命令：openclaw gateway --port 18789
• 服务管理：launchd/systemd/计划任务
• 健康检查：openclaw gateway status

2.2.2 Layer 2: Agent Runtime（Pi）

Pi（由 Mario Zechner 开发）是嵌入式代理执行引擎：

核心职责：

1. Model Provider Communication：与 Anthropic、OpenAI、Google 等通信
2. Prompt Assembly：构建系统提示、技能上下文、历史消息
3. Tool Execution：执行工具调用，返回结果
4. Streaming：流式输出 assistant deltas
5. Compaction：长对话自动摘要压缩

配置示例：

{
  agents: {
    defaults: {
      model: "anthropic/claude-3.5-sonnet",
      thinking: "medium",
      timeoutSeconds: 172800,  // 48 hours
    },
  },
}

2.2.3 Layer 3: Tools（工具层）

工具是 Agent 与外部世界交互的接口：

三、多代理协作机制

3.1 多代理架构概述

OpenClaw 的多代理协作机制允许多个独立智能体在同一 Gateway 服务下并行运行，同时保持完全隔离。

Brain Isolation（大脑隔离）：每个 Agent 是一个完全独立的"大脑"，拥有：

• 独立的工作区
• 独立的状态目录
• 独立的会话存储
• 独立的认证配置

┌─────────────────────────────────────────────────────────────┐
│                          Gateway 网关                        │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
│  │  WhatsApp  │  │  Telegram  │  │  Discord   │            │
│  └───────┬────┘  └───────┬────┘  └───────┬────┘            │
│          └───────────────┴───────────────┘                  │
│                          │                                  │
│                  ┌───────┴───────┐                          │
│                  │   Bindings    │ ← 确定性路由规则          │
│                  └───────┬───────┘                          │
│          ┌───────────────┼───────────────┐                  │
│          ▼               ▼               ▼                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ Agent: main │  │ Agent: work │  │Agent: family│          │
│  │ workspace/  │  │ workspace/  │  │ workspace/  │          │
│  │ sessions/   │  │ sessions/   │  │ sessions/   │          │
│  │ auth-       │  │ auth-       │  │ auth-       │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘

3.2 多代理配置与隔离

3.2.1 Agent 定义

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Assistant",
        workspace: "~/.openclaw/workspace-main",
        agentDir: "~/.openclaw/agents/main/agent",
      },
      {
        id: "coding",
        name: "Coding Assistant",
        workspace: "~/.openclaw/workspace-coding",
        model: "anthropic/claude-opus-4-6",
        tools: {
          allow: ["read", "exec"],
          deny: ["write", "edit"],
        },
      },
    ],
  },
}

3.2.2 工作区隔离

每个 Agent 的工作区包含核心配置文件：

~/.openclaw/workspace-coding/
├── AGENTS.md          # 运行指令和行为准则
├── SOUL.md            # 人格设定和语气风格
├── USER.md            # 用户档案信息
├── TOOLS.md           # 工具使用说明
├── MEMORY.md          # 长期记忆存储
├── memory/            # 每日记忆日志
└── skills/            # 代理专属技能

关键点：

• 工作区是默认 cwd，但不是硬性沙箱
• 相对路径在工作区内解析
• 绝对路径可访问其他位置（除非启用沙箱）
• 认证配置不自动共享，需手动复制 auth-profiles.json

3.3 绑定规则与消息路由

3.3.1 确定性路由优先级

OpenClaw 使用确定性路由，按优先级匹配绑定规则：

匹配规则：

• 最具体优先
• 同层级时配置顺序决定
• 多字段匹配为 AND 语义

3.3.2 配置示例

场景：两个 WhatsApp 账户路由到两个代理

{
  agents: {
    list: [
      { id: "home", default: true },
      { id: "work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

3.4 代理间通信

OpenClaw 提供四个核心会话工具，实现代理间协作：

sessions_send 回复循环机制：

Agent:main ──sessions_send──> Agent:work
                  │
                  │ response round 1
Agent:main <───────────────── Agent:work
                  │
                  │ response round 2
Agent:main <───────────────── Agent:work
                  │
                  │ REPLY_SKIP (停止循环)
Agent:main <───────────────── Agent:work

四、节点连接与远程控制

4.1 Node 架构设计

OpenClaw 采用"Brain vs Body"分离架构：

• Brain（Gateway）：运行在服务器，负责 AI 推理和决策
• Body（Node）：运行在用户设备，负责本地交互（Canvas、Camera、Voice）

┌─────────────────┐         WebSocket         ┌─────────────────┐
│     Gateway     │ ◄───────────────────────► │      Node       │
│   (Server/VPS)  │                           │  (iOS/Android)  │
│                 │                           │                 │
│  - AI Runtime   │                           │  - Canvas       │
│  - Session Mgmt │                           │  - Camera       │
│  - Tool Dispatch│                           │  - Voice Wake   │
└─────────────────┘                           └─────────────────┘

4.2 设备配对与信任模型

配对流程：

1. 设备声明身份：Node 连接时声明设备标识
2. 挑战 - 响应认证：

   • Local connects（loopback/same-host Tailnet）→ 可自动批准
   • Non-local connects → 必须签名 challenge nonce + 显式批准
3. 设备 Token 颁发：认证成功后颁发持久化 token

配对策略配置：

{
  gateway: {
    auth: {
      allowTailscale: true,
      dmPolicy: "pairing",  // pairing | allowlist | open
    },
  },
}

4.3 Tailscale/零信任网络集成

安全远程访问方案：

# 方案 1：Tailscale 隧道
tailscale up
openclaw gateway --bind private  # 绑定到 Tailscale IP

# 方案 2：SSH 隧道
ssh -L 18789:localhost:18789 user@server
# 本地访问 localhost:18789 即可

Tailscale 配置优势：

• 自动加密通信
• 无需公网 IP
• 细粒度访问控制（ACL）
• 设备身份验证

4.4 Exec 节点绑定

当多个节点可用时，可绑定 exec 到特定节点：

# 全局默认
openclaw config set tools.exec.node "node-id-or-name"

# 每代理覆盖
openclaw config set --agent coding tools.exec.node "macbook-pro"

五、安全框架与权限管理

5.1 认证机制

OpenClaw 支持多种认证方式：

认证配置：

{
  gateway: {
    auth: {
      allowList: ["+15555550123"],  // 允许的用户
      requireAuth: true,             // 强制认证
      tokenExpiry: "30d",            // Token 有效期
    },
  },
}

5.2 访问控制

5.2.1 命令白名单

{
  tools: {
    exec: {
      policy: "ask",  // ask | deny | allow
      allowList: [
        "git status",
        "git diff",
        "npm test",
        "docker ps",
      ],
      denyList: [
        "rm -rf",
        "sudo *",
        "curl * | bash",
      ],
    },
  },
}

5.2.2 文件系统限制

{
  tools: {
    read: {
      allowPaths: [
        "~/.openclaw/workspace/**",
        "/home/user/projects/**",
      ],
      denyPaths: [
        "/etc/**",
        "/root/**",
        "~/.ssh/**",
      ],
    },
  },
}

5.3 安全最佳实践

5.3.1 网络绑定

关键原则：默认绑定 localhost，非本地访问使用安全隧道

# ✅ 推荐：localhost 绑定 + SSH 隧道
openclaw gateway --bind 127.0.0.1
ssh -L 18789:localhost:18789 user@server

# ❌ 避免：直接公网绑定
openclaw gateway --bind 0.0.0.0  # 危险！

5.3.2 安全审计

# 运行安全审计
openclaw security audit

# 检查项包括：
# - 非 localhost 绑定
# - 未加密的远程连接
# - 过宽的 exec 权限
# - 缺失的认证配置

5.3.3 凭证管理

使用 SecretRef 安全存储凭证：

{
  agents: {
    defaults: {
      model: "anthropic/claude-3.5-sonnet",
      auth: {
        apiKey: "${ANTHROPIC_API_KEY}",  // 环境变量
      },
    },
  },
}

六、与 Hermes 的对比与选型

6.1 设计哲学对比

6.2 架构差异详解

OpenClaw 架构：
┌─────────────────────────────────────┐
│         Gateway (控制平面)           │
│  ┌───────┬───────┬───────┬───────┐ │
│  │Channel│Session│ Tool  │ Auth  │ │
│  └───────┴───────┴───────┴───────┘ │
└─────────────────┬───────────────────┘
                  │ RPC
                  ▼
         ┌─────────────────┐
         │  Agent Runtime  │
         │    (Pi Engine)  │
         └─────────────────┘

Hermes 架构：
┌─────────────────────────────────────┐
│      AIAgent Core (学习循环)         │
│  Execute → Evaluate → Extract → ... │
└─────────────────┬───────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐  ┌────────┐   ┌─────────┐
│Gateway │  │ Memory │   │ Skills  │
│Interface│  │ System │   │ System  │
└────────┘  └────────┘   └─────────┘

6.3 如何选择？

选择 OpenClaw，如果：

• ✅ 需要管理多个独立代理（工作/家庭/项目隔离）
• ✅ 需要统一接入多个消息平台
• ✅ 重视会话管理和路由控制
• ✅ 企业级部署，需要审计和访问控制
• ✅ 需要远程控制（Node 架构）

选择 Hermes Agent，如果：

• ✅ 想要一个能自我改进的个人助手
• ✅ 重视学习能力和技能自动进化
• ✅ 单代理场景，不需要复杂路由
• ✅ 快速原型开发，简单配置即可用
• ✅ 研究用途（工具调用训练、行为评估）

6.4 混合部署方案

实际上，OpenClaw 和 Hermes 可以互补使用：

┌─────────────────────────────────────────┐
│           OpenClaw Gateway              │
│  (多代理路由、会话管理、渠道接入)         │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐   ┌────────┐   ┌─────────┐
│ Hermes │   │ Hermes │   │  Pi     │
│ Agent  │   │ Agent  │   │ Agent   │
│(学习)  │   │(学习)  │   │(原生)   │
└────────┘   └────────┘   └─────────┘

方案优势：

• OpenClaw 提供统一 Gateway 和路由
• Hermes 提供自学习能力
• Pi Agent 提供轻量级执行

七、总结

OpenClaw 的核心价值

1. Gateway-first 架构：将连接、路由、会话管理等基础设施作为核心，而非事后补充
2. 多代理协作：完善的代理隔离、绑定规则、Agent-to-Agent 通信机制
3. Node 架构：Brain/Body 分离，支持安全的远程设备访问
4. 企业级特性：审计、访问控制、凭证管理、高可用部署

与 Hermes 的互补关系

• OpenClaw：提供代理运行基础设施、多代理协作、渠道统一接入
• Hermes：提供智能决策能力、自学习机制、技能自动进化

两者共同推动 AI 代理从"对话伙伴"到"执行伙伴"的演进。

对开发者的启示

• 架构选择决定产品形态：Gateway-first vs Agent-first 是不同的技术路线，各有优劣
• 安全是第一位：自托管不等于不安全，需要多层防护（认证、授权、审计、隔离）
• 开放生态是关键：Plugin/Skills 平台让社区贡献成为可能
• 工程化思维：AI 代理不仅是模型调用，更是系统工程

下一篇预告：《Agent 安全与隔离机制》——深入探讨 AI 代理的安全框架、沙箱技术、提示注入防御等关键议题。

本文基于 OpenClaw 官方文档（v2026.4.12）及社区技术分析整理，技术细节以官方发布为准。

参考资料：

• OpenClaw 官方文档：https://docs.openclaw.ai^[1]
• OpenClaw GitHub：https://github.com/openclaw/openclaw^[2]
• OpenClaw Discord 社区：https://discord.gg/clawd^[3]

引用链接