OpenClawをまだインストールしていませんか？ここをクリックしてワンライナーインストールコマンドを表示
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
PCへの影響が心配ですか？ ClawTank ならクラウド上で動作し、インストール不要で誤削除のリスクもありません
主要な知見
  • openclaw doctorはOpenClaw内蔵のワンストップ診断ツールであり、設定ファイルの構文、モデル認証ステータス、Gateway接続性、Node.jsバージョンの互換性を自動的にチェックする[1]
  • --fixフラグを追加することで、doctorは不足している設定値、期限切れトークン、破損したワークスペースインデックスなど、よくある問題の大半を自動修復できる[1]
  • Gateway接続障害（「Pairing Required」エラー）は初心者が最もよく遭遇する問題であり、通常はGateway Tokenの再生成だけで解決できる[2]
  • エージェント「フリーズ」の根本原因は通常LLMリクエストのタイムアウトであり、timeoutSecondsの延長またはフォールバックモデルの設定で効果的に軽減できる[4]

1. openclaw doctor：最初の防衛線

OpenClawに異常が発生した場合、まず最初に実行すべきはopenclaw doctorである。このコマンドはシステム全体の包括的なヘルスチェックを行い、各項目のステータスを赤/黄/緑の明確なインジケーターで報告する。[1]

1.1 基本診断

openclaw doctor

このコマンドは以下を順番にチェックする：

  1. Node.jsバージョン：OpenClawはNode.js 22以上を必要とする
  2. 設定ファイルの整合性：openclaw.jsonの構文と必須フィールド
  3. モデル認証：設定済みプロバイダーに正常に接続できるか
  4. Gatewayステータス：Gatewayが動作中でポートに到達可能か
  5. チャネル接続性：設定済みチャネル（Telegram、WhatsAppなど）が正常に機能しているか

1.2 自動修復

openclaw doctor --fix

--fixを追加すると、doctorは問題の診断だけでなく修復も試みる。一般的な自動修復には以下が含まれる：

1.3 Gateway Token生成

openclaw doctor --generate-gateway-token

このコマンドはGateway認証Tokenの生成または再生成に特化している。「Pairing Required」エラーが表示された場合、このコマンド一つで解決することが多い。[2]

2. 最もよくある5つの問題と解決策

2.1 「Pairing Required」 -- Gateway接続障害

症状：Web UI（http://127.0.0.1:18789）またはメッセージングチャネルで「Pairing Required」メッセージが表示される。

原因：Gateway Tokenが不足、期限切れ、またはミスマッチしている。

解決策：

openclaw doctor --generate-gateway-token
# その後Gatewayを再起動
openclaw gateway restart

2.2 「LLM Request Timed Out」 -- モデルリクエストタイムアウト

症状：エージェントがタスク途中で応答を停止し、ログにタイムアウトエラーが表示される。[4]

原因：LLM APIの応答時間がデフォルトの制限を超えている。複雑なタスクやAPIトラフィックのピーク時によく発生する。

解決策：

# タイムアウトを延長（秒単位）
openclaw config set agents.defaults.timeoutSeconds 600

# フォールバックモデルを設定し、プライマリモデルがタイムアウトした時に自動切り替え
openclaw config set agents.defaults.model.fallbacks '["claude-sonnet-4-6"]'

2.3 エージェントの「フリーズ」で無応答

症状：エージェントが完全に無応答になり、メッセージを送信しても返信もエラーもない。

原因：Gatewayプロセスのフリーズ、Nodeプロセスのクラッシュ、またはワークスペース状態の破損が考えられる。

解決策（影響が小さい順）：

# 1. Gatewayを再起動
openclaw gateway restart

# 2. Gatewayが正常に再起動できない場合、強制停止してから再起動
openclaw gateway stop
openclaw gateway start

# 3. それでも解決しない場合、完全診断修復を実行
openclaw doctor --fix

2.4 ポート18789が既に使用中

症状：Gatewayの起動時にポートが既に使用中と表示される。

解決策：

# ポートを使用しているプロセスを確認
lsof -i :18789

# 方法A：占有しているプロセスをkill
kill -9 PID

# 方法B：ポートを変更
openclaw config set gateway.port 28789

2.5 モデル認証エラー

症状：エージェントが「Model not allowed」または「Authentication failed」と報告する。[4]

解決策：

# モデルステータスを確認
openclaw models status

# APIキーを再設定
openclaw models auth setup-token --provider anthropic

# またはOAuthフローを再実行
openclaw models auth login --provider openai

3. 再起動とリセットの手順

3.1 通常再起動（すべてのデータを保持）

openclaw gateway restart

これは最も安全な再起動方法である。Gatewayは再起動前に現在の状態を永続ストレージに書き込む。すべてのワークスペース、メモリ、設定が保持される。

3.2 完全停止と起動

openclaw gateway stop
# 数秒待機
openclaw gateway start

gateway restartが機能しない場合に使用する。stopコマンドにより、関連するすべてのプロセスが完全に終了する。

3.3 デーモンモード再起動（systemd）

openclaw onboard --install-daemonでsystemdサービスをインストールした場合：

systemctl --user restart openclaw-gateway

3.4 コンテキストのクリア（ソフトリセット）

エージェントの会話コンテキストが混乱した場合、システム全体を再起動せずにコンテキストのみをクリアできる：

openclaw tui

これによりワークスペースの長期メモリに影響を与えずに、新しいインタラクティブ会話インターフェースが開く。

4. ログ分析と高度なデバッグ

4.1 リアルタイムログの表示

openclaw logs --follow

このコマンドはtail -fと同様に、Gatewayのランタイムログをリアルタイムで出力する。各リクエストの処理、モデル呼び出しのレイテンシ、エラーメッセージを確認できる。[7]

4.2 よくあるログメッセージリファレンス

ログメッセージ意味推奨アクション
Gateway started on :18789正常起動対応不要
Pairing requiredToken認証失敗doctor --generate-gateway-tokenを実行
LLM request timed outモデル応答タイムアウトtimeoutSecondsを延長するかフォールバックを設定
Model not allowedモデルが許可リストにない許可リスト設定を確認
Agent bootstrap pendingエージェント初期化中完了を待つ（通常10〜30秒）
WebSocket connection closedWebSocket切断ネットワーク接続またはリバースプロキシ設定を確認

5. 予防保守の推奨事項

事後対応のトラブルシューティングよりも、予防保守の方が効果的である。以下は実務経験に基づいた保守チェックリストである：[5][6]

  1. 週に1回openclaw doctorを実行する：システムが正常に動作していても、定期的なチェックで潜在的な問題を早期に発見できる
  2. OpenClawを最新に保つ：npm update -g openclawを実行して最新のセキュリティパッチと機能改善を取得する
  3. フォールバックモデルを設定する：単一のモデルプロバイダーに依存しないこと
  4. Gatewayのメモリ使用量を監視する：長時間動作するGatewayはメモリリークが発生する場合がある。週1回の再起動を推奨
  5. ~/.openclaw/ディレクトリのバックアップ：すべての設定、認証情報、ワークスペースデータが含まれている

まとめ

openclaw doctorに--fixフラグを付けることで、よくある問題の80%以上を自動解決できる。[1]より複雑な問題については、本記事で解説したログ分析と体系的なトラブルシューティング手順が根本原因の迅速な特定に役立つ。

OpenClawを使い始めたばかりの方には、まずアーキテクチャ解析＆実践デプロイガイドを読んでシステムの全体像を把握することをお勧めする。設定の調整が必要な場合は設定完全ガイドを参照されたい。