#第 9 章：故障排查与日志分析

openclaw doctor        # 全面诊断
openclaw doctor --fix  # 自动修复已知问题
openclaw doctor --json # 输出 JSON 格式（适合脚本调用）

# 检查 Gateway 进程
ps aux | grep openclaw
systemctl status openclaw-gateway --user

# 检查端口占用
lsof -i :18789
ss -tlnp | grep 18789

# 检查配置文件语法
python3 -m json.tool ~/.openclaw/openclaw.json

# 检查磁盘空间
df -h ~/.openclaw/
du -sh ~/.openclaw/*/

#!/bin/bash
# health-check.sh — OpenClaw 自动健康检查
set -e

echo "=== OpenClaw 健康检查 $(date) ==="

# 1. 检查 Gateway 进程
if pgrep -f "openclaw" > /dev/null; then
  echo "✅ Gateway 进程正常"
else
  echo "❌ Gateway 未运行，尝试重启..."
  openclaw gateway start
fi

# 2. 检查端口
if ss -tlnp | grep -q 18789; then
  echo "✅ 端口 18789 正常监听"
else
  echo "❌ 端口 18789 未监听"
fi

# 3. 检查磁盘空间
DISK_USAGE=$(df -h ~/.openclaw/ | tail -1 | awk '{print $5}' | tr -d '%')
if [ "$DISK_USAGE" -lt 90 ]; then
  echo "✅ 磁盘使用 ${DISK_USAGE}%"
else
  echo "⚠️  磁盘使用 ${DISK_USAGE}%，建议清理"
fi

# 4. 检查配置文件
if python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1; then
  echo "✅ 配置文件语法正确"
else
  echo "❌ 配置文件 JSON 格式错误"
fi

echo "=== 检查完成 ==="

# 实时跟踪 Gateway 日志
openclaw logs --follow

# systemd 服务日志
journalctl --user -u openclaw-gateway -f

# 只看错误
journalctl --user -u openclaw-gateway --priority=err

# 查最近 1 小时
journalctl --user -u openclaw-gateway --since "1 hour ago"

# 查看配置审计记录
tail -20 ~/.openclaw/logs/config-audit.jsonl | python3 -m json.tool

# 调高日志级别（排查问题时使用）
openclaw config set logLevel debug

# 恢复正常级别
openclaw config set logLevel info

# 统计最近一天各级别日志数量
journalctl --user -u openclaw-gateway --since "1 day ago" --no-pager | \
  grep -oP '(DEBUG|INFO|WARN|ERROR|FATAL)' | sort | uniq -c | sort -rn

# 提取所有错误信息的时间线
journalctl --user -u openclaw-gateway --priority=err --since "7 days ago" \
  --no-pager -o short-iso | tail -50

# 统计 Cron 任务执行成功/失败次数
for f in ~/.openclaw/cron/runs/*.jsonl; do
  status=$(tail -1 "$f" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status','unknown'))" 2>/dev/null)
  echo "$(basename $f): $status"
done | sort -t: -k2 | uniq -c -f1

# 步骤 1: 检查端口
lsof -i :18789
# 如果有其他程序占用，kill 或改端口

# 步骤 2: 检查配置
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 如果 JSON 无效，用备份恢复：
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 步骤 3: 重新安装服务
openclaw daemon install --force
openclaw gateway start

# 检查 Gateway 连接状态
openclaw gateway status --deep

# 检查 AI 模型可用性
curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_KEY" | head

# 检查飞书通道连接
openclaw channels status

# 重启 Gateway
openclaw gateway restart

# 验证 SKILL.md 格式
head -20 ~/.openclaw/workspace/skills/<name>/SKILL.md

# 检查 YAML front matter 是否有效
python3 -c "
import yaml
with open('SKILL.md') as f:
    content = f.read()
    # 提取 front matter
    parts = content.split('---')
    if len(parts) >= 3:
        meta = yaml.safe_load(parts[1])
        print('Valid:', meta.get('name'))
"

# 检查 _meta.json
python3 -m json.tool ~/.openclaw/workspace/skills/<name>/_meta.json

# 全面诊断
openclaw doctor

# 检查 cron 配置
python3 -m json.tool ~/.openclaw/cron/jobs.json

# 检查任务状态
python3 -c "
import json
jobs = json.load(open('$HOME/.openclaw/cron/jobs.json'))
for job in jobs['jobs']:
    state = job.get('state', {})
    print(f'{job[\"name\"]}: enabled={job[\"enabled\"]}, '
          f'lastStatus={state.get(\"lastStatus\", \"never\")}, '
          f'errors={state.get(\"consecutiveErrors\", 0)}')
"

# 查看当前内存占用
ps -o pid,vsz,rss,comm -p $(pgrep -f openclaw)

# 限制 Node.js 内存
NODE_OPTIONS="--max-old-space-size=512" openclaw gateway start

# 查看各目录占用
du -sh ~/.openclaw/*/

# 清理历史会话
find ~/.openclaw/agents/*/sessions/ -mtime +30 -delete

# 清理 Cron 运行记录
find ~/.openclaw/cron/runs/ -mtime +7 -delete

# 压缩日志
gzip ~/.openclaw/logs/*.log.old

# 统计过去 24h 各级别日志数量
cat ~/.openclaw/logs/gateway.log | \
  jq -r '.level' 2>/dev/null | sort | uniq -c | sort -rn

# 查看 Cron 任务失败历史（最近 10 条）
for f in ~/.openclaw/cron/runs/*.jsonl; do
  tail -1 "$f" | jq -r 'select(.status=="error") | "\(.timestamp) \(.error)"' 2>/dev/null
done | tail -10

# 分析 Agent 工具调用频率
grep -h '"tool"' ~/.openclaw/agents/main/sessions/*.jsonl 2>/dev/null | \
  jq -r '.tool' | sort | uniq -c | sort -rn | head -10

# 第 1 步：查看 Gateway 当前状态
openclaw gateway status
echo "当前状态已记录"

# 第 2 步：检查端口和进程
ps aux | grep openclaw | grep -v grep
lsof -i :18789 2>/dev/null || echo "端口未被占用"

# 第 3 步：验证配置文件完整性
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1 \
  && echo "✅ 配置文件有效" \
  || echo "❌ 配置文件格式错误，尝试恢复备份"

# 第 4 步：运行全面诊断
openclaw doctor

# 第 5 步：查看最近的错误日志
journalctl --user -u openclaw-gateway --priority=err --since "1 hour ago" --no-pager | tail -20

#!/bin/bash
# disk-monitor.sh — 磁盘空间监控
THRESHOLD=80  # 告警阈值百分比

USAGE=$(df -h ~/.openclaw/ | tail -1 | awk '{print $5}' | tr -d '%')
echo "当前磁盘使用率: ${USAGE}%"

if [ "$USAGE" -ge "$THRESHOLD" ]; then
  echo "⚠️  磁盘使用超过 ${THRESHOLD}%，执行清理..."

  # 清理 30 天前的会话
  DELETED=$(find ~/.openclaw/agents/*/sessions/ -mtime +30 -delete -print 2>/dev/null | wc -l)
  echo "已清理 $DELETED 个旧会话文件"

  # 清理 7 天前的 Cron 记录
  DELETED2=$(find ~/.openclaw/cron/runs/ -mtime +7 -delete -print 2>/dev/null | wc -l)
  echo "已清理 $DELETED2 个 Cron 运行记录"

  # 重新检查
  NEW_USAGE=$(df -h ~/.openclaw/ | tail -1 | awk '{print $5}' | tr -d '%')
  echo "清理后磁盘使用率: ${NEW_USAGE}%"
else
  echo "✅ 磁盘空间充足"
fi

# 查看可用备份
ls -la ~/.openclaw/openclaw.json.bak*

# 使用最新备份恢复
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw gateway reload

# 方案 1：终止占用进程
kill $(lsof -ti :18789)

# 方案 2：修改 OpenClaw 端口
openclaw config set gateway.port 18790
openclaw gateway restart

# 开启 DEBUG
openclaw config set logLevel debug
# 排查问题...
# 恢复
openclaw config set logLevel info