第二章:核心概念
约 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.challengenonce - 本地连接(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 --bindings2.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)。
