# OpenClaw 架构与运行机制详解

> 从框架层面理解 OpenClaw 的工作原理

---

## 1. OpenClaw 是什么

OpenClaw 是一个**开源 AI 智能体框架**，旨在让 AI 助手能够：
- 通过多种渠道（QQ、微信、Telegram、Discord 等）与用户交互
- 调用各种工具（文件操作、网络搜索、代码执行、浏览器控制等）
- 扩展能力（通过 Skill 系统）
- 持久化记忆（文件记忆系统）

---

## 2. 核心架构组件

```
┌─────────────────────────────────────────────────────────────┐
│                      OpenClaw 架构全景                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐            │
│  │ Provider │     │ Provider │     │ Provider │            │
│  │  (QQ)    │     │(Telegram)│     │ (Discord)│            │
│  └────┬─────┘     └────┬─────┘     └────┬─────┘            │
│       │                │                │                   │
│       └────────────────┼────────────────┘                   │
│                        │                                      │
│                        ▼                                      │
│              ┌──────────────────┐                          │
│              │     Gateway      │  ← 核心枢纽                │
│              │    (网关服务)     │                          │
│              └────────┬─────────┘                          │
│                       │                                      │
│       ┌───────────────┼───────────────┐                    │
│       │               │               │                    │
│       ▼               ▼               ▼                    │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐                │
│  │  Agent  │    │  Agent  │    │  Agent  │                │
│  │ (Main)  │    │(Sub-1)  │    │(Sub-2)  │                │
│  └────┬────┘    └────┬────┘    └────┬────┘                │
│       │              │              │                      │
│       └──────────────┼──────────────┘                      │
│                      │                                      │
│                      ▼                                      │
│              ┌──────────────────┐                          │
│              │     Skills       │  ← 能力扩展                │
│              │  (技能系统)       │                          │
│              └──────────────────┘                          │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 2.1 Gateway（网关）

**Gateway 是 OpenClaw 的核心枢纽**，负责：

| 功能 | 说明 |
|------|------|
| **消息路由** | 将不同渠道的消息转发给对应的 Agent |
| **协议转换** | 统一各种 IM 协议的差异 |
| **会话管理** | 维护用户会话状态 |
| **安全控制** | 权限验证、隐私保护 |
| **任务调度** | 定时任务（Cron）、心跳检测 |

**Gateway 启动方式：**
```bash
openclaw gateway start    # 启动网关
openclaw gateway status   # 查看状态
openclaw gateway stop     # 停止网关
```

### 2.2 Provider（提供商）

**Provider 是消息渠道的适配器**，每个 Provider 负责对接一个 IM 平台：

| Provider | 平台 | 说明 |
|----------|------|------|
| `qqbot` | QQ | 对接 OneBot 协议 |
| `telegram` | Telegram | 对接 Bot API |
| `discord` | Discord | 对接 Discord.js |
| `wecom` | 企业微信 | 对接企业微信 API |
| `feishu` | 飞书 | 对接飞书机器人 |

**Provider 的工作：**
1. 接收平台推送的消息
2. 转换为 OpenClaw 内部格式
3. 发送给 Gateway 处理
4. 将 Agent 响应发送回平台

### 2.3 Agent（智能体）

**Agent 是实际执行任务的 AI 实例**：

```
┌────────────────────────────────────┐
│           Agent 架构               │
├────────────────────────────────────┤
│                                    │
│  ┌──────────────┐                 │
│  │  系统提示词   │  ← 定义行为     │
│  │  (System)    │                 │
│  └──────────────┘                 │
│                                    │
│  ┌──────────────┐                 │
│  │  对话历史    │  ← 上下文记忆   │
│  │ (Context)    │                 │
│  └──────────────┘                 │
│                                    │
│  ┌──────────────┐                 │
│  │  工具调用    │  ← 技能调用     │
│  │  (Tools)     │                 │
│  └──────────────┘                 │
│                                    │
│  ┌──────────────┐                 │
│  │  文件记忆    │  ← MEMORY.md   │
│  │  (Memory)    │                 │
│  └──────────────┘                 │
│                                    │
└────────────────────────────────────┘
```

**Agent 类型：**
- **Main Agent**：主会话 Agent，直接与用户对话
- **Sub-Agent**：子 Agent，执行特定任务（如 Cron 任务、后台处理）
- **ACP Agent**：代码执行专用 Agent

### 2.4 Skill（技能）

**Skill 是 Agent 的能力扩展单元**：

```
my-skill/
├── SKILL.md          # 技能定义文件（必需）
├── scripts/          # 脚本文件
├── tools/            # 工具实现
└── assets/           # 资源文件
```

**SKILL.md 结构：**
```markdown
---
name: skill-name
description: 技能描述
metadata:
  requires:
    bins: ["node", "python"]
    env: ["API_KEY"]
---

# 技能说明
...
```

**Skill 安装：**
```bash
clawhub install skill-name    # 从 clawhub 安装
clawhub link ./local-skill    # 本地链接
```

---

## 3. QQ 机器人对话流程详解

以 QQ 机器人为例，完整的消息流转过程：

```
┌──────────────────────────────────────────────────────────────┐
│                    QQ 消息流转流程                            │
└──────────────────────────────────────────────────────────────┘

[用户手机 QQ]
      │
      │ 1. 用户发送消息
      ▼
[QQ 服务器]
      │
      │ 2. 推送消息
      ▼
[OneBot 协议端] ←── (如 go-cqhttp, NapCat, LLOneBot)
      │
      │ 3. HTTP/WebSocket 上报
      ▼
[OpenClaw Gateway]
      │
      │ 4. 消息解析、路由
      ▼
[OpenClaw Agent] ←── (加载 MEMORY.md, TOOLS.md)
      │
      │ 5. AI 处理、工具调用
      ▼
[LLM API] ←── (Kimi, GPT, Claude 等)
      │
      │ 6. 生成回复
      ▼
[OpenClaw Agent]
      │
      │ 7. 格式化响应
      ▼
[OpenClaw Gateway]
      │
      │ 8. 调用 QQ API
      ▼
[OneBot 协议端]
      │
      │ 9. 发送消息
      ▼
[QQ 服务器]
      │
      │ 10. 推送至用户
      ▼
[用户手机 QQ]
```

### 3.1 详细步骤解析

#### Step 1-2: 消息产生
用户在 QQ 发送消息，经过腾讯服务器中转。

#### Step 3: OneBot 协议
OneBot 是一个**统一的聊天机器人应用接口标准**，让不同的 QQ 协议端可以统一对接：

**常见的 OneBot 实现：**
- **go-cqhttp**（已停止维护，但仍在用）
- **NapCat**（基于 QQ NT，目前主流）
- **LLOneBot**（轻量级，基于 LiteLoader）

**OneBot 消息格式示例：**
```json
{
  "post_type": "message",
  "message_type": "private",
  "user_id": 279417FB319D4A99,
  "message": "你好",
  "raw_message": "你好",
  "time": 1773221197
}
```

#### Step 4: Gateway 处理
Gateway 接收到消息后：
1. **解析消息**：提取内容、用户ID、群ID等
2. **查找会话**：确定对应的 Agent 会话
3. **加载上下文**：读取 memory/ 下的历史记录
4. **构建提示**：组装 System Prompt + Context

#### Step 5-6: Agent 处理
Agent 接收到请求后：
1. **理解意图**：分析用户想做什么
2. **选择工具**：决定是否需要调用工具
3. **执行操作**：调用 Skill、执行命令、搜索等
4. **生成回复**：LLM 生成自然语言响应

#### Step 7-10: 响应返回
Agent 的回复经过 Gateway 格式化，通过 OneBot 协议发送回 QQ。

---

## 4. 消息格式与上下文

### 4.1 入站消息格式

```json
{
  "schema": "openclaw.inbound_meta.v1",
  "chat_id": "qqbot:c2c:279417FB319D4A994015DFFBF56B428D",
  "channel": "qqbot",
  "provider": "qqbot",
  "surface": "qqbot",
  "chat_type": "direct"
}
```

**字段说明：**
- `chat_id`：会话唯一标识
- `channel`：渠道类型
- `chat_type`：`direct` 私聊 / `group` 群聊

### 4.2 上下文文件

**AGENTS.md**：工作空间配置
```markdown
# AGENTS.md - Your Workspace
...
```

**SOUL.md**：Agent 人格定义
```markdown
# SOUL.md - Who You Are
...
```

**MEMORY.md**：长期记忆（仅在主会话加载）
```markdown
# MEMORY.md - 长期记忆
...
```

**memory/YYYY-MM-DD.md**：每日对话记录

---

## 5. 工具调用机制

当 Agent 需要执行操作时，通过工具调用：

```
用户: "查一下北京天气"
      │
      ▼
[Agent 思考]
      │
      ▼
调用 weather skill
      │
      ▼
[weather skill]
  ├── 调用天气 API
  ├── 解析返回数据
  └── 格式化输出
      │
      ▼
返回给 Agent
      │
      ▼
生成回复: "北京今天晴天，25°C..."
```

**工具调用方式：**
```python
# 通过 exec 执行命令
exec(command="curl api.weather.com/beijing")

# 通过 web_search 搜索
web_search(query="北京天气")

# 通过 browser 浏览网页
browser(action="open", url="https://weather.com")
```

---

## 6. 定时任务（Cron）机制

```
┌─────────────────────────────────────┐
│           Cron 任务流程              │
├─────────────────────────────────────┤
│                                     │
│  [Cron 表达式] ──► [Scheduler]      │
│       │               │             │
│       │               ▼             │
│       │         [触发时间到]        │
│       │               │             │
│       │               ▼             │
│       │    [Spawn Sub-Agent]        │
│       │               │             │
│       │               ▼             │
│       │    [执行任务逻辑]           │
│       │               │             │
│       │               ▼             │
│       │    [发送结果给用户]         │
│                                     │
└─────────────────────────────────────┘
```

**Cron 配置示例：**
```json
{
  "action": "add",
  "job": {
    "name": "健康提醒",
    "schedule": {
      "kind": "cron",
      "expr": "0 */4 * * *",
      "tz": "Asia/Shanghai"
    },
    "payload": {
      "kind": "agentTurn",
      "message": "提醒内容...",
      "deliver": true,
      "channel": "qqbot",
      "to": "用户ID"
    }
  }
}
```

---

## 7. 安全与隐私

### 7.1 安全边界

| 层级 | 保护措施 |
|------|----------|
| **系统级** | 不执行危险命令（rm -rf / 等） |
| **文件级** | 只能访问 workspace 目录 |
| **网络级** | 不泄露 IP、端口等敏感信息 |
| **隐私级** | 不读取用户其他聊天记录 |

### 7.2 隐私原则

1. **最小权限**：只访问完成任务必需的资源
2. **会话隔离**：不同会话之间不共享敏感信息
3. **用户授权**：涉及外部操作前需用户确认
4. **数据透明**：明确告知用户数据使用方式

---

## 8. 总结

```
┌────────────────────────────────────────────────────┐
│                  OpenClaw 核心要点                  │
├────────────────────────────────────────────────────┤
│                                                    │
│  🔄 Gateway    ── 消息中枢，路由调度               │
│  📱 Provider   ── 渠道适配，协议转换               │
│  🤖 Agent      ── 智能体，执行任务                 │
│  🛠️ Skill      ── 能力扩展，工具封装              │
│  💾 Memory     ── 持久化记忆，上下文保持           │
│                                                    │
│  工作流程：                                        │
│  Provider → Gateway → Agent → LLM → Skill → 回复  │
│                                                    │
└────────────────────────────────────────────────────┘
```

---

*生成时间：2026-03-11*  
*OpenClaw 版本：2026.2.26*