555 lines
13 KiB
Markdown
555 lines
13 KiB
Markdown
# 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. **紧急排查：** 结合两者结果处理问题
|