OpenClaw Gateway 卡死假死问题诊断与预防方案

OpenClaw Gateway 卡死假死问题完整诊断与预防方案

🔍 根因分析：8 大类问题

1️⃣ Gateway 机制问题

问题	描述	影响
单线程事件循环	Node.js 单线程模型，长时间任务阻塞主循环	所有请求排队，表现为无响应
WebSocket 连接泄漏	客户端断开后连接未正确释放	连接数累积，内存增长
缺少背压控制	请求速率超过处理能力时无降级	雪崩效应

症状表现：

# Gateway 状态显示正常，但所有请求超时
openclaw gateway status
# 输出：Listening: 127.0.0.1:18789
# 但实际请求无响应

问题	描述	影响
异常退出残留	进程被 kill、系统崩溃、断电	.lock 文件残留，新进程无法启动
PID 文件过期	进程结束但 PID 文件未清理	提示 Gateway 已运行但实际未运行
临时文件累积	日志/缓存未定期清理	磁盘空间占用，IO 变慢

典型错误：

Error: Gateway is already running (PID file exists) 但实际上进程已不存在

问题	描述	影响
快速重启	旧进程未完全释放端口 (TIME_WAIT)	等待 30-60 秒或使用 SO_REUSEADDR
多实例竞争	配置重复启动	使用锁文件机制
其他进程占用	其他应用使用相同端口	修改端口或停止冲突进程

排查命令：

# 查找占用进程
Get-NetTCPConnection -LocalPort 18789 | Select-Object OwningProcess
# 释放端口
Stop-Process -Id <PID> -Force

问题	描述	影响
API 请求超时	外部 API 无响应时无限等待	30-120 秒
数据库连接超时	连接池耗尽时阻塞	10-30 秒
文件 IO 超时	大文件读写卡住	60 秒
WebSocket 心跳	客户端断开未检测	60 秒间隔

配置项	当前状态	建议配置
心跳检测	❌ 未配置	每 15 分钟检查
自动重启	❌ 未配置	失败时自动重启
健康告警	❌ 未配置	异常时通知用户

问题	描述	影响
无重试机制	单次失败直接报错	服务不可用
无限重试	死循环重试，资源耗尽	系统过载
缺少降级	依赖服务挂掉时整体不可用	用户体验差

问题	描述	影响
会话内存无限制	长时间运行后内存泄漏	单会话≤512MB
大文件加载	一次性加载大文件到内存	流式处理
缓存无淘汰	缓存无限增长	LRU 淘汰策略

问题	描述	影响
未充分测试	边界条件触发崩溃	稳定性风险
缺少开关	无法快速禁用问题功能	故障恢复慢
日志不足	问题难以定位	排查困难

✅ 步骤 2：检查端口占用

# 检查 18789 端口
Get-NetTCPConnection -LocalPort 18789 -ErrorAction SilentlyContinue | Select-Object LocalAddress, LocalPort, OwningProcess, State

✅ 步骤 4：清理临时文件

# 清理锁文件
Remove-Item -Path "$env:TEMP\openclaw\*.lock" -Force -ErrorAction SilentlyContinue
# 清理旧日志
Get-ChildItem "$env:TEMP\openclaw" | Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)} | Remove-Item -Force

✅ 预防性维护方案

方案一：PowerShell 维护脚本

创建 preventive-maintenance.ps1：

# OpenClaw 预防性维护脚本
# 安全执行，不影响当前运行的服务
Write-Host "🔧 OpenClaw 预防性维护" -ForegroundColor Cyan
Write-Host "========================" -ForegroundColor Cyan

# 1. 清理 7 天前的日志
$LogDir = "$env:TEMP\openclaw"
if (Test-Path $LogDir) {
    $OldLogs = Get-ChildItem $LogDir | Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)}
    $OldLogs | Remove-Item -Force
    Write-Host "✅ 已清理 $($OldLogs.Count) 个旧日志文件"
}

# 2. 清理残留锁文件
$LockFiles = @("$env:TEMP\openclaw\*.lock", "$env:TEMP\openclaw\gateway.pid")
foreach ($lock in $LockFiles) {
    if (Test-Path $lock) {
        Remove-Item $lock -Force -ErrorAction SilentlyContinue
        Write-Host "✅ 已清理锁文件：$lock"
    }
}

# 3. 检查端口占用
$Port = Get-NetTCPConnection -LocalPort 18789 -ErrorAction SilentlyContinue
if ($Port) {
    Write-Host "✅ 端口 18789 正常占用 (PID: $($Port.OwningProcess))"
} else {
    Write-Host "⚠️ 端口 18789 未被占用，Gateway 可能未运行"
}

# 4. 检查 Gateway 状态
try {
    $Status = openclaw gateway status 2>&1
    if ($Status -match "Listening") {
        Write-Host "✅ Gateway 运行正常"
    } else {
        Write-Host "⚠️ Gateway 状态异常，建议运行 openclaw doctor --repair"
    }
} catch {
    Write-Host "❌ Gateway 状态检查失败：$_"
}

# 5. 配置文件备份
$ConfigPath = "$env:USERPROFILE\.openclaw\openclaw.json"
if (Test-Path $ConfigPath) {
    $BackupPath = "$ConfigPath.backup.$(Get-Date -Format 'yyyyMMdd-HHmmss')"
    Copy-Item $ConfigPath $BackupPath
    Write-Host "✅ 配置已备份：$BackupPath"
}

Write-Host ""
Write-Host "🎉 预防性维护完成！" -ForegroundColor Green

方案二：健康检查配置

创建 gateway-healthcheck.json：

{
  "healthcheck": {
    "enabled": true,
    "intervalMinutes": 15,
    "timeoutSeconds": 30,
    "maxRetries": 3,
    "autoRestart": true,
    "alerts": {
      "onFailure": true,
      "onRestart": true
    }
  },
  "resourceLimits": {
    "maxSessionMemoryMb": 512,
    "maxConcurrentSessions": 10,
    "sessionTimeoutMinutes": 120,
    "idleTimeoutMinutes": 30
  },
  "gateway": {
    "connectionTimeout": 30,
    "requestTimeout": 120,
    "keepAliveInterval": 60,
    "maxRequestBodySize": "50mb"
  },
  "logging": {
    "level": "warn",
    "rotateDaily": true,
    "maxBackups": 7
  }
}

指标	正常范围	异常范围
Gateway 响应时间	<100ms	>1000ms
内存占用	<512MB	>1GB
活跃连接数	<50	>200
错误率	<1%	>5%
磁盘空间	>10GB	<1GB

端口占用处理

# 查找占用进程
$Port = Get-NetTCPConnection -LocalPort 18789 -ErrorAction SilentlyContinue
if ($Port) {
    Write-Host "占用进程 PID: $($Port.OwningProcess)"
    # 释放端口
    Stop-Process -Id $Port.OwningProcess -Force
    Write-Host "✅ 端口已释放"
    # 等待端口释放
    Start-Sleep -Seconds 5
}

📈 长期稳定方案

短期 (立即执行)

1. ✅ 添加看门狗进程（任务计划）
2. ✅ 配置日志轮转
3. ✅ 设置资源限制

中期 (1 周内)

1. 升级 OpenClaw 到最新版本
2. 配置远程监控 webhook
3. 建立备份策略

长期 (架构优化)

1. 多实例部署（主备模式）
2. 容器化部署（Docker）
3. 服务网格（熔断降级）