282 lines
7.8 KiB
Markdown
282 lines
7.8 KiB
Markdown
# OpenClaw 架构与创新分析
|
||
|
||
> 来源: OpenClaw 官方文档 | https://docs.openclaw.ai
|
||
|
||
---
|
||
|
||
## 一、总体架构
|
||
|
||
OpenClaw 采用 **Gateway 中心化架构**，是一个多智能体（Multi-Agent）运行框架。
|
||
|
||
### 核心组件
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Gateway │
|
||
│ (WebSocket + HTTP API + OpenAI兼容端点) │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Agent 1 │ │ Agent 2 │ │ Agent N │ │
|
||
│ │ (main) │ │ │ │ │ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
│ │ │ │ │
|
||
│ ┌────┴─────────────┴─────────────┴────┐ │
|
||
│ │ Workspace + Sessions │ │
|
||
│ │ AGENTS.md / SOUL.md / USER.md │ │
|
||
│ │ Skills / Memory / Tools │ │
|
||
│ └───────────────────────────────────────┘ │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ Channels (飞书/Discord/Telegram等) │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Gateway 核心特性
|
||
|
||
- **单一进程**：常驻运行，负责路由、控制平面、频道连接
|
||
- **多协议端口**：WebSocket 控制/RPC + HTTP API + OpenAI 兼容端点
|
||
- **默认绑定 loopback**：安全优先
|
||
- **热重载支持**：hybrid 模式（hot-apply when safe, restart when required）
|
||
|
||
### OpenAI 兼容端点
|
||
|
||
```
|
||
GET /v1/models # 返回 openclaw/openclaw/default
|
||
POST /v1/chat/completions # 标准聊天补全
|
||
POST /v1/embeddings # 向量嵌入
|
||
POST /v1/responses # Agent 原生响应格式
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Agent 架构
|
||
|
||
### 什么是 Agent
|
||
|
||
一个 **Agent** 是完整的人设范围，包含：
|
||
|
||
- **Workspace**：文件、AGENTS.md/SOUL.md/USER.md、本地笔记、规则
|
||
- **State Directory (agentDir)**：`~/.openclaw/agents/<agentId>/agent`，存放 auth profiles、model registry、per-agent config
|
||
- **Session Store**：聊天历史 + 路由状态
|
||
|
||
### Workspace 文件结构
|
||
|
||
```
|
||
~/.openclaw/workspace/
|
||
├── AGENTS.md # 操作指令
|
||
├── SOUL.md # 人设和语气
|
||
├── USER.md # 用户信息
|
||
├── IDENTITY.md # 名称、emoji
|
||
├── TOOLS.md # 本地工具约定
|
||
├── HEARTBEAT.md # 心跳检查清单
|
||
├── MEMORY.md # 长期记忆（仅主会话加载）
|
||
├── memory/
|
||
│ └── YYYY-MM-DD.md # 每日记忆日志
|
||
└── skills/ # 工作区技能（最高优先级）
|
||
```
|
||
|
||
### 单 Agent vs 多 Agent
|
||
|
||
**单 Agent 模式（默认）**：
|
||
- `agentId` 默认为 `main`
|
||
- Workspace: `~/.openclaw/workspace`
|
||
- State: `~/.openclaw/agents/main/agent`
|
||
|
||
**多 Agent 模式**：
|
||
- 每个 agent 完全隔离（独立 workspace、auth、sessions）
|
||
- 通过 **Binding** 系统路由消息
|
||
|
||
---
|
||
|
||
## 三、Binding 系统（消息路由）
|
||
|
||
Bindings 是**确定性**的，**最特定匹配优先**：
|
||
|
||
| 优先级 | 匹配类型 |
|
||
|--------|----------|
|
||
| 1 | peer match（精确 DM/群组 ID） |
|
||
| 2 | parentPeer match（线程继承） |
|
||
| 3 | guildId + roles（Discord 角色路由） |
|
||
| 4 | guildId |
|
||
| 5 | teamId（Slack） |
|
||
| 6 | accountId match for channel |
|
||
| 7 | Channel-level match |
|
||
| 8 | Default agent |
|
||
|
||
### Binding 示例
|
||
|
||
```json5
|
||
{
|
||
bindings: [
|
||
{ agentId: "alex", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } } },
|
||
{ agentId: "mia", match: { channel: "telegram" } },
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Skills 系统
|
||
|
||
### 加载优先级
|
||
|
||
1. **Workspace skills**（`workspace/skills/`）— 最高优先级
|
||
2. **Agent skills**（`~/.openclaw/agents/<agentId>/skills/`）
|
||
3. **Managed skills**（`~/.openclaw/skills/`）
|
||
4. **Bundled skills**
|
||
|
||
### Skill 结构
|
||
|
||
每个 Skill 是一个文件夹，包含：
|
||
- `SKILL.md` — 描述和指令
|
||
- 工具脚本/CLI
|
||
|
||
### 共享技能配置
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
skills: ["skill-a", "skill-b"] // 共享基线
|
||
},
|
||
list: [
|
||
{
|
||
id: "main",
|
||
skills: ["skill-c", "skill-d"] // 替换基线
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、记忆系统 (Memory)
|
||
|
||
### QMD 后端
|
||
|
||
OpenClaw 使用 **QMD** 作为记忆后端，支持：
|
||
- 跨会话语义搜索
|
||
- 自动记忆刷新
|
||
- 额外集合支持
|
||
|
||
### 记忆文件
|
||
|
||
- **MEMORY.md**：精选长期记忆（仅主私有会话加载）
|
||
- **memory/YYYY-MM-DD.md**：每日记忆日志
|
||
|
||
### 跨 Agent 记忆共享
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
memorySearch: {
|
||
qmd: {
|
||
extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、工具系统 (Tools)
|
||
|
||
### 内置工具
|
||
|
||
- `read` / `write` / `edit` — 文件操作
|
||
- `exec` — 执行 shell 命令
|
||
- `sessions_list` / `sessions_history` / `sessions_send` — 会话管理
|
||
- `subagents` — 子 agent 管理
|
||
- `gateway` / `config.*` — 配置管理
|
||
- `web_search` / `web_fetch` — 网页搜索
|
||
- `image_generate` — 图片生成
|
||
|
||
### 工具策略（Per-Agent）
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [{
|
||
id: "family",
|
||
tools: {
|
||
allow: ["exec", "read", "sessions_list"],
|
||
deny: ["write", "edit", "browser"]
|
||
}
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、安全模型
|
||
|
||
### 认证方式
|
||
|
||
- **Token/Password**：共享密钥认证
|
||
- **Trusted-Proxy**：反向代理后的信任模式
|
||
- **OAuth**：第三方登录
|
||
|
||
### 安全特性
|
||
|
||
1. **默认 loopback 绑定**：不允许外部直接访问
|
||
2. **Tool Policy**：每个 agent 可配置 allow/deny 列表
|
||
3. **Sandboxing**：可配置工作区沙盒隔离
|
||
4. **Session 隔离**：不同 agent 的 sessions 完全隔离
|
||
|
||
---
|
||
|
||
## 八、创新点总结
|
||
|
||
### 1. Binding 驱动的多 Agent 路由
|
||
|
||
不同于简单的角色分配，OpenClaw 的 Binding 系统支持：
|
||
- 精确的 peer/guild/role 匹配
|
||
- 最特定匹配优先的确定性路由
|
||
- 跨渠道的统一管理
|
||
|
||
### 2. Workspace 隔离 + 灵活共享
|
||
|
||
- 每个 agent 有独立 workspace
|
||
- 通过 extraCollections 实现受控的记忆共享
|
||
- Skills 支持层级覆盖
|
||
|
||
### 3. OpenAI 兼容 API
|
||
|
||
原生支持 `/v1/models`、`/v1/chat/completions`、`/v1/embeddings`，便于：
|
||
- 集成到 LobeChat、Open WebUI 等
|
||
- RAG 和记忆 pipelines
|
||
- Agent 原生客户端
|
||
|
||
### 4. 分布式记忆（QMD）
|
||
|
||
- 跨会话语义搜索
|
||
- 自动压缩和刷新
|
||
- 可配置的额外集合
|
||
|
||
### 5. 灵活的 Tool Policy
|
||
|
||
- 每个 agent 独立配置
|
||
- 细粒度 allow/deny 控制
|
||
- 沙盒模式可选
|
||
|
||
---
|
||
|
||
## 九、与 Hermes 的核心区别
|
||
|
||
| 维度 | OpenClaw | Hermes |
|
||
|------|-----------|--------|
|
||
| **架构** | Gateway 中心化 | AIAgent 核心循环 |
|
||
| **记忆** | 手动编辑 markdown / QMD 自动搜索 | 全自动压缩+提炼+用户画像 |
|
||
| **技能** | 手动安装市场技能 | 自动生成 SK.md |
|
||
| **路由** | Binding 系统 | 无（单 agent） |
|
||
| **安全** | Tool Policy + 审批 | 沙盒+零遥测 |
|
||
| **定位** | 企业级/可审计 | 个人/长气AI朋友 |
|
||
| **设计哲学** | 你告诉它做什么 | 它学会你想做什么 |
|
||
|
||
---
|
||
|
||
*总结时间: 2026-05-06* |