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