第二章：核心概念

约 1487 字大约 5 分钟

本章介绍 OpenClaw 的系统架构、核心组件和多智能体路由机制，帮助你理解 OpenClaw 如何工作。

2.1 系统架构概览

OpenClaw 采用 单网关（Gateway）+ 多客户端 的架构模型。

                   ┌─────────────────────────────────────────┐
                   │              Gateway（守护进程）           │
                   │                                         │
消息渠道 ──────────►│  WhatsApp / Telegram / Discord / Signal │
                   │                                         │
                   │  WebSocket API (默认端口 18789)          │
                   └──────────────┬──────────────────────────┘
                                  │
              ┌───────────────────┼───────────────────┐
              ▼                   ▼                   ▼
        macOS 菜单栏应用       CLI 工具           Web 控制台
        iOS / Android 节点     自动化脚本         (控制界面)

核心组件

Gateway（网关守护进程）

统一管理所有消息渠道（WhatsApp、Telegram、Discord、Signal、iMessage 等）
通过 WebSocket 暴露 API（请求/响应/事件推送）
使用 JSON Schema 验证入站数据
发送事件：agent、chat、presence、health、heartbeat、cron
每台机器只能运行一个 Gateway

Clients（客户端）

连接到 Gateway 的控制端：

macOS 菜单栏应用
CLI 命令行工具（openclaw 命令）
Web 控制台（浏览器界面）

每个客户端维护一个 WebSocket 连接，可发送请求并订阅事件。

Nodes（节点）

节点是通过 WebSocket 连接到同一 Gateway 的设备扩展：

macOS 节点（菜单栏伴侣应用）
iOS 节点（手机应用）
Android 节点（手机应用）
Headless 节点（无头服务器）

节点声明 role: node，提供额外能力：

canvas.* — Canvas 界面渲染
camera.* — 摄像头访问
screen.record — 屏幕录制
location.get — 地理位置

WebChat

内置的 Web 聊天界面，通过 Gateway WebSocket API 运作，支持聊天历史和消息发送。

2.2 通信协议

OpenClaw 使用 WebSocket + JSON 进行所有内部通信。

连接握手

客户端连接后，第一帧必须是 connect
Gateway 返回 hello-ok（包含状态快照、健康信息、版本号等）
之后正常通信

消息格式

// 请求（客户端 → 网关）
{"type": "req", "id": "abc123", "method": "health", "params": {}}

// 响应（网关 → 客户端）
{"type": "res", "id": "abc123", "ok": true, "payload": {...}}

// 事件（网关 → 客户端，主动推送）
{"type": "event", "event": "agent", "payload": {...}, "seq": 42}

身份验证

若设置了 OPENCLAW_GATEWAY_TOKEN，connect 帧中的 auth.token 必须匹配
所有连接需签名 connect.challenge nonce
本地连接（loopback）可配置自动信任

2.3 功能特性全览

类别	功能
消息渠道	WhatsApp (Baileys)、Telegram (grammY)、Discord、Slack、Signal、iMessage
智能体	Pi 智能体 RPC 模式，支持工具流式调用
会话管理	多智能体路由、按发送者隔离会话
媒体	图片/音频/文档的收发，可选语音转文字
界面	WebChat、macOS 菜单栏、iOS/Android 节点应用
订阅授权	Anthropic、OpenAI OAuth 认证
群组	群聊支持，@提及激活
流式输出	长响应自动分块发送

2.4 多智能体（Multi-Agent）路由

什么是"一个智能体"

每个智能体（Agent）是一个独立的"大脑"，拥有：

组件	说明
工作区（Workspace）	独立的文件目录，含 `SOUL.md`、`AGENTS.md`、记忆文件
状态目录（agentDir）	认证配置、模型注册、每智能体配置
会话存储	独立的聊天历史和路由状态

重要：不同智能体的 agentDir 不能共用，否则会导致认证/会话冲突。

路径结构

~/.openclaw/
├── openclaw.json              # 主配置文件
├── workspace/                 # 默认智能体工作区
├── agents/
│   ├── main/
│   │   ├── agent/             # 主智能体状态目录（agentDir）
│   │   └── sessions/          # 会话记录
│   ├── work/
│   │   ├── agent/
│   │   └── sessions/
│   └── ...
└── credentials/               # 渠道认证（WhatsApp 等）

创建多个智能体

# 添加新智能体（向导引导）
openclaw agents add work
openclaw agents add coding

# 查看所有智能体及绑定关系
openclaw agents list --bindings

2.5 路由规则（Bindings）

Bindings（绑定）决定消息如何路由到对应的智能体。

优先级（从高到低）

peer 精确匹配（特定 DM 或群组 ID）
parentPeer 匹配（线程继承）
guildId + roles（Discord 角色路由）
guildId（Discord 服务器）
teamId（Slack 工作区）
accountId 匹配（特定渠道账户）
渠道级匹配（accountId: "*"）
默认智能体（fallback）

基本绑定示例

{
  "agents": {
    "list": [
      {"id": "main", "workspace": "~/.openclaw/workspace-main"},
      {"id": "work", "workspace": "~/.openclaw/workspace-work"}
    ]
  },
  "bindings": [
    // Telegram 路由到 main
    {"agentId": "main", "match": {"channel": "telegram"}},
    // WhatsApp 路由到 work
    {"agentId": "work", "match": {"channel": "whatsapp"}}
  ]
}

2.6 多智能体场景示例

场景一：按渠道分流（日常聊天 vs 深度工作）

{
  "agents": {
    "list": [
      {
        "id": "chat",
        "name": "日常助手",
        "workspace": "~/.openclaw/workspace-chat",
        "model": "anthropic/claude-sonnet-4-5"
      },
      {
        "id": "opus",
        "name": "深度工作",
        "workspace": "~/.openclaw/workspace-opus",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  },
  "bindings": [
    {"agentId": "chat", "match": {"channel": "whatsapp"}},
    {"agentId": "opus", "match": {"channel": "telegram"}}
  ]
}

场景二：同一 WhatsApp，不同人对应不同智能体

{
  "agents": {
    "list": [
      {"id": "alex", "workspace": "~/.openclaw/workspace-alex"},
      {"id": "mia", "workspace": "~/.openclaw/workspace-mia"}
    ]
  },
  "bindings": [
    {
      "agentId": "alex",
      "match": {"channel": "whatsapp", "peer": {"kind": "direct", "id": "+15551230001"}}
    },
    {
      "agentId": "mia",
      "match": {"channel": "whatsapp", "peer": {"kind": "direct", "id": "+15551230002"}}
    }
  ],
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551230001", "+15551230002"]
    }
  }
}

场景三：多个 WhatsApp 号码（个人 + 工作）

# 先配对各个账户
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

{
  "agents": {
    "list": [
      {"id": "home", "default": true, "workspace": "~/.openclaw/workspace-home"},
      {"id": "work", "workspace": "~/.openclaw/workspace-work"}
    ]
  },
  "bindings": [
    {"agentId": "home", "match": {"channel": "whatsapp", "accountId": "personal"}},
    {"agentId": "work", "match": {"channel": "whatsapp", "accountId": "biz"}}
  ],
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": {},
        "biz": {}
      }
    }
  }
}

场景四：家庭群组专属智能体（限制工具权限）

{
  "agents": {
    "list": [
      {
        "id": "family",
        "name": "家庭助手",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {"mode": "all", "scope": "agent"},
        "tools": {
          "allow": ["exec", "read", "sessions_list"],
          "deny": ["write", "edit", "browser", "canvas"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "channel": "whatsapp",
        "peer": {"kind": "group", "id": "120363999999999999@g.us"}
      }
    }
  ]
}

2.7 每智能体沙箱与工具权限

从 v2026.1.6 起，每个智能体可以有独立的沙箱和工具限制：

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": {"mode": "off"}
      },
      {
        "id": "restricted",
        "workspace": "~/.openclaw/workspace-restricted",
        "sandbox": {
          "mode": "all",
          "scope": "agent",
          "docker": {
            "setupCommand": "apt-get update && apt-get install -y git curl"
          }
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit"]
        }
      }
    ]
  }
}

优势

安全隔离：为不可信智能体限制工具权限
资源控制：按需启用沙箱
灵活策略：每个智能体独立权限配置

2.8 远程访问

推荐方式：Tailscale（详见第五章）

配置 Tailscale VPN 后，可从任何网络安全访问 Gateway。

SSH 隧道

ssh -N -L 18789:127.0.0.1:18789 user@your-server

配置相同的握手和认证 Token 即可通过隧道连接。

TLS 加密

可为远程场景启用 WebSocket TLS 和可选的证书固定（pinning）。

2.9 下一步

第三章：平台与渠道 — 配置各平台接入
第四章：工具与功能 — 了解智能体可用工具
第五章：网关配置 — 深入 Gateway 运维