OpenClawのテストとベンチマーク実行ガイド

開発中にテストが思うように通らなかったり、パフォーマンスのボトルネックを特定するのに苦労したりすることは、多くのエンジニアが経験する悩みではないでしょうか。OpenClawのテストスイートやベンチマークツールを活用すれば、こうした開発上の課題を効率的に解決し、安定した開発サイクルを維持できるようになります。

テスト

テスト環境を構築するための完全なキット（スイート、ライブテスト、Docker）については、Testing を参照してください。

pnpm test:force: デフォルトの制御ポートを占有しているGatewayプロセスを強制終了し、サーバーテストが実行中のインスタンスと競合しないよう、分離されたGatewayポートでVitestスイート全体を実行します。以前のGateway実行でポート18789が占有されたままの場合に使用してください。
pnpm test:coverage: V8カバレッジを使用してユニットスイートを実行します（vitest.unit.config.ts経由）。これはリポジトリ全体の全ファイルではなく、ロードされたファイルのユニットカバレッジを測定します。しきい値は行/関数/ステートメントで70%、分岐で55%です。coverage.allがfalseであるため、すべてのソースファイルを未カバーとして扱うのではなく、ユニットカバレッジスイートによってロードされたファイルを測定します。
pnpm test:coverage:changed: origin/mainから変更されたファイルのみに対してユニットカバレッジを実行します。
pnpm test:changed: diffがルーティング可能なソース/テストファイルのみに触れている場合、変更されたgitパスをスコープ付きのVitestレーンに展開します。設定やセットアップの変更はネイティブのルートプロジェクト実行にフォールバックされるため、必要な場合は配線の編集が広範囲に再実行されます。
pnpm changed:lanes: origin/mainに対するdiffによってトリガーされるアーキテクチャレーンを表示します。
pnpm check:changed: origin/mainに対するdiffに対してスマートな変更ゲートを実行します。コア作業はコアテストレーンで、拡張機能の作業は拡張機能テストレーンで、テストのみの作業はテスト型チェック/テストのみで実行し、公開されているPlugin SDKやプラグインコントラクトの変更は拡張機能の検証に展開されます。
pnpm test: 明示的なファイル/ディレクトリターゲットをスコープ付きのVitestレーンにルーティングします。ターゲット指定がない場合は固定シャードグループを使用し、ローカル並列実行のためにリーフ設定に展開されます。拡張機能グループは、巨大なルートプロジェクトプロセスではなく、常に拡張機能ごとのシャード設定に展開されます。
フルおよび拡張機能のシャード実行は、.artifacts/vitest-shard-timings.jsonのローカルタイミングデータを更新します。その後の実行では、それらのタイミングを使用して低速シャードと高速シャードのバランスを取ります。ローカルタイミングアーティファクトを無視するには、OPENCLAW_TEST_PROJECTS_TIMINGS=0を設定してください。
一部のplugin-sdkおよびcommandsテストファイルは、test/setup.tsのみを保持する専用の軽量レーンにルーティングされるようになり、ランタイム負荷の高いケースは既存のレーンに残ります。
一部のplugin-sdkおよびcommandsヘルパーソースファイルも、pnpm test:changedをそれらの軽量レーン内の明示的な兄弟テストにマッピングするため、小さなヘルパーの編集で重いランタイムバックエンドのスイートを再実行することを回避できます。
auto-replyも3つの専用設定（core、top-level、reply）に分割されたため、リプライハーネスが軽量なトップレベルのステータス/トークン/ヘルパーテストを支配することはありません。
基本のVitest設定はデフォルトでpool: "threads"およびisolate: falseとなり、リポジトリ設定全体で共有の非分離ランナーが有効になっています。
pnpm test:channelsはvitest.channels.config.tsを実行します。
pnpm test:extensionsおよびpnpm test extensionsはすべての拡張機能/プラグインシャードを実行します。重いチャネル拡張機能とOpenAIは専用シャードとして実行され、その他の拡張機能グループはバッチ処理されます。プラグインをバンドルした1つのレーンにはpnpm test extensions/<id>を使用してください。
pnpm test:perf:imports: Vitestのインポート時間とインポートの内訳レポートを有効にしつつ、明示的なファイル/ディレクトリターゲットに対してはスコープ付きのレーンルーティングを使用します。
pnpm test:perf:imports:changed: 上記と同じインポートプロファイリングですが、origin/mainから変更されたファイルのみを対象とします。
pnpm test:perf:changed:bench -- --ref <git-ref>: ルーティングされた変更モードのパスを、同じコミット済みgit diffに対するネイティブのルートプロジェクト実行と比較してベンチマークします。
pnpm test:perf:changed:bench -- --worktree: コミットする前に、現在のワークツリーの変更セットをベンチマークします。
pnpm test:perf:profile:main: VitestメインスレッドのCPUプロファイルを書き出します（.artifacts/vitest-main-profile）。
pnpm test:perf:profile:runner: ユニットランナーのCPU + ヒーププロファイルを書き出します（.artifacts/vitest-runner-profile）。
Gateway統合: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm testまたはpnpm test:gatewayでオプトインします。
pnpm test:e2e: Gatewayのend-to-endスモークテスト（マルチインスタンスWS/HTTP/nodeペアリング）を実行します。vitest.e2e.config.tsでアダプティブワーカーを使用したthreads + isolate: falseがデフォルトです。OPENCLAW_E2E_WORKERS=<n>で調整し、詳細なログが必要な場合はOPENCLAW_E2E_VERBOSE=1を設定してください。
pnpm test:live: プロバイダーのライブテスト（minimax/zai）を実行します。APIキーとLIVE=1（またはプロバイダー固有の*_LIVE_TEST=1）が必要です。
pnpm test:docker:openwebui: Docker化されたOpenClawとOpen WebUIを起動し、Open WebUI経由でサインインし、/api/modelsをチェックしてから、/api/chat/completionsを通じて実際のプロキシチャットを実行します。使用可能なライブモデルキー（例：~/.profile内のOpenAI）が必要で、外部のOpen WebUIイメージをプルします。通常のユニット/e2eスイートのようにCIで安定していることは期待されていません。
pnpm test:docker:mcp-channels: シードされたGatewayコンテナと、openclaw mcp serveを生成する2番目のクライアントコンテナを起動します。その後、ルーティングされた会話の検出、トランスクリプトの読み取り、添付ファイルのメタデータ、ライブイベントキューの動作、アウトバウンド送信ルーティング、Claudeスタイルのチャネル+権限通知を実際のstdioブリッジ経由で検証します。Claude通知のアサーションは生のstdio MCPフレームを直接読み取るため、スモークテストはブリッジが実際に放出するものと一致します。

ローカルPRゲート

ローカルでのPRマージやゲートチェックを行うには、以下のコマンドを実行してください。

pnpm check:changed
pnpm check
pnpm check:test-types
pnpm build
pnpm test
pnpm check:docs

もしpnpm testがロードされたホストで不安定な場合は、回帰と判断する前に一度再実行し、その後pnpm test <path/to/test>で分離してください。メモリ制限のあるホストでは、以下を使用してください。

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

モデルのレイテンシベンチマーク（ローカルキー）

スクリプト: scripts/bench-model.ts

使用方法:

source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
オプションの環境変数: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
デフォルトのプロンプト: “Reply with a single word: ok. No punctuation or extra text.”

前回の実行結果（2025-12-31, 20回実行）:

minimax 中央値 1279ms (最小 1114, 最大 2431)
opus 中央値 2454ms (最小 1224, 最大 3170)

CLI起動ベンチマーク

スクリプト: scripts/bench-cli-startup.ts

使用方法:

pnpm test:startup:bench
pnpm test:startup:bench:smoke
pnpm test:startup:bench:save
pnpm test:startup:bench:update
pnpm test:startup:bench:check
pnpm tsx scripts/bench-cli-startup.ts
pnpm tsx scripts/bench-cli-startup.ts --runs 12
pnpm tsx scripts/bench-cli-startup.ts --preset real
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
pnpm tsx scripts/bench-cli-startup.ts --json

プリセット:

startup: --version, --help, health, health --json, status --json, status
real: health, status, status --json, sessions, sessions --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
all: 両方のプリセット

出力には、各コマンドのsampleCount、平均、p50、p95、最小/最大、終了コード/シグナル分布、および最大RSSの概要が含まれます。オプションの--cpu-prof-dir / --heap-prof-dirは実行ごとにV8プロファイルを書き出すため、タイミングとプロファイルのキャプチャに同じハーネスを使用します。

保存された出力の規則:

pnpm test:startup:bench:smokeは、ターゲットとなるスモークアーティファクトを.artifacts/cli-startup-bench-smoke.jsonに書き出します。
pnpm test:startup:bench:saveは、runs=5およびwarmup=1を使用して、フルスイートのアーティファクトを.artifacts/cli-startup-bench-all.jsonに書き出します。
pnpm test:startup:bench:updateは、runs=5およびwarmup=1を使用して、test/fixtures/cli-startup-bench.jsonにあるチェックイン済みのベースラインフィクスチャを更新します。

チェックイン済みのフィクスチャ:

test/fixtures/cli-startup-bench.json
pnpm test:startup:bench:updateで更新
pnpm test:startup:bench:checkで現在の結果をフィクスチャと比較

オンボーディングE2E（Docker）

Dockerはオプションであり、コンテナ化されたオンボーディングのスモークテストにのみ必要です。

クリーンなLinuxコンテナでの完全なコールドスタートフロー:

scripts/e2e/onboard-docker.sh

このスクリプトは擬似端末を介してインタラクティブウィザードを駆動し、設定/ワークスペース/セッションファイルを検証してから、Gatewayを起動し、openclaw healthを実行します。

QRインポートスモーク（Docker）

サポートされているDocker Nodeランタイム（Node 24デフォルト、Node 22互換）でqrcode-terminalがロードされることを確認します。

pnpm test:docker:qr

さらなる設定や詳細については、AI Setup Assistant をご確認ください。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。