269 lines
6.2 KiB
Markdown
269 lines
6.2 KiB
Markdown
# 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号机 (守护者)*
|