sw_dm
/
openClaw_agent_dm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
39 Commits
1 Branch
0 Tags
1.2 MiB
 
 
 
 
 
Tag: Branch: Tree: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
openClaw_agent_dm/docs/SYSTEM_ARCHITECTURE.md

414 lines
18 KiB
Raw Permalink Blame History Escape

# 系统架构文档 - 单一实体多 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 (陈医生)