陌讯skills聚合平台

openclaw-troubleshooter

📁 tighten724-hub/openclaw-troubleshooter 📅 5 days ago
2
总安装量
2
周安装量
#63487
全站排名
安装命令
npx skills add https://github.com/tighten724-hub/openclaw-troubleshooter --skill openclaw-troubleshooter

Agent 安装分布

openclaw 2
github-copilot 2
codex 2
kimi-cli 2
gemini-cli 2
cursor 2

Skill 文档

OpenClaw 故障排除技能

适用于0代码基础用户跟着操作解决问题

🎯 触发条件

当用户遇到以下关键词时，自动触发此技能：

类别 触发关键词
Gateway 无法启动、启动失败、连接失败、无响应
Dashboard 打不开、连接失败、空白、报错
渠道 WhatsApp连不上、Telegram报错、Discord失败
模型 API Key、模型切换、模型错误
会话 会话丢失、无法创建新会话
配置 配置文件错误、配置无效
节点 配对失败、工具调用失败
浏览器 浏览器工具失败、Chrome报错
自动化 Cron不执行、心跳没反应
安装 安装失败、更新失败、升级失败

🚀 快速诊断流程（60秒）

第一步：运行诊断命令

打开终端（Windows用PowerShell/Mac用终端），依次执行：

# 1. 查看基本状态
openclaw status

# 2. 查看完整状态
openclaw status --all

# 3. 检查Gateway状态
openclaw gateway status

# 4. 运行诊断
openclaw doctor

第二步：根据问题选择具体检查

问题类型 检查命令
渠道问题 openclaw channels status --probe
模型问题 openclaw models status
日志查看 openclaw logs --follow
节点问题 openclaw nodes status
Cron问题 openclaw cron status

🔍 决策树

根据您的实际问题，选择对应路径：

我的问题是：
├─ 1️⃣ Gateway无法启动/无响应
│  └─ → 见"问题1：Gateway无法启动"
│
├─ 2️⃣ Dashboard/Control UI打不开
│  └─ → 见"问题2：Dashboard无法连接"
│
├─ 3️⃣ 渠道消息发不出去/收不到
│  └─ → 见"问题3：渠道消息不流动"
│
├─ 4️⃣ 模型相关问题
│  └─ → 见"问题4：模型问题"
│
├─ 5️⃣ 会话相关问题
│  └─ → 见"问题5：会话问题"
│
├─ 6️⃣ 安装/更新问题
│  └─ → 见"问题6：安装更新问题"
│
├─ 7️⃣ 节点/配对问题
│  └─ → 见"问题7：节点问题"
│
└─ 8️⃣ 其他问题
   └─ → 运行基础诊断命令后查看日志

📋 问题解决方案

问题1：Gateway无法启动

症状：运行openclaw gateway报错、闪退、无响应

解决步骤：

# 步骤1：检查端口占用
netstat -ano | findstr 18789

# 步骤2：停止现有进程（如果有）
openclaw gateway stop

# 步骤3：重新启动
openclaw gateway restart

# 步骤4：如果还是不行，运行诊断
openclaw doctor
openclaw doctor --fix

常见错误和解决方法：

错误信息 解决方法
EADDRINUSE 端口被占用 运行 openclaw gateway stop 然后重启
gateway.mode=local 被阻止 修改配置 gateway.mode="local"
缺少认证 运行 openclaw configure 重新配置

问题2：Dashboard无法连接

症状：浏览器打开 http://127.0.0.1:18789 失败

解决步骤：

# 步骤1：检查Gateway是否运行
openclaw gateway status

# 步骤2：如果没运行，启动它
openclaw gateway start

# 步骤3：检查认证
openclaw config get gateway.auth.token

# 步骤4：如果没有token，生成一个
openclaw doctor --generate-gateway-token

常见错误和解决方法：

错误信息 解决方法
unauthorized unauthorized 检查token是否正确
device identity required 需要安全上下文，用localhost访问
连接被拒绝 Gateway没运行，先启动

问题3：渠道消息不流动

症状：渠道显示已连接，但发消息没有回复

解决步骤：

# 步骤1：检查渠道状态
openclaw channels status --probe

# 步骤2：检查配对列表
openclaw pairing list whatsapp   # 替换为对应渠道

# 步骤3：检查日志
openclaw logs --follow

常见错误和解决方法：

错误信息 解决方法
pairing request 运行配对批准
mention required 群聊需要@机器人
allowlist blocked 发送者在白名单吗

问题4：模型问题

症状：模型无法切换、API报错

解决步骤：

# 步骤1：查看模型状态
openclaw models status

# 步骤2：查看配置的模型
openclaw config get agents.defaults.model.primary

# 步骤3：切换模型
openclaw models set anthropic/claude-sonnet-4-5

常见错误和解决方法：

错误信息 解决方法
Model is not allowed 模型不在允许列表，修改配置
API Key invalid 检查API Key是否正确
rate limit 等待后重试

问题5：会话问题

症状：会话丢失、无法创建新会话

解决步骤：

# 步骤1：查看会话列表
openclaw sessions list

# 步骤2：创建新会话（发送消息时用 /new）

常见错误和解决方法：

错误信息 解决方法
会话自动重置 检查 session.reset 配置
上下文太长 运行 /new 开始新会话

问题6：安装更新问题

症状：安装失败、无法更新

解决步骤：

# 方式1：重新运行安装脚本（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash

# 方式2：npm更新
npm install -g openclaw@latest

# 方式3：pnpm更新
pnpm add -g openclaw@latest

# 更新后运行诊断
openclaw doctor
openclaw gateway restart

问题7：节点问题

症状：节点配对失败、工具调用失败

解决步骤：

# 步骤1：查看节点状态
openclaw nodes status

# 步骤2：查看配对请求
openclaw pairing list

# 步骤3：批准配对
openclaw pairing approve <channel> <code>

⚠️ 重要：避免让AI自己”瘫痪”

问题

当AI执行 openclaw gateway stop 时：

  • Gateway停止 → WebSocket断开 → AI无法响应 → 瘫痪

解决方案

1. 永远不要让AI自己执行 gateway stop

  • 提供命令 → 让用户手动执行
  • 使用 gateway restart 时也要警告用户

2. 使用热重载（推荐）

大多数配置更改不需要重启Gateway：

# 查看热重载配置
openclaw config get gateway.config.hotReload

设置热重载模式：

openclaw config set gateway.config.hotReload "hybrid"
模式 行为
hybrid (默认) 即时应用安全更改，自动重启关键更改
hot 仅热应用安全更改
restart 任何更改都重启
off 禁用文件监视

3. 修改配置的安全流程

  1. 先说明要改什么
  2. 给出修改命令
  3. 建议用户手动执行
  4. 或让用户确认后再执行

4. 如果必须重启

  1. 警告用户：”即将重启Gateway，我会暂时断开连接”
  2. 执行 openclaw gateway restart
  3. 提醒用户：”Gateway已重启，请刷新页面或重新发送消息”

📖 查阅官方文档

当以上解决方案无法解决问题时，按需查阅官方文档：

常用文档链接

问题类型 文档链接
故障排除总览 https://docs.openclaw.ai/help/troubleshooting.md
Gateway问题 https://docs.openclaw.ai/gateway/troubleshooting.md
渠道问题 https://docs.openclaw.ai/channels/troubleshooting.md
配置问题 https://docs.openclaw.ai/gateway/configuration.md
模型问题 https://docs.openclaw.ai/providers/models.md
安装更新 https://docs.openclaw.ai/install/updating.md

使用web_fetch获取文档

web_fetch(url="https://docs.openclaw.ai/xxx/xxx.md", maxChars=10000)

📝 输出响应模板

找到解决方案后，按以下格式输出：

## 🔧 问题诊断

**您的问题**：{描述问题现象}

**可能原因**：{分析可能的原因}

---

## ✅ 解决步骤

请按顺序执行以下命令：

### 步骤1：{命令1}
```bash
{具体命令}

步骤2：{命令2}

{具体命令}

步骤3：{命令3}

{具体命令}

🔍 验证结果

执行以下命令验证问题是否解决：

{验证命令}

预期输出：{描述预期输出}

📖 相关文档

如需了解更多，参考：

  • {官方文档链接1}
  • {官方文档链接2}

❓ 如果还是不行

  1. 运行 openclaw doctor --fix 自动修复
  2. 运行 openclaw logs --follow 查看详细日志
  3. 将日志复制到 Discord 社区寻求帮助：https://discord.gg/clawd

---

## 🆘 紧急情况处理

### Gateway完全无响应

```bash
# 强制停止
openclaw gateway stop

# 清理并重启
openclaw doctor --fix
openclaw gateway start

配置文件损坏

# 备份旧配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 重置配置
openclaw reset --scope config

# 重新配置
openclaw configure

📚 参考资料

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。