每日备份 2026-06-10 12:57:13

doc/HEALTH_STABILITY_GUIDE.md

@@ -0,0 +1,268 @@
+# OpenClaw 配置健康稳定运营指南
+
+> 文档版本: v1.0  
+> 创建时间: 2026-02-07  
+> 适用: 青龙 & 2号机
+
+---
+
+## 核心原则
+
+### 优先级排序
+
+| 优先级 | 原则 | 说明 |
+|--------|------|------|
+| **1** | **稳定 > 功能** | 宁可禁用功能，也不让系统崩溃 |
+| **2** | **简单 > 复杂** | 避免复杂的批量操作，单条处理更可靠 |
+| **3** | **监控 > 信任** | 关键操作要有日志和状态检查 |
+| **4** | **备份 > 自信** | 自动备份配置文件，防止灾难性错误 |
+
+---
+
+## 配置备份策略
+
+### 自动备份脚本
+
+```bash
+# 脚本位置
+/root/.openclaw/scripts/config-backup-monitor.sh
+
+# 功能
+- 每60秒检查 openclaw.json 变化
+- 自动备份（带时间戳）
+- 最多保留10个版本
+```
+
+### 使用方法
+
+```bash
+# 启动监控
+nohup /root/.openclaw/scripts/config-backup-monitor.sh > /var/log/openclaw-config-backup.log 2>&1 &
+
+# 查看日志
+tail -f /var/log/openclaw-config-backup.log
+
+# 查看备份
+ls -la /root/.openclaw/backups/
+```
+
+---
+
+## 监控体系
+
+### 系统级监控
+
+| 监控项 | 脚本 | 频率 |
+|--------|------|------|
+| Gateway 状态 | system-monitor.sh | 每10分钟 |
+| 配置变更 | config-backup-monitor.sh | 每60秒 |
+| Telegram 连接 | telegram-watchdog.sh | 持续运行 |
+| 会话文件大小 | 内置监控 | 实时 |
+
+### 告警阈值
+
+| 指标 | 警告 | 危险 | 处理 |
+|------|------|------|------|
+| 内存使用 | >70% | >85% | 检查进程 |
+| 会话文件 | >5MB | >8MB | 建议新会话 |
+| Gateway 响应 | >30s | >60s | 重启 Gateway |
+| 磁盘空间 | <20% | <10% | 清理日志 |
+
+---
+
+## 问题排查清单
+
+### 1. Gateway 无法连接
+
+```bash
+# 排查步骤
+1. 检查 NO_PROXY 是否包含 Ollama 地址
+2. Gateway 是普通进程，需手动设置环境变量
+3. 执行: NO_PROXY="192.168.0.66" openclaw gateway restart
+```
+
+### 2. Embedding 上下文超限
+
+```bash
+# 症状
+input length exceeds the context length
+
+# 解决方案
+sed -i 's/mxbai/nomic/' /root/.openclaw/openclaw.json
+
+# 模型对比
+| 模型 | 大小 | 上下文 | 适用 |
+|------|------|--------|------|
+| mxbai-embed-large | 669MB | 短 (512) | 短文本 |
+| nomic-embed-text | 274MB | 长 (8192) | 长文档 |
+```
+
+### 3. Ollama 批量上传 404
+
+```bash
+# 症状
+batch file upload failed: 404
+
+# 处理
+正常现象，OpenClaw 自动降级到非批量模式，无需干预
+```
+
+### 4. Compaction 卡死 (重点!)
+
+```bash
+# 症状
+- 系统无响应，会话中断
+- Gateway 无法关闭 (shutdown timed out)
+- 日志显示 compaction retry 反复出现
+
+# 根因
+大会话文件 (9MB+) 导致 compaction 算法超时
+
+# 解决方案
+# 1. 清理卡死的会话
+rm /root/.openclaw/agents/main/sessions/[session-id].jsonl
+
+# 2. 重启 Gateway
+openclaw gateway restart
+
+# 3. 预防
+# agents.defaults.compaction.enabled = false
+```
+
+### 5. LLM 请求超时
+
+```bash
+# 排查步骤
+1. 检查模型 API 是否正常
+2. 查看代理是否通畅
+3. 检查是否有会话文件过大
+4. 重启 Gateway 清理状态
+
+# 日志关键词
+FailoverError: LLM request timed out
+```
+
+---
+
+## 性能优化经验
+
+### 青龙 (1号机) - 8GB 内存
+
+| 场景 | 推荐配置 | 说明 |
+|------|----------|------|
+| 轻量服务 | 2-3并发 | Ollama / 监控脚本 |
+| 中等负载 | 1-2并发 | 可运行一个 Agent |
+| 本地模型 | qwen2.5:3b / llama3:8b | 注意内存占用 |
+| 向量化 | nomic-embed-text | 274MB，适合 SSD |
+
+### 2号机 - 8GB 内存 + HDD
+
+| 场景 | 推荐配置 | 说明 |
+|------|----------|------|
+| 避免大量 | 文件 I/O 操作 | HDD 读写慢 |
+| 本地模型 | qwen2.5:3b (2GB) | 流畅运行 |
+| 监控脚本 | 定期清理日志 | 防止磁盘满 |
+
+---
+
+## 技术决策记录
+
+| 决策 | 选择 | 原因 |
+|------|------|------|
+| 向量模型 | nomic-embed-text | 长上下文适合文档索引 |
+| 批量写入 | 禁用 | Ollama 不稳定，单条更可靠 |
+| paths 配置 | symlink 替代 | OpenClaw 不支持自定义路径 |
+| compaction | 监控为主 | 大文件会卡死，需手动清理 |
+| 版本升级 | 稳定优先 | 不盲目追新，验证后再升级 |
+
+---
+
+## 配置修改流程
+
+### 修改前
+
+1. ✅ 确认修改必要性
+2. ✅ 备份当前配置
+3. ✅ 记录修改意图
+
+### 修改中
+
+1. ✅ 使用 `openclaw config.patch` 或手动编辑
+2. ✅ 修改后检查语法: `python3 -m json.tool openclaw.json > /dev/null`
+
+### 修改后
+
+1. ✅ 重启 Gateway: `openclaw gateway restart`
+2. ✅ 观察日志: `tail -f /tmp/openclaw/openclaw-*.log`
+3. ✅ 验证功能正常
+
+---
+
+## 常见问题速查
+
+| 问题 | 快速解决 |
+|------|----------|
+| Gateway 无响应 | `openclaw gateway restart` |
+| Telegram 断开 | 检查代理，查看 telegram-watchdog.log |
+| 模型调用失败 | 检查 API Key，确认网络通畅 |
+| 内存占用过高 | 强制重启 Gateway |
+| 日志文件过大 | `> /tmp/openclaw/openclaw.log` |
+
+---
+
+## 经验教训
+
+### 历史问题
+
+| 日期 | 问题 | 教训 |
+|------|------|------|
+| 2026-02-04 | 内存管理器缺少 embedding 模型 | 需单独配置 provider + embedding |
+| 2026-02-05 | memorySearch.paths 配置无效 | OpenClaw 不支持自定义 paths，用 symlink 替代 |
+| 2026-02-05 | Gateway 反复重启 | 不要手动添加 agents.memorySearch 配置 |
+| 2026-02-06 | Compaction 卡死导致"死机" | 大会话需要分片或禁用 compaction |
+
+### 核心认识
+
+1. **Gateway 是普通进程** - 不继承 systemd 环境变量，需手动设置 NO_PROXY
+2. **memorySearch 是独立 plugin** - 不走 agents.defaults 配置
+3. **Symlink 解决路径问题** - OpenClaw 不支持 paths，用 `ln -s` 替代
+4. **Compaction 不是必须的** - 可以禁用，不会影响对话功能
+
+---
+
+## 维护命令速查
+
+```bash
+# Gateway 管理
+openclaw gateway status
+openclaw gateway restart
+openclaw gateway stop
+
+# 问题排查
+openclaw doctor --fix
+openclaw doctor
+
+# 配置管理
+openclaw config.get
+openclaw config.patch
+
+# 日志查看
+tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
+
+# 内存清理
+rm /root/.openclaw/agents/main/sessions/*.jsonl
+openclaw gateway restart
+```
+
+---
+
+## 参考文档
+
+- `/root/doc/OPENCLAW_HEALTH_CHECK.md` - 健康检查指南
+- `/root/doc/TROUBLESHOOTING_GUIDE.md` - 故障排查
+- `/root/doc/MULTI-MACHINE.md` - 多机部署
+- `/root/doc/COORDINATION_DEPLOYMENT.md` - 协同部署
+
+---
+
+*文档维护: 2号机 (守护者)*