OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

デバッグ

ストリーミング出力、Gateway の反復作業、起動プロファイリング用のデバッグヘルパー。

ランタイムデバッグオーバーライド

/debug は、ランタイムのみの設定オーバーライド（メモリ上であり、ディスク上ではない）を設定します。デフォルトでは無効です。commands.debug: true で有効にします。

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

/debug reset はすべてのオーバーライドを消去し、ディスク上の設定に戻します。

セッショントレース出力

/trace は、完全な詳細モードを有効にせずに、1つのセッションについて Plugin が所有するトレース／デバッグ行を表示します。Active Memory のデバッグ概要など、Plugin の診断に使用してください。通常のステータス／ツール出力には /verbose を使用します。

text
/trace/trace on/trace off

Plugin ライフサイクルトレース

Plugin のメタデータ、検出、レジストリ、ランタイムミラー、設定変更、更新処理をフェーズごとに分析するには、OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 を設定します。stderr に書き込むため、JSON コマンド出力は解析可能なまま維持されます。

bash
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
text
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

CPU プロファイラーを使用する前に、まずこれを使用してください。ソースチェックアウトでは、pnpm build の後に node dist/entry.js ... を使用してビルド済みランタイムを測定します。pnpm openclaw ... はソースランナーのオーバーヘッドも測定します。

CLI の起動とコマンドのプロファイリング

リポジトリに含まれる起動ベンチマーク：

bash
pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

通常のソースランナーを介して一度だけプロファイリングするには、OPENCLAW_RUN_NODE_CPU_PROF_DIR を設定します。

bash
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

ソースランナーは Node CPU プロファイルフラグを追加し、コマンド用の .cpuprofile を書き込みます。コマンドコードに一時的な計測処理を追加する前に、まずこれを使用してください。

同期ファイルシステム処理またはモジュールローダー処理が原因と思われる起動停止を調べるには、ソースランナー経由で Node の同期 I/O トレースフラグを追加します。

bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch では、監視対象の Gateway 子プロセスに対してこのフラグはデフォルトで無効です。監視モードでも同期 I/O トレース出力が必要な場合は、OPENCLAW_TRACE_SYNC_IO=1 を設定します。

Gateway 監視モード

bash
pnpm gateway:watch

デフォルトでは、openclaw-gateway-watch-<profile> という名前（例：openclaw-gateway-watch-main）の tmux セッションを起動または再起動します。OPENCLAW_GATEWAY_PORT がデフォルトポート 18789 と異なる場合にのみ、openclaw-gateway-watch-dev-19001 のようなポートサフィックスが追加されます。対話型ターミナルからは自動的にアタッチされます。非対話型シェル、CI、エージェントの exec 呼び出しではデタッチされたままとなり、代わりにアタッチ手順が表示されます。

bash
tmux attach -t openclaw-gateway-watch-main# アタッチせずに最近の出力を読み取るtmux capture-pane -ep -t openclaw-gateway-watch-main -S -200

ペインでは tmux の remain-on-exit を使用するため、起動失敗時にもセッションは削除されず、後からアタッチまたはキャプチャできます。pnpm gateway:watch を再実行すると、そのペインが再生成されます。

tmux ペインでは生のウォッチャーが実行されます。

bash
node scripts/watch-node.mjs gateway --force

設定済み／デフォルトのポートを監視する前に、tmux ラッパーはアクティブなプロファイルにインストールされている Gateway サービスを停止します。これにより、launchd、systemd、Scheduled Task がサービスを再生成して置き換えることなく、ソースウォッチャーがポートを使用できます。サービスはインストールされたままです。監視セッション終了後、次のコマンドで復元します。

bash
pnpm openclaw gateway start

明示的な --port または OPENCLAW_GATEWAY_PORT が、インストール済みサービスの実効ポートと異なる場合、ラッパーはサービスを実行したままにするため、両方の Gateway を並行して実行できます。

tmux を使用しないフォアグラウンドモード：

bash
pnpm gateway:watch:raw# またはOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Raw モードでは、インストール済みサービスは管理されません。同じポートを使用する場合は、先に pnpm openclaw gateway stop を実行してください。

tmux 管理を維持しながら自動アタッチを無効にするには、次のようにします。

bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

起動時／ランタイムのホットスポットをデバッグするときに、監視対象 Gateway の CPU 時間をプロファイリングします。

bash
pnpm gateway:watch --benchmark

監視ラッパーは Gateway を呼び出す前に --benchmark を消費し、Gateway 子プロセスが終了するたびに、V8 の .cpuprofile を1つずつ .artifacts/gateway-watch-profiles/ 配下へ書き込みます。現在のプロファイルを書き出すには監視対象 Gateway を停止または再起動し、Chrome DevTools または Speedscope で開きます。

bash
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
  • --benchmark-dir <path>：別の場所にプロファイルを書き込みます。
  • --benchmark-no-force：デフォルトの --force ポートのクリーンアップを省略し、Gateway ポートがすでに使用中の場合は即座に失敗します。

ベンチマークモードでは、同期 I/O トレースの大量出力がデフォルトで抑制されます。CPU プロファイルと同期 I/O スタックトレースの両方を取得するには、--benchmark とともに OPENCLAW_TRACE_SYNC_IO=1 を設定します。ベンチマークモードでは、それらのトレースブロックはベンチマークディレクトリ配下の gateway-watch-output.log に出力され（ターミナルペインからは除外されます）、通常の Gateway ログは引き続き表示されます。

tmux ラッパーは、OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT、OPENCLAW_SKIP_CHANNELS など、一般的な非機密のランタイムセレクターをペインへ引き継ぎます。プロバイダーの認証情報は通常のプロファイル／設定に保存するか、一時的なシークレットを一度だけ使用する場合は Raw フォアグラウンドモードを使用してください。

監視対象 Gateway が起動中に終了すると、ウォッチャーは openclaw doctor --fix --non-interactive を一度実行し、Gateway 子プロセスを再起動します。開発専用の修復処理を行わずに元の起動エラーを確認するには、OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 を設定します。

管理対象の tmux ペインでは、デフォルトで Gateway ログに色が付きます。ANSI 出力を無効にするには、pnpm gateway:watch の起動時に FORCE_COLOR=0 を設定します。

ウォッチャーは、src/ 配下のビルド関連ファイル、拡張機能のソースファイル、拡張機能の package.json および openclaw.plugin.json メタデータ、tsconfig.json、package.json、tsdown.config.ts が変更されると再起動します。拡張機能のメタデータ変更では、強制的な再ビルドを行わずに Gateway が再起動します。ソースと設定の変更時は、引き続き先に dist が再ビルドされます。

gateway:watch の後に Gateway CLI フラグを追加すると、再起動のたびにそのまま渡されます。同じ監視コマンドを再実行すると、指定された tmux ペインが再生成されます。Raw ウォッチャーでは単一ウォッチャーロックが維持されるため、ウォッチャーの親プロセスが重複して蓄積するのではなく、既存のものが置き換えられます。

開発プロファイル＋開発用 Gateway（--dev）

別々の --dev フラグが2つあります。

  • グローバル --dev（プロファイル）： 状態を ~/.openclaw-dev 配下に分離し、Gateway ポートをデフォルトで 19001 にします（派生ポートもそれに合わせて移動します）。
  • gateway --dev： デフォルトの設定とワークスペースが存在しない場合に、それらを自動作成し、ブートストラップを省略するよう Gateway に指示します。

推奨フロー（開発プロファイル＋開発用ブートストラップ）：

bash
pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

グローバルインストールがない場合は、pnpm openclaw ... 経由で CLI を実行します。

実行される処理：

  1. プロファイルの分離（グローバル --dev）

    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001（ブラウザー／Canvas のポートもそれに合わせて移動します）

  2. 開発用ブートストラップ（gateway --dev）

    • 存在しない場合は最小限の設定を書き込みます（gateway.mode=local、loopback にバインド）。
    • agents.defaults.workspace を開発用ワークスペースと agents.defaults.skipBootstrap=true に設定します。
    • 存在しない場合は、ワークスペースファイルを初期作成します：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md。
    • デフォルトのアイデンティティ：C3-PO（プロトコル・ドロイド）。
    • pnpm gateway:dev は、チャンネルプロバイダーを省略するために OPENCLAW_SKIP_CHANNELS=1 も設定します。

リセットフロー（新規開始）：

bash
pnpm gateway:dev:reset

--reset は設定、認証情報、セッション、開発用ワークスペースを消去し（削除ではなくゴミ箱へ移動）、デフォルトの開発環境を再作成します。

Raw ストリームのログ記録

OpenClaw は、フィルタリング／フォーマット処理を行う前の生のアシスタントストリームをログに記録できます。推論がプレーンテキストの差分として到着しているのか（または個別の思考ブロックとして到着しているのか）を確認するには、これが最適な方法です。

CLI で有効にします。

bash
pnpm gateway:watch --raw-stream

任意のパスを指定する場合：

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

同等の環境変数：

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

デフォルトファイル：~/.openclaw/logs/raw-stream.jsonl

安全上の注意

  • Raw ストリームログには、プロンプト全体、ツール出力、ユーザーデータが含まれる場合があります。
  • ログはローカルに保持し、デバッグ後に削除してください。
  • ログを共有する場合は、先にシークレットと個人識別情報（PII）を除去してください。

VSCode でのデバッグ

ビルドによって生成ファイル名がハッシュ化されるため、ソースマップが必要です。付属の launch.json は Gateway サービスを対象とします。

  1. Rebuild and Debug Gateway - Gateway の起動前に /dist を削除し、デバッグを有効にして再ビルドします。
  2. Debug Gateway - /dist を変更せず、既存のビルドをデバッグします。

セットアップ

  1. Run and Debug（Activity Bar、または Ctrl+Shift+D）を開きます。
  2. Rebuild and Debug Gateway を選択し、Start Debugging を押します。

代わりにビルド／デバッグサイクルを手動で管理するには、次のようにします。

  1. ターミナルでソースマップを有効にします。
    • Linux/macOS：export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell)：$env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD)：set OUTPUT_SOURCE_MAPS=1
  2. 再ビルド：pnpm clean:dist && pnpm build
  3. Debug Gateway を選択し、Start Debugging を押します。

src/ の TypeScript ファイルにブレークポイントを設定します。デバッガーは、ソースマップを使用してコンパイル済み JavaScript にマッピングします。

注意事項

  • Rebuild and Debug Gateway は、起動するたびに /dist を削除し、ソースマップを有効にして完全な pnpm build を実行します。
  • Debug Gateway は /dist に影響を与えずに起動／停止できますが、ビルドサイクルは別のターミナルで管理します。
  • ほかの CLI サブコマンドをデバッグするには、launch.json の args を編集します。
  • ほかのタスクでビルド済み CLI を使用するには（たとえば、デバッグセッションによって新しい認証トークンが生成された場合の dashboard --no-open）、別のターミナルから node ./openclaw.mjs、または alias openclaw-build="node $(pwd)/openclaw.mjs" のようなエイリアスを実行します。

関連項目

Was this useful?
On this page

On this page