🔧 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          # 修复所有

🔍 诊断范围

📋 诊断流程

阶段 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"]
  }
}