openClaw_agent_dm/docs/SYSTEM_ARCHITECTURE.md

# 系统架构文档 - 单一实体多 Agent 结构

**文档版本:** 2026-02-26  
**架构师:** Eason (陈医生) 👨‍⚕️  
**部署环境:** Ubuntu 24.04 LTS VPS (KVM)

---

## 🏗️ 整体架构概览

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        王院长的多 Agent 系统                              │
│                    单一实体 · 多 Agent 协作 · 统一管理                      │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                           接入层 (Access Layer)                          │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   WebChat   │  │  Telegram   │  │  Tailscale  │  │   Nginx     │    │
│  │  (本地调试)  │  │  (@bot)     │  │  (远程访问)  │  │ (反向代理)   │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │                │                │                │            │
│         └────────────────┴────────────────┴────────────────┘            │
│                                  │                                       │
│                        ┌─────────▼─────────┐                            │
│                        │  OpenClaw Gateway  │                            │
│                        │   Port: 18789      │                            │
│                        │   Bind: Tailscale  │                            │
│                        └─────────┬─────────┘                            │
└──────────────────────────────────┼──────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │                             │
           ┌────────▼────────┐          ┌────────▼────────┐
           │   Main Agent    │          │  Spoke Agent(s) │
           │    (Eason)      │          │  (Hub-and-Spoke) │
           │  架构师/管理员   │          │  按需扩展        │
           │  Session: main  │          │  Session: <id>   │
           └────────┬────────┘          └────────┬────────┘
                    │                             │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │     共享基础设施层           │
                    │  (Shared Infrastructure)    │
                    └─────────────────────────────┘
```

---

## 👥 Agent 角色与职责

### 1. Eason (主 Agent) - 架构师/系统管理员

| 属性 | 值 |
|------|-----|
| **Agent ID** | `main` |
| **角色** | AI Agent 架构师 / 系统管理员 |
| **职责** | 系统管理、Agent 协调、安全审计、配置优化 |
| **工作区** | `/root/.openclaw/workspace` |
| **Session** | `main` (直接对话) |
| **模型** | `bailian/qwen3.5-plus` |
| **服务对象** | 王院长 |

**核心能力:**
- 🔧 系统配置与管理
- 🛡️ 安全审计与加固
- 📊 性能监控与优化
- 📝 知识沉淀与文档
- 🤖 子 Agent 协调与部署

---

## 🏛️ 物理文件架构

```
/root/.openclaw/
├── config.json                          # 主配置文件 (Gateway)
├── workspace/                           # 共享工作区 (Git 仓库)
│   ├── openclaw-config.json             # 工作区配置
│   ├── MEMORY.md                        # 长期记忆
│   ├── memory/                          # 每日记忆日志
│   │   ├── 2026-02-26.md
│   │   └── ...
│   ├── agents/
│   │   ├── registry.md                  # Agent 注册表
│   │   ├── <agent_id>-workspace/        # Spoke agent 工作区
│   │       └── ...
│   ├── skills/                          # 共享技能库
│   │   ├── mem0-integration/            # 记忆系统
│   │   ├── chinese-almanac/             # 黄历查询
│   │   ├── google-calendar-node/        # 日历管理
│   │   ├── system-date/                 # 日期获取
│   │   ├── tavily/                      # 网络搜索
│   │   └── openclaw-wecom/              # 企业微信 (待部署)
│   ├── logs/
│   │   ├── operations/                  # 操作日志
│   │   ├── system/                      # 系统日志
│   │   ├── agents/                      # Agent 日志
│   │   └── security/                    # 安全审计
│   └── deploy.sh                        # 部署脚本
├── agents/
│   ├── main/                            # Eason 运行时状态
│   │   └── agent/
│   └── <agent_id>/                      # Spoke agent 运行时状态
│       └── agent/
└── backups/                             # 备份目录
    └── workspace-YYYYMMDD-HHMMSS.tar.gz
```

---

## 🔧 共享基础设施

### 1. 记忆系统 (Memory System) - 单库融合架构

```
┌──────────────────────────────────────────────────────────────┐
│                    记忆系统架构 (单库融合)                     │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐     ┌─────────────────────────┐            │
│  │  Mem0 Core  │────▶│      Qdrant             │            │
│  │  (Python)   │     │   mem0_v4_shared        │            │
│  └──────┬──────┘     │  (统一共享 Collection)   │            │
│         │            │                         │            │
│         │ Embedding  │  ┌──────────────────┐   │            │
│         │ v4 (1024)  │  │ Payload Metadata │   │            │
│         ▼            │  │ ┌──────────────┐ │   │            │
│  ┌─────────────┐     │  │ │ agent_id     │ │   │            │
│  │ DashScope   │     │  │ │ - "main"     │ │   │            │
│  │ Gemini Pro  │     │  │ │ - "<id>"     │ │   │            │
│  │ text-embed- │     │  │ │ user_id      │ │   │            │
│  │ ding-v4     │     │  │ │ - "wang_..." │ │   │            │
│  └─────────────┘     │  │ └──────────────┘ │   │            │
│                      │  └──────────────────┘   │            │
│                      └─────────────────────────┘            │
└──────────────────────────────────────────────────────────────┘
```

**核心架构:**
- **Qdrant:** `localhost:6333`
- **Embedding:** Gemini Pro `text-embedding-v4` (1024 维度)
- **Collection:** `mem0_v4_shared` (**统一共享 Collection** - 多 Agent 共用)
- **隔离方式:** 元数据标签软隔离 (`metadata.agent_id`)
- **更新频率:** 每 5 分钟自动同步

**隔离机制:**
```python
# 写入时注入 agent_id
metadata = {
    "agent_id": "main",  # 或 "<agent_id>"
    "user_id": "wang_yuanzhang",
    "source": "openclaw"
}

# 检索时使用 metadata 过滤
memories = memory.search(
    query,
    user_id="wang_yuanzhang",
    filters={"agent_id": "main"}  # 软隔离关键
)
```

**架构优势:**
- ✅ **维度统一** - 避免多 Collection 维度不一致导致的崩溃风险
- ✅ **运维简化** - 单一 Collection，降低管理复杂度
- ✅ **记忆共享** - 支持跨 Agent 记忆查询（可选）
- ✅ **最佳实践** - 符合 Mem0 官方推荐的元数据隔离模式

---

### 2. 系统服务 (Systemd Services)

| 服务名 | 类型 | 状态 | 职责 |
|--------|------|------|------|
| `openclaw-gateway.service` | User-level | ✅ Active | Gateway 主服务 (Port 18789) |
| `openclaw-agent-monitor.service` | System-level | ✅ Active | 健康监控与自动恢复 |

**监控特性:**
- 每 30 秒健康检查
- 崩溃自动重启 (max 5 次/5 分钟)
- Telegram 告警通知
- 资源限制 (CPU 80%, Memory 2G)

---

### 3. 网络架构

```
┌─────────────────────────────────────────────────────┐
│                  网络访问路径                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  公网用户                                            │
│      │                                              │
│      ▼                                              │
│  ┌─────────────┐                                    │
│  │  Tailscale  │  WireGuard 加密                    │
│  │  100.115.94.1 │  仅 5 台信任设备可访问              │
│  └──────┬──────┘                                    │
│         │                                           │
│         ▼                                           │
│  ┌─────────────────────────────────────────────┐   │
│  │        OpenClaw Gateway (Port 18789)        │   │
│  │        Bind: Tailscale 接口                  │   │
│  │        Auth: Token (48 字符)                 │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
└─────────────────────────────────────────────────────┘
```

**安全特性:**
- Tailscale WireGuard 加密传输
- Token 认证 (48 字符十六进制)
- 仅 5 台信任设备可访问
- 无公网端口暴露

---

## 🔄 Agent 协作模式

### 单一实体架构

```
┌─────────────────────────────────────────────────────┐
│                 单一 Gateway 实例                     │
│              (OpenClaw Gateway v2026.2.19-2)          │
└─────────────────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┌──────────┐   ┌──────────┐   ┌──────────┐
   │ Session  │   │ Session  │   │ Session  │
   │  (main)  │   │  (spoke) │   │ Session  │
   │  Eason   │   │ 按需扩展  │   │  (new)   │
   │agent_id= │   │agent_id= │   │  未来    │
   │ "main"   │   │ "<id>"   │   │          │
   └────┬─────┘   └────┬─────┘   └──────────┘
        │              │
        └──────┬───────┘
               │
               ▼
    ┌──────────────────────┐
    │  mem0_v4_shared      │
    │  (统一共享 Collection) │
    │  metadata.agent_id   │
    │  软隔离              │
    └──────────────────────┘
```

**关键特性:**
1. **单一 Gateway** - 所有 Agent 共享同一个 Gateway 实例
2. **Session 隔离** - 每个 Agent 有独立的 session 和上下文
3. **共享技能** - skills/ 目录下的技能所有 Agent 可用
4. **独立配置** - 每个 Agent 有自己的 workspace 和配置
5. **统一管理** - Eason 负责所有 Agent 的部署和优化
6. **单库融合** - 所有记忆写入 `mem0_v4_shared` Collection，通过 `metadata.agent_id` 隔离

---

## 📊 资源配置

### 计算资源

| 资源 | 总量 | Gateway 使用 | Monitor 使用 | 可用 |
|------|------|-------------|-------------|------|
| **CPU** | 4 核 | 80% 限制 | 20% 限制 | - |
| **内存** | 3.8GB | 558MB | 24MB | 3.2GB |
| **磁盘** | 63GB | 25GB 已用 | - | 37GB |

### 模型配置

```json
{
  "primary": "bailian/qwen3.5-plus",
  "fallbacks": [
    "bailian/qwen3.5-plus-2026-02-15",
    "minimax-cn/MiniMax-M2.5"
  ]
}
```

---

## 🔐 安全架构

### 分层防护

```
┌─────────────────────────────────────────────────────┐
│  Layer 1: 网络层                                     │
│  - Tailscale WireGuard 加密                         │
│  - 仅信任设备可访问 (5 台)                            │
│  - 无公网端口暴露                                    │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  Layer 2: 认证层                                     │
│  - Token 认证 (48 字符)                              │
│  - 设备认证 (已知权衡：HTTP 下禁用)                    │
│  - 速率限制 (可选)                                   │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  Layer 3: 应用层                                     │
│  - 插件白名单 (待启用)                               │
│  - 会话隔离                                          │
│  - 权限控制                                          │
└─────────────────────────────────────────────────────┘
```

---

## 📈 扩展性设计

### 新增 Agent 流程

```
1. 定义 Agent 功能
   │
   ▼
2. 创建配置文件 (agents/<agent_id>-workspace 模板)
   │
   ▼
3. 注册到 registry.md
   │
   ▼
4. 配置技能和模型
   │
   ▼
5. 设置 systemd 服务 (可选)
   │
   ▼
6. 配置监控和日志
   │
   ▼
7. 测试验证
   │
   ▼
8. 更新 MEMORY.md
```

### 容量规划

| 指标 | 当前 | 上限 | 备注 |
|------|------|------|------|
| Agent 数量 | 1+ | ~10 | 受内存限制 |
| 并发 Session | 5 | 20 | Gateway 配置 |
| 记忆条目 | ~1000 | 无限制 | Qdrant 向量库 |

---

## 📝 运维命令

### 服务管理

```bash
# 查看状态
./deploy.sh status

# 重启服务
./deploy.sh restart

# 健康检查
./deploy.sh health

# 查看日志
./deploy.sh logs
```

### Git 管理

```bash
# 提交配置
cd /root/.openclaw/workspace
git add -A
git commit -m "描述"
git push origin master

# 回滚
./deploy.sh rollback
```

### 备份

```bash
# 手动备份
./deploy.sh backup

# 备份位置
/root/.openclaw/backups/workspace-YYYYMMDD-HHMMSS.tar.gz
```

---

## 🎯 待扩展功能

| 功能 | 优先级 | 状态 |
|------|--------|------|
| 企业微信集成 | 中 | 技能已开发，待部署 |
| Prometheus 监控 | 低 | 规划中 |
| 自动化 CI/CD | 低 | 规划中 |
| 多节点高可用 | 低 | 远期规划 |

---

**最后更新:** 2026-02-26 21:20 UTC  
**维护人:** Eason (陈医生)