OpenClaw 架构学习笔记
位置: /home/tenbox/.openclaw/workspace/openclaw-architecture-study.md
大小: 12.8KB | 创建时间: 2026-04-05 20:30
🏗️ 一、整体架构
核心组件
┌─────────────────────────────────────────────────────────────┐
│ Chat Apps │
│ WhatsApp │ Telegram │ Discord │ iMessage │ Signal │ Slack │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Gateway (Daemon) │
│ - WebSocket Server (127.0.0.1:18789) │
│ - Channel Adapters (Baileys, grammY, etc.) │
│ - Agent Routing │
│ - Session Management │
│ - Plugin System │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Pi │ │ CLI │ │ Web │
│ Agent │ │ │ │ Control │
│ Runtime │ │ │ │ UI │
└──────────┘ └──────────┘ └──────────┘
│
▼
┌─────────────────┐
│ Mobile Nodes │
│ iOS / Android │
│ (Canvas, etc.) │
└─────────────────┘
关键特性
特性 | 说明 |
|---|
自托管 | 运行在自己的硬件上，完全控制数据 |
多通道 | 单一 Gateway 服务同时支持 WhatsApp、Telegram、Discord 等 |
Agent 原生 | 为编码 Agent 设计，支持工具调用、会话、记忆、多 Agent 路由 |
开源 | MIT 许可，社区驱动 |
🔌 二、Gateway 架构
WebSocket 协议
事件推送: {type:"event", event, payload, seq?, stateVersion?}
配对 + 本地信任
🤖 三、Agent 运行时
工作空间文件
文件 | 用途 |
|---|
AGENTS.md | 操作指令 + "记忆" |
SOUL.md | 人格、边界、语气 |
TOOLS.md | 用户维护的工具笔记 |
BOOTSTRAP.md | 一次性首次运行仪式（完成后删除） |
IDENTITY.md | Agent 名称/氛围/emoji |
USER.md | 用户档案 + 首选称呼 |
会话启动流程
读取 SOUL.md — 我是谁
读取 USER.md — 我在帮助谁
读取 memory/YYYY-MM-DD.md（今天 + 昨天）— 最近上下文
如果在主会话：也读取 MEMORY.md
💾 四、会话管理
会话键格式
会话类型 | 键格式 |
|---|
直接聊天（默认） | agent:<agentId>:<mainKey> |
直接聊天（per-peer） | agent:<agentId>:direct:<peerId> |
群聊 | agent:<agentId>:<channel>:group:<id> |
Sub-agent | agent:<agentId>:subagent:<uuid> |
安全 DM 模式
{
session: {
dmScope: "per-channel-peer", // 按频道 + 发送者隔离
}
}
🧠 五、记忆系统
workspace/
├── MEMORY.md # 长期记忆（精选）
└── memory/
├── 2026-04-04.md # 每日日志
└── 2026-04-05.md # 每日日志
记忆工具
🎯 六、技能系统
技能位置（优先级从高到低）
<workspace>/skills
~/.agents/skills
~/.openclaw/skills
Bundled skills
skills.load.extraDirs
ClawHub
openclawskillsinstall<skill-slug>
openclawskillsupdate--all
🕷️ 七、Sub-Agents
会话键形状
深度 | 会话键格式 | 角色 |
|---|
0 | agent:<id>:main | 主 Agent |
1 | agent:<id>:subagent:<uuid> | Sub-agent |
2 | agent:<id>:subagent:<uuid>:subagent:<uuid> | Sub-sub-agent |
Slash 命令
/subagentslist
/subagentsspawn<agentId><task>
/subagentskill<id>
📝 十三、关键洞见
架构设计亮点
单一网关模式: 一个 Gateway 进程管理所有通道
WebSocket 优先: 实时双向通信，支持流式响应
会话隔离: 每会话独立上下文
插件化技能: AgentSkills 兼容，易于扩展
记忆分层: 每日日志 + 长期记忆
子 Agent 编排: 支持并行任务和嵌套工作流
🎓 学习总结
我学到了什么
✅ Gateway WebSocket 架构（端口 18789）
✅ 会话管理（会话键格式、安全 DM 模式）
✅ 记忆系统（MEMORY.md + memory/YYYY-MM-DD.md）
✅ 技能系统（AgentSkills 兼容、6 层优先级）
✅ Sub-Agents 编排（嵌套深度、通知链）
✅ 压缩机制（自动/手动）
