OpenClaw テストガイド：ユニットテストから実プロバイダーでの検証まで

ローカル環境では完璧に動いているのに、いざ外部サービスと連携させると予期せぬ挙動に悩まされる。そんな経験は誰にでもあるはずです。開発をスムーズに進めるには、高速なフィードバックと、本番に近い環境での検証をうまく使い分けるのがベストな方法です。

OpenClaw には、実行速度とリアリズム（およびコスト）のバランスが異なる 3 つのテストスイートがあります。普段の開発では高速なユニットテストを使い、プロバイダー固有の問題をデバッグする際には Live テストを活用しましょう。

必要なもの

テストを実行する前に、以下の準備ができているか確認してください。

• Node.js 環境と pnpm
• OpenClaw のソースコード
• Live テスト用の API キー（実プロバイダーを使用する場合）
• Docker（Linux 環境での検証を行う場合）

クイックスタート

まずは、5 分でできる最小限のテスト手順です。コードをプッシュする前には、以下のフルゲートを実行することをおすすめします。

# フルゲート（プッシュ前に推奨）
pnpm lint && pnpm build && pnpm test

# カバレッジの確認
pnpm test:coverage

# E2E スイート（Gateway のネットワーク検証）
pnpm test:e2e

# Live スイート（実プロバイダーを使用、実コストが発生）
pnpm test:live

テストスイートの概要

OpenClaw のテストは、目的や実行環境に合わせて使い分けます。

シナリオ	推奨スイート
ロジックやテストの編集時	pnpm test
Gateway のネットワーク周りの変更	pnpm test:e2e を追加
プロバイダー側の不具合が疑われる時	範囲を絞った pnpm test:live

Unit / Integration (Default)

pnpm test で実行します。

• 対象ファイル: src/**/*.test.ts
• スコープ: 純粋なユニットテスト、プロセス内での統合テスト
• CI での実行: はい
• 必要なキー: 不要
• 実行速度: 高速 ⚡

E2E (Gateway Smoke)

pnpm test:e2e で実行します。

• 対象ファイル: src/**/*.e2e.test.ts
• スコープ: 複数インスタンスの Gateway、WebSocket、HTTP Surface、Node のペアリング
• CI での実行: はい（有効な場合）
• 必要なキー: 不要
• 実行速度: 低速

Live (Real Providers)

pnpm test:live で実行します。

• 対象ファイル: src/**/*.live.test.ts
• スコープ: 実際のプロバイダーへの API コール
• CI での実行: いいえ（設計上、CI では不安定なため）
• 必要なキー: 必要
• 実行速度: プロバイダーのレイテンシに依存
• コスト: 実際の費用 / レート制限が発生

Live Testing の詳細

Live テストには 2 つのレイヤーがあります。

Layer 1: Direct Model Completion

Gateway を介さずにプロバイダーを直接テストします。「API 自体が壊れているのか」と「自分のパイプラインが壊れているのか」を切り分けるのに便利です。

OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

Layer 2: Gateway + Agent Smoke

Gateway → Agent → Model → Tools というフルパイプラインをテストします。

OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Docker での実行

Linux 環境での動作検証を行うには、Docker 内でテストを実行します。

pnpm test:docker:live-models       # モデルの直接テスト
pnpm test:docker:live-gateway      # Gateway + Agent
pnpm test:docker:onboard           # オンボーディングウィザード
pnpm test:docker:gateway-network   # 2 コンテナ間のネットワーク
pnpm test:docker:plugins           # プラグインの読み込み

トラブルシューティング

テスト実行中によくある問題と解決策です。

• Live テストの実行速度が遅い: プロバイダーのレイテンシに依存します。特定のモデルのみに絞って実行してください。
• 実コストやレート制限: Live テストは実際の API を使用するため、費用が発生します。不要な全件テストを避け、allowlist を活用してください。

最後に

テストの構築や実行で困ったことがあれば、こちらのツールも活用してみてください。

解決しない場合は？ AI Setup Assistant がテストの問題解決をサポートします。

次のステップ

• Logging → — ログファイルとコンソール出力について
• Debugging → — ウォッチモードと生ストリームの確認方法
• Contributing → — 開発ガイドライン