跟我一起学 OpenClaw 核心概念入门

OpenClaw 看起来复杂，但其实有一套清晰的设计哲学。Gateway 架构- 它如何管理所有消息Session 管理- 它如何维护对话状态Memory 系统- 它如何让 Agent 记忆Multi-Agent 路由- 它如何支持多个 Agent 独立工作这些概念像四根柱子，撑起整个 OpenClaw 的天空。每个 Agent 有独立的 AGENTS.md、SOUL.md（人格）独立的 auth

arvin_xiaoting

487人浏览 · 2026-03-13 13:09:34

arvin_xiaoting · 2026-03-13 13:09:34 发布

深度学习笔记 | 创建于 2026-03-07 | 难度：⭐⭐⭐ 入门

本文是一份从零开始学 OpenClaw 的深度指南。如果你想理解 OpenClaw 的架构设计，而不仅仅是用它，这篇文章就是为你写的。

前言：为什么先学核心概念

OpenClaw 看起来复杂，但其实有一套清晰的设计哲学。要真正理解它，我们需要从根本上认识它的四个"心脏"：

Gateway 架构 - 它如何管理所有消息
Session 管理 - 它如何维护对话状态
Memory 系统 - 它如何让 Agent 记忆
Multi-Agent 路由 - 它如何支持多个 Agent 独立工作

这些概念像四根柱子，撑起整个 OpenClaw 的天空。

一、Gateway 架构：消息流的中心枢纽

问题：为什么需要 Gateway？

想象你同时在用 WhatsApp、Telegram、Discord、Feishu 等多个平台。每个平台的 API 都不一样。如果 AI Agent 要回复所有消息，是不是得：

学会每个平台的 API
维护每个平台的连接
处理每个平台的消息格式
管理多个登录状态…

这太复杂了！

方案：一个 Gateway 统一管理

OpenClaw 的设计很聪明——用一个 Gateway 充当中间人：

多个信道连接              Agent 在这里
  ↓                         ↓
WhatsApp ─\
Discord   ├─→ Gateway ──→ Agent Logic ──→ 工具执行
Telegram─/                   ↑
Feishu  ─\                   │
         / User Interface    │
         (macOS App)        └─ 回复消息
Web UI ─┤
CLI    ─┘

Gateway 的三个角色：

消息集线器：汇聚所有信道的消息
API 翻译器：把不同平台的消息转成统一格式给 Agent
连接管理器：一个 Gateway 维护所有信道、一个 Baileys 会话

关键设计：单 Gateway 原则

一个主机 = 一个 Gateway 实例

好处：
- 状态集中管理，不用同步
- 一个 WhatsApp 会话（Baileys 只支持一个）
- 所有 Agent 共享一个网关

限制：
- 一台机器上只能跑一个 Gateway
- 要多个 Gateway，用多台主机

为什么用 WebSocket 而不是 HTTP？

✅ 双向通信（Gateway 可以推送事件）
✅ 长连接（实时性好）
✅ 低开销（比 HTTP 轮询高效）

Wire Protocol（协议详解）

第一帧必须是 connect（握手）：

→ 客户端：
{
  "type": "connect",
  "params": {
    "deviceId": "my-mac",
    "auth": { "token": "optional" },
    "challenge": "nonce-value"
  }
}

← Gateway：
{
  "type": "res",
  "ok": true,
  "payload": {
    "status": "hello-ok",
    "health": { ... },
    "snapshot": { ... }
  }
}

握手后，标准请求-响应流程：

→ 请求：
{ "type": "req", "id": "id1", "method": "agent", "params": { ... } }

← 响应（可能多帧）：
{ "type": "event", "event": "agent", "payload": { ... } }
{ "type": "event", "event": "agent", "payload": { ... } }
{ "type": "res", "id": "id1", "ok": true, "payload": { ... } }

二、Session 管理：对话连续性的魔法

问题：如何维护对话上下文？

你在 WhatsApp 问 AI 一个问题，第二天在 Telegram 问相关的问题。AI 应该记得昨天的内容吗？

OpenClaw 的答案：取决于你的配置。

Session 的四个隔离级别

dmScope 配置项决定了 DM 的隔离方式：

级别	说明	Session Key
`main`	所有 DM 共享	agent:main:main
`per-peer`	按发送者隔离	agent:main:dm:alice
`per-channel-peer` ⭐	按信道+发送者隔离	agent:main:whatsapp:dm:alice
`per-account-channel-peer`	按账户+信道+发送者隔离	agent:main:whatsapp:default:dm:alice

⭐ 推荐：多人环境使用 per-channel-peer（完全隔离，安全性最高）

多人 DM 的安全陷阱

不安全的配置（dmScope: "main"）：

Alice:  "我下周要辞职，这是秘密"
        ↓
        共享 Session

Bob:    "我们最近讨论了什么？"
        ↓
        Model 可能用 Alice 的内容回答！🚨

解决方案：使用 per-channel-peer 隔离。

Session 生命周期：三种重置策略

1. Daily Reset（按天重置）：每天凌晨 4 点清空历史，隐私好

2. Idle Reset（按空闲重置）：2 小时没消息就重置

3. Per-Type Override：不同类型的聊天用不同策略

Session 维护策略

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "30d",
      "maxEntries": 500,
      "maxDiskBytes": "1gb",
      "highWaterBytes": "800mb"
    }
  }
}

工作流程：

写入 Session
  ↓
检查大小是否超限
  ↓
触发维护：
  1. 删除 30 天前的旧 Session
  2. 如果超过 500 个，删除最旧的
  3. 如果超过 1GB，按优先级删除
  4. 归档已删除的转录文件

三、Memory 系统：让 Agent 能记住东西

问题：Context Window 是有限的

一个 Model 的 Context Window 有上限。比如 Claude 的 context 是 200K tokens。如果对话已经 100K tokens 了，新对话会挤掉旧的。

怎么办？Agent 需要"长期记忆"。

Memory = Markdown 文件

OpenClaw 的记忆系统很简单：就是纯文本 Markdown 文件。

~/.openclaw/workspace/
├── MEMORY.md
└── memory/
    ├── 2026-03-07.md
    ├── 2026-03-06.md
    └── projects.md

分层设计：

层级	文件	作用
长期	`MEMORY.md`	核心记忆
短期	`memory/YYYY-MM-DD.md`	日志
参考	`memory/*.md`	笔记

Memory Search：语义搜索

不只是关键词搜索，而是语义搜索。

Agent 问："我家网络怎么配置的？"
Markdown 里："Omada 路由器，192.168.1.1，VLAN 10"

搜索能找到，因为语义相似！

背后原理：

把文本分段（~400 tokens）
转成向量（embedding）
用向量相似度搜索

混合搜索（Hybrid Search）

Vector 分数：0.8（语义相似度）
BM25 分数：0.95（关键词匹配）
最终分数：0.7×0.8 + 0.3×0.95 = 0.845

优势：既能捕捉语义，又能精确匹配硬数字。

高级特性

MMR（多样性排序）：保证搜索结果的多样性，不会重复

时间衰减（Temporal Decay）：最近的记忆权重更高

半生期 30 天的衰减：
- 今天：100%
- 7 天前：84%
- 30 天前：50%
- 90 天前：12.5%

自动内存刷新

检测到 Context 快满
  ↓
触发无声 memory flush 回合
  ↓
提醒 Model：写下重要的东西到 MEMORY.md
  ↓
Model 写入记忆
  ↓
压缩旧对话

用户通常看不到这个过程（返回 NO_REPLY）

Memory 的使用原则

何时写 MEMORY.md（长期记忆）：

决策
偏好
持久的事实

何时写 memory/YYYY-MM-DD.md（日志）：

日常活动
一次性任务
学习笔记

四、Multi-Agent 路由：多个 Agent 的协奏

问题：一个 Agent 够用吗？

不一定。你可能需要：

- 一个快速的 Agent 处理日常聊天
- 一个深度思考的 Agent 处理复杂问题
- 一个安全受限的 Agent 处理家庭群组
- 一个工作 Agent 处理公司事务

方案：Multi-Agent 架构

一个 Gateway 内多个独立的 Agent：

Inbound Message
    ↓
  Gateway
    ↓
  Routing
  ↓ ↓ ↓ ↓
Agent  Agent  Agent  Agent
(家)   (工)   (编码) (安全)

Agent 的完整定义

Agent = Workspace + AuthDir + SessionStore + Personality

{
  "id": "work",
  "workspace": "~/.openclaw/workspace-work",
  "model": "anthropic/claude-opus-4-6"
}

每个 Agent 有：

独立的 AGENTS.md、SOUL.md（人格）
独立的 auth-profiles.json（认证）
独立的 sessions/（对话历史）
独立选择的模型

Routing 规则（最具体优先）

优先级从高到低：

Peer match（最具体）
ParentPeer match（线程继承）
GuildId + Roles（Discord）
GuildId（Discord）
TeamId（Slack）
AccountId match
Channel-wide fallback
Default agent

规则：第一个匹配就用，后面的被忽略。

配置示例 1：快速 vs 深度

{
  "agents": {
    "list": [
      {
        "id": "chat",
        "model": "anthropic/claude-sonnet-4-5"
      },
      {
        "id": "opus",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "opus",
      "match": { "channel": "whatsapp" }
    },
    {
      "agentId": "chat",
      "match": { "channel": "telegram" }
    }
  ]
}

配置示例 2：多个 WhatsApp 账户

{
  "agents": {
    "list": [
      { "id": "home", "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" }
    }
  ]
}

Per-Agent 工具和沙箱

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit"]
        }
      }
    ]
  }
}

五、身份链接（Identity Links）

问题：同一个人多个账户

Alice 在 Telegram 上是 123456789，在 WhatsApp 上是 +1234567890。

怎么知道是同一个人？

方案：Identity Links

{
  "session": {
    "identityLinks": {
      "alice": [
        "telegram:123456789",
        "whatsapp:+1234567890",
        "discord:987654321012345678"
      ]
    }
  }
}

效果：Alice 在不同平台的 DM 都用 session key agent:main:telegram:dm:alice，对话有连续性！

💭 学习心得

我的理解过程

一开始看文档，我被 Session、Memory、Routing 搞糊涂了。但当我把它们想象成一个饭馆的管理系统时，一切都清楚了：

Gateway = 前台（接收所有订单）
Session = 餐桌（每个客人一个，保持对话连续）
Memory = 笔记本（记住常客的偏好）
Multi-Agent = 多个厨师（不同厨师做不同菜系）

关键洞察

Session 隔离是安全的基石 - 多人环境下必须用 per-channel-peer
Memory 是补充，不是替代 - Context Window 有限，定期刷新很重要
Routing 是灵活性的源头 - 通过 Binding 实现复杂工作流
Gateway 的单一原则 - 一个主机一个网关，限制了水平扩展，但提高了稳定性

常见误区

❌ “我把所有人的 DM 放在 ‘main’ Session，这样很连续”
✅ 对于单用户是对的，但多人会信息泄露

❌ “我用 Local Embedding，这样可以离线搜索”
✅ 对的，但首次加载 GGUF 模型可能很慢

❌ “我把一个 Session 跑了 3 天，为什么 Agent 开始说傻话”
✅ 可能是 Context 满了，需要压缩或重置

📋 学习总结

关键概念速查表

概念	核心	实战用处
Gateway	一个主机一个，管理所有信道	理解部署限制
Session	每个对话一个，隔离是安全基础	配置 dmScope 保护隐私
Memory	向量搜索 + 文本搜索，层级记忆	让 Agent 记住重要东西
Multi-Agent	独立 Workspace + Routing	多角色、多模型协作
Identity Link	同一个人跨平台	保持连续性

关键配置速查

安全的多人 DM：

{ "session": { "dmScope": "per-channel-peer" } }

快速 + 深度双 Agent：

{
  "agents": {
    "list": [
      { "id": "chat", "model": "claude-sonnet-4-5" },
      { "id": "opus", "model": "claude-opus-4-6" }
    ]
  }
}

向量记忆搜索：

{
  "memorySearch": {
    "provider": "openai",
    "query": {
      "hybrid": { "enabled": true },
      "mmr": { "enabled": true },
      "temporalDecay": { "enabled": true, "halfLifeDays": 30 }
    }
  }
}