openclaw-troubleshooter

# 🔧 OpenClaw Troubleshooter

**一键诊断 + 修复 OpenClaw 常见问题**

基于真实故障经验提取（2026-03-14 Gateway 断开 + Control UI origin 验证失败事件）

---

## 🚀 快速使用

### 完整诊断（推荐）
```powershell
openclaw troubleshoot
```

### 仅诊断不修复
```powershell
openclaw troubleshoot --check-only
```

### 修复特定问题
```powershell
openclaw troubleshoot --fix gateway      # 修复 Gateway
openclaw troubleshoot --fix config       # 修复配置
openclaw troubleshoot --fix security     # 修复安全问题
openclaw troubleshoot --fix all          # 修复所有
```

---

## 🔍 诊断范围

| 检查项 | 检测内容 | 修复方式 |
|--------|----------|----------|
| **Gateway 状态** | 进程是否运行、端口是否监听、WebSocket 是否就绪 | 重启 Gateway |
| **端口冲突** | 18789 是否被占用 | 终止占用进程或换端口 |
| **Control UI** | origin 验证配置、trustedProxies | 自动添加 allowedOrigins |
| **配置语法** | openclaw.json 是否合法 | 修复 JSON 格式 |
| **危险技能** | 扫描 skills/ 中的危险代码 | 卸载或标记 |
| **模型配置** | 模型是否可用、API key 是否有效 | 提示用户更新 |
| **日志错误** | 读取 gateway.log 最后 50 行 | 标出 ERROR/WARN |

---

## 📋 诊断流程

### 阶段 1：Gateway 健康检查
```powershell
# 1. 检查进程
tasklist | findstr "openclaw"

# 2. 检查端口
netstat -ano | findstr :18789

# 3. 检查 WebSocket
curl -ws "ws://127.0.0.1:18789"

# 4. 检查 HTTP 健康接口
curl -s http://127.0.0.1:18789/health
```

### 阶段 2：配置检查
```powershell
# 读取 openclaw.json
# 检查 gateway.controlUi.allowedOrigins
# 检查 gateway.trustedProxies
# 检查 gateway.nodes.denyCommands
```

### 阶段 3：安全检查
```powershell
# 扫描 skills/ 目录
# 检测 dangerous-exec 模式
# 检测 env-harvesting 模式
```

### 阶段 4：日志分析
```powershell
# 读取 C:\Users\34596\.openclaw\logs\gateway.log
# 提取 ERROR/WARN 行
# 分析卡点原因
```

---

## 🛠️ 修复方案

### Gateway 问题

**症状：**
- `openclaw status` 超时
- `openclaw logs` 报错 "Gateway not reachable"
- Control UI 显示连接中

**修复：**
```powershell
# 1. 终止旧进程
taskkill /F /IM "node.exe" /FI "WINDOWTITLE eq *openclaw*"

# 2. 清理端口
netstat -ano | findstr :18789
# 如果有 PID，执行 taskkill /F /PID <PID>

# 3. 重启 Gateway
openclaw gateway --port 18789 --no-browser

# 4. 等待 15 秒后验证
openclaw status
```

### Control UI Origin 验证失败

**症状：**
```
origin not allowed (open the Control UI from the gateway host or 
allow it in gateway.controlUi.allowedOrigins)
```

**修复：**
编辑 `openclaw.json`，在 `gateway` 部分添加：
```json
{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "http://127.0.0.1:18789",
        "http://localhost:18789"
      ]
    }
  }
}
```

然后重启网关：
```powershell
openclaw gateway restart
```

### 危险技能代码

**症状：**
- `capability-evolver`：27+ 处危险代码（shell 执行、环境变量窃取）
- `feishu-doc`：环境变量 + 网络发送

**修复：**
```powershell
# 直接卸载
clawhub uninstall capability-evolver --yes
clawhub uninstall feishu-doc --yes

# 或深度审查
clawhub inspect <skill-name> --file <file-path>
```

### 配置警告

**trustedProxies 未配置：**
```json
{
  "gateway": {
    "trustedProxies": ["127.0.0.1"]
  }
}
```

**denyCommands 无效：**
```json
{
  "gateway": {
    "nodes": {
      "denyCommands": [
        "canvas.present",
        "canvas.hide",
        "canvas.navigate",
        "canvas.eval",
        "canvas.snapshot",
        "canvas.a2ui.push",
        "canvas.a2ui.pushJSONL",
        "canvas.a2ui.reset"
      ]
    }
  }
}
```

---

## 📊 输出格式

### 诊断报告
```
🔴 核心问题（导致卡住/断掉的根本原因）
├─ Gateway 服务已断开
└─ 修复方案：openclaw gateway restart

🔴 严重安全风险（2 个技能含危险代码）
├─ capability-evolver（27 处危险代码）
└─ feishu-doc（1 处危险代码）

🟡 配置警告（2 个）
├─ gateway.trustedProxies 未配置
└─ gateway.nodes.denyCommands 配置无效

✅ 修复优先级清单
├─ P0: 重启 Gateway
├─ P0: 卸载 capability-evolver
└─ P1: 修正配置
```

---

## 🔧 脚本文件

### scripts/diagnose.ps1
```powershell
# OpenClaw 诊断脚本

param(
    [switch]$Deep,
    [switch]$Json
)

$ErrorActionPreference = "Stop"
$OpenClawHome = $env:OPENCLAW_HOME ?? "$env:USERPROFILE\.openclaw"

Write-Host "🦞 OpenClaw 诊断工具" -ForegroundColor Cyan
Write-Host "==================" -ForegroundColor Cyan

# 1. Gateway 状态
Write-Host "`n📡 Gateway 状态" -ForegroundColor Yellow
$gatewayPort = 18789
$process = Get-NetTCPConnection -LocalPort $gatewayPort -ErrorAction SilentlyContinue
if ($process) {
    Write-Host "✅ Gateway 正在监听端口 $gatewayPort (PID: $($process.OwningProcess))" -ForegroundColor Green
} else {
    Write-Host "❌ Gateway 未运行" -ForegroundColor Red
}

# 2. 配置检查
Write-Host "`n⚙️  配置检查" -ForegroundColor Yellow
$configPath = Join-Path $OpenClawHome "openclaw.json"
if (Test-Path $configPath) {
    $config = Get-Content $configPath -Raw | ConvertFrom-Json
    if ($config.gateway.controlUi.allowedOrigins) {
        Write-Host "✅ Control UI allowedOrigins 已配置" -ForegroundColor Green
    } else {
        Write-Host "⚠️  Control UI allowedOrigins 未配置" -ForegroundColor Yellow
    }
} else {
    Write-Host "❌ openclaw.json 不存在" -ForegroundColor Red
}

# 3. 危险技能扫描
Write-Host "`n🔒 安全检查" -ForegroundColor Yellow
$skillsPath = Join-Path $OpenClawHome "workspace\skills"
if (Test-Path $skillsPath) {
    $dangerousSkills = @()
    Get-ChildItem $skillsPath -Directory | ForEach-Object {
        $skillName = $_.Name
        $files = Get-ChildItem $_.FullName -Recurse -Include *.js,*.ts,*.py
        foreach ($file in $files) {
            $content = Get-Content $file.FullName -Raw
            if ($content -match "child_process|exec\(|spawn\(|environment.*network") {
                $dangerousSkills += $skillName
                break
            }
        }
    }
    if ($dangerousSkills) {
        Write-Host "⚠️  发现危险技能：$($dangerousSkills -join ', ')" -ForegroundColor Yellow
    } else {
        Write-Host "✅ 未发现明显危险技能" -ForegroundColor Green
    }
}

Write-Host "`n✅ 诊断完成" -ForegroundColor Green
```

### scripts/fix-gateway.ps1
```powershell
# Gateway 修复脚本

param(
    [int]$Port = 18789
)

Write-Host "🔧 修复 Gateway..." -ForegroundColor Cyan

# 1. 终止旧进程
Write-Host "📋 终止旧 Gateway 进程..." -ForegroundColor Yellow
Get-Process | Where-Object { 
    $_.ProcessName -eq "node" -and 
    $_.CommandLine -like "*openclaw*gateway*" 
} | Stop-Process -Force

# 2. 清理端口
Write-Host "📋 清理端口 $Port..." -ForegroundColor Yellow
$connection = Get-NetTCPConnection -LocalPort $Port -ErrorAction SilentlyContinue
if ($connection) {
    Stop-Process -Id $connection.OwningProcess -Force
    Start-Sleep -Seconds 2
}

# 3. 启动新 Gateway
Write-Host "📋 启动新 Gateway..." -ForegroundColor Yellow
Start-Process "openclaw" -ArgumentList "gateway", "--port", $Port, "--no-browser"

# 4. 等待就绪
Write-Host "⏳ 等待 Gateway 就绪..." -ForegroundColor Yellow
for ($i = 0; $i -lt 30; $i++) {
    Start-Sleep -Seconds 1
    try {
        $response = Invoke-WebRequest -Uri "http://127.0.0.1:$Port/health" -TimeoutSec 2 -UseBasicParsing
        if ($response.StatusCode -eq 200) {
            Write-Host "✅ Gateway 已就绪！" -ForegroundColor Green
            break
        }
    } catch {
        # 继续等待
    }
}

Write-Host "✅ Gateway 修复完成" -ForegroundColor Green
```

### scripts/fix-config.ps1
```powershell
# 配置修复脚本

$ErrorActionPreference = "Stop"
$OpenClawHome = $env:OPENCLAW_HOME ?? "$env:USERPROFILE\.openclaw"
$configPath = Join-Path $OpenClawHome "openclaw.json"

Write-Host "🔧 修复 openclaw.json 配置..." -ForegroundColor Cyan

$config = Get-Content $configPath -Raw | ConvertFrom-Json

# 修复 Control UI allowedOrigins
if (-not $config.gateway.controlUi) {
    $config.gateway.controlUi = @{}
}
$config.gateway.controlUi.allowedOrigins = @(
    "http://127.0.0.1:18789",
    "http://localhost:18789"
)

# 修复 trustedProxies
if (-not $config.gateway.trustedProxies) {
    $config.gateway.trustedProxies = @("127.0.0.1")
}

# 修复 denyCommands
$config.gateway.nodes.denyCommands = @(
    "canvas.present",
    "canvas.hide",
    "canvas.navigate",
    "canvas.eval",
    "canvas.snapshot",
    "canvas.a2ui.push",
    "canvas.a2ui.pushJSONL",
    "canvas.a2ui.reset"
)

# 保存配置
$config | ConvertTo-Json -Depth 10 | Set-Content $configPath -Encoding UTF8

Write-Host "✅ 配置已修复" -ForegroundColor Green
Write-Host "📋 需要重启 Gateway 使配置生效" -ForegroundColor Yellow
Write-Host "   执行：openclaw gateway restart" -ForegroundColor Gray
```

---

## 📝 经验来源

**提取自：** 2026-03-14 OpenClaw 健康诊断事件

**原始问题：**
- Gateway 断开导致所有功能不可用
- Control UI 显示 "origin not allowed"
- capability-evolver 和 feishu-doc 含危险代码
- 配置缺少 trustedProxies 和 allowedOrigins

**修复流程：**
1. 运行 `openclaw status --deep` 诊断
2. 卸载危险技能
3. 修复 openclaw.json 配置
4. 重启 Gateway
5. 验证健康状态

**提取时间：** 2026-03-14

---

## ⚠️ 注意事项

1. **备份配置** - 修复前自动备份 openclaw.json
2. **用户确认** - 卸载技能前需要用户确认
3. **网关重启** - 配置修改后需要重启 Gateway
4. **权限检查** - 某些操作需要管理员权限

---

## 🔄 更新日志

### v1.0.0 (2026-03-14)
- 初始版本
- 基于真实故障经验提取
- 支持 Gateway 诊断 + 修复
- 支持配置自动修复
- 支持危险技能扫描

---

*本技能由 self-improvement 流程自动提取，经验来源：memory/2026-03-14-openclaw-health-diagnosis.md*