# 系统架构文档 - 单一实体多 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: │ └────────┬────────┘ └────────┬────────┘ │ │ └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ 共享基础设施层 │ │ (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 注册表 │ │ ├── -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/ │ └── / # 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 │ │ │ │ - "" │ │ │ │ │ │ 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", # 或 "" "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" │ │ "" │ │ │ └────┬─────┘ └────┬─────┘ └──────────┘ │ │ └──────┬───────┘ │ ▼ ┌──────────────────────┐ │ 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/-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 (陈医生)