OpenClaw デバッグガイド

開発を進めていると、「期待通りに動くはず」のコードが実際には動かない場面に遭遇します。モデルの生の出力が見えなかったり、開発中の変更が本番環境の設定と混ざってしまったりすると、原因の特定は難しくなります。

こうした問題を解決するには、システムの内部で何が起きているかを正確に把握するためのツールが必要です。OpenClaw が提供するデバッグ機能を活用して、迅速なトライアンドエラーを可能にしましょう。

必要なもの

デバッグを始める前に、以下の準備ができているか確認してください。

• OpenClaw のインストール
• pnpm パッケージマネージャー
• 設定ファイル（config）での commands.debug: true の有効化（/debug コマンドを使用する場合）

クイックスタート

最短でデバッグ環境を整えるための 4 つのステップです。

1. Watch Mode の起動: pnpm gateway:watch --force を実行して、ファイルの変更を自動検知させます。
2. Dev Profile の作成: pnpm gateway:dev を実行し、本番環境から分離された開発用プロファイルを立ち上げます。
3. ランタイム上書き: チャット内で /debug set messages.responsePrefix="[test]" を入力し、設定ファイルを書き換えずに挙動をテストします。
4. 生ログの確認: pnpm gateway:watch --force --raw-stream を実行して、モデルからの未加工の出力を監視します。

Runtime Debug Overrides

設定ファイルを直接編集することなく、チャット内で /debug コマンドを使用して一時的に設定を上書きできます。

/debug show                                    # 現在の上書き内容を表示
/debug set messages.responsePrefix="[test]"    # 値を設定
/debug unset messages.responsePrefix           # 上書きを解除
/debug reset                                   # すべての上書きをクリア

これらの設定はメモリ内でのみ保持され、永続化されません。使用するには、設定ファイルで commands.debug: true を有効にする必要があります。

Gateway Watch Mode

開発のサイクルを速めるために、ファイル監視モードで Gateway を実行します。

pnpm gateway:watch --force

このコマンドは、ファイルを保存するたびに Gateway を自動的に再起動します。以下のコマンドも同じ動作をします。

tsx watch src/entry.ts gateway --force

Dev Profile (Isolated State)

開発中のデータを本番環境から分離したい場合は、dev プロファイルを使用します。

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

dev プロファイルの特徴:

• 状態保存ディレクトリ: ~/.openclaw-dev
• Gateway ポート: 19001
• BOOTSTRAP.md の読み込みをスキップ
• 最小限のデフォルト設定を自動作成
• デフォルトの Identity: C3-PO (protocol droid)
• channel providers をスキップ

環境を完全にリセットして最初からやり直すには、次のコマンドを使用します。

pnpm gateway:dev:reset

このコマンドは rm ではなく trash を使用して、開発用の設定、認証情報、セッションを削除します。

Raw Stream Logging

フィルタリングされる前の、モデルが返したそのままのデータを確認できます。

pnpm gateway:watch --force --raw-stream

デフォルトのログ保存先: ~/.openclaw/logs/raw-stream.jsonl

カスタムパスを指定する場合:

pnpm gateway:watch --force --raw-stream --raw-stream-path /custom/path.jsonl

環境変数で設定する場合:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

これは、推論内容（reasoning content）が通常のテキスト出力に漏れていないかを確認する際に非常に有効です。

Raw Chunk Logging (pi-mono)

OpenAI 互換のチャンクを解析前にキャプチャするには、以下の環境変数を使用します。

PI_RAW_STREAM=1
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

Environment Variable Reference

環境変数	説明
OPENCLAW_PROFILE=dev	dev プロファイルを使用する
OPENCLAW_STATE_DIR=~/.openclaw-dev	状態保存ディレクトリを上書きする
OPENCLAW_GATEWAY_PORT=19001	Gateway のポート番号を上書きする
OPENCLAW_RAW_STREAM=1	Raw stream logging を有効にする
OPENCLAW_SKIP_CHANNELS=1	channel providers をスキップする

トラブルシューティング

デバッグ中に注意すべき点と解決策です。

• 機密情報の取り扱い: 生データのログには、プロンプト、ツールの出力、ユーザーデータが含まれることがあります。ログはローカルに保持し、デバッグが終わったら削除してください。共有する際は、シークレットや個人情報を必ず削除してください。
• 推論内容の漏洩: テキスト出力に不要なデータが含まれる場合は、Raw Stream Logging を有効にしてモデルの生のレスポンスを確認してください。

解決しない場合は、AI Setup Assistant がセットアップのデバッグをサポートします。

次のステップ

• Logging → — ファイルログとコンソール出力の詳細
• Testing → — テストスイートとライブテストの実行
• Gateway Configuration → — Gateway の全設定リファレンス