my-project/doc/HEALTH_STABILITY_GUIDE.md

OpenClaw 配置健康稳定运营指南

文档版本: v1.0
创建时间: 2026-02-07
适用: 青龙 & 2号机

---

核心原则

优先级排序

优先级	原则	说明
1	稳定 > 功能	宁可禁用功能，也不让系统崩溃
2	简单 > 复杂	避免复杂的批量操作，单条处理更可靠
3	监控 > 信任	关键操作要有日志和状态检查
4	备份 > 自信	自动备份配置文件，防止灾难性错误

---

配置备份策略

自动备份脚本

# 脚本位置
/root/.openclaw/scripts/config-backup-monitor.sh

# 功能
- 每60秒检查 openclaw.json 变化
- 自动备份（带时间戳）
- 最多保留10个版本

使用方法

# 启动监控
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 无法连接

# 排查步骤
1. 检查 NO_PROXY 是否包含 Ollama 地址
2. Gateway 是普通进程，需手动设置环境变量
3. 执行: NO_PROXY="192.168.0.66" openclaw gateway restart

2. Embedding 上下文超限

# 症状
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

# 症状
batch file upload failed: 404

# 处理
正常现象，OpenClaw 自动降级到非批量模式，无需干预

4. Compaction 卡死 (重点!)

# 症状
- 系统无响应，会话中断
- 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 请求超时

# 排查步骤
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 不是必须的 - 可以禁用，不会影响对话功能

---

维护命令速查

# 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号机 (守护者)