核心概念

约 1914 字大约 6 分钟

架构设计

概览

单个长期运行的 Gateway 拥有所有消息通道（WhatsApp via Baileys、Telegram via grammY、Slack、Discord、Signal、iMessage、WebChat）
控制面板客户端（macOS 应用、CLI、Web UI、自动化）通过 WebSocket 连接到网关，默认绑定 127.0.0.1:18789
节点（macOS/iOS/Android/headless）也通过 WebSocket 连接，但声明 role: node 及明确的能力/命令
每台主机一个网关；它是唯一打开 WhatsApp 会话的地方
Canvas 主机（默认 18793）提供智能体可编辑的 HTML 和 A2UI

组件和流程

Gateway（守护进程）

维护 provider 连接
暴露类型化的 WS API（请求、响应、服务器推送事件）
根据 JSON Schema 验证入站帧
发出事件如 agent、chat、presence、health、heartbeat、cron

客户端（Mac 应用 / CLI / Web 管理）

每个客户端一个 WS 连接
发送请求（health、status、send、agent、system-presence）
订阅事件（tick、agent、presence、shutdown）

节点（macOS / iOS / Android / headless）

连接到同一 WS 服务器，带 role: node
在 connect 中提供设备身份；配对是基于设备的（角色 node），审批存储在设备配对存储中
暴露命令如 canvas.*、camera.*、screen.record、location.get

WebChat

静态 UI，使用网关 WS API 进行聊天历史和发送
远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接

连接生命周期（单客户端）

Client                          Gateway
  |                               |
  |---- req:connect ------------>|
  |
  |  (payload=hello-ok 携带快照: presence + health)
  |                               |
  |
  |
  |                               |
  |------- req:agent ----------->|
  |
  |
  |

线协议（摘要）

传输：WebSocket，文本帧带 JSON 负载
第一帧必须是 connect
握手后：请求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
事件：{type:"event", event, payload, seq?, stateVersion?}
如果设置了 OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则套接字关闭
副作用方法（send、agent）需要幂等键以安全重试；服务器保持短期去重缓存
节点必须在 connect 中包含 role: "node" 及 caps/commands/permissions

配对与本地信任

所有 WS 客户端（操作员 + 节点）在 connect 时包含设备身份
新设备 ID 需要配对审批；网关为后续连接颁发设备 token
本地连接（回环或网关主机自己的 tailnet 地址）可以自动审批以保持同主机 UX 流畅
非本地连接必须签署 connect.challenge nonce 并需要明确审批
网关认证（gateway.auth.*）仍适用于所有连接，本地或远程

远程访问

首选：Tailscale 或 VPN
替代：SSH 隧道

ssh -N -L 18789:127.0.0.1:18789 user@host

隧道上应用相同的握手 + 认证 token
远程设置中可以启用 TLS + 可选固定

操作快照

启动：openclaw gateway（前台，日志到 stdout）
健康：通过 WS 的 health（也包含在 hello-ok 中）
监督：launchd/systemd 用于自动重启

不变量

每台主机正好一个 Gateway 控制单个 Baileys 会话
握手是必需的；任何非 JSON 或非 connect 的第一帧都会硬关闭
事件不重放；客户端必须在间隙时刷新

智能体Agent

智能体是 OpenClaw 的核心组件，负责处理用户消息并生成响应。

概述

每个智能体具有：

工作区 - 文件存储和工作目录
会话 - 对话历史和上下文
记忆 - 长期知识存储
模型配置 - 使用的 AI 模型
工具 - 可用的能力和技能

智能体配置

智能体配置在 openclaw.json 中：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514"
      },
      "workspace": "~/.openclaw/workspace"
    }
  }

多智能体

OpenClaw 支持多智能体配置：

## 添加新智能体
openclaw agents add my-agent --workspace ~/my-workspace

## 列出智能体

每个智能体可以有：

独立的工作区
独立的模型配置
独立的会话存储
绑定到不同的通道

智能体工作流

接收消息 - 从通道接收用户消息
加载上下文 - 加载会话历史和记忆
构建提示 - 组装系统提示词和用户消息
调用模型 - 发送到 AI 模型
处理响应 - 解析模型输出，执行工具调用
发送响应 - 返回给用户

会话Session

会话存储对话历史和上下文状态。

概述

每个会话包含：

消息历史 - 用户和助手的消息
工具调用记录 - 工具调用和结果
元数据 - 创建时间、最后活跃时间等

会话键

会话通过键标识：

main - 默认 DM 会话
group:xxx - 群组会话
thread:xxx - 线程会话

会话存储

会话存储在 ~/.openclaw/agents/>/sessions/。

会话管理

开始新会话

/new

查看会话

openclaw sessions

会话自动压缩

当上下文超过模型限制时，会话自动压缩。参见压缩。

配置

{
  "sessions": {
    "dmPolicy": "collapse",
    "groupPolicy": "isolate"
  }

collapse - DM 合并到 main 会话
isolate - 每个对话独立会话

会话裁剪

旧会话可以自动裁剪以节省空间。参见会话裁剪。

记忆Memory

记忆系统提供长期知识存储和语义检索。

概述

记忆存储在工作区的 markdown 文件中：

MEMORY.md - 主记忆文件
memory/*.md - 额外记忆文件

记忆类型

显式记忆

用户或智能体明确保存的信息：

请记住我的 API 密钥是 xxx

自动记忆

智能体自动提取和保存的重要信息。

语义搜索

记忆支持向量语义搜索：

## 查看索引状态
openclaw memory status

## 重建索引
openclaw memory index

## 搜索
openclaw memory search "我的偏好设置"

记忆文件格式

## 用户偏好

- 喜欢简洁的回复
- 使用中文交流
- 时区：Asia/Shanghai

## 项目信息

### 项目 A
- 技术栈：React + Node.js
- 仓库：https://github.com/xxx/project-a

### 项目 B
- 技术栈：Python + FastAPI

配置

{
  "memory": {
    "enabled": true,
    "autoIndex": true,
    "maxEntries": 1000
  }

最佳实践

结构化存储 - 使用标题和列表组织
定期清理 - 删除过时信息
分类存储 - 使用 memory/ 目录分类

模型Models

OpenClaw 支持多种 AI 模型提供商。

支持的提供商

Anthropic - Claude 系列
OpenAI - GPT 系列、Codex
Google - Gemini 系列
OpenRouter - 多模型聚合
本地模型 - LM Studio、Ollama 等

模型配置

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514",
        "fallbacks": ["openai/gpt-4o"]
      }
    }
  }

设置模型

## 设置默认模型
openclaw models set anthropic/claude-sonnet-4-20250514

## 查看模型状态
openclaw models status

## 列出可用模型
openclaw models list

模型别名

可以定义简短别名：

## 添加别名
openclaw models aliases add sonnet anthropic/claude-sonnet-4-20250514

## 列出别名
openclaw models aliases list

内置别名：

opus → Claude Opus
sonnet → Claude Sonnet
gpt → GPT-4o

故障转移

配置备用模型：

## 添加故障转移模型
openclaw models fallbacks add openai/gpt-4o

## 列出故障转移
openclaw models fallbacks list

动态切换

在聊天中切换：

/model sonnet

多智能体路由

OpenClaw 支持多智能体配置，将不同的消息路由到不同的智能体。

概述

多智能体路由允许：

不同用户使用不同智能体
不同通道使用不同智能体
不同任务使用不同模型

配置示例

{
  "agents": {
    "entries": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "model": {
          "primary": "anthropic/claude-sonnet-4-20250514"
        }
      },
      "coding": {
        "workspace": "~/.openclaw/workspace-coding",
        "model": {
          "primary": "anthropic/claude-opus-4-20250514"
        }
      }
    },
    "routing": [
      {
        "match": {
          "channel": "telegram",
          "accountId": "coding-bot"
        },
        "agentId": "coding"
      }
    ]
  }

路由规则

路由可以基于：

通道 - WhatsApp、Telegram、Discord 等
账户 - 通道账户 ID
发送者 - 用户 ID 或电话号码
群组 - 群组 ID

添加智能体

## 交互式添加
openclaw agents add

## 带参数添加
openclaw agents add coding --workspace ~/coding-workspace --model anthropic/claude-opus-4-20250514

## 绑定到通道
openclaw agents add work --bind telegram:work-bot --bind discord:work

列出智能体

## 列出所有智能体
openclaw agents list

## 显示绑定
openclaw agents list --bindings

使用场景

按用户分离

不同用户使用独立的工作区和会话：

{
  "routing": [
    {
      "match": { "sender": "+15551234567" },
      "agentId": "user-alice"
    },
    {
      "match": { "sender": "+15559876543" },
      "agentId": "user-bob"
    }
  ]

按任务分离

聊天和编程使用不同模型：

{
  "routing": [
    {
      "match": { "channel": "telegram", "accountId": "chat" },
      "agentId": "fast-chat"
    },
    {
      "match": { "channel": "telegram", "accountId": "code" },
      "agentId": "opus-coding"
    }
  ]