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.
19 KiB
19 KiB
系统架构文档 - 单一实体多 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 │ │ Life Agent │
│ (Eason) │ │ (张大师) │
│ 架构师/管理员 │ │ 生活与运程助手 │
│ Session: main │ │ Session: life │
└────────┬────────┘ └────────┬────────┘
│ │
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ 共享基础设施层 │
│ (Shared Infrastructure) │
└─────────────────────────────┘
👥 Agent 角色与职责
1. Eason (主 Agent) - 架构师/系统管理员
| 属性 | 值 |
|---|---|
| Agent ID | main |
| 角色 | AI Agent 架构师 / 系统管理员 |
| 职责 | 系统管理、Agent 协调、安全审计、配置优化 |
| 工作区 | /root/.openclaw/workspace |
| Session | main (直接对话) |
| 模型 | bailian/qwen3.5-plus |
| 服务对象 | 王院长 |
核心能力:
- 🔧 系统配置与管理
- 🛡️ 安全审计与加固
- 📊 性能监控与优化
- 📝 知识沉淀与文档
- 🤖 子 Agent 协调与部署
2. 张大师 (Life Agent) - 生活与运程助手
| 属性 | 值 |
|---|---|
| Agent ID | life |
| 角色 | 生活与运程助手 |
| 职责 | 日程管理、黄历查询、运程推送、生活建议 |
| 工作区 | /root/.openclaw/workspace/agents/life-workspace |
| Session | life |
| 模型 | bailian/qwen3.5-plus |
| Telegram | @master_zhang_bot |
| 定时任务 | 每日 21:00 推送运程 |
核心能力:
- 📅 Google Calendar 日程管理
- 📜 中国传统黄历查询
- 🔮 每日运程推送
- 🧠 记忆系统（用户偏好、生辰八字）
🏛️ 物理文件架构
/root/.openclaw/
├── config.json # 主配置文件 (Gateway)
├── workspace/ # 共享工作区 (Git 仓库)
│ ├── openclaw-config.json # 工作区配置
│ ├── MEMORY.md # 长期记忆
│ ├── memory/ # 每日记忆日志
│ │ ├── 2026-02-26.md
│ │ └── ...
│ ├── agents/
│ │ ├── registry.md # Agent 注册表
│ │ ├── life-agent.json # 张大师配置
│ │ └── life-workspace/ # 张大师工作区
│ │ ├── AGENTS.md
│ │ ├── SOUL.md
│ │ ├── memory/
│ │ └── skills/
│ ├── 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/
│ └── life/ # 张大师运行时状态
│ └── 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 │ │ │ │ - "life" │ │ │ │
│ │ text-embed- │ │ │ │ user_id │ │ │ │
│ │ ding-v4 │ │ │ │ - "wang_..." │ │ │ │
│ └─────────────┘ │ │ └──────────────┘ │ │ │
│ │ └──────────────────┘ │ │
│ └─────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
核心架构:
- Qdrant:
localhost:6333 - Embedding: Gemini Pro
text-embedding-v4(1024 维度) - Collection:
mem0_v4_shared(统一共享 Collection - 陈医生/张大师共用) - 隔离方式: 元数据标签软隔离 (
metadata.agent_id) - 更新频率: 每 5 分钟自动同步
隔离机制:
# 写入时注入 agent_id
metadata = {
"agent_id": "main", # 或 "life"
"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) │ │ (life) │ │ Session │
│ Eason │ │ 张大师 │ │ (new) │
│agent_id= │ │agent_id= │ │ 未来 │
│ "main" │ │ "life" │ │ │
└────┬─────┘ └────┬─────┘ └──────────┘
│ │
└──────┬───────┘
│
▼
┌──────────────────────┐
│ mem0_v4_shared │
│ (统一共享 Collection) │
│ metadata.agent_id │
│ 软隔离 │
└──────────────────────┘
关键特性:
- 单一 Gateway - 所有 Agent 共享同一个 Gateway 实例
- Session 隔离 - 每个 Agent 有独立的 session 和上下文
- 共享技能 - skills/ 目录下的技能所有 Agent 可用
- 独立配置 - 每个 Agent 有自己的 workspace 和配置
- 统一管理 - Eason 负责所有 Agent 的部署和优化
- 单库融合 - 所有记忆写入
mem0_v4_sharedCollection，通过metadata.agent_id隔离
📊 资源配置
计算资源
| 资源 | 总量 | Gateway 使用 | Monitor 使用 | 可用 |
|---|---|---|---|---|
| CPU | 4 核 | 80% 限制 | 20% 限制 | - |
| 内存 | 3.8GB | 558MB | 24MB | 3.2GB |
| 磁盘 | 63GB | 25GB 已用 | - | 37GB |
模型配置
{
"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/life-agent.json 模板)
│
▼
3. 注册到 registry.md
│
▼
4. 配置技能和模型
│
▼
5. 设置 systemd 服务 (可选)
│
▼
6. 配置监控和日志
│
▼
7. 测试验证
│
▼
8. 更新 MEMORY.md
容量规划
| 指标 | 当前 | 上限 | 备注 |
|---|---|---|---|
| Agent 数量 | 2 | ~10 | 受内存限制 |
| 并发 Session | 5 | 20 | Gateway 配置 |
| 记忆条目 | ~1000 | 无限制 | Qdrant 向量库 |
📝 运维命令
服务管理
# 查看状态
./deploy.sh status
# 重启服务
./deploy.sh restart
# 健康检查
./deploy.sh health
# 查看日志
./deploy.sh logs
Git 管理
# 提交配置
cd /root/.openclaw/workspace
git add -A
git commit -m "描述"
git push origin master
# 回滚
./deploy.sh rollback
备份
# 手动备份
./deploy.sh backup
# 备份位置
/root/.openclaw/backups/workspace-YYYYMMDD-HHMMSS.tar.gz
🎯 待扩展功能
| 功能 | 优先级 | 状态 |
|---|---|---|
| 企业微信集成 | 中 | 技能已开发，待部署 |
| Prometheus 监控 | 低 | 规划中 |
| 自动化 CI/CD | 低 | 规划中 |
| 多节点高可用 | 低 | 远期规划 |
最后更新: 2026-02-26 21:20 UTC
维护人: Eason (陈医生)