核心概念
约 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.challengenonce 并需要明确审批 - 网关认证(
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 Opussonnet→ Claude Sonnetgpt→ 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"
}
]