OpenClawのデバッグガイド：ストリーミングと設定のトラブルシューティング

ストリーミング出力が期待通りに動かないときや、設定ファイルが複雑になってくると、どこに原因があるのか特定するのが難しくて困りますよね。特にAIプロバイダーが推論プロセスと通常のテキストを混ぜて出力してくるような場合、中身を直接確認できないと修正の糸口が見つかりません。

今回は、OpenClawでの開発をスムーズにするためのデバッグ手法について、ベストな方法を紹介します。

必要なもの

• OpenClaw のインストール
• pnpm パッケージマネージャー

クイックスタート

まずは、最も手軽に試せる5分以内のデバッグ手順です。

1. runtime-only の設定変更を有効にする openclaw.json を書き換えずに一時的な設定変更を試すため、/debug コマンドを有効にします。

   "commands.debug": true

2. Gateway を watch モードで起動する コードの変更を即座に反映させるため、以下のコマンドを使用します。

   pnpm gateway:watch --force

Runtime debug overrides

チャット内で /debug を使うと、メモリ上でのみ保持される設定の上書き（runtime-only overrides）が可能です。これは、ディスク上の openclaw.json を編集せずに、細かい設定をトグルしたいときに便利です。

使用例：

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset

/debug reset を実行すると、すべての上書きがクリアされ、ディスク上の設定に戻ります。

Dev profile + dev gateway (—dev)

状態を分離してデバッグしたい場合は、使い捨て可能な dev プロファイルを利用するのがおすすめです。OpenClaw には2つの --dev フラグがあります。

• Global --dev (profile): 状態を ~/.openclaw-dev に分離し、Gateway のポートを 19001 に設定します。
• gateway --dev: 設定やワークスペースがない場合に、デフォルト設定を自動作成します。

推奨されるフローは以下の通りです。

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

このコマンドを実行すると、以下の処理が行われます。

1. プロファイルの分離

   • OPENCLAW_PROFILE=dev の設定
   • OPENCLAW_STATE_DIR=~/.openclaw-dev への保存
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json の使用
   • OPENCLAW_GATEWAY_PORT=19001 での動作

2. Dev bootstrap

   • 最小限の設定ファイルの作成（gateway.mode=local など）
   • ワークスペースファイル（AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md など）の自動生成
   • デフォルトの Identity として C3-PO を設定
   • チャンネルプロバイダーのスキップ（OPENCLAW_SKIP_CHANNELS=1）

環境を完全にリセットしてやり直したい場合は、以下のコマンドを使用してください。

pnpm gateway:dev:reset

Raw stream logging

OpenClaw では、フィルタリングやフォーマットが行われる前の raw assistant stream をログに記録できます。推論がプレーンテキストとして届いているのか、あるいは特定のブロックとして届いているのかを確認するのに最適です。

CLI から有効にする方法：

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

ログの保存先をカスタマイズする場合：

pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

また、pi-mono を使用している場合は、PI_RAW_STREAM=1 を設定することで OpenAI 互換の生のチャンクを確認できます。

トラブルシューティング

問題：non-dev の Gateway が既に動いていてポートが衝突する dev プロファイルを使用する前に、実行中の Gateway を停止してください。

openclaw gateway stop

問題：--dev フラグがランナーに無視される 環境変数形式で明示的に指定してください。

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

安全のための注意点

• 生のストリームログには、プロンプト全文や Tool の出力、ユーザーデータが含まれる可能性があります。
• ログはローカルに保持し、デバッグが終わったら削除してください。機密情報や個人情報が含まれるログを共有する場合は、必ず事前にマスキングを行ってください。

詳細な設定やトラブルシューティングについては、AI Setup Assistant も活用してください。

次のステップ

• Gateway Configuration
• CLI Reference