OpenClawSkills
GitHub
Gateway & Ops • 5分で読める

トラブルシューティング

よくある OpenClaw の不具合を素早く切り分けるガイド

OpenClaw の挙動がおかしいときは、このチェックリストで素早く原因を切り分けて修復できます。

最短の“応急処置フロー”だけ欲しい場合は、FAQ の 最初の 60 秒 を参照してください。このページでは、実行時の失敗、診断方法、よくある落とし穴を扱います。

チャンネル別の入口：/channels/troubleshooting

Tutorial.step

状態と診断

クイックチェック：

  • Gateway のファイルログ（構造化）：/tmp/openclaw/openclaw-YYYY-MM-DD.log（または logging.file）。
  • Gateway サービスログ（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

完全リセット

Nuclear option:

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 の既存 issue を検索する。
  3. 新しい issue を立てるときは、次を含める：
    • OpenClaw のバージョン
    • 関連ログの抜粋
    • Steps to reproduce
    • 設定（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 を参照