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.
267 lines
9.7 KiB
267 lines
9.7 KiB
# OpenClaw Extensions Architecture |
|
|
|
**版本:** 1.0 |
|
**日期:** 2026-03-03 |
|
**维护者:** Eason (陈医生) |
|
|
|
> **重要提示**: 本文档是所有自定义扩展的权威参考。在修改任何基础设施代码（systemd 服务、监控脚本、部署脚本、记忆系统）之前，必须阅读本文档。OpenClaw UI 升级可能覆盖部分文件，请参考第 7 节的升级安全清单。 |
|
|
|
--- |
|
|
|
## 1. 扩展概览 |
|
|
|
OpenClaw 核心是上游提供的 AI Agent 网关。以下组件为自定义扩展，不属于上游代码，升级时需特别保护： |
|
|
|
| 扩展组件 | 位置 | 说明 | |
|
|---------|------|------| |
|
| 四层记忆系统 | `skills/mem0-integration/` | Mem0 + Qdrant + FTS5 本地检索 | |
|
| Agent Monitor | `agent-monitor.js` | 健康监控、自动重启、Telegram 通知 | |
|
| 部署脚本 | `deploy.sh` | 服务管理、备份、回滚、调试命令 | |
|
| 环境变量文件 | `systemd/gateway.env`, `systemd/life-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-life.service │ ← Life Agent │ |
|
│ │ (张大师) │ │ |
|
│ │ EnvironmentFile=life-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-life.service` | `~/.config/systemd/user/openclaw-gateway-life.service` | Life 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 环境变量 | |
|
| `life-gateway.env` | 原地引用 (不复制) | Life Agent 环境变量 | |
|
|
|
--- |
|
|
|
## 3. 监控系统 (Agent Monitor) |
|
|
|
**文件**: `agent-monitor.js` |
|
**服务**: `openclaw-agent-monitor.service` (system-level) |
|
|
|
### 功能 |
|
|
|
| 功能 | 说明 | |
|
|------|------| |
|
| 双服务监控 | 同时监控 gateway 和 life agent | |
|
| 重启限制 | 5 分钟内最多 5 次重启，超限停止并报警 | |
|
| 升级容忍 | 首次检测到服务停止后等待 60 秒，避免升级期间误报 | |
|
| 心跳日志 | 每 10 分钟输出一次状态 (`gateway=OK, life=OK`) | |
|
| Telegram 通知 | 服务异常、重启失败时发送告警 | |
|
| 日志记录 | `logs/agents/health-YYYY-MM-DD.log` | |
|
|
|
### 监控流程 |
|
|
|
``` |
|
每 30 秒 → 检查 gateway 状态 |
|
→ 检查 life 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` |
|
|
|
### 快速参考 |
|
|
|
- **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/life-gateway.env` | 600 | openclaw-gateway-life.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` (和/或 `life-gateway.env`) |
|
2. 运行 `systemctl --user daemon-reload` |
|
3. 运行 `./deploy.sh restart` |
|
|
|
--- |
|
|
|
## 6. 调试流程 |
|
|
|
### 停止所有服务 (含监控) |
|
|
|
```bash |
|
./deploy.sh debug-stop |
|
``` |
|
|
|
这会停止 gateway、life agent 和 monitor，防止 monitor 在调试期间自动重启 gateway。 |
|
|
|
### 手动启动 Gateway (前台模式) |
|
|
|
```bash |
|
openclaw gateway start |
|
``` |
|
|
|
### 查看日志 |
|
|
|
```bash |
|
journalctl --user -u openclaw-gateway -f # 主 gateway |
|
journalctl --user -u openclaw-gateway-life -f # life 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/life-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 命令速查 |
|
|
|
| 命令 | 说明 | |
|
|------|------| |
|
| `install` | 安装所有 systemd 服务并启动 | |
|
| `start` | 启动 gateway + life + monitor | |
|
| `stop` | 停止所有服务 | |
|
| `restart` | 重启所有服务 | |
|
| `status` | 显示所有服务状态 | |
|
| `logs` | 显示最近日志 | |
|
| `health` | 运行健康检查 | |
|
| `backup` | 创建工作区备份 | |
|
| `rollback` | 回滚到上一个 Git 提交 | |
|
| `rollback-to <commit>` | 回滚到指定提交 | |
|
| `debug-stop` | 停止所有服务 (含 monitor)，安全调试 | |
|
| `debug-start` | 调试完成后恢复所有服务 | |
|
| `fix-service` | 升级后重新注入 EnvironmentFile= | |
|
|
|
--- |
|
|
|
## 变更日志 |
|
|
|
| 版本 | 日期 | 变更 | |
|
|------|------|------| |
|
| 1.0 | 2026-03-03 | 初始版本: 统一记忆系统与监控系统文档 |
|
|
|