OpenClawのログ確認・デバッグ手順：トラブルを即座に解決

開発をしていると、「さっきまで動いていたのに、なぜか動かなくなった」「設定を変えたはずなのに反映されない」といった状況に必ず遭遇します。原因がわからず画面を見つめる時間は、エンジニアにとって最もストレスが溜まるものです。

そんな時、一番の味方になるのがログです。OpenClawで何が起きているのかを正確に把握し、素早くトラブルを解決するためのデバッグ手法をまとめました。

OpenClawのログはどこにありますか？

ログは $OPENCLAW_STATE_DIR/logs（デフォルトは ~/.openclaw/logs）に保存されています。

以下のコマンドを使うと、ログディレクトリへのアクセスや内容の確認がスムーズに行えます。

# Open logs directory
openclaw logs --path

# Tail live
openclaw logs --follow

# Show last 500 lines
openclaw logs

ログは毎日ローテーションされ、構造化された解析がしやすいように JSON 形式で出力することも可能です。

リアルタイムでログを確認するには？

動作を確認しながらログを追いかけたい場合は、--follow フラグを使用してください。

openclaw logs --follow

# Filter JSON logs
openclaw logs --follow --json | jq 'select(.level == "error")'

メッセージが届いたのに返信がありません。どうデバッグすればいいですか？

メッセージが無視されているように見える場合は、以下の手順で原因を切り分けてみてください。

1. ログを確認します：

   openclaw logs --follow

2. デバッグモードを一時的に起動します：

   openclaw gateway stop
   OPENCLAW_DEBUG=1 openclaw gateway start

3. チャンネルが有効で、メッセージが無視されていないか確認します：

   openclaw channels status

4. セッションとモデルのステータスを確認します：

   openclaw status
   openclaw models status

5. ログの中にレート制限、認証エラー、またはモデルに関連するエラーが出ていないか探します。

ログが多すぎる、または詳細が足りません。調整方法は？

ログの出力量は gateway.logLevel（デフォルトは info）で調整できます。用途に合わせて以下のレベルを選択してください。

• debug = 非常に詳細な出力
• info = 通常の出力
• warn = 警告とエラーのみ
• error = エラーのみ

{
  gateway: { logLevel: "debug" }
}

クラッシュ後にサービスが自動再起動しません。何が原因ですか？

サービスが自動で立ち上がらない場合は、OS ごとのサービスマネージャー（launchd または systemd）の設定を確認してください。

• launchd: KeepAlive が true になっている必要があります。
• systemd: Restart=on-failure と WantedBy=multi-user.target が設定されているか確認してください。

現在のサービスの状態は、以下のコマンドで確認できます。

# macOS
launchctl list | grep openclaw

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw
journalctl --user -u openclaw -n 100

プログラムから Gateway のヘルスチェックを行うには？

外部ツールやスクリプトから Gateway の状態を監視したい場合は、専用の API エンドポイントまたは CLI を利用してください。

curl http://localhost:18789/health

# Or via CLI
openclaw health
openclaw health --json

設定を壊してしまいました。リセットする方法は？

設定が複雑になりすぎて収拾がつかなくなった場合は、一度リセットしてクリーンな状態に戻すのが近道です。

# Full reset (wipes config, creds, sessions)
openclaw reset --scope full --yes

# Or just sessions
openclaw reset --scope sessions --yes

リセット後は、再度オンボーディングを実行してください。

openclaw onboard --install-daemon

バグを報告するには？

もし OpenClaw 自体の不具合を見つけた場合は、以下の手順で報告をお願いします。

1. デバッグログを有効にして現象を再現させます：

   OPENCLAW_DEBUG=1 openclaw gateway restart

2. GitHub Issues で既知の問題として報告されていないか確認します。
3. 未報告の場合は、新しい Issue を作成してください。その際、以下の情報を含めていただけると助かります。
   • OpenClaw のバージョン (openclaw --version)
   • 使用している OS と Node.js のバージョン
   • 関連するログの抜粋（API キーやトークンは必ず伏せてください）
   • 再現手順

次のステップ

セットアップや設定でさらにサポートが必要な場合は、アシスタントに相談してみてください。

AI Setup Assistant