# OpenClaw Extensions Architecture

**版本:** 1.0
**日期:** 2026-03-03
**维护者:** Eason (陈医生)

> **重要提示**: 本文档是所有自定义扩展的权威参考。在修改任何基础设施代码（systemd 服务、监控脚本、部署脚本、记忆系统）之前，必须阅读本文档。OpenClaw UI 升级可能覆盖部分文件，请参考第 7 节的升级安全清单。

---

## 1. 扩展概览

OpenClaw 核心是上游提供的 AI Agent 网关。以下组件为自定义扩展，不属于上游代码，升级时需特别保护：

| 扩展组件 | 位置 | 说明 |
|---------|------|------|
| Agent 注册表 | `agents.yaml` | 中央 Agent 注册表，deploy.sh / agent-monitor.js 均从此读取配置 |
| 解析辅助脚本 | `scripts/parse_agents.py` | 解析 agents.yaml，供 deploy.sh / agent-monitor.js 等调用 |
| 四层记忆系统 | `skills/mem0-integration/` | Mem0 + Qdrant + FTS5 本地检索 |
| Agent Monitor | `agent-monitor.js` | 健康监控、自动重启、Telegram 通知（**config-driven**，读取 agents.yaml） |
| 部署脚本 | `deploy.sh` | 服务管理、备份、回滚、调试命令（**config-driven**，读取 agents.yaml） |
| 生命周期脚本 | `templates/onboard.sh`, `templates/offboard.sh` | 新 Agent 创建、Agent 下线与清理 |
| 环境变量文件 | `systemd/gateway.env`, `systemd/{agent_id}-gateway.env` | 升级安全的环境变量持久化 |
| Systemd 服务模板 | `systemd/` | 用户级和系统级服务定义 |
| 项目注册表 | `skills/mem0-integration/project_registry.yaml` | Agent-项目归属映射 |

---

## 2. 服务架构 (Hybrid Systemd)

### 架构图

```
┌─────────────────────────────────────────────────────────┐
│  System-level (/etc/systemd/system/)                    │
│  ┌───────────────────────────────────┐                  │
│  │ openclaw-agent-monitor.service    │ ← 健康监控守护进程 │
│  │ (Node.js, PID独立于gateway)       │                  │
│  └────────────┬──────────────────────┘                  │
│               │ monitors                                │
├───────────────┼─────────────────────────────────────────┤
│  User-level (~/.config/systemd/user/)                   │
│  ┌────────────▼──────────────────────┐                  │
│  │ openclaw-gateway.service          │ ← 主 Gateway     │
│  │ (port 18789)                      │                  │
│  │ EnvironmentFile=gateway.env       │                  │
│  ├───────────────────────────────────┤                  │
│  │ openclaw-gateway-{agent_id}.service │ ← 可选扩展 Agent │
│  │ EnvironmentFile={agent_id}-gateway.env │             │
│  └───────────────────────────────────┘                  │
└─────────────────────────────────────────────────────────┘
```

### User-level vs System-level

| 属性 | User-level (gateway) | System-level (monitor) |
|------|---------------------|----------------------|
| 路径 | `~/.config/systemd/user/` | `/etc/systemd/system/` |
| 管理命令 | `systemctl --user ...` | `systemctl ...` |
| 日志查看 | `journalctl --user -u <name>` | `journalctl -u <name>` |
| 升级风险 | **高** — OpenClaw UI 可能覆盖 | 低 — 不受 UI 升级影响 |
| 依赖 | 需要 `loginctl enable-linger` | 无特殊依赖 |

### 文件映射

| 模板 (workspace/systemd/) | 安装位置 | 说明 |
|--------------------------|---------|------|
| `openclaw-gateway-user.service` | `~/.config/systemd/user/openclaw-gateway.service` | 主 Gateway |
| `agent-{agent_id}.service` | `~/.config/systemd/user/openclaw-gateway-{agent_id}.service` | 可选扩展 Agent |
| `openclaw-agent-monitor.service` | `/etc/systemd/system/openclaw-agent-monitor.service` | 监控 |
| `openclaw-gateway.service.legacy` | `/etc/systemd/system/openclaw-gateway.service` (已 masked) | 废弃 |
| `gateway.env` | 原地引用 (不复制) | 主 Gateway 环境变量 |
| `{agent_id}-gateway.env` | 原地引用 (不复制) | 扩展 Agent 环境变量 |

---

## 3. 监控系统 (Agent Monitor)

**文件**: `agent-monitor.js`
**服务**: `openclaw-agent-monitor.service` (system-level)
**配置**: **config-driven** — 通过 `scripts/parse_agents.py` 解析 `agents.yaml` 获取待监控的 Agent 列表

### 功能

| 功能 | 说明 |
|------|------|
| 多服务监控 | 同时监控 gateway 及已注册的扩展 Agent |
| 重启限制 | 5 分钟内最多 5 次重启，超限停止并报警 |
| 升级容忍 | 首次检测到服务停止后等待 60 秒，避免升级期间误报 |
| 心跳日志 | 每 10 分钟输出一次状态 (`gateway=OK`, `{agent_id}=OK`) |
| Telegram 通知 | 服务异常、重启失败时发送告警 |
| 日志记录 | `logs/agents/health-YYYY-MM-DD.log` |

### 监控流程

```
每 30 秒 → 检查 gateway 状态
         → 检查各扩展 Agent 状态
         → 如果正常: 重置故障计时器
         → 如果异常:
            首次: 记录时间，进入 grace period (60s)
            仍异常且已过 grace period:
              检查重启次数 → 未超限: 执行重启
                           → 已超限: 发送 critical 告警
每 10 分钟 → 输出心跳日志
```

### 配置参数 (构造函数)

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `maxRestarts` | 5 | 重启窗口内最大重启次数 |
| `restartWindow` | 300000 (5min) | 重启计数窗口 |
| `gracePeriod` | 60000 (60s) | 首次故障后的等待时间 |
| `heartbeatInterval` | 600000 (10min) | 心跳日志间隔 |

---

## 4. 记忆系统

> 完整文档: `docs/MEMORY_ARCHITECTURE.md` (v2.1)
> 开发者文档: `skills/mem0-integration/SKILL.md`
> 多 Agent 管理: `docs/MULTI_AGENT_MANAGEMENT.md` (Hub-and-Spoke 模型、Onboarding、远程 Agent)

### 快速参考

- **Layer 1**: Core Memory — MD 文件 (CORE_INDEX.md, IDENTITY.md, SOUL.md)
- **Layer 2**: Daily Memory — MEMORY.md + memory/*.md, Git 版本控制
- **Layer 3**: Short-term — SQLite FTS5 本地检索 (`local_search.py`)
- **Layer 4**: Mem0 — Qdrant (`mem0_v4_shared`) + DashScope Embedding

### 关键依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| Qdrant | 1.15.3 (Docker) | Layer 4 向量存储 |
| mem0ai | latest | Layer 4 客户端 |
| DashScope API | text-embedding-v4 | 1024 维嵌入 |
| SQLite FTS5 | Python stdlib | Layer 3 全文检索 |

---

## 5. 环境变量与 API 密钥

### 持久化策略

环境变量存放在 `.env` 文件中，通过 `EnvironmentFile=` 指令注入 systemd 服务。这种方式确保 OpenClaw UI 升级覆盖 `.service` 文件后，只需执行 `./deploy.sh fix-service` 即可恢复。

| 文件 | 权限 | 被引用者 |
|------|------|---------|
| `systemd/gateway.env` | 600 | openclaw-gateway.service |
| `systemd/{agent_id}-gateway.env` | 600 | openclaw-gateway-{agent_id}.service |

### 变量清单

| 变量名 | 说明 | 使用者 |
|--------|------|--------|
| `MEM0_DASHSCOPE_API_KEY` | DashScope API 密钥 | mem0_client.py, session_init.py |
| `OPENAI_API_BASE` | DashScope 兼容端点 | mem0 SDK (旧版参数名) |
| `OPENAI_BASE_URL` | DashScope 兼容端点 | mem0 SDK (新版参数名) |
| `TAVILY_API_KEY` | Tavily 搜索 API | OpenClaw 核心 |

### 添加新变量

1. 编辑 `systemd/gateway.env` (和/或 `{agent_id}-gateway.env`)
2. 运行 `systemctl --user daemon-reload`
3. 运行 `./deploy.sh restart`

---

## 6. 调试流程

### 停止所有服务 (含监控)

```bash
./deploy.sh debug-stop
```

这会停止 gateway、各扩展 Agent 和 monitor，防止 monitor 在调试期间自动重启 gateway。

### 手动启动 Gateway (前台模式)

```bash
openclaw gateway start
```

### 查看日志

```bash
journalctl --user -u openclaw-gateway -f          # 主 gateway
journalctl --user -u openclaw-gateway-{agent_id} -f  # 扩展 Agent
journalctl -u openclaw-agent-monitor -f            # monitor
```

### 恢复服务

```bash
./deploy.sh debug-start
```

### 修复升级后的服务文件

```bash
./deploy.sh fix-service
./deploy.sh restart
```

---

## 7. 升级安全清单

OpenClaw UI 升级 (`openclaw gateway install` 或类似操作) 可能覆盖以下文件：

### 会被覆盖的文件

| 文件 | 风险 | 恢复方式 |
|------|------|---------|
| `~/.config/systemd/user/openclaw-gateway.service` | `EnvironmentFile=` 行丢失 | `./deploy.sh fix-service` |
| OpenClaw 二进制 / Node 模块 | 正常升级行为 | 无需恢复 |

### 不会被覆盖的文件

| 文件 | 说明 |
|------|------|
| `workspace/systemd/gateway.env` | 环境变量安全 |
| `workspace/systemd/{agent_id}-gateway.env` | 环境变量安全 |
| `workspace/agent-monitor.js` | 自定义监控逻辑 |
| `workspace/deploy.sh` | 部署脚本 |
| `workspace/skills/mem0-integration/*` | 记忆系统代码 |
| `/etc/systemd/system/openclaw-agent-monitor.service` | 系统级服务 |

### 升级后操作

```bash
# 1. 恢复环境变量引用
./deploy.sh fix-service

# 2. 重启所有服务
./deploy.sh restart

# 3. 验证服务状态
./deploy.sh health
```

---

## deploy.sh 命令速查

**说明**: `deploy.sh` 为 **config-driven**，通过 `scripts/parse_agents.py` 解析 `agents.yaml` 获取 Agent 列表，无需硬编码。

| 命令 | 说明 |
|------|------|
| `install` | 安装所有 systemd 服务并启动 |
| `start` | 启动 gateway + 扩展 Agent + monitor |
| `stop` | 停止所有服务 |
| `restart` | 重启所有服务 |
| `status` | 显示所有服务状态 |
| `logs` | 显示最近日志 |
| `health` | 运行健康检查 |
| `backup` | 完整备份 (workspace + Qdrant snapshot + agent profiles) |
| `backup quick` | 快速备份 (仅 workspace 文件) |
| `restore <dir>` | 从备份目录恢复 workspace + profiles |
| `restore-qdrant <file>` | 从 snapshot 恢复 Qdrant 数据 |
| `rollback` | 回滚到上一个 Git 提交 |
| `rollback-to <commit>` | 回滚到指定提交 |
| `debug-stop` | 停止所有服务 (含 monitor)，安全调试 |
| `debug-start` | 调试完成后恢复所有服务 |
| `fix-service` | 升级后重新注入 EnvironmentFile= |

---

## 变更日志

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0 | 2026-03-03 | 初始版本: 统一记忆系统与监控系统文档 |
| 1.1 | 2026-03-06 | deploy.sh 增加 backup (full/quick)、restore、restore-qdrant 命令; memory_cleanup.py 实现实际删除逻辑; 新增 setup-cron.sh 自动化定时任务 |