# OpenClaw 系统健康检查标准流程

> **文档版本：** v1.0  
> **创建日期：** 2026-02-06  
> **用途：** OpenClaw 守护者日常自我健康检查标准流程  
> **执行方式：** `/root/.openclaw/scripts/standard-check.sh`

---

## 📋 检查概述

本标准流程用于 OpenClaw 守护者 (2号机) 进行系统性自我健康检查，确保所有核心组件正常运行。

**检查频率：**
- ⏰ **每日自动：** 通过 cron 定时任务执行 (每日 00:00)
- 🔧 **手动执行：** `/root/.openclaw/scripts/standard-check.sh`
- 🚨 **异常时执行：** 服务不稳定或收到告警时

**通过标准：** 0 个失败项 (允许最多 1-2 个警告项)

---

## 🛡️ 九步检查流程

### 【第一步】系统基础信息

**检查目的：** 确认系统基本信息，记录运行状态

**检查项：**
| 项目 | 说明 | 正常范围 |
|------|------|----------|
| 主机名 | 当前运行主机 | `yh6788-ThinkPad-X230` |
| 内核版本 | Linux 内核 | 6.x.x |
| 运行时间 | 系统启动后持续运行时间 | > 0 |

**执行命令：**
```bash
hostname
uname -r
uptime -p
```

**预期结果：**
- ✅ 系统正常运行，无异常重启
- ✅ 运行时间符合预期 (通常 > 1小时)

---

### 【第二步】OpenClaw 服务检查

**检查目的：** 确认 Gateway 核心服务运行状态

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| Gateway 进程 | openclaw-gateway 主进程 | 运行中 (有 PID) |
| Gateway 端口 | 默认监听端口 18789 | 正常监听 |

**执行命令：**
```bash
# 检查进程
pgrep -f "openclaw-gateway"

# 检查端口
ss -tlnp | grep ":18789 "
# 或
netstat -tlnp | grep ":18789 "
```

**异常处理：**
- ❌ **Gateway 未运行：** 执行 `openclaw gateway start`
- ❌ **端口未监听：** 检查日志 `tail -f /tmp/openclaw/openclaw-*.log`

---

### 【第三步】Ollama 服务检查

**检查目的：** 确认本地向量模型服务可用

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| Ollama 进程 | ollama serve 主进程 | 运行中 |
| Ollama API | 本地 API 访问 | HTTP 200 |
| 已安装模型 | 向量嵌入模型数量 | ≥1 个 |

**执行命令：**
```bash
# 检查进程
pgrep -f "ollama serve"

# API 测试
curl -s http://localhost:11434/api/version

# 模型列表
curl -s http://localhost:11434/api/tags | grep -o '"name":"[^"]*"'
```

**正常结果示例：**
```json
{"version":"0.15.4"}
```

**已安装模型：**
- `nomic-embed-text:latest` (默认，长上下文)
- `mxbai-embed-large:latest` (快速，短文本)

**异常处理：**
- ❌ **Ollama 未运行：** 执行 `ollama serve`
- ❌ **API 不可访问：** 检查端口 11434 监听状态
- ❌ **模型缺失：** 执行 `ollama pull nomic-embed-text:latest`

---

### 【第四步】内存索引状态

**检查目的：** 确认向量检索功能正常

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| 索引状态 | 文件索引进度 | 17/18 files |
| 向量引擎 | 向量数据库就绪 | Vector: ready |
| 同步状态 | 是否有未保存变动 | Dirty: no |

**执行命令：**
```bash
openclaw memory status
```

**输出示例：**
```
Memory Search (main)
Provider: openai (requested: openai)
Model: nomic-embed-text:latest
Sources: memory
Indexed: 17/18 files · 56 chunks
Dirty: yes
Store: ~/.openclaw/memory/main.sqlite
Workspace: ~/.openclaw/workspace
Vector: ready
Vector dims: 768
```

**关键指标解读：**
- `Indexed: 17/18 files` → 17个文件已索引，共18个文件
- `56 chunks` → 知识库已分割为56个向量块
- `Dirty: yes` → 有文件变动，需要重新索引
- `Vector: ready` → 向量引擎工作正常

**异常处理：**
- ⚠️ **Dirty: yes:** 执行 `openclaw memory index`
- ❌ **Vector not ready:** 重启 Gateway `openclaw gateway restart`
- ❌ **Indexed 文件数异常：** 检查 workspace 文件完整性

---

### 【第五步】代理配置检查

**检查目的：** 确认网络代理配置正确，不干扰本地服务

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| NO_PROXY | 本地服务免代理 | 已配置 |
| 代理可达 | 外部网络访问 | 可访问 |

**执行命令：**
```bash
# 检查环境变量
env | grep NO_PROXY

# 代理测试
curl -s -o /dev/null -w "%{http_code}" --proxy http://192.168.0.66:7890 https://api.openai.com/v1/models
```

**预期 NO_PROXY 配置：**
```
NO_PROXY=localhost,127.0.0.1,192.168.0.66,192.168.0.32,.local
```

**异常处理：**
- ❌ **NO_PROXY 未配置：** 编辑 `/etc/systemd/system/openclaw-gateway.service.d/override.conf`
- ❌ **代理不可达：** 检查代理服务状态 (192.168.0.66:7890)

---

### 【第六步】磁盘空间检查

**检查目的：** 确保系统有足够磁盘空间运行

**检查项：**
| 分区 | 挂载点 | 警告阈值 | 严重阈值 |
|------|--------|----------|----------|
| 根分区 | / | 80% | 90% |
| Workspace | /root/.openclaw/workspace | 80% | 90% |

**执行命令：**
```bash
# 根分区
df -h /

# Workspace
df -h /root/.openclaw/workspace
```

**预期结果：**
- ✅ 使用率 < 80%
- ✅ 可用空间 > 50GB

**异常处理：**
- ⚠️ **使用率 > 80%:** 清理日志文件 `/var/log/openclaw-monitor/`
- ❌ **使用率 > 90%:** 紧急清理，扩展磁盘

---

### 【第七步】监控脚本检查

**检查目的：** 确认后台监控正常运行

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| 脚本存在 | system-monitor.sh | 存在 |
| 语法检查 | bash -n 测试 | 无错误 |
| 进程运行 | 监控进程 | 运行中 |
| 日志目录 | /var/log/openclaw-monitor | 存在 |

**执行命令：**
```bash
# 检查脚本存在
ls -la /root/.openclaw/scripts/system-monitor.sh

# 语法检查
bash -n /root/.openclaw/scripts/system-monitor.sh

# 进程检查
pgrep -f "system-monitor.sh"

# 日志文件数
ls -1 /var/log/openclaw-monitor/*.log | wc -l
```

**监控脚本功能：**
- CPU/内存/负载实时监控
- 阈值告警 (CPU > 80%, 内存 > 80%)
- OpenClaw 服务状态检测
- 日志保留 3 小时 (5400 条记录)

**异常处理：**
- ❌ **脚本不存在：** 从文档恢复
- ❌ **语法错误：** 检查最近修改
- ❌ **进程未运行：** 执行 `nohup /root/.openclaw/scripts/system-monitor.sh &`

---

### 【第八步】配置检查

**检查目的：** 验证核心配置文件完整性

**检查项：**
| 文件 | 说明 | 检查方法 |
|------|------|----------|
| openclaw.json | 主配置 | JSON 语法验证 |
| Systemd override | 代理配置 | 文件存在验证 |

**执行命令：**
```bash
# JSON 语法检查
python3 -m json.tool /root/.openclaw/openclaw.json > /dev/null && echo "OK"

# 提取当前模型配置
grep '"model":' /root/.openclaw/openclaw.json

# Systemd override 检查
cat /etc/systemd/system/openclaw-gateway.service.d/override.conf
```

**openclaw.json 关键配置：**
```json
{
  "providers": {
    "openai": {
      "DEFAULT": ["minimax/minimax-m2.1"]
    }
  },
  "memorySearch": {
    "provider": "openai",
    "model": "nomic-embed-text:latest",
    "remote": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama-local"
    }
  }
}
```

**Systemd override 预期内容：**
```ini
[Service]
Environment="NO_PROXY=localhost,127.0.0.1"
Environment="no_proxy=localhost,127.0.0.1"
```

**异常处理：**
- ❌ **JSON 语法错误：** 检查引号、逗号、括号
- ❌ **override 不存在：** 创建配置文件并重启 Gateway

---

### 【第九步】1号机 SSH 检查

**检查目的：** 确认协同机器人的网络连通性

**检查项：**
| 检查点 | 说明 | 正常状态 |
|--------|------|----------|
| SSH 连接 | 1号机网络可达 | 可连接 |
| 1号机 Gateway | 1号机 OpenClaw 服务 | 运行中 |

**执行命令：**
```bash
# SSH 连接测试 (需要配置 SSH 密钥)
ssh -o BatchMode=yes -o ConnectTimeout=3 root@192.168.0.31 "echo 'OK'"

# 1号机 Gateway 检查
ssh root@192.168.0.31 "pgrep -f openclaw-gateway"
```

**1号机信息：**
- **地址：** root@192.168.0.31
- **密码：** 3efvVGY&
- **已知问题：** 内存持久化故障 (已手动修复)

**异常处理：**
- ⚠️ **SSH 密钥未配置：** 配置 SSH 密钥实现免密登录
- ❌ **连接失败：** 检查网络 (192.168.0.31)
- ⚠️ **1号机 Gateway 未运行：** 提醒用户检查 1号机

---

## 📊 结果汇总标准

### 通过等级

| 等级 | 失败数 | 警告数 | 行动 |
|------|--------|--------|------|
| 🎉 **优秀** | 0 | 0 | 无需操作 |
| ✅ **良好** | 0 | 1-2 | 计划内处理 |
| ⚠️ **警告** | 0 | 3+ | 尽快处理 |
| ❌ **异常** | 1+ | 任意 | **立即处理** |

### 输出模板

```
========================================
  🛡️ OpenClaw 标准系统检查
  时间: YYYY-MM-DD HH:MM:SS
========================================
  总检查项: XX
  ✅ 通过: XX
  ⚠️ 警告: XX
  ❌ 失败: XX
========================================
```

### 告警日志位置

- **告警日志：** `/var/log/openclaw-monitor/alerts.log`
- **指标日志：** `/var/log/openclaw-monitor/system-metrics.log`

---

## 🚨 异常处理预案

### 紧急情况 (失败数 ≥ 1)

1. **Gateway 未运行**
   ```bash
   openclaw gateway status
   openclaw gateway start
   ```

2. **Ollama 崩溃**
   ```bash
   pkill -f ollama
   ollama serve
   ```

3. **索引损坏**
   ```bash
   rm -rf ~/.openclaw/memory/
   openclaw memory index
   ```

### 警告情况

1. **Dirty 状态持续**
   ```bash
   openclaw memory index
   ```

2. **磁盘空间不足**
   ```bash
   # 清理日志
   rm -f /var/log/openclaw-monitor/*.log.*
   
   # 检查大文件
   du -sh /root/.openclaw/workspace/*
   ```

---

## 📝 检查记录

| 日期 | 检查人 | 通过项 | 警告项 | 失败项 | 备注 |
|------|--------|--------|--------|--------|------|
| 2026-02-05 | 2号机 | 18 | 1 | 0 | Dirty 状态 |
| | | | | | |

---

## 🔗 相关文档

- **监控脚本：** `/root/.openclaw/scripts/system-monitor.sh`
- **主配置：** `/root/.openclaw/openclaw.json`
- **系统配置：** `/etc/systemd/system/openclaw-gateway.service.d/override.conf`
- **记忆文件：** `/root/.openclaw/workspace/MEMORY.md`
- **多机部署：** `/root/doc/MULTI-MACHINE.md`

---

## ✨ 更新日志

| 版本 | 日期 | 修改内容 |
|------|------|----------|
| v1.0 | 2026-02-06 | 初版发布，基于 standard-check.sh 脚本 |
| v1.1 | 2026-02-06 | 新增 Web 服务访问、锁文件、日志深度检查、系统资源深度诊断 |

---

## 🔧 补充：深度诊断工具 (why.py)

> **说明：** 标准检查流程覆盖基础项目，`why.py` 提供更深入的诊断能力

### 工具位置
```
/root/tools/why.py
```

### 安装依赖
```bash
pip install psutil requests
```

### 执行方式
```bash
python3 /root/tools/why.py
```

### why.py 专属检查项

| 检查项 | 说明 | 严重程度 |
|--------|------|----------|
| Web 服务访问 | 测试 localhost:18789 HTTP 访问 | HIGH |
| 锁文件检测 | 检查死锁文件 (*.lock) | MEDIUM/HIGH |
| 日志深度分析 | 扫描 error/fail/timeout/crash | MEDIUM |
| 进程内存统计 | OpenClaw 单独内存使用 | MEDIUM |
| API 连接测试 | DeepSeek API 连通性 | HIGH |
| 配置完整性 | JSON 语法 + 关键配置项 | CRITICAL |

### 输出示例
```
========================================
OpenClaw 问题诊断工具
运行时间: 2026-02-06 07:40:00
========================================

🔍 检查系统资源...
内存: 45% 已使用 (3625MB/7982MB)

🔍 检查配置文件...
✅ 配置文件存在: /root/.openclaw/openclaw.json
✅ 包含 agents 配置
DeepSeek API密钥: sk-...ab12

🔍 检查网关进程...
找到 1 个网关进程:
  PID: 968802, 状态: running

🔍 检查端口监听...
✅ 端口 18789 正在监听
   监听进程: tcp LISTEN 0 128 127.0.0.1:18789 users:(("openclaw-gateway")

🔍 检查Web服务...
✅ 本地访问: 成功 (HTTP 200)

🔍 检查锁文件...
✅ 未发现锁文件

🔍 检查模型连接性...
✅ DeepSeek API: 连接成功 (HTTP 200)

🔍 检查日志文件...
找到 3 个日志文件
   /root/.openclaw/openclaw.log (修改时间: 2026-02-06 07:30:00)

========================================
诊断报告摘要
========================================

CRITICAL级别问题 (0个):
HIGH级别问题 (0个):
MEDIUM级别问题 (0个):

📄 详细报告已保存到: /root/.openclaw/diagnosis_20260206_074000.json
```

### 告警级别定义

| 级别 | 含义 | 建议行动 |
|------|------|----------|
| **CRITICAL** | 系统不可用 | **立即处理** |
| **HIGH** | 功能受损 | 尽快处理 |
| **MEDIUM** | 潜在问题 | 计划处理 |
| **LOW** | 轻微问题 | 可忽略 |
| **INFO** | 信息提示 | 记录备查 |

### 快速建议生成

`why.py` 会根据问题自动生成处理建议：
```
💡 建议操作:
  1. 建议: 启动网关 - `openclaw gateway --force &`
  2. 建议: 更新DeepSeek API密钥
  3. 建议: 清理锁文件 - `find ~/.openclaw -name '*.lock' -delete`
```

### 诊断报告位置

每次执行会生成 JSON 报告：
```
~/.openclaw/diagnosis_YYYYMMDD_HHMMSS.json
```

---

## 📋 完整检查流程

**标准流程 + 深度诊断配合使用：**

1. **日常检查：** 执行 `standard-check.sh`
2. **异常诊断：** 执行 `python3 /root/tools/why.py`
3. **紧急排查：** 结合两者结果处理问题