OpenClawテストガイド：VitestスイートとQA環境の構築・実行手順

快速開始

日常開発で頻繁に使用するコマンドは以下の通りです。

1. プッシュ前のフルチェック：pnpm build && pnpm check && pnpm check:test-types && pnpm test
2. 高スペックマシンでの高速なフルスイート実行：pnpm test:max
3. Vitestのウォッチモード：pnpm test:watch
4. 特定ファイルのテスト実行（拡張機能やチャンネルパスも指定可能）：pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
5. 修正中の単一テストに集中したい場合は、ターゲットを絞った実行を推奨します。
6. DockerベースのQAサイト起動：pnpm qa:lab:up
7. Linux VMベースのQAレーン実行：pnpm openclaw qa suite —runner multipass —scenario channel-chat-baseline

テストの変更時や、より確実な検証を行いたい場合は以下を使用してください。

1. カバレッジ確認：pnpm test:coverage
2. E2Eスイート実行：pnpm test:e2e

実際のプロバイダーやモデルをデバッグする場合（有効な認証情報が必要です）：

1. ライブスイート（モデルおよびGatewayツール/画像プローブの検証）：pnpm test:live
2. 特定のライブテストファイルを静かに実行：pnpm test:live — src/agents/models.profiles.live.test.ts

ヒント：失敗したケースのみを特定したい場合は、後述の環境変数による許可リスト（allowlist）を使用してライブテストの範囲を絞り込むことをお勧めします。

QA専用ランナー

以下のコマンドは、QAラボのリアリティが必要な場合にメインのテストスイートと併用します。

1. pnpm openclaw qa suite
   • リポジトリベースのQAシナリオをホスト上で直接実行します。
   • デフォルトでは、隔離されたGatewayワーカーを使用して複数の選択済みシナリオを並列実行します。qa-channelのデフォルト同時実行数は4（選択したシナリオ数に依存）です。ワーカー数を調整するには —concurrency <count> を使用し、従来のシリアル実行を行うには —concurrency 1 を指定してください。
   • シナリオが失敗すると非ゼロで終了します。アーティファクトを保持しつつ終了コードを正常にしたい場合は —allow-failures を使用してください。
   • プロバイダーモードとして live-frontier、mock-openai、aimock をサポートしています。aimock は実験的なフィクスチャやプロトコルモックの網羅性を高めるために、ローカルのAIMockバックエンドプロバイダーサーバーを起動します。
2. pnpm openclaw qa suite —runner multipass
   • 使い捨てのMultipass Linux VM内で同じQAスイートを実行します。
   • ホスト上の qa suite と同じシナリオ選択動作を維持します。
   • qa suite と同じプロバイダー/モデル選択フラグを再利用します。
   • ライブ実行では、ゲスト環境で実用的なQA認証入力（環境変数ベースのプロバイダーキー、QAライブプロバイダー設定パス、および存在する場合は CODEX_HOME）を転送します。
   • 出力ディレクトリは、ゲストがマウントされたワークスペースを通じて書き戻せるよう、リポジトリルート配下に留める必要があります。
   • 通常のQAレポートとサマリーに加え、Multipassのログを .artifacts/qa-e2e/... に書き出します。
3. pnpm qa:lab:up
   • オペレーター形式のQA作業用に、DockerベースのQAサイトを起動します。
4. pnpm openclaw qa aimock
   • 直接的なプロトコル・スモークテストのために、ローカルのAIMockプロバイダーサーバーのみを起動します。
5. pnpm openclaw qa matrix
   • 使い捨てのDockerベースのTuwunelホームサーバーに対して、MatrixライブQAレーンを実行します。
   • このQAホストは現時点ではリポジトリ/開発者専用です。パッケージ化されたOpenClawインストールには qa-lab が含まれていないため、openclaw qa は公開されません。
   • リポジトリのチェックアウトによりバンドルされたランナーが直接読み込まれるため、別途プラグインをインストールする手順は不要です。
   • 3つの暫定的なMatrixユーザー（driver、sut、observer）と1つのプライベートルームをプロビジョニングし、SUTトランスポートとして実際のMatrixプラグインを使用してQA Gatewayの子プロセスを起動します。
   • デフォルトで固定された安定版Tuwunelイメージ ghcr.io/matrix-construct/tuwunel:v1.5.1 を使用します。別のイメージをテストする必要がある場合は OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE で上書きしてください。
   • Matrixはローカルで使い捨てユーザーをプロビジョニングするため、共有認証情報ソースフラグは公開されません。
   • Matrix QAレポート、サマリー、観測イベントのアーティファクト、および結合されたstdout/stderr出力ログを .artifacts/qa-e2e/... に書き出します。
6. pnpm openclaw qa telegram
   • 環境変数から取得したドライバーおよびSUTボットトークンを使用して、実際のプライベートグループに対してTelegramライブQAレーンを実行します。
   • OPENCLAW_QA_TELEGRAM_GROUP_ID、OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN、および OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN が必要です。グループIDは数値のTelegramチャットIDである必要があります。
   • 共有プールされた認証情報のために —credential-source convex をサポートしています。デフォルトは環境変数モードですが、プールされたリースを選択するには OPENCLAW_QA_CREDENTIAL_SOURCE=convex を設定してください。
   • シナリオが失敗すると非ゼロで終了します。アーティファクトを保持したい場合は —allow-failures を使用してください。
   • 同じプライベートグループ内に2つの異なるボットが必要であり、SUTボットはTelegramユーザー名を公開している必要があります。
   • ボット間の安定した観測のために、@BotFather で両方のボットに対してBot-to-Bot通信モードを有効にし、ドライバーボットがグループ内のボットトラフィックを観測できることを確認してください。
   • Telegram QAレポート、サマリー、観測メッセージのアーティファクトを .artifacts/qa-e2e/... に書き出します。

ライブトランスポートレーンは、新しいトランスポートが乖離しないよう標準的な契約を共有しています。qa-channel は広範な合成QAスイートであり、ライブトランスポートの網羅性マトリックスには含まれません。

テストスイート（どこで何が実行されるか）

テストスイートは「リアリティの向上（および不安定さ/コストの増加）」という観点で分類されています。

ユニット / 統合テスト（デフォルト）

1. コマンド：pnpm test
2. 設定：既存のスコープ付きVitestプロジェクト全体で10個のシーケンシャルなシャード実行（vitest.full-*.config.ts）を行います。
3. 対象ファイル：src/**/*.test.ts、packages/**/*.test.ts、test/**/*.test.ts 配下のコア/ユニットインベントリ、および vitest.unit.config.ts でカバーされるホワイトリスト化されたUI Nodeテスト。
4. スコープ：純粋なユニットテスト、インプロセス統合テスト（Gateway認証、ルーティング、ツール、パース、設定）、既知のバグに対する決定論的なリグレッションテスト。
5. 期待値：CIで実行されること、実際のキーが不要であること、高速かつ安定していること。
6. プロジェクトに関する注記：Untargetedな pnpm test は、単一の巨大なルートプロジェクトプロセスではなく、11個の小さなシャード設定（core-unit-src、core-unit-security、core-unit-ui、core-unit-support、core-support-boundary、core-contracts、core-bundled、core-runtime、agentic、auto-reply、extensions）を実行します。これにより、読み込み時のピークRSSが削減され、auto-replyや拡張機能の作業が他のスイートを圧迫するのを防ぎます。

E2E（Gatewayスモークテスト）

1. コマンド：pnpm test:e2e
2. 設定：vitest.e2e.config.ts
3. 対象ファイル：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts
4. ランタイムのデフォルト：Vitestの threads と isolate: false を使用し、リポジトリの他の部分と合わせます。適応型ワーカー（CI：最大2、ローカル：デフォルト1）を使用し、コンソールI/Oのオーバーヘッドを減らすためデフォルトでサイレントモードで実行されます。
5. スコープ：マルチインスタンスGatewayのE2E動作、WebSocket/HTTPインターフェース、ノードペアリング、および負荷の高いネットワーク処理。

E2E：OpenShellバックエンドスモークテスト

1. コマンド：pnpm test:e2e:openshell
2. 対象ファイル：test/openshell-sandbox.e2e.test.ts
3. スコープ：Dockerを介してホスト上で隔離されたOpenShell Gatewayを起動し、一時的なローカルDockerfileからサンドボックスを作成します。実際の sandbox ssh-config + SSH exec を通じてOpenClawのOpenShellバックエンドを検証し、サンドボックスFSブリッジを介したリモート正規ファイルシステムの動作を確認します。
4. 期待値：オプトインのみ。デフォルトの pnpm test:e2e には含まれません。ローカルの openshell CLIと動作するDockerデーモンが必要です。

ライブテスト（実際のプロバイダー + 実際のモデル）

1. コマンド：pnpm test:live
2. 設定：vitest.live.config.ts
3. 対象ファイル：src/**/*.live.test.ts
4. デフォルト：pnpm test:live によって有効化されます（OPENCLAW_LIVE_TEST=1 を設定）。
5. スコープ：「このプロバイダー/モデルは、実際の認証情報を使用して今日現在動作するか？」を確認します。プロバイダーのフォーマット変更、ツール呼び出しの癖、認証の問題、レート制限の動作をキャッチします。
6. 期待値：設計上、CIでの安定性は保証されません（実際のネットワーク、プロバイダーポリシー、クォータ、停止の影響を受けるため）。コストが発生し、レート制限を消費します。

どのスイートを実行すべきか？

以下の判断表に従ってください。

• ロジックやテストの編集：pnpm test を実行（変更量が多い場合は pnpm test:coverage も併用）。
• Gatewayのネットワーク、WSプロトコル、ペアリングに関する変更：pnpm test:e2e を追加。
• 「ボットがダウンしている」というデバッグ、プロバイダー固有の失敗、ツール呼び出しのデバッグ：範囲を絞った pnpm test:live を実行。

AI Setup Assistant

Live: Android node 機能スイープ

Androidデバイスとの連携において、OpenClaw Androidノードが正しく機能しているかを確認するためのテストスイートです。

1. テストファイル: src/gateway/android-node.capabilities.live.test.ts
2. 実行スクリプト: pnpm android:test:integration
3. 目的: 接続されたAndroidノードが公開しているすべてのコマンドを呼び出し、コマンドのコントラクト動作を検証します。
4. 範囲:
   • 事前条件付き/手動セットアップ（このスイート自体はアプリのインストール、実行、ペアリングを行いません）。
   • 選択したAndroidノードに対する、コマンドごとのGateway node.invoke の検証。
5. 必要な事前準備:
   • AndroidアプリがすでにGatewayに接続およびペアリングされていること。
   • アプリがフォアグラウンドで維持されていること。
   • 期待する機能に対して、権限およびキャプチャの同意が与えられていること。
6. オプションのターゲット上書き:
   • OPENCLAW_ANDROID_NODE_ID または OPENCLAW_ANDROID_NODE_NAME。
   • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD。
7. Androidセットアップの詳細: Android App

Live: モデルスモークテスト（プロファイルキー）

ライブテストは、障害箇所を特定するために2つのレイヤーに分割されています。

• 「Direct model」は、特定のキーを使用してプロバイダーやモデルが応答可能かどうかを判断します。
• 「Gateway smoke」は、そのモデルに対してGatewayとエージェントのパイプライン全体（セッション、履歴、ツール、サンドボックスポリシーなど）が機能するかを判断します。

レイヤー1: 直接モデルの完了テスト（Gatewayなし）

このテストでは、Gatewayを介さずにモデル単体の応答性を確認します。

1. テストファイル: src/agents/models.profiles.live.test.ts
2. 目的:
   • 発見されたモデルを列挙する。
   • getApiKeyForModel を使用して、認証情報を持つモデルを選択する。
   • モデルごとに小さな完了テスト（および必要に応じたターゲット回帰テスト）を実行する。
3. 有効化する方法:
   • pnpm test:live （Vitestを直接呼び出す場合は OPENCLAW_LIVE_TEST=1）。
4. OPENCLAW_LIVE_MODELS=modern （または all、modernのエイリアス）を設定してスイートを実行します。設定しない場合、pnpm test:live がGatewayスモークに集中できるようスキップされます。
5. モデルの選択方法:
   • OPENCLAW_LIVE_MODELS=modern でモダンな許可リスト（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）を実行。
   • OPENCLAW_LIVE_MODELS=all はモダンな許可リストのエイリアス。
   • または OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." （カンマ区切りの許可リスト）。
   • モダン/allスイープはデフォルトで厳選された高シグナルなキャップを使用します。網羅的なスイープを行うには OPENCLAW_LIVE_MAX_MODELS=0 を設定し、数を制限するには正の数値を設定してください。
6. プロバイダーの選択方法:
   • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" （カンマ区切りの許可リスト）。
7. キーの取得元:
   • デフォルト: プロファイルストアおよび環境変数のフォールバック。
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 を設定すると、プロファイルストアのみを強制します。
8. 存在理由:
   • 「プロバイダーAPIの破損/キーの無効」と「Gatewayエージェントパイプラインの破損」を切り分けるため。
   • 小規模で分離された回帰テスト（例: OpenAI Responses/Codex Responsesの推論リプレイやツール呼び出しフロー）を含みます。

レイヤー2: Gateway + 開発エージェントスモーク（“@openclaw”の実際の動作）

このテストでは、Gatewayとエージェントの統合環境を検証します。

1. テストファイル: src/gateway/gateway-models.profiles.live.test.ts
2. 目的:
   • インプロセスでGatewayを起動する。
   • agent:dev:* セッションを作成/パッチする（実行ごとにモデルを上書き）。
   • キーを持つモデルを反復し、以下をアサートする:
     • 「意味のある」応答（ツールなし）。
     • 実際のツール呼び出しが機能する（readプローブ）。
     • オプションの追加ツールプローブ（exec+readプローブ）。
     • OpenAIの回帰パス（ツール呼び出しのみ → フォローアップ）が維持されていること。
3. プローブの詳細:
   • read プローブ: テストがワークスペースにnonceファイルを書き込み、エージェントにそれを read させてnonceをエコーバックさせる。
   • exec+read プローブ: テストがエージェントに exec で一時ファイルへnonceを書き込ませ、それを read で読み戻す。
   • 画像プローブ: テストが生成されたPNG（猫 + ランダムコード）を添付し、モデルが cat <CODE> を返すことを期待する。
   • 実装リファレンス: src/gateway/gateway-models.profiles.live.test.ts および src/gateway/live-image-probe.ts。
4. 有効化する方法:
   • pnpm test:live （Vitestを直接呼び出す場合は OPENCLAW_LIVE_TEST=1）。
5. モデルの選択方法:
   • デフォルト: モダンな許可リスト（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）。
   • OPENCLAW_LIVE_GATEWAY_MODELS=all はモダンな許可リストのエイリアス。
   • または OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" （またはカンマ区切りリスト）で絞り込む。
   • モダン/allのGatewayスイープはデフォルトで厳選された高シグナルなキャップを使用します。網羅的なスイープを行うには OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 を設定してください。
6. プロバイダーの選択方法（“OpenRouter everything”を避ける）:
   • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" （カンマ区切りの許可リスト）。
7. ツール + 画像プローブは、このライブテストでは常に有効です:
   • read プローブ + exec+read プローブ（ツール負荷テスト）。
   • 画像プローブは、モデルが画像入力サポートをアドバタイズしている場合に実行。
   • フロー（概要）:
     • テストが「CAT」+ ランダムコードを含む小さなPNGを生成 (src/gateway/live-image-probe.ts)。
     • agent を介して attachments: [{ mimeType: "image/png", content: "<base64>" }] で送信。
     • Gatewayが添付ファイルを images[] に解析 (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)。
     • 埋め込みエージェントがマルチモーダルなユーザーメッセージをモデルに転送。
     • アサーション: 返信に cat + コードが含まれていること（OCR許容範囲: 軽微なミスは許可）。

ヒント: マシン上でテスト可能なもの（および正確な provider/model ID）を確認するには、以下を実行してください。

openclaw models list
openclaw models list --json

Live: CLIバックエンドスモーク（Claude、Codex、Gemini、その他のローカルCLI）

ローカルCLIバックエンドを使用して、デフォルト設定を変更せずにGatewayとエージェントのパイプラインを検証します。

1. テストファイル: src/gateway/gateway-cli-backend.live.test.ts
2. 目的: ローカルCLIバックエンドを使用してGatewayとエージェントのパイプラインを検証する。
3. バックエンド固有のスモークデフォルトは、所有する拡張機能の cli-backend.ts 定義に存在します。
4. 有効化:
   • pnpm test:live （Vitestを直接呼び出す場合は OPENCLAW_LIVE_TEST=1）。
   • OPENCLAW_LIVE_CLI_BACKEND=1。
5. デフォルト:
   • デフォルトのプロバイダー/モデル: claude-cli/claude-sonnet-4-6。
   • コマンド/引数/画像動作は、所有するCLIバックエンドプラグインのメタデータから取得。
6. 上書き（オプション）:
   • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
   • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"
   • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'
   • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 で実際の画像添付を送信（パスはプロンプトに注入されます）。
   • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" で画像ファイルパスをプロンプト注入ではなくCLI引数として渡す。
   • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" （または "list") で IMAGE_ARG 設定時の画像引数の渡し方を制御。
   • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 で2回目のターンを送信し、再開フローを検証。
   • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0 でデフォルトのClaude Sonnet -> Opusの同一セッション継続性プローブを無効化（選択したモデルがスイッチターゲットをサポートしている場合に強制的に有効にするには 1 を設定）。

例:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Dockerレシピ:

pnpm test:docker:live-cli-backend

単一プロバイダーのDockerレシピ:

pnpm test:docker:live-cli-backend:claude
pnpm test:docker:live-cli-backend:claude-subscription
pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini

注意点:

• Dockerランナーは scripts/test-live-cli-backend-docker.sh にあります。
• リポジトリのDockerイメージ内で、非rootの node ユーザーとしてライブCLIバックエンドスモークを実行します。
• 所有する拡張機能からCLIスモークメタデータを解決し、対応するLinux CLIパッケージ（@anthropic-ai/claude-code、@openai/codex、または @google/gemini-cli）を OPENCLAW_DOCKER_CLI_TOOLS_DIR（デフォルト: ~/.cache/openclaw/docker-cli-tools）のキャッシュ可能な書き込み可能プレフィックスにインストールします。
• pnpm test:docker:live-cli-backend:claude-subscription は、~/.claude/.credentials.json （claudeAiOauth.subscriptionType を含む）または claude setup-token からの CLAUDE_CODE_OAUTH_TOKEN を介したポータブルなClaude CodeサブスクリプションOAuthを必要とします。まずDocker内で直接 claude -p を証明し、次にAnthropic APIキーの環境変数を保持せずに2つのGateway CLIバックエンドターンを実行します。このサブスクリプションレーンでは、Claudeが現在サードパーティアプリの使用を通常のサブスクリプション制限ではなく追加使用料として請求するため、デフォルトでClaude MCP/ツールおよび画像プローブが無効になっています。
• ライブCLIバックエンドスモークは、Claude、Codex、Geminiに対して同じエンドツーエンドフロー（テキストターン、画像分類ターン、Gateway CLIを通じて検証されるMCP cron ツール呼び出し）を実行します。
• Claudeのデフォルトスモークは、セッションをSonnetからOpusにパッチし、再開されたセッションが以前のメモを記憶していることを検証します。

Live: ACPバインドスモーク (/acp spawn ... --bind here)

実際のACP会話バインドフローをライブACPエージェントで検証します。

1. テストファイル: src/gateway/gateway-acp-bind.live.test.ts
2. 目的: ライブACPエージェントを使用した実際のACP会話バインドフローを検証する:
   • /acp spawn <agent> --bind here を送信。
   • 合成メッセージチャネルの会話をその場でバインド。
   • 同じ会話に対して通常のフォローアップを送信。
   • フォローアップがバインドされたACPセッションのトランスクリプトに反映されることを検証。
3. 有効化:
   • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
   • OPENCLAW_LIVE_ACP_BIND=1
4. デフォルト:
   • Docker内のACPエージェント: claude,codex,gemini
   • 直接 pnpm test:live ... を実行する場合のACPエージェント: claude
   • 合成チャネル: Slack DMスタイルの会話コンテキスト
   • ACPバックエンド: acpx
5. 上書き:
   • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
   • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
   • OPENCLAW_LIVE_ACP_BIND_AGENT=gemini
   • OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini
   • OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'
6. 注意点:
   • このレーンは、管理者専用の合成発信ルートフィールドを持つGateway chat.send サーフェスを使用するため、外部への配信を装うことなくメッセージチャネルコンテキストをテストに添付できます。
   • OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND が設定されていない場合、テストは埋め込み acpx プラグインの組み込みエージェントレジストリを使用します。

例:

OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts

Dockerレシピ:

pnpm test:docker:live-acp-bind

単一エージェントのDockerレシピ:

pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini

Dockerの注意点:

• Dockerランナーは scripts/test-live-acp-bind-docker.sh にあります。
• デフォルトでは、サポートされているすべてのライブCLIエージェント（claude、codex、gemini）に対して順次ACPバインドスモークを実行します。
• マトリックスを絞り込むには OPENCLAW_LIVE_ACP_BIND_AGENTS=claude、OPENCLAW_LIVE_ACP_BIND_AGENTS=codex、または OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini を使用してください。
• ~/.profile をソースし、一致するCLI認証素材をコンテナにステージングし、acpx を書き込み可能なnpmプレフィックスにインストールし、不足している場合は要求されたライブCLI（@anthropic-ai/claude-code、@openai/codex、または @google/gemini-cli）をインストールします。
• Docker内では、ランナーが OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx を設定するため、acpx はソースされたプロファイルからのプロバイダー環境変数を子ハーネスCLIで利用可能にします。

AI Setup Assistant

Live: Codex app-server harness smoke

このセクションでは、OpenClaw の Codex プラグインが提供するハーネス（harness）が、通常の Gateway を介して正しく動作するかを検証します。以下の手順で、agent メソッドの動作確認を行います。

1. バンドルされている codex プラグインを読み込みます。
2. OPENCLAW_AGENT_RUNTIME=codex を選択します。
3. 最初の Gateway エージェントターンを codex/gpt-5.4 に送信します。
4. 同じ OpenClaw セッションに対して2回目のターンを送信し、app-server スレッドが再開できることを確認します。
5. 同じ Gateway コマンドパスを通じて /codex status および /codex models を実行します。

テストの実行には src/gateway/gateway-codex-harness.live.test.ts を使用し、有効化には OPENCLAW_LIVE_CODEX_HARNESS=1 を設定してください。デフォルトモデルは codex/gpt-5.4 です。オプションとして、画像プローブには OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 を、MCP / ツールプローブには OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 を指定できます。このスモークテストでは OPENCLAW_AGENT_HARNESS_FALLBACK=none が設定されるため、Codex ハーネスが壊れている場合に、PI（Plugin Infrastructure）へのフォールバックによって問題が隠蔽されることはありません。認証にはシェルやプロファイルで設定された OPENAI_API_KEY に加え、必要に応じてコピーされた ~/.codex/auth.json および ~/.codex/config.toml が使用されます。

ローカルでの実行レシピ：

source ~/.profile
OPENCLAW_LIVE_CODEX_HARNESS=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts

Docker での実行レシピ：

source ~/.profile
pnpm test:docker:live-codex-harness

Docker に関する注意点：

1. Docker ランナーは scripts/test-live-codex-harness-docker.sh に配置されています。
2. マウントされた ~/.profile を読み込み、OPENAI_API_KEY を渡します。また、存在する場合は Codex CLI の認証ファイルをコピーし、書き込み可能なマウント済み npm プレフィックスに @openai/codex をインストールしてソースツリーをステージングした後、Codex ハーネスのライブテストのみを実行します。
3. Docker はデフォルトで画像および MCP / ツールプローブを有効にします。デバッグのために範囲を絞る必要がある場合は、OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 または OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 を設定してください。
4. Docker は OPENCLAW_AGENT_HARNESS_FALLBACK=none もエクスポートします。これはライブテストの構成と一致しており、openai-codex/* や PI へのフォールバックが Codex ハーネスの回帰を隠さないようにしています。

推奨されるライブテストのレシピ：

明確で限定的な許可リストを使用するのが、最も高速で安定しています。

• 単一モデル、直接接続（Gateway なし）：

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

• 単一モデル、Gateway スモークテスト：

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

• 複数のプロバイダー間でのツール呼び出し：

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Google へのフォーカス（Gemini API キー + Antigravity）：

  • Gemini (API キー): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

注意点：

• google/... は Gemini API (API キー) を使用します。
• google-antigravity/... は Antigravity OAuth ブリッジ（Cloud Code Assist スタイルのエージェントエンドポイント）を使用します。
• google-gemini-cli/... はマシン上のローカル Gemini CLI を使用します（独自の認証とツールの癖があります）。
• Gemini API と Gemini CLI の違い：
  • API: OpenClaw は Google のホスト型 Gemini API を HTTP 経由で呼び出します（API キー / プロファイル認証）。これがほとんどのユーザーが「Gemini」と呼ぶものです。
  • CLI: OpenClaw はローカルの gemini バイナリをシェル経由で実行します。独自の認証を持ち、ストリーミングやツールサポート、バージョンの差異などで挙動が異なる場合があります。

Live: model matrix (what we cover)

固定された「CI モデルリスト」はありませんが、開発マシン上でキーを使用して定期的にカバーすべき推奨モデルを以下に示します。

モダンなスモークセット（ツール呼び出し + 画像）

これらは継続的に動作を確認すべき「一般的なモデル」です。

• OpenAI (非 Codex): openai/gpt-5.4 (オプション: openai/gpt-5.4-mini)
• OpenAI Codex: openai-codex/gpt-5.4
• Anthropic: anthropic/claude-opus-4-6 (または anthropic/claude-sonnet-4-6)
• Google (Gemini API): google/gemini-3.1-pro-preview および google/gemini-3-flash-preview (古い Gemini 2.x モデルは避けてください)
• Google (Antigravity): google-antigravity/claude-opus-4-6-thinking および google-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

ツール + 画像を含む Gateway スモークテストの実行： OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

ベースライン：ツール呼び出し（読み取り + オプションの実行）

プロバイダーファミリーごとに少なくとも1つを選択してください。

• OpenAI: openai/gpt-5.4 (または openai/gpt-5.4-mini)
• Anthropic: anthropic/claude-opus-4-6 (または anthropic/claude-sonnet-4-6)
• Google: google/gemini-3-flash-preview (または google/gemini-3.1-pro-preview)
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

追加のカバー範囲（推奨）：

• xAI: xai/grok-4 (または利用可能な最新版)
• Mistral: mistral/… (ツール対応モデルを1つ選択)
• Cerebras: cerebras/… (アクセス権がある場合)
• LM Studio: lmstudio/… (ローカル; ツール呼び出しは API モードに依存)

ビジョン：画像送信（添付ファイル → マルチモーダルメッセージ）

画像プローブを検証するために、OPENCLAW_LIVE_GATEWAY_MODELS に画像対応モデル（Claude/Gemini/OpenAI のビジョン対応バリアントなど）を少なくとも1つ含めてください。

アグリゲーター / 代替 Gateway

キーが有効な場合、以下を通じたテストもサポートしています。

• OpenRouter: openrouter/...（数百のモデル。ツールと画像に対応した候補を探すには openclaw models scan を使用してください）
• OpenCode: Zen 用の opencode/... および Go 用の opencode-go/...（認証は OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY 経由）

ライブマトリックスに追加可能なその他のプロバイダー（資格情報や設定がある場合）：

• ビルトイン: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
• models.providers 経由（カスタムエンドポイント）: minimax (クラウド/API)、および OpenAI/Anthropic 互換プロキシ（LM Studio, vLLM, LiteLLM など）

ヒント: ドキュメントに「すべてのモデル」をハードコードしようとしないでください。信頼できるリストは、マシン上で discoverModels(...) が返すものと、利用可能なキーの組み合わせです。

Credentials (never commit)

ライブテストは CLI と同じ方法で資格情報を検出します。実用上の意味は以下の通りです。

1. CLI が動作すれば、ライブテストも同じキーを見つけられるはずです。
2. ライブテストで「資格情報がない」と表示される場合は、openclaw models list やモデル選択時と同じ方法でデバッグしてください。
3. エージェントごとの認証プロファイル: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（ライブテストにおける「プロファイルキー」とはこれを指します）
4. 設定: ~/.openclaw/openclaw.json (または OPENCLAW_CONFIG_PATH)
5. レガシー状態ディレクトリ: ~/.openclaw/credentials/（存在する場合はステージングされたライブホームにコピーされますが、メインのプロファイルキー保存場所ではありません）
6. ローカルでのライブ実行は、デフォルトでアクティブな設定、エージェントごとの auth-profiles.json ファイル、レガシーな credentials/、およびサポートされている外部 CLI 認証ディレクトリを一時的なテストホームにコピーします。ステージングされたライブホームは workspace/ や sandboxes/ をスキップし、agents.*.workspace や agentDir のパス上書きは削除されるため、プローブが実際のホストワークスペースに影響を与えることはありません。

環境変数キー（~/.profile にエクスポートされたものなど）に依存したい場合は、source ~/.profile の後にローカルテストを実行するか、以下の Docker ランナーを使用してください（これらは ~/.profile をコンテナにマウントできます）。

Deepgram live (audio transcription)

音声文字起こしのテストは以下の通りです。

• テスト: src/media-understanding/providers/deepgram/audio.live.test.ts
• 有効化: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

AI Setup Assistant

BytePlus coding plan live

開発中に外部サービスの統合をテストする際、設定が正しく反映されているかを確認するのは非常に重要です。OpenClaw の BytePlus コーディングプラン機能の動作を検証するために、以下の手順でライブテストを実行してください。

1. テストファイルを確認します。

   src/agents/byteplus.live.test.ts

2. 以下のコマンドを実行してテストを有効化します。

   BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts

3. 必要に応じてモデルを上書きします。

   BYTEPLUS_CODING_MODEL=ark-code-latest

ComfyUI workflow media live

OpenClaw の ComfyUI ワークフローにおけるメディア処理のライブテストでは、画像や動画生成のパイプラインが正しく動作するかを確認します。ワークフローの変更やプラグイン登録後に、このテストを実行することをお勧めします。

1. テストファイルを確認します。

   extensions/comfy/comfy.live.test.ts

2. 以下のコマンドでテストを実行します。

   OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

3. このテストは、バンドルされた画像、動画、および music_generate パスを検証します。各機能は models.providers.comfy.<capability> が設定されている場合のみ実行され、設定がない場合はスキップされます。

Image generation live

OpenClaw の画像生成機能のライブテストでは、登録されているすべてのプロバイダープラグインを網羅的に検証します。環境変数や API キーの読み込み順序を考慮し、実際の環境で正しく動作するかをチェックします。

1. テストファイルを確認します。

   src/image-generation/runtime.live.test.ts

2. テストを実行します。

   pnpm test:live src/image-generation/runtime.live.test.ts

3. または、以下のハーネスを使用します。

   pnpm test:live:media image

4. このテストは、ログインシェル（~/.profile）から不足している環境変数を読み込み、auth-profiles.json に保存された古いキーよりも、ライブ環境の API キーを優先して使用します。
5. 必要に応じて、以下のオプションで対象を絞り込むことができます。

   OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"
   OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"
   OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"

6. プロファイルストアの認証を強制し、環境変数の上書きを無視したい場合は以下を使用します。

   OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1

Music generation live

OpenClaw の音楽生成機能のライブテストでは、Google や MiniMax といったプロバイダーの共有パスを検証します。画像生成と同様に、環境変数と認証プロファイルを適切に管理しながらテストを行います。

1. テストファイルを確認します。

   extensions/music-generation-providers.live.test.ts

2. 以下のコマンドでテストを有効化します。

   OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

3. または、以下のハーネスを使用します。

   pnpm test:live:media music

4. このテストは、プロンプトのみの generate モードと、プロバイダーがサポートしている場合の edit モードの両方を実行します。
5. 必要に応じて、以下のオプションで対象を絞り込むことができます。

   OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
   OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"

6. プロファイルストアの認証を強制したい場合は以下を使用します。

   OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1

Video generation live

OpenClawのvideo generation機能は、実際のAPI環境で動作を確認するためのライブテストスイートを提供しています。この機能を利用することで、各プロバイダーの連携やリクエスト処理が正しく行われているかを検証できます。

1. テストの実行: extensions/video-generation-providers.live.test.ts
2. 有効化: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
3. ハーネスの利用: pnpm test:live:media video
4. スコープ:
   • 共有バンドルされたvideo-generationプロバイダーのパスを検証します。
   • デフォルトではリリース安全なスモークパスを使用します（非FALプロバイダー、プロバイダーごとに1つのtext-to-videoリクエスト、1秒のlobsterプロンプト、およびOPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS（デフォルト180000）によるプロバイダーごとの操作制限）。
   • FALはプロバイダー側のキュー遅延がリリース時間に影響するためデフォルトでスキップされます。明示的に実行するには--video-providers falまたはOPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"を渡してください。
   • プローブ前にログインシェル（~/.profile）からプロバイダーの環境変数を読み込みます。
   • デフォルトで保存された認証プロファイルよりもライブ/環境APIキーを優先するため、auth-profiles.json内の古いテストキーが実際のシェル認証情報を隠すことはありません。
   • 使用可能な認証/プロファイル/モデルがないプロバイダーはスキップされます。
   • デフォルトではgenerateのみを実行します。
   • OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1を設定すると、利用可能な場合に宣言された変換モードも実行されます：
     • プロバイダーがcapabilities.imageToVideo.enabledを宣言し、選択されたプロバイダー/モデルが共有スイープでバッファベースのローカル画像入力を受け入れる場合のimageToVideo。
     • プロバイダーがcapabilities.videoToVideo.enabledを宣言し、選択されたプロバイダー/モデルが共有スイープでバッファベースのローカルビデオ入力を受け入れる場合のvideoToVideo。
   • 共有スイープで現在宣言されているがスキップされているimageToVideoプロバイダー:
     • vydra（バンドルされているveo3はテキストのみであり、バンドルされているklingはリモート画像URLを必要とするため）。
   • プロバイダー固有のVydraカバレッジ:
     • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
     • このファイルはveo3のtext-to-videoに加え、デフォルトでリモート画像URLフィクスチャを使用するklingレーンを実行します。
   • 現在のvideoToVideoライブカバレッジ:
     • runway（選択されたモデルがrunway/gen4_alephの場合のみ）。
   • 共有スイープで現在宣言されているがスキップされているvideoToVideoプロバイダー:
     • alibaba、qwen、xai（これらのパスは現在リモートのhttp(s) / MP4参照URLを必要とするため）。
     • google（現在の共有Gemini/Veoレーンはローカルバッファベースの入力を使用しており、そのパスは共有スイープで受け入れられないため）。
     • openai（現在の共有レーンには組織固有のビデオinpaint/remixアクセスの保証がないため）。
5. オプションの絞り込み:
   • OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"
   • OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"
   • OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""（FALを含むすべてのプロバイダーをデフォルトスイープに含める場合）。
   • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000（各プロバイダーの操作制限を減らしてアグレッシブなスモークテストを行う場合）。
6. オプションの認証動作:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1（プロファイルストアの認証を強制し、環境変数のみのオーバーライドを無視する場合）。

Media live harness

Media live harnessは、OpenClawのメディア生成機能を一元的に管理・テストするための便利なツールです。複数のメディアタイプを効率的にテストしたい場合に最適です。

1. コマンド: pnpm test:live:media
2. 目的:
   • 画像、音楽、ビデオのライブスイートを1つのリポジトリネイティブなエントリーポイントから実行します。
   • ~/.profileから不足しているプロバイダーの環境変数を自動的に読み込みます。
   • デフォルトで現在使用可能な認証を持つプロバイダーに各スイートを自動的に絞り込みます。
   • scripts/test-live.mjsを再利用するため、ハートビートやquietモードの動作が一貫しています。
3. 使用例:
   • pnpm test:live:media
   • pnpm test:live:media image video --providers openai,google,minimax
   • pnpm test:live:media video --video-providers openai,runway --all-providers
   • pnpm test:live:media music --quiet

Docker ランナー (Linux での動作確認)

これらの Docker ランナーは、大きく分けて2つのカテゴリーに分類されます。

1. ライブモデルランナー：test:docker:live-models および test:docker:live-gateway は、リポジトリ内の Docker イメージを使用して、対応するプロファイルキーのライブファイル（src/agents/models.profiles.live.test.ts および src/gateway/gateway-models.profiles.live.test.ts）のみを実行します。この際、ローカルの構成ディレクトリとワークスペースがマウントされます（マウントされている場合は ~/.profile も読み込まれます）。対応するローカルのエントリポイントは test:live:models-profiles および test:live:gateway-profiles です。
2. Docker ライブランナーは、Docker 全体のスイープを実用的に保つため、デフォルトで小規模なスモークテスト上限が設定されています。test:docker:live-models はデフォルトで OPENCLAW_LIVE_MAX_MODELS=12 となり、test:docker:live-gateway はデフォルトで OPENCLAW_LIVE_GATEWAY_SMOKE=1、OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8、OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000、OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000 となります。より広範囲なスキャンを明示的に実行したい場合は、これらの環境変数を上書きしてください。
3. test:docker:all は test:docker:live-build を通じてライブ Docker イメージを一度ビルドし、それを2つのライブ Docker レーンで再利用します。
4. コンテナスモークランナー：test:docker:openwebui、test:docker:onboard、test:docker:gateway-network、test:docker:mcp-channels、および test:docker:plugins は、1つ以上の実際のコンテナを起動し、より上位レベルの統合パスを検証します。

ライブモデル Docker ランナーは、必要な CLI 認証ホームのみをバインドマウントし（実行範囲が絞られていない場合はサポートされているすべてのホームをマウント）、実行前にコンテナのホームディレクトリへコピーします。これにより、外部 CLI の OAuth がホスト側の認証ストアを変更することなくトークンを更新できるようになります。

• Direct models: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• ACP bind smoke: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh)
• CLI backend smoke: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Codex app-server harness smoke: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
• Gateway + dev agent: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Open WebUI live smoke: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Onboarding wizard (TTY, full scaffolding): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Gateway networking (two containers, WS auth + health): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Plugins (install smoke + /plugin alias + Claude-bundle restart semantics): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

ライブモデル Docker ランナーは、現在のチェックアウトを読み取り専用でバインドマウントし、コンテナ内の作業用ディレクトリへステージングします。これにより、ランタイムイメージを軽量に保ちつつ、ローカルの正確なソースや構成に対して Vitest を実行できます。ステージングのステップでは、.pnpm-store、.worktrees、__openclaw_vitest__、アプリローカルの .build や Gradle 出力ディレクトリなどの巨大なローカルキャッシュやビルド成果物をスキップするため、Docker ライブ実行でマシン固有のアーティファクトのコピーに時間を費やすことはありません。

また、OPENCLAW_SKIP_CHANNELS=1 が設定されるため、Gateway のライブプローブがコンテナ内で実際の Telegram や Discord などのチャンネルワーカーを起動することはありません。test:docker:live-models は引き続き pnpm test:live を実行するため、その Docker レーンから Gateway のライブカバレッジを除外または絞り込みたい場合は、OPENCLAW_LIVE_GATEWAY_* を渡してください。

test:docker:openwebui は上位レベルの互換性スモークテストです。これは、OpenAI 互換の HTTP エンドポイントを有効にした OpenClaw Gateway コンテナを起動し、その Gateway に対して固定された Open WebUI コンテナを起動します。Open WebUI を通じてサインインし、/api/models が openclaw/default を公開していることを確認した後、Open WebUI の /api/chat/completions プロキシを通じて実際のチャットリクエストを送信します。初回実行時は、Docker が Open WebUI イメージをプルする必要がある場合や、Open WebUI が独自のコールドスタート設定を完了させる必要があるため、動作が遅くなることがあります。このレーンは使用可能なライブモデルキーを必要とし、Docker 化された実行環境でキーを提供するための主な方法は OPENCLAW_PROFILE_FILE（デフォルトは ~/.profile）です。成功すると、{ "ok": true, "model": "openclaw/default", ... } のような小さな JSON ペイロードが出力されます。

test:docker:mcp-channels は決定論的であり、実際の Telegram、Discord、iMessage アカウントを必要としません。シード済みの Gateway コンテナを起動し、openclaw mcp serve を実行する2つ目のコンテナを立ち上げます。その後、ルーティングされた会話の検出、トランスクリプトの読み取り、添付ファイルのメタデータ、ライブイベントキューの動作、送信ルーティング、および実際の stdio API ブリッジを介した Claude スタイルのチャンネルと権限の通知を検証します。通知チェックは生の stdio API フレームを直接検査するため、特定クライアントの SDK が表面化させる内容だけでなく、ブリッジが実際に送信する内容を検証します。

手動による ACP 平文スレッドスモーク（CI 用ではありません）：

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• このスクリプトは回帰テストやデバッグワークフローのために保持してください。ACP スレッドルーティングの検証で再び必要になる可能性があるため、削除しないでください。

便利な環境変数：

• OPENCLAW_CONFIG_DIR=... (デフォルト: ~/.openclaw) → /home/node/.openclaw にマウント
• OPENCLAW_WORKSPACE_DIR=... (デフォルト: ~/.openclaw/workspace) → /home/node/.openclaw/workspace にマウント
• OPENCLAW_PROFILE_FILE=... (デフォルト: ~/.profile) → /home/node/.profile にマウントされ、テスト実行前に読み込まれます
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 → OPENCLAW_PROFILE_FILE から読み込まれた環境変数のみを検証します（一時的な構成/ワークスペースディレクトリを使用し、外部 CLI 認証マウントは行いません）
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (デフォルト: ~/.cache/openclaw/docker-cli-tools) → Docker 内のキャッシュされた CLI インストール用に /home/node/.npm-global にマウントされます
• $HOME 配下の外部 CLI 認証ディレクトリ/ファイルは /host-auth... に読み取り専用でマウントされ、テスト開始前に /home/node/... へコピーされます
  • デフォルトディレクトリ: .minimax
  • デフォルトファイル: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • プロバイダーを絞り込んだ実行では、OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS から推論された必要なディレクトリ/ファイルのみがマウントされます
  • OPENCLAW_DOCKER_AUTH_DIRS=all、OPENCLAW_DOCKER_AUTH_DIRS=none、またはカンマ区切りのリスト（例: OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex）で手動上書き可能です
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... → 実行範囲を絞り込みます
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... → コンテナ内のプロバイダーをフィルタリングします
• OPENCLAW_SKIP_DOCKER_BUILD=1 → 再ビルドが不要な場合に、既存の openclaw:local-live イメージを再利用します
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 → 認証情報が（環境変数ではなく）プロファイルストアから取得されることを保証します
• OPENCLAW_OPENWEBUI_MODEL=... → Open WebUI スモークテスト用に Gateway が公開するモデルを選択します
• OPENCLAW_OPENWEBUI_PROMPT=... → Open WebUI スモークテストで使用される nonce チェックプロンプトを上書きします
• OPENWEBUI_IMAGE=... → 固定された Open WebUI イメージタグを上書きします

ドキュメントの健全性チェック

ドキュメントを編集した後は、以下のコマンドでチェックを実行してください：pnpm check:docs。 ページ内の見出しチェックも必要な場合は、Mintlify のアンカー検証をフル実行してください：pnpm docs:check-links:anchors。

AI Setup Assistant

オフライン回帰テスト（CI-safe）

これらは、実際のプロバイダーを使用せずに「実際のパイプライン」を再現する回帰テストです。OpenClaw のオフライン回帰テストは、環境に依存せず安定した検証を可能にします。

1. Gateway ツール呼び出し（mock OpenAI、実際の Gateway + エージェントループを使用）：src/gateway/gateway.test.ts（ケース：「runs a mock OpenAI tool call end-to-end via gateway agent loop」）
2. Gateway ウィザード（WS wizard.start/wizard.next、設定の書き込み + 認証の強制）：src/gateway/gateway.test.ts（ケース：「runs wizard over ws and writes auth token config」）

src/gateway/gateway.test.ts

エージェントの信頼性評価（スキル）

私たちはすでに、エージェントの信頼性を評価するような「CI-safe」なテストをいくつか備えています。OpenClaw のエージェント信頼性評価を活用することで、複雑なタスクにおける挙動を事前に確認できます。

1. 実際の Gateway + エージェントループを通じたモックツール呼び出し（src/gateway/gateway.test.ts）。
2. セッションの接続と設定の影響を検証するエンドツーエンドのウィザードフロー（src/gateway/gateway.test.ts）。

スキル（Skills を参照）に関して、まだ不足している要素は以下の通りです。

1. 意思決定（Decisioning）: スキルがプロンプトにリストされている際、エージェントは適切なスキルを選択できているか（あるいは無関係なものを回避できているか）。
2. コンプライアンス（Compliance）: エージェントは使用前に SKILL.md を読み込み、必要なステップや引数に従っているか。
3. ワークフロー契約（Workflow contracts）: ツールの順序、セッション履歴の引き継ぎ、サンドボックスの境界をアサートするマルチターンのシナリオ。

将来的な評価は、まず決定論的なアプローチを維持すべきです。

1. モックプロバイダーを使用して、ツール呼び出しと順序、スキルファイルの読み込み、セッションの接続をアサートするシナリオランナー。
2. スキルに焦点を当てた小規模なシナリオスイート（使用 vs 回避、ゲーティング、プロンプトインジェクション）。
3. CI-safe スイートが整備された後にのみ導入される、オプションのライブ評価（オプトイン、環境変数で制御）。

Contract tests (plugin and channel shape)

Contract testsは、登録されたすべてのpluginやchannelが、定義されたインターフェースの契約に準拠しているかを検証するためのものです。これらは検出されたすべてのpluginを反復処理し、形状や動作に関する一連のアサーションを実行します。デフォルトの pnpm test ユニットレーンでは、これらの共有シームやsmokeファイルは意図的にスキップされるようになっています。共有channelやproviderの表面的な部分に変更を加えた際は、明示的にcontractコマンドを実行してください。

Commands

コマンドを実行することで、特定の契約テストを個別に、あるいは一括で実行できます。

1. すべての契約テストを実行: pnpm test:contracts
2. Channelの契約テストのみ実行: pnpm test:contracts:channels
3. Providerの契約テストのみ実行: pnpm test:contracts:plugins

Channel contracts

これらのテストは src/channels/plugins/contracts/*.contract.test.ts に配置されています。

1. plugin - 基本的なpluginの形状（id, name, capabilities）
2. setup - セットアップウィザードの契約
3. session-binding - セッションバインディングの動作
4. outbound-payload - メッセージのペイロード構造
5. inbound - インバウンドメッセージの処理
6. actions - Channelのアクションハンドラー
7. threading - スレッドIDの処理
8. directory - ディレクトリ/名簿 API
9. group-policy - グループポリシーの適用

Provider status contracts

これらのテストは src/plugins/contracts/*.contract.test.ts に配置されています。

1. status - Channelのステータスプローブ
2. registry - Pluginレジストリの形状

Provider contracts

これらのテストは src/plugins/contracts/*.contract.test.ts に配置されています。

1. auth - 認証フローの契約
2. auth-choice - 認証の選択肢
3. catalog - モデルカタログ API
4. discovery - Pluginの検出
5. loader - Pluginの読み込み
6. runtime - Providerのランタイム
7. shape - Pluginの形状/インターフェース
8. wizard - セットアップウィザード

When to run

以下のタイミングで実行してください。

1. plugin-sdkのexportsやサブパスを変更したとき
2. channelやproviderのpluginを追加・修正したとき
3. pluginの登録や検出の仕組みをリファクタリングしたとき

Contract testsは GitHub CI上で実行され、実際の API キーは必要ありません。

Adding regressions (guidance)

ライブ環境で発見されたproviderやモデルの問題を修正する際は、以下のガイドラインに従ってください。

1. 可能であれば、CIで安全に実行できるリグレッションテストを追加してください（providerのモック/スタブを使用するか、リクエスト形状の変換を正確にキャプチャします）。
2. レート制限や認証ポリシーなど、本質的にライブ環境でしか発生しない問題の場合は、ライブテストを限定的にし、環境変数経由でオプトインするようにしてください。
3. バグを捕捉できる最小限のレイヤーをターゲットにすることを推奨します。
   • providerのリクエスト変換やリプレイのバグ → 直接モデルのテスト
   • Gateway のセッション、履歴、ツールパイプラインのバグ → Gateway のライブsmokeテスト、またはCIで安全な Gateway モックテスト
4. SecretRefトラバーサルガードレールについて:
   • src/secrets/exec-secret-ref-id-parity.test.ts は、レジストリメタデータ（listSecretTargetRegistryEntries()）からSecretRefクラスごとにターゲットを1つサンプリングし、トラバーサルセグメントのexec idが拒否されることをアサートします。
   • src/secrets/target-registry-data.ts に新しい includeInPlan のSecretRefターゲットファミリーを追加した場合は、そのテスト内の classifyTargetClass を更新してください。このテストは未分類のターゲットIDに対して意図的に失敗するようになっており、新しいクラスが黙ってスキップされることを防いでいます。

pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>