# 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*