OpenClawSkills
GitHub
网关与运维 • 5 分钟阅读

故障排除

常见 OpenClaw 故障的快速排障指南

当 OpenClaw 表现异常时，可以按这份清单快速定位并修复。

如果你只想要一套最短的“急救流程”，先看 FAQ 的 前 60 秒。本页更深入：运行时失败、诊断方式与常见坑。

通道相关快捷入口：/channels/troubleshooting

Tutorial.step

状态与诊断

快速排查要点：

  • Gateway 文件日志（结构化）：/tmp/openclaw/openclaw-YYYY-MM-DD.log（或 logging.file）。
  • Gateway service 日志（supervisor）：

    macOS: $OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log (default ~/.openclaw/logs/...; profiles use ~/.openclaw-<profile>/logs/...).

    Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager

    Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

  • Session files: $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
  • Media cache：$OPENCLAW_STATE_DIR/media/
  • Credentials：$OPENCLAW_STATE_DIR/credentials/
Tutorial.step

健康检查

Bash
openclaw gateway status

openclaw gateway status --deep


openclaw health --json

openclaw health --verbose


lsof -nP -iTCP:18789 -sTCP:LISTEN


openclaw logs --follow

tail -20 /tmp/openclaw/openclaw-*.log
Tutorial.step

全量重置

核按钮：

Bash
openclaw gateway stop



trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # Re-pair WhatsApp
openclaw gateway restart           # Or: openclaw gateway

警告：这会丢失所有 sessions，并需要重新配对 WhatsApp。

Tutorial.step

获取帮助

  1. 先看日志：默认在 /tmp/openclaw/（openclaw-YYYY-MM-DD.log 或你配置的 logging.file）。
  2. 搜索 GitHub 上已有 issues。
  3. 新开 issue 时包含：
    • OpenClaw 版本
    • 相关日志片段
    • 复现步骤
    • 你的配置（脱敏 secrets！）

“关机重启试过了吗？”—— 每一个 IT 人

Tutorial.step

浏览器无法启动（Linux）

如果你看到 "Failed to start Chrome CDP on port 18800"：

最可能原因： Ubuntu 上使用了 Snap 打包的 Chromium。

快速修复： 安装 Google Chrome：

Bash
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

并在配置中设置：

Json
{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

完整指南： 见 /reference/tools/browser-linux-troubleshooting