11 KiB

Raw Permalink Blame History

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 核心

添加新变量

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

6. 调试流程

停止所有服务 (含监控)

./deploy.sh debug-stop

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

手动启动 Gateway (前台模式)

openclaw gateway start

查看日志

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

恢复服务

./deploy.sh debug-start

修复升级后的服务文件

./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`	系统级服务

升级后操作

# 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 自动化定时任务

11 KiB Raw Permalink Blame History