openclaw-troubleshooter

name	openclaw-troubleshooter
description	OpenClaw 故障诊断与一键修复工具。自动检测 Gateway 状态、配置错误、端口冲突、危险技能代码，并提供修复方案。基于真实故障经验提取。

🔧 OpenClaw Troubleshooter

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

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

---

🚀 快速使用

完整诊断（推荐）

openclaw troubleshoot

仅诊断不修复

openclaw troubleshoot --check-only

修复特定问题

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 健康检查

# 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：配置检查

# 读取 openclaw.json
# 检查 gateway.controlUi.allowedOrigins
# 检查 gateway.trustedProxies
# 检查 gateway.nodes.denyCommands

阶段 3：安全检查

# 扫描 skills/ 目录
# 检测 dangerous-exec 模式
# 检测 env-harvesting 模式

阶段 4：日志分析

# 读取 C:\Users\34596\.openclaw\logs\gateway.log
# 提取 ERROR/WARN 行
# 分析卡点原因

---

🛠️ 修复方案

Gateway 问题

症状：

• openclaw status 超时
• openclaw logs 报错 "Gateway not reachable"
• Control UI 显示连接中

修复：

# 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 部分添加：

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "http://127.0.0.1:18789",
        "http://localhost:18789"
      ]
    }
  }
}

然后重启网关：

openclaw gateway restart

危险技能代码

症状：

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

修复：

# 直接卸载
clawhub uninstall capability-evolver --yes
clawhub uninstall feishu-doc --yes

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

配置警告

trustedProxies 未配置：

{
  "gateway": {
    "trustedProxies": ["127.0.0.1"]
  }
}

denyCommands 无效：

{
  "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

# 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

# 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

# 配置修复脚本

$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