テスト

OpenClaw には 3 つの Vitest スイート（ユニット/統合、e2e、ライブ）と小規模な Docker ランナー群があります。このドキュメントは「どのようにテストするか」のガイドです。

• 各スイートが何をカバーするか（そして意図的に何をカバーしないか）。
• 一般的なワークフロー（ローカル、プッシュ前、デバッグ）で実行するコマンド。
• ライブテストが認証情報を検出し、モデル/プロバイダーを選択する方法。
• 実際のモデル/プロバイダー問題に対するリグレッションを追加する方法。

クイックスタート

通常は次のとおりです。

• フルゲート（プッシュ前に期待されるもの）: pnpm build && pnpm check && pnpm check:test-types && pnpm test
• 余裕のあるマシンでの高速なローカルフルスイート実行: pnpm test:max
• 直接の Vitest ウォッチループ: pnpm test:watch
• 直接ファイル指定は、拡張機能/チャンネルパスにもルーティングされるようになりました: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• 単一の失敗を反復している場合は、まず対象を絞った実行を優先してください。
• Docker ベースの QA サイト: pnpm qa:lab:up
• Linux VM ベースの QA レーン: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

テストに触れた場合や追加の信頼性が必要な場合:

• カバレッジゲート: pnpm test:coverage
• E2E スイート: pnpm test:e2e

テスト一時ディレクトリ

テスト所有の一時ディレクトリには、test/helpers/temp-dir.ts の共有ヘルパーを優先してください。これらは所有権を明示し、同じテストライフサイクル内でクリーンアップを維持します。

  const tempDirs = useAutoCleanupTempDirTracker(afterEach); it("uses a temp workspace", () => {  const workspace = tempDirs.make("openclaw-example-");  // use workspace});

useAutoCleanupTempDirTracker(afterEach) は意図的に手動クリーンアップメソッドを公開していません。Vitest が各テスト後のクリーンアップを所有します。まだ移行していないテストのために既存の低レベルヘルパーは残っていますが、新規および移行済みのテストでは自動クリーンアップトラッカーを使うべきです。新しい手動の makeTempDir、cleanupTempDirs、または createTempDirTracker の使用は避け、テスト内で新たに裸の fs.mkdtemp* 呼び出しを追加することも避けてください。ただし、生の一時ディレクトリ挙動を明示的に検証するケースは例外です。テストが意図的に裸の一時ディレクトリを必要とする場合は、具体的な理由を含む監査可能な許可コメントを追加してください。

// openclaw-temp-dir: allow verifies raw fs cleanup behaviorconst workspace = fs.mkdtempSync(prefix);

移行の可視性のために、node scripts/report-test-temp-creations.mjs は追加された差分行における新しい裸の一時ディレクトリ作成と、新しい手動共有ヘルパー使用を報告しますが、既存のクリーンアップスタイルはブロックしません。そのファイルスコープは、別個のテストヘルパーファイル名ヒューリスティックを維持する代わりに、scripts/changed-lanes.mjs で使われている同じテストパス分類に意図的に従い、共有ヘルパー実装自体はスキップします。check:changed は変更されたテストパスに対してこのレポートを警告専用の CI シグナルとして実行します。検出結果は GitHub の警告アノテーションであり、失敗ではありません。

実際のプロバイダー/モデルをデバッグする場合（実際の認証情報が必要）:

• ライブスイート（モデル + Gateway ツール/画像プローブ）: pnpm test:live
• 1 つのライブファイルを静かに対象指定: pnpm test:live -- src/agents/models.profiles.live.test.ts
• ランタイムパフォーマンスレポート: 実際の openai/gpt-5.5 エージェントターンには live_openai_candidate=true を、Kova CPU/ヒープ/トレースアーティファクトには deep_profile=true を付けて OpenClaw Performance をディスパッチします。日次スケジュール実行は、CLAWGRIT_REPORTS_TOKEN が設定されている場合に、モックプロバイダー、ディーププロファイル、GPT 5.5 レーンのアーティファクトを openclaw/clawgrit-reports に公開します。モックプロバイダーレポートには、ソースレベルの Gateway 起動、メモリ、Plugin 負荷、反復 fake-model hello-loop、CLI 起動の数値も含まれます。
• Docker ライブモデルスイープ: pnpm test:docker:live-models
  • 選択された各モデルは、テキストターンに加えて小さなファイル読み取り風プローブを実行するようになりました。メタデータが image 入力を宣伝しているモデルでは、小さな画像ターンも実行します。プロバイダーの失敗を切り分けるときは、追加プローブを OPENCLAW_LIVE_MODEL_FILE_PROBE=0 または OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 で無効化してください。
  • CI カバレッジ: 日次の OpenClaw Scheduled Live And E2E Checks と手動の OpenClaw Release Checks はどちらも、include_live_suites: true で再利用可能なライブ/E2E ワークフローを呼び出します。これには、プロバイダー別にシャーディングされた個別の Docker ライブモデルマトリックスジョブが含まれます。
  • 集中的な CI 再実行には、include_live_suites: true と live_models_only: true を指定して OpenClaw Live And E2E Checks (Reusable) をディスパッチします。
  • 新しい高シグナルのプロバイダーシークレットは、scripts/ci-hydrate-live-auth.sh に加え、.github/workflows/openclaw-live-and-e2e-checks-reusable.yml とそのスケジュール/リリース呼び出し元に追加してください。
• ネイティブ Codex バインドチャットスモーク: pnpm test:docker:live-codex-bind
  • Codex app-server パスに対して Docker ライブレーンを実行し、/codex bind で合成 Slack DM をバインドし、/codex fast と /codex permissions を実行してから、プレーン返信と画像添付が ACP ではなくネイティブ Plugin バインディング経由でルーティングされることを検証します。
• Codex app-server ハーネススモーク: pnpm test:docker:live-codex-harness
  • Plugin 所有の Codex app-server ハーネスを通じて Gateway エージェントターンを実行し、 /codex status と /codex models を検証し、デフォルトでは画像、cron MCP、サブエージェント、Guardian プローブを実行します。他の Codex app-server 失敗を切り分ける場合は、OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 でサブエージェントプローブを無効化します。サブエージェントに集中したチェックでは、他のプローブを無効化してください: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness。 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 が設定されていない限り、これはサブエージェントプローブ後に終了します。
• Codex オンデマンドインストールスモーク: pnpm test:docker:codex-on-demand
  • パッケージ化された OpenClaw tarball を Docker にインストールし、OpenAI API キーのオンボーディングを実行し、Codex Plugin と @openai/codex 依存関係がオンデマンドで管理対象 npm プロジェクトルートにダウンロードされたことを検証します。
• ライブ Plugin ツール依存関係スモーク: pnpm test:docker:live-plugin-tool
  • 実際の slugify 依存関係を持つフィクスチャ Plugin をパックし、npm-pack: 経由でインストールし、管理対象 npm プロジェクトルート配下の依存関係を検証してから、ライブ OpenAI モデルに Plugin ツールを呼び出して隠された slug を返すよう要求します。
• Crestodian レスキューコマンドスモーク: pnpm test:live:crestodian-rescue-channel
  • メッセージチャンネルのレスキューコマンドサーフェスに対するオプトインの二重確認チェックです。/crestodian status を実行し、永続的なモデル変更をキューに入れ、/crestodian yes と返信し、監査/設定書き込みパスを検証します。
• Crestodian プランナー Docker スモーク: pnpm test:docker:crestodian-planner
  • PATH 上に偽の Claude CLI を置いた設定なしコンテナーで Crestodian を実行し、ファジープランナーフォールバックが監査済みの型付き設定書き込みへ変換されることを検証します。
• Crestodian 初回実行 Docker スモーク: pnpm test:docker:crestodian-first-run
  • 空の OpenClaw 状態ディレクトリから開始し、最新のオンボード Crestodian エントリーポイントを検証し、セットアップ/モデル/エージェント/Discord Plugin + SecretRef 書き込みを適用し、設定を検証し、監査エントリを検証します。同じ Ring 0 セットアップパスは QA Lab でも pnpm openclaw qa suite --scenario crestodian-ring-zero-setup によりカバーされています。
• Moonshot/Kimi コストスモーク: MOONSHOT_API_KEY を設定した状態で openclaw models list --provider moonshot --json を実行し、その後 moonshot/kimi-k2.6 に対して分離された openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json を実行します。JSON が Moonshot/K2.6 を報告し、アシスタントトランスクリプトが正規化された usage.cost を保存していることを確認してください。

QA 固有ランナー

これらのコマンドは、QA-lab の現実性が必要なときにメインのテストスイートの隣で使います。

CI は専用ワークフローで QA Lab を実行します。エージェント型パリティはスタンドアロンの PR ワークフローではなく、 QA-Lab - All Lanes とリリース検証の下にネストされています。広範な検証には、rerun_group=qa-parity またはリリースチェックの QA グループを指定した Full Release Validation を使うべきです。安定版/デフォルトのリリースチェックでは、網羅的なライブ/Docker ソークは run_release_soak=true の背後に置かれます。 full プロファイルはソークを強制的に有効化します。QA-Lab - All Lanes は main で毎晩、および手動ディスパッチから、モックパリティレーン、ライブ Matrix レーン、Convex 管理のライブ Telegram レーン、Convex 管理のライブ Discord レーンを並列ジョブとして実行します。スケジュール済み QA とリリースチェックは Matrix に明示的に --profile fast を渡しますが、Matrix CLI と手動ワークフロー入力のデフォルトは all のままです。手動ディスパッチでは all を transport、 media、e2ee-smoke、e2ee-deep、e2ee-cli ジョブへシャーディングできます。OpenClaw Release Checks はリリース承認前にパリティに加えて高速 Matrix と Telegram レーンを実行し、リリーストランスポートチェックには mock-openai/gpt-5.5 を使うため、決定論的に保たれ、通常のプロバイダー Plugin 起動を回避できます。これらのライブトランスポート Gateway はメモリ検索を無効化します。メモリ挙動は引き続き QA パリティスイートでカバーされます。

フルリリースのライブメディアシャードでは ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04 を使います。これにはすでに ffmpeg と ffprobe が含まれています。Docker ライブモデル/バックエンドシャードは、選択されたコミットごとに一度だけビルドされる共有 ghcr.io/openclaw/openclaw-live-test:<sha> イメージを使い、各シャード内で再ビルドする代わりに OPENCLAW_SKIP_DOCKER_BUILD=1 でそれをプルします。

• pnpm openclaw qa suite
  • リポジトリに裏付けられた QA シナリオをホスト上で直接実行します。
  • 選択されたシナリオセットについて、mixed flow、Vitest、Playwright のシナリオ選択を含む、トップレベルの qa-evidence.json、qa-suite-summary.json、および qa-suite-report.md アーティファクトを書き込みます。
  • pnpm openclaw qa run --qa-profile <profile> によってディスパッチされた場合、選択された分類プロファイルのスコアカードを同じ qa-evidence.json に埋め込みます。 smoke-ci はスリムなエビデンスを書き込み、evidenceMode: "slim" を設定して、各エントリの execution を省略します。release は厳選されたリリース準備状況の範囲を対象にします。 all はすべてのアクティブな成熟度カテゴリを選択し、完全なスコアカードアーティファクトが必要な場合に明示的な QA Profile Evidence ワークフローディスパッチで使うことを意図しています。
  • デフォルトでは、分離された gateway ワーカーを使って、選択された複数のシナリオを並列実行します。qa-channel のデフォルト並列数は 4 です（選択されたシナリオ数によって上限があります）。ワーカー数を調整するには --concurrency <count> を使い、従来の直列レーンには --concurrency 1 を使います。
  • いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしでアーティファクトが必要な場合は --allow-failures を使います。
  • provider モード live-frontier、mock-openai、および aimock をサポートします。 aimock は、シナリオを認識する mock-openai レーンを置き換えずに、実験的な fixture とプロトコルモックのカバレッジのために、ローカルの AIMock ベース provider サーバーを起動します。
• pnpm openclaw qa coverage --match <query>
  • シナリオ ID、タイトル、surface、カバレッジ ID、docs refs、code refs、plugins、provider 要件を検索し、一致する suite target を出力します。
  • 変更対象の挙動またはファイルパスは分かっているが、最小のシナリオが分からない場合、QA Lab 実行の前にこれを使います。これは助言のみです。変更される挙動に基づいて、mock、live、Multipass、Matrix、または transport proof を選択してください。
• pnpm test:plugins:kitchen-sink-live
  • QA Lab を通じて、ライブ OpenAI Kitchen Sink Plugin ガントレットを実行します。外部 Kitchen Sink パッケージをインストールし、plugin SDK surface inventory を検証し、/healthz と /readyz をプローブし、gateway CPU/RSS エビデンスを記録し、ライブ OpenAI turn を実行し、敵対的診断を確認します。 OPENAI_API_KEY などのライブ OpenAI 認証が必要です。hydrated Testbox セッションでは、openclaw-testbox-env ヘルパーが存在する場合、Testbox live-auth プロファイルを自動的に source します。
• pnpm test:gateway:cpu-scenarios
  • gateway 起動ベンチに加えて、小さな mock QA Lab シナリオパック（channel-chat-baseline、memory-failure-fallback、 gateway-restart-inflight-run）を実行し、結合された CPU 観測サマリーを .artifacts/gateway-cpu-scenarios/ 配下に書き込みます。
  • デフォルトでは継続的な高 CPU 観測のみをフラグします（--cpu-core-warn と --hot-wall-warn-ms）。そのため、短い起動バーストは、数分続く gateway 固着リグレッションのようには見えず、メトリクスとして記録されます。
  • ビルド済みの dist アーティファクトを使います。チェックアウトに新しいランタイム出力がまだない場合は、先にビルドを実行してください。
• pnpm openclaw qa suite --runner multipass
  • 使い捨ての Multipass Linux VM 内で同じ QA suite を実行します。
  • ホスト上の qa suite と同じシナリオ選択挙動を維持します。
  • qa suite と同じ provider/model 選択フラグを再利用します。
  • ライブ実行では、ゲストに実用的なサポート対象 QA 認証入力を転送します。env ベースの provider キー、QA live provider config パス、および存在する場合の CODEX_HOME です。
  • 出力ディレクトリは repo root 配下に維持する必要があります。これにより、ゲストはマウントされたワークスペースを通じて書き戻せます。
  • 通常の QA レポートとサマリーに加え、Multipass ログを .artifacts/qa-e2e/... 配下に書き込みます。
• pnpm qa:lab:up
  • オペレーター形式の QA 作業向けに、Docker ベースの QA サイトを起動します。
• pnpm test:docker:npm-onboard-channel-agent
  • 現在のチェックアウトから npm tarball をビルドし、Docker 内でグローバルにインストールし、非対話型の OpenAI API キーオンボーディングを実行し、デフォルトで Telegram を設定し、パッケージ化された Plugin ランタイムが起動時の依存関係修復なしで読み込まれることを検証し、doctor を実行し、mock OpenAI endpoint に対してローカル agent turn を 1 回実行します。
  • Discord で同じパッケージ化インストールレーンを実行するには、OPENCLAW_NPM_ONBOARD_CHANNEL=discord を使います。
• pnpm test:docker:session-runtime-context
  • 埋め込みランタイムコンテキスト transcript 向けに、決定的なビルド済みアプリ Docker smoke を実行します。hidden OpenClaw runtime context が、表示される user turn に漏れる代わりに、非表示の custom message として永続化されることを検証します。その後、影響を受ける壊れた session JSONL を seed し、openclaw doctor --fix がそれをバックアップ付きで active branch に書き換えることを検証します。
• pnpm test:docker:npm-telegram-live
  • OpenClaw パッケージ候補を Docker にインストールし、インストール済みパッケージのオンボーディングを実行し、インストール済み CLI を通じて Telegram を設定し、その後、そのインストール済みパッケージを SUT Gateway としてライブ Telegram QA レーンを再利用します。
  • wrapper はチェックアウトから qa-lab harness source のみをマウントします。インストール済みパッケージが dist、openclaw/plugin-sdk、および bundled Plugin ランタイムを所有するため、このレーンは現在のチェックアウトの plugins をテスト対象パッケージに混在させません。
  • デフォルトは OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta です。registry からインストールする代わりに、解決済みのローカル tarball をテストするには、OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz または OPENCLAW_CURRENT_PACKAGE_TGZ を設定します。
  • デフォルトでは OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20 により、反復 RTT タイミングを qa-evidence.json に出力します。RTT 実行を調整するには、 OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES、 OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS、または OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES を上書きします。 OPENCLAW_NPM_TELEGRAM_RTT_CHECKS は、サンプリングする Telegram QA check ID のカンマ区切りリストを受け付けます。未設定の場合、デフォルトの RTT 対応 check は telegram-mentioned-message-reply です。
  • pnpm openclaw qa telegram と同じ Telegram env 認証情報または Convex credential source を使います。CI/リリース自動化では、 OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex に加えて、 OPENCLAW_QA_CONVEX_SITE_URL と role secret を設定します。 OPENCLAW_QA_CONVEX_SITE_URL と Convex role secret が CI に存在する場合、Docker wrapper は Convex を自動的に選択します。
  • wrapper は、Docker build/install 作業の前に、ホスト上で Telegram または Convex credential env を検証します。pre-credential setup を意図的にデバッグする場合にのみ、OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 を設定します。
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer は、このレーンでのみ共有の OPENCLAW_QA_CREDENTIAL_ROLE を上書きします。Convex credentials が選択され、role が設定されていない場合、wrapper は CI では ci を使い、CI 外では maintainer を使います。
  • GitHub Actions は、このレーンを手動 maintainer ワークフロー NPM Telegram Beta E2E として公開します。merge 時には実行されません。このワークフローは qa-live-shared environment と Convex CI credential lease を使います。
• GitHub Actions は、1 つの候補パッケージに対するサイド実行の product proof として Package Acceptance も公開します。trusted ref、公開済み npm spec、HTTPS tarball URL と SHA-256、または別の実行からの tarball artifact を受け付け、正規化された openclaw-current.tgz を package-under-test としてアップロードし、その後、smoke、package、product、full、または custom lane profile で既存の Docker E2E scheduler を実行します。同じ package-under-test artifact に対して Telegram QA workflow を実行するには、telegram_mode=mock-openai または live-frontier を設定します。
  • 最新 beta product proof:

gh workflow run package-acceptance.yml --ref main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=product \  -f telegram_mode=mock-openai

• 正確な tarball URL proof には digest が必要で、public URL safety policy を使います:

gh workflow run package-acceptance.yml --ref main \  -f source=url \  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

• Enterprise/private tarball mirror は、明示的な trusted-source policy を使います:

gh workflow run package-acceptance.yml --ref main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

source=trusted-url は trusted workflow ref から .github/package-trusted-sources.json を読み取り、URL credentials や workflow-input private-network bypass を受け付けません。指定された policy が bearer auth を宣言している場合は、固定の OPENCLAW_TRUSTED_PACKAGE_TOKEN secret を設定します。

• Artifact proof は、別の Actions run から tarball artifact をダウンロードします:

gh workflow run package-acceptance.yml --ref main \  -f source=artifact \  -f artifact_run_id=<run-id> \  -f artifact_name=<artifact-name> \  -f suite_profile=smoke

• pnpm test:docker:plugins

  • 現在の OpenClaw build を Docker 内で pack および install し、OpenAI が設定された Gateway を起動してから、config edits を通じて bundled channel/plugins を有効化します。
  • setup discovery が未設定の downloadable plugins を存在しないままにすること、最初の configured doctor repair が欠落している各 downloadable Plugin を明示的にインストールすること、2 回目の restart で隠れた dependency repair が実行されないことを検証します。
  • 既知の古い npm baseline もインストールし、openclaw update --tag <candidate> を実行する前に Telegram を有効化し、候補の post-update doctor が harness-side postinstall repair なしで legacy Plugin dependency debris をクリーンにすることを検証します。

• pnpm test:parallels:npm-update

  • Parallels guest 全体で、native packaged-install update smoke を実行します。選択された各 platform は、まず要求された baseline package をインストールし、その後同じ guest 内でインストール済みの openclaw update コマンドを実行し、インストール済み version、update status、gateway readiness、およびローカル agent turn を 1 回検証します。

  • 1 つの guest で反復作業する場合は、--platform macos、--platform windows、または --platform linux を使います。summary artifact path と per-lane status には --json を使います。

  • OpenAI レーンは、デフォルトで live agent-turn proof に openai/gpt-5.5 を使います。別の OpenAI model を意図的に検証する場合は、--model <provider/model> を渡すか、OPENCLAW_PARALLELS_OPENAI_MODEL を設定します。

  • Parallels transport stall が残りのテスト時間を消費しないように、長いローカル実行を host timeout でラップします:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --jsontimeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json

  • script は nested lane log を /tmp/openclaw-parallels-npm-update.* 配下に書き込みます。outer wrapper がハングしていると判断する前に、windows-update.log、macos-update.log、または linux-update.log を確認してください。

  • Windows update は、cold guest では post-update doctor と package update 作業に 10 分から 15 分かかることがあります。nested npm debug log が進んでいる場合、それは正常です。

  • この aggregate wrapper を、個別の Parallels macOS、Windows、または Linux smoke lane と並列に実行しないでください。これらは VM state を共有しており、snapshot restore、package serving、または guest gateway state で衝突する可能性があります。

  • post-update proof は通常の bundled Plugin surface を実行します。speech、image generation、media understanding などの capability facade は、agent turn 自体が単純な text response だけを確認する場合でも、bundled runtime API を通じて読み込まれるためです。

• pnpm openclaw qa aimock

  • 直接プロトコルのスモークテスト用に、ローカル AIMock プロバイダーサーバーだけを起動します。

• pnpm openclaw qa matrix

  • 使い捨ての Docker-backed Tuwunel homeserver に対して Matrix ライブ QA レーンを実行します。ソースチェックアウト専用です - パッケージ化されたインストールには qa-lab は含まれません。
  • 完全な CLI、プロファイル/シナリオカタログ、環境変数、アーティファクトレイアウト: Matrix QA.

• 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 をサポートします。デフォルトでは env モードを使用するか、OPENCLAW_QA_CREDENTIAL_SOURCE=convex を設定してプールされたリースを明示的に使用します。
  • デフォルトは canary、mention gating、コマンド指定、/status、ボット間のメンション付き返信、コアのネイティブコマンド返信をカバーします。mock-openai のデフォルトは、決定的な返信チェーンと Telegram final-message ストリーミング回帰もカバーします。session_status などの任意プローブには --list-scenarios を使用します。
  • いずれかのシナリオが失敗すると非ゼロで終了します。失敗終了コードなしでアーティファクトが必要な場合は --allow-failures を使用します。
  • 同じ非公開グループ内に 2 つの異なるボットが必要で、SUT ボットは Telegram ユーザー名を公開している必要があります。
  • 安定したボット間観測のため、両方のボットで @BotFather の Bot-to-Bot Communication Mode を有効にし、ドライバーボットがグループ内のボットトラフィックを観測できるようにします。
  • Telegram QA レポート、サマリー、qa-evidence.json を .artifacts/qa-e2e/... 配下に書き込みます。返信シナリオには、ドライバーの送信リクエストから観測された SUT 返信までの RTT が含まれます。

Mantis Telegram Live は、このレーンをラップする PR エビデンス用ラッパーです。候補 ref を Convex でリースされた Telegram 認証情報で実行し、墨消し済み QA レポート/エビデンスバンドルを Crabbox デスクトップブラウザーでレンダリングし、MP4 エビデンスを記録し、モーションをトリムした GIF を生成し、アーティファクトバンドルをアップロードし、pr_number が設定されている場合は Mantis GitHub App 経由でインライン PR エビデンスを投稿します。メンテナーは Actions UI の Mantis Scenario (scenario_id: telegram-live) から、または pull request コメントから直接開始できます。

@openclaw-mantis telegram@openclaw-mantis telegram scenario=telegram-status-command@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

Mantis Telegram Desktop Proof は、PR の視覚的 proof のためのエージェント型ネイティブ Telegram Desktop before/after ラッパーです。Actions UI で自由形式の instructions を指定して、Mantis Scenario (scenario_id: telegram-desktop-proof) から、または PR コメントから開始します。

@openclaw-mantis telegram desktop proof

Mantis エージェントは PR を読み、どの Telegram で見える挙動が変更を証明するかを判断し、baseline ref と candidate ref で実ユーザー Crabbox Telegram Desktop proof レーンを実行し、ネイティブ GIF が有用になるまで反復し、ペアの motionPreview マニフェストを書き込み、pr_number が設定されている場合は Mantis GitHub App 経由で同じ 2 列 GIF テーブルを投稿します。

• pnpm openclaw qa mantis telegram-desktop-builder
  • Crabbox Linux デスクトップをリースまたは再利用し、ネイティブ Telegram Desktop をインストールし、リースされた Telegram SUT ボットトークンで OpenClaw を設定し、gateway を起動し、表示されている VNC デスクトップからスクリーンショット/MP4 エビデンスを記録します。
  • ワークフローが Convex broker シークレットだけを必要とするように、デフォルトは --credential-source convex です。pnpm openclaw qa telegram と同じ OPENCLAW_QA_TELEGRAM_* 変数で --credential-source env を使用します。
  • Telegram Desktop には引き続きユーザーログイン/プロファイルが必要です。ボットトークンは OpenClaw のみを設定します。base64 .tgz プロファイルアーカイブには --telegram-profile-archive-env <name> を使用するか、--keep-lease を使用して一度 VNC 経由で手動ログインします。
  • 出力ディレクトリ配下に mantis-telegram-desktop-builder-report.md、mantis-telegram-desktop-builder-summary.json、telegram-desktop-builder.png、telegram-desktop-builder.mp4 を書き込みます。

ライブ transport レーンは標準契約を 1 つ共有するため、新しい transport が乖離しません。レーンごとのカバレッジマトリクスは QA 概要 → ライブ transport カバレッジ にあります。qa-channel は広範な合成スイートであり、そのマトリクスの一部ではありません。

Convex 経由の共有 Telegram 認証情報 (v1)

ライブ transport QA で --credential-source convex (または OPENCLAW_QA_CREDENTIAL_SOURCE=convex) が有効な場合、QA lab は Convex-backed pool から排他的リースを取得し、レーンの実行中にそのリースへ Heartbeat を送り、シャットダウン時にリースを解放します。セクション名は Discord、Slack、WhatsApp サポートより前からあるものです。リース契約は kind 間で共有されます。

参考 Convex プロジェクトスキャフォールド:

• qa/convex-credential-broker/

必須環境変数:

• OPENCLAW_QA_CONVEX_SITE_URL (例: https://your-deployment.convex.site)
• 選択したロール用のシークレット 1 つ:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER は maintainer 用
  • OPENCLAW_QA_CONVEX_SECRET_CI は ci 用
• 認証情報ロール選択:
  • CLI: --credential-role maintainer|ci
  • 環境変数のデフォルト: OPENCLAW_QA_CREDENTIAL_ROLE (CI では ci、それ以外では maintainer がデフォルト)

任意の環境変数:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (デフォルト 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (デフォルト 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (デフォルト 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (デフォルト 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (デフォルト /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (任意のトレース ID)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 は、ローカル専用開発のために loopback http:// Convex URL を許可します。

通常運用では、OPENCLAW_QA_CONVEX_SITE_URL は https:// を使用するべきです。

メンテナー管理コマンド (pool add/remove/list) には、特に OPENCLAW_QA_CONVEX_SECRET_MAINTAINER が必要です。

メンテナー向け CLI ヘルパー:

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

ライブ実行の前に doctor を使用して、シークレット値を出力せずに Convex site URL、broker シークレット、endpoint prefix、HTTP timeout、admin/list 到達性を確認します。スクリプトと CI ユーティリティで機械可読出力が必要な場合は --json を使用します。

デフォルトエンドポイント契約 (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • リクエスト: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • 成功: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • 枯渇/再試行可能: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • リクエスト: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • 成功: { status: "ok", index, data }
• POST /heartbeat
  • リクエスト: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • 成功: { status: "ok" } (または空の 2xx)
• POST /release
  • リクエスト: { kind, ownerId, actorRole, credentialId, leaseToken }
  • 成功: { status: "ok" } (または空の 2xx)
• POST /admin/add (メンテナーシークレットのみ)
  • リクエスト: { kind, actorId, payload, note?, status? }
  • 成功: { status: "ok", credential }
• POST /admin/remove (メンテナーシークレットのみ)
  • リクエスト: { credentialId, actorId }
  • 成功: { status: "ok", changed, credential }
  • アクティブリースガード: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (メンテナーシークレットのみ)
  • リクエスト: { kind?, status?, includePayload?, limit? }
  • 成功: { status: "ok", credentials, count }

Telegram kind の payload 形状:

• { groupId: string, driverToken: string, sutToken: string }
• groupId は数値の Telegram チャット ID 文字列である必要があります。
• admin/add は kind: "telegram" に対してこの形状を検証し、不正な payload を拒否します。

Telegram real-user kind の payload 形状:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId、testerUserId、telegramApiId は数値文字列である必要があります。
• tdlibArchiveSha256 と desktopTdataArchiveSha256 は SHA-256 hex 文字列である必要があります。
• kind: "telegram-user" は Mantis Telegram Desktop proof ワークフロー用に予約されています。汎用 QA Lab レーンはこれを取得してはいけません。

broker が検証するマルチチャンネル payload:

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Slack レーンも pool からリースできますが、Slack payload 検証は現在 broker ではなく Slack QA runner にあります。Slack 行には { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string } を使用します。

QA へのチャンネル追加

新しいチャンネルアダプターのアーキテクチャとシナリオヘルパー名は QA 概要 → チャンネルの追加 にあります。最低要件は、共有 qa-lab host seam 上に transport runner を実装し、Plugin マニフェストで qaRunners を宣言し、openclaw qa <runner> としてマウントし、qa/scenarios/ 配下にシナリオを作成することです。

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

スイートは「リアリズムが増す」(そして flakiness/コストも増す) ものと考えてください。

ユニット / 統合 (デフォルト)

• コマンド: pnpm test
• 設定: ターゲット指定なしの実行は vitest.full-*.config.ts shard セットを使用し、並列スケジューリングのためにマルチプロジェクト shard をプロジェクト別 config に展開する場合があります
• ファイル: src/**/*.test.ts、packages/**/*.test.ts、test/**/*.test.ts 配下のコア/ユニットインベントリ。UI ユニットテストは専用の unit-ui shard で実行されます
• スコープ:
  • 純粋なユニットテスト
  • インプロセス統合テスト (gateway auth、routing、tooling、parsing、config)
  • 既知のバグに対する決定的な回帰
• 期待事項:
  • CI で実行されます
  • 実際のキーは不要です
  • 高速かつ安定しているべきです
  • Resolver と public-surface loader テストは、実際の bundled plugin ソース API ではなく、生成された小さな plugin fixture で広範な api.js と runtime-api.js の fallback 挙動を証明する必要があります。実際の plugin API ロードは plugin 所有の契約/統合スイートに属します。

ネイティブ依存関係ポリシー:

• デフォルトのテストインストールでは、任意のネイティブ Discord opus ビルドをスキップします。Discord voice は bundled libopus-wasm を使用し、@discordjs/opus は allowBuilds で無効のままにするため、ローカルテストと Testbox レーンでネイティブ addon をコンパイルしません。
• ネイティブ opus の性能比較は、デフォルトの OpenClaw install/test ループではなく、libopus-wasm ベンチマークリポジトリで行ってください。デフォルトの allowBuilds で @discordjs/opus を true に設定しないでください。無関係な install/test ループでネイティブコードがコンパイルされます。

Stability（gateway）

• Command: pnpm test:stability:gateway
• Config: vitest.gateway.config.ts、1 worker に強制
• Scope:
  • diagnostics をデフォルトで有効にした実際の loopback Gateway を起動します
  • synthetic gateway message、memory、large-payload churn を diagnostic event path に通します
  • Gateway WS RPC 経由で diagnostics.stability を query します
  • diagnostic stability bundle persistence helpers をカバーします
  • recorder が bounded のままであること、synthetic RSS samples が pressure budget 未満に留まること、per-session queue depths がゼロまで drain することを assert します
• Expectations:
  • CI-safe かつ keyless
  • stability-regression follow-up 向けの狭い lane であり、完全な Gateway suite の代替ではありません

E2E（repo aggregate）

• Command: pnpm test:e2e
• Scope:
  • gateway smoke E2E lane を実行します
  • mocked Control UI browser E2E lane を実行します
• Expectations:
  • CI-safe かつ keyless
  • Playwright Chromium がインストールされている必要があります

E2E（gateway smoke）

• Command: pnpm test:e2e:gateway
• Config: vitest.e2e.config.ts
• Files: src/**/*.e2e.test.ts、test/**/*.e2e.test.ts、および extensions/ 配下の bundled-plugin E2E tests
• Runtime defaults:
  • リポジトリの他の部分と同様に、Vitest threads を isolate: false で使います。
  • adaptive workers を使います（CI: 最大 2、local: デフォルトで 1）。
  • console I/O overhead を減らすため、デフォルトでは silent mode で実行します。
• Useful overrides:
  • worker count を強制するには OPENCLAW_E2E_WORKERS=<n>（上限 16）。
  • verbose console output を再度有効にするには OPENCLAW_E2E_VERBOSE=1。
• Scope:
  • multi-instance gateway の end-to-end 挙動
  • WebSocket/HTTP surfaces、node pairing、より重い networking
• Expectations:
  • CI で実行されます（pipeline で有効な場合）
  • 実際の keys は不要です
  • unit tests より moving parts が多いです（遅くなる場合があります）

E2E（Control UI mocked browser）

• Command: pnpm test:ui:e2e
• Config: test/vitest/vitest.ui-e2e.config.ts
• Files: ui/src/**/*.e2e.test.ts
• Scope:
  • Vite Control UI を起動します
  • Playwright 経由で実際の Chromium page を操作します
  • Gateway WebSocket を決定論的な in-browser mocks に置き換えます
• Expectations:
  • pnpm test:e2e の一部として CI で実行されます
  • 実際の Gateway、agents、provider keys は不要です
  • browser dependency が存在している必要があります（pnpm --dir ui exec playwright install chromium）

E2E: OpenShell backend smoke

• Command: pnpm test:e2e:openshell
• File: extensions/openshell/src/backend.e2e.test.ts
• Scope:
  • active な local OpenShell gateway を再利用します
  • temporary local Dockerfile から sandbox を作成します
  • 実際の sandbox ssh-config + SSH exec 経由で OpenClaw の OpenShell backend を exercise します
  • sandbox fs bridge を通じて remote-canonical filesystem behavior を検証します
• Expectations:
  • opt-in のみ。デフォルトの pnpm test:e2e 実行には含まれません
  • local openshell CLI と、動作する Docker daemon が必要です
  • active な local OpenShell gateway とその config source が必要です
  • isolated HOME / XDG_CONFIG_HOME を使い、その後 test sandbox を破棄します
• Useful overrides:
  • broader e2e suite を手動で実行するときに test を有効にするには OPENCLAW_E2E_OPENSHELL=1
  • non-default CLI binary または wrapper script を指すには OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell
  • registered gateway config を isolated test に公開するには OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config
  • host policy fixture が使う Docker gateway IP を override するには OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1

Live（real providers + real models）

• コマンド: pnpm test:live
• 設定: vitest.live.config.ts
• ファイル: src/**/*.live.test.ts、test/**/*.live.test.ts、および extensions/ 配下のバンドル済み Plugin ライブテスト
• デフォルト: pnpm test:live により有効（OPENCLAW_LIVE_TEST=1 を設定）
• スコープ:
  • 「このプロバイダー/モデルは、実際の認証情報で today 本当に動作するか？」
  • プロバイダーのフォーマット変更、ツール呼び出しの癖、認証の問題、レート制限の挙動を検出する
• 期待値:
  • 設計上、CI で安定しない（実ネットワーク、実プロバイダーポリシー、クォータ、障害）
  • 費用がかかる / レート制限を消費する
  • 「すべて」を実行するのではなく、絞り込んだサブセットの実行を推奨
• ライブ実行では、すでにエクスポート済みの API キーとステージ済みの認証プロファイルを使用する。
• デフォルトでは、ライブ実行でも HOME を分離し、設定/認証素材を一時テストホームにコピーするため、ユニットフィクスチャが実際の ~/.openclaw を変更することはない。
• ライブテストで意図的に実際のホームディレクトリを使う必要がある場合にのみ、OPENCLAW_LIVE_USE_REAL_HOME=1 を設定する。
• pnpm test:live はデフォルトで静かなモードになる。[live] ... の進捗出力は保持し、Gateway のブートストラップログ/Bonjour の雑音はミュートする。完全な起動ログを戻したい場合は OPENCLAW_LIVE_TEST_QUIET=0 を設定する。
• API キーのローテーション（プロバイダー固有）: カンマ/セミコロン形式の *_API_KEYS または *_API_KEY_1、*_API_KEY_2（例: OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS）を設定するか、OPENCLAW_LIVE_*_KEY によるライブごとの上書きを設定する。テストはレート制限レスポンスで再試行する。
• 進捗/Heartbeat 出力:
  • ライブスイートは stderr に進捗行を出力するようになったため、Vitest のコンソールキャプチャが静かな場合でも、長いプロバイダー呼び出しが動作中であることが見える。
  • vitest.live.config.ts は Vitest のコンソールインターセプトを無効化し、ライブ実行中にプロバイダー/Gateway の進捗行が即時にストリームされるようにする。
  • 直接モデルの Heartbeat は OPENCLAW_LIVE_HEARTBEAT_MS で調整する。
  • Gateway/プローブの Heartbeat は OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS で調整する。

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

この判断表を使用する:

• ロジック/テストを編集する場合: pnpm test を実行する（多くを変更した場合は pnpm test:coverage も）
• Gateway ネットワーク / WS プロトコル / ペアリングに触れる場合: pnpm test:e2e を追加する
• 「自分のボットが落ちている」/ プロバイダー固有の失敗 / ツール呼び出しをデバッグする場合: 絞り込んだ pnpm test:live を実行する

ライブ（ネットワークに触れる）テスト

ライブモデルマトリクス、CLI バックエンド smoke、ACP smoke、Codex app-server ハーネス、およびすべてのメディアプロバイダーのライブテスト（Deepgram、BytePlus、ComfyUI、画像、 音楽、動画、メディアハーネス）- さらにライブ実行の認証情報処理については - ライブスイートのテストを参照。専用の更新と Plugin 検証チェックリストについては、 更新と Plugin のテストを参照。

Docker ランナー（任意の「Linux で動作する」チェック）

これらの Docker ランナーは 2 つの区分に分かれる:

• ライブモデルランナー: test:docker:live-models と test:docker:live-gateway は、リポジトリの Docker イメージ内で、それぞれ一致するプロファイルキーのライブファイル（src/agents/models.profiles.live.test.ts と src/gateway/gateway-models.profiles.live.test.ts）だけを実行し、ローカル設定ディレクトリ、ワークスペース、任意のプロファイル env ファイルをマウントする。一致するローカルエントリポイントは test:live:models-profiles と test:live:gateway-profiles。
• Docker ライブランナーは、必要に応じて独自の実用的な上限を維持する: test:docker:live-models は、キュレーション済みのサポート対象でシグナルの高いセットをデフォルトとし、 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 をデフォルトとする。明示的に上限を小さくしたり、より大きなスキャンを行いたい場合は、OPENCLAW_LIVE_MAX_MODELS または Gateway の env var を設定する。
• test:docker:all は test:docker:live-build でライブ Docker イメージを一度ビルドし、scripts/package-openclaw-for-docker.mjs を通じて OpenClaw を npm tarball として一度パックしてから、2 つの scripts/e2e/Dockerfile イメージをビルド/再利用する。bare イメージは install/update/plugin-dependency レーン用の Node/Git ランナーのみであり、これらのレーンは事前ビルド済み tarball をマウントする。functional イメージは、ビルド済みアプリ機能レーン用に同じ tarball を /app にインストールする。Docker レーン定義は scripts/lib/docker-e2e-scenarios.mjs にあり、プランナーロジックは scripts/lib/docker-e2e-plan.mjs にあり、scripts/test-docker-all.mjs が選択された計画を実行する。集約は重み付きローカルスケジューラーを使用する。OPENCLAW_DOCKER_ALL_PARALLELISM はプロセススロットを制御し、リソース上限は重いライブ、npm-install、複数サービスのレーンがすべて同時に開始されるのを防ぐ。単一のレーンが有効な上限より重い場合でも、プールが空であればスケジューラーはそれを開始でき、その後、容量が再び利用可能になるまで単独で実行し続ける。デフォルトは 10 スロット、OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9、OPENCLAW_DOCKER_ALL_NPM_LIMIT=5、OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7。Docker ホストに余裕がある場合にのみ、OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT または OPENCLAW_DOCKER_ALL_DOCKER_LIMIT を調整する。ランナーはデフォルトで Docker preflight を実行し、古い OpenClaw E2E コンテナを削除し、30 秒ごとにステータスを出力し、成功したレーンのタイミングを .artifacts/docker-tests/lane-timings.json に保存し、以降の実行でそれらのタイミングを使って長いレーンを先に開始する。Docker をビルドまたは実行せずに重み付きレーンマニフェストを出力するには OPENCLAW_DOCKER_ALL_DRY_RUN=1 を使用し、選択されたレーン、パッケージ/イメージの必要性、認証情報に関する CI 計画を出力するには node scripts/test-docker-all.mjs --plan-json を使用する。
• Package Acceptance は、「このインストール可能な tarball はプロダクトとして動作するか？」の GitHub ネイティブなパッケージゲートである。source=npm、source=ref、source=url、または source=artifact から候補パッケージを 1 つ解決し、それを package-under-test としてアップロードし、選択された ref を再パックする代わりに、その正確な tarball に対して再利用可能な Docker E2E レーンを実行する。プロファイルは網羅範囲の順に smoke、package、product、full。パッケージ/更新/Plugin の契約、公開済みアップグレード生存マトリクス、リリースデフォルト、失敗トリアージについては、更新と Plugin のテストを参照。
• ビルドおよびリリースチェックは、tsdown 後に scripts/check-cli-bootstrap-imports.mjs を実行する。このガードは dist/entry.js と dist/cli/run-main.js から静的ビルドグラフをたどり、コマンドディスパッチ前の起動時に Commander、prompt UI、undici、logging などのパッケージ依存関係をインポートしている場合に失敗する。また、バンドル済み Gateway 実行チャンクを予算内に保ち、既知のコールド Gateway パスの静的インポートを拒否する。パッケージ化された CLI smoke は、ルートヘルプ、onboard ヘルプ、doctor ヘルプ、status、config schema、model-list コマンドもカバーする。
• Package Acceptance のレガシー互換性は 2026.4.25（2026.4.25-beta.* を含む）で上限が設定されている。その期限までは、ハーネスは出荷済みパッケージのメタデータギャップのみを許容する。省略された非公開 QA inventory エントリ、欠落した gateway install --wrapper、tarball 由来の git fixture 内の欠落した patch ファイル、欠落した永続化済み update.channel、レガシー Plugin install-record の場所、欠落した marketplace install-record 永続化、plugins update 中の設定メタデータ移行。2026.4.25 より後のパッケージでは、これらのパスは厳密な失敗となる。
• コンテナ smoke ランナー: test:docker:openwebui、test:docker:onboard、test:docker:npm-onboard-channel-agent、test:docker:release-user-journey、test:docker:release-typed-onboarding、test:docker:release-media-memory、test:docker:release-upgrade-user-journey、test:docker:release-plugin-marketplace、test:docker:skill-install、test:docker:update-channel-switch、test:docker:upgrade-survivor、test:docker:published-upgrade-survivor、test:docker:session-runtime-context、test:docker:agents-delete-shared-workspace、test:docker:gateway-network、test:docker:browser-cdp-snapshot、test:docker:mcp-channels、test:docker:agent-bundle-mcp-tools、test:docker:cron-mcp-cleanup、test:docker:plugins、test:docker:plugin-update、test:docker:plugin-lifecycle-matrix、および test:docker:config-reload は、1 つ以上の実コンテナを起動し、より高レベルの統合パスを検証する。
• packed OpenClaw tarball を scripts/lib/openclaw-e2e-instance.sh 経由でインストールする Docker/Bash E2E レーンは、npm install を OPENCLAW_E2E_NPM_INSTALL_TIMEOUT（デフォルト 600s。デバッグ用にラッパーを無効化するには 0 を設定）で上限設定する。

ライブモデル Docker ランナーは、必要な CLI 認証ホームのみ（または実行が絞り込まれていない場合はサポート対象のすべて）も bind-mount し、その後、実行前にそれらをコンテナホームへコピーするため、外部 CLI OAuth はホストの認証ストアを変更せずにトークンを更新できる:

• 直接モデル: 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。デフォルトで Claude、Codex、Gemini をカバーし、pnpm test:docker:live-acp-bind:droid と pnpm test:docker:live-acp-bind:opencode による厳密な Droid/OpenCode カバレッジを含む）

• CLI バックエンド smoke: pnpm test:docker:live-cli-backend（script: scripts/test-live-cli-backend-docker.sh）

• Codex app-server ハーネス 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）

• Observability smoke: pnpm qa:otel:smoke、pnpm qa:prometheus:smoke、および pnpm qa:observability:smoke は非公開 QA ソースチェックアウトレーンである。npm tarball は QA Lab を省略するため、意図的にパッケージ Docker リリースレーンには含まれていない。

• Open WebUI ライブ smoke: pnpm test:docker:openwebui（script: scripts/e2e/openwebui-docker.sh）

• オンボーディングウィザード（TTY、完全なスキャフォールディング）: pnpm test:docker:onboard（script: scripts/e2e/onboard-docker.sh）

• Npm tarball オンボーディング/channel/agent smoke: pnpm test:docker:npm-onboard-channel-agent は、packed OpenClaw tarball を Docker 内にグローバルインストールし、env-ref オンボーディング経由の OpenAI とデフォルトの Telegram を設定し、doctor を実行し、モックされた OpenAI agent turn を 1 回実行する。事前ビルド済み tarball を再利用するには OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz を使用し、ホストの再ビルドをスキップするには OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 を使用し、channel を切り替えるには OPENCLAW_NPM_ONBOARD_CHANNEL=discord または OPENCLAW_NPM_ONBOARD_CHANNEL=slack を使用する。

• リリースユーザージャーニースモーク: pnpm test:docker:release-user-journey は、パック済みの OpenClaw tarball をクリーンな Docker ホームにグローバルインストールし、オンボーディングを実行し、モックされた OpenAI プロバイダーを構成し、エージェントターンを実行し、外部 Plugin をインストール/アンインストールし、ローカルフィクスチャに対して ClickClack を構成し、送信/受信メッセージングを検証し、Gateway を再起動し、doctor を実行します。

• リリース型付きオンボーディングスモーク: pnpm test:docker:release-typed-onboarding は、パック済み tarball をインストールし、実際の TTY で openclaw onboard を操作し、OpenAI を env-ref プロバイダーとして構成し、生キーが永続化されないことを検証し、モックされたエージェントターンを実行します。

• リリースメディア/メモリスモーク: pnpm test:docker:release-media-memory は、パック済み tarball をインストールし、PNG 添付からの画像理解、OpenAI 互換の画像生成出力、メモリ検索の想起、Gateway 再起動後も想起が維持されることを検証します。

• リリースアップグレードユーザージャーニースモーク: pnpm test:docker:release-upgrade-user-journey は、デフォルトで候補 tarball より古い最新の公開済みベースラインをインストールし、公開済みパッケージ上でプロバイダー/Plugin/ClickClack 状態を構成し、候補 tarball にアップグレードしてから、中核のエージェント/Plugin/チャンネルジャーニーを再実行します。古い公開済みベースラインが存在しない場合は、候補バージョンを再利用します。OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version> でベースラインを上書きします。

• リリース Plugin マーケットプレイススモーク: pnpm test:docker:release-plugin-marketplace は、ローカルフィクスチャマーケットプレイスからインストールし、インストール済み Plugin を更新し、アンインストールし、インストールメタデータが削除された状態で Plugin CLI が消えることを検証します。

• Skill インストールスモーク: pnpm test:docker:skill-install は、パック済み OpenClaw tarball を Docker にグローバルインストールし、設定でアップロード済みアーカイブのインストールを無効化し、検索から現在のライブ ClawHub Skill スラッグを解決し、openclaw skills install でインストールし、インストール済み Skill と .clawhub の origin/lock メタデータを検証します。

• 更新チャンネル切り替えスモーク: pnpm test:docker:update-channel-switch は、パック済み OpenClaw tarball を Docker にグローバルインストールし、パッケージ stable から git dev に切り替え、永続化されたチャンネルと Plugin の更新後動作を検証してから、パッケージ stable に戻し、更新状態を確認します。

• アップグレードサバイバースモーク: pnpm test:docker:upgrade-survivor は、エージェント、チャンネル設定、Plugin 許可リスト、古い Plugin 依存関係状態、既存のワークスペース/セッションファイルを含む、汚れた旧ユーザーフィクスチャの上にパック済み OpenClaw tarball をインストールします。ライブプロバイダーまたはチャンネルキーなしで、パッケージ更新と非対話型 doctor を実行し、その後 loopback Gateway を起動して、設定/状態の保持と起動/状態予算を確認します。

• 公開済みアップグレードサバイバースモーク: pnpm test:docker:published-upgrade-survivor は、デフォルトで openclaw@latest をインストールし、現実的な既存ユーザーファイルをシードし、焼き込み済みコマンドレシピでそのベースラインを構成し、結果の設定を検証し、その公開済みインストールを候補 tarball に更新し、非対話型 doctor を実行し、.artifacts/upgrade-survivor/summary.json を書き込み、その後 loopback Gateway を起動して、構成済み intent、状態保持、起動、/healthz、/readyz、RPC 状態予算を確認します。1 つのベースラインは OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC で上書きし、集約スケジューラーには OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS を使って openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15 のような正確なローカルベースラインを展開させ、OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS を使って reported-issues のような issue 形式のフィクスチャを展開します。reported-issues セットには、外部 OpenClaw Plugin インストールの自動修復用に configured-plugin-installs が含まれます。Package Acceptance は、それらを published_upgrade_survivor_baseline、published_upgrade_survivor_baselines、published_upgrade_survivor_scenarios として公開し、last-stable-4 や all-since-2026.4.23 などのメタベースライントークンを解決し、Full Release Validation はリリースソークパッケージゲートを last-stable-4 2026.4.23 2026.5.2 2026.4.15 と reported-issues に展開します。

• セッションランタイムコンテキストスモーク: pnpm test:docker:session-runtime-context は、隠しランタイムコンテキストの transcript 永続化と、影響を受けた重複プロンプト書き換え分岐の doctor 修復を検証します。

• Bun グローバルインストールスモーク: bash scripts/e2e/bun-global-install-smoke.sh は、現在のツリーをパックし、隔離されたホームで bun install -g を使ってインストールし、openclaw infer image providers --json がハングせずにバンドル済み画像プロバイダーを返すことを検証します。事前ビルド済み tarball は OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz で再利用し、ホストビルドは OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 でスキップし、ビルド済み Docker イメージから dist/ をコピーするには OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local を使います。

• インストーラー Docker スモーク: bash scripts/test-install-sh-docker.sh は、root、update、direct-npm コンテナ間で 1 つの npm キャッシュを共有します。更新スモークは、候補 tarball にアップグレードする前の安定版ベースラインとして、デフォルトで npm latest を使います。ローカルでは OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 で、GitHub では Install Smoke ワークフローの update_baseline_version 入力で上書きします。非 root インストーラーチェックは、root 所有のキャッシュエントリがユーザーローカルのインストール動作を覆い隠さないように、隔離された npm キャッシュを維持します。ローカル再実行間で root/update/direct-npm キャッシュを再利用するには、OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache を設定します。

• Install Smoke CI は、OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1 で重複する direct-npm グローバル更新をスキップします。直接の npm install -g カバレッジが必要な場合は、その env なしでスクリプトをローカル実行します。

• エージェント共有ワークスペース削除 CLI スモーク: pnpm test:docker:agents-delete-shared-workspace（スクリプト: scripts/e2e/agents-delete-shared-workspace-docker.sh）は、デフォルトでルート Dockerfile イメージをビルドし、隔離されたコンテナホームに 1 つのワークスペースを持つ 2 つのエージェントをシードし、agents delete --json を実行し、有効な JSON とワークスペース保持動作を検証します。install-smoke イメージを再利用するには、OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1 を使います。

• Gateway ネットワーキング（2 コンテナ、WS 認証 + ヘルス）: pnpm test:docker:gateway-network（スクリプト: scripts/e2e/gateway-network-docker.sh）

• ブラウザー CDP スナップショットスモーク: pnpm test:docker:browser-cdp-snapshot（スクリプト: scripts/e2e/browser-cdp-snapshot-docker.sh）は、ソース E2E イメージと Chromium レイヤーをビルドし、生 CDP で Chromium を起動し、browser doctor --deep を実行し、CDP ロールスナップショットがリンク URL、カーソル昇格されたクリック可能要素、iframe ref、フレームメタデータをカバーすることを検証します。

• OpenAI Responses web_search 最小推論回帰: pnpm test:docker:openai-web-search-minimal（スクリプト: scripts/e2e/openai-web-search-minimal-docker.sh）は、モックされた OpenAI サーバーを Gateway 経由で実行し、web_search が reasoning.effort を minimal から low に引き上げることを検証してから、プロバイダースキーマの reject を強制し、生の詳細が Gateway ログに現れることを確認します。

• MCP チャンネルブリッジ（シード済み Gateway + stdio ブリッジ + 生 Claude 通知フレームスモーク）: pnpm test:docker:mcp-channels（スクリプト: scripts/e2e/mcp-channels-docker.sh）

• OpenClaw バンドル MCP ツール（実際の stdio MCP サーバー + 埋め込み OpenClaw プロファイル allow/deny スモーク）: pnpm test:docker:agent-bundle-mcp-tools（スクリプト: scripts/e2e/agent-bundle-mcp-tools-docker.sh）

• Cron/サブエージェント MCP クリーンアップ（実際の Gateway + 隔離された Cron とワンショットサブエージェント実行後の stdio MCP 子プロセスの終了処理）: pnpm test:docker:cron-mcp-cleanup（スクリプト: scripts/e2e/cron-mcp-cleanup-docker.sh）

• Plugins（ローカルパス、file:、hoist された依存関係を持つ npm レジストリ、不正な npm パッケージメタデータ、git moving ref、ClawHub kitchen-sink、マーケットプレイス更新、Claude バンドルの有効化/検査に対するインストール/更新スモーク）: pnpm test:docker:plugins（スクリプト: scripts/e2e/plugins-docker.sh） ClawHub ブロックをスキップするには OPENCLAW_PLUGINS_E2E_CLAWHUB=0 を設定し、デフォルトの kitchen-sink パッケージ/ランタイムペアを上書きするには OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC と OPENCLAW_PLUGINS_E2E_CLAWHUB_ID を使います。OPENCLAW_CLAWHUB_URL/CLAWHUB_URL がない場合、テストは hermetic なローカル ClawHub フィクスチャサーバーを使います。

• Plugin 更新変更なしスモーク: pnpm test:docker:plugin-update（スクリプト: scripts/e2e/plugin-update-unchanged-docker.sh）

• Plugin ライフサイクルマトリックススモーク: pnpm test:docker:plugin-lifecycle-matrix は、素のコンテナにパック済み OpenClaw tarball をインストールし、npm Plugin をインストールし、有効化/無効化を切り替え、ローカル npm レジストリ経由でアップグレードおよびダウングレードし、インストール済みコードを削除してから、各ライフサイクルフェーズの RSS/CPU メトリクスをログに記録しつつ、古い状態が残っていてもアンインストールで削除されることを検証します。

• 設定再読み込みメタデータスモーク: pnpm test:docker:config-reload（スクリプト: scripts/e2e/config-reload-source-docker.sh）

• Plugins: pnpm test:docker:plugins は、ローカルパス、file:、hoist された依存関係を持つ npm レジストリ、git moving ref、ClawHub フィクスチャ、マーケットプレイス更新、Claude バンドルの有効化/検査に対するインストール/更新スモークをカバーします。pnpm test:docker:plugin-update は、インストール済み Plugin の変更なし更新動作をカバーします。pnpm test:docker:plugin-lifecycle-matrix は、リソース追跡付き npm Plugin のインストール、有効化、無効化、アップグレード、ダウングレード、コード欠落時のアンインストールをカバーします。

共有 functional イメージを手動で事前ビルドして再利用するには:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-buildOPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE などのスイート固有イメージ上書きは、設定されている場合は引き続き優先されます。OPENCLAW_SKIP_DOCKER_BUILD=1 がリモート共有イメージを指している場合、スクリプトはそれがまだローカルにないときに pull します。QR とインストーラーの Docker テストは、共有ビルド済みアプリランタイムではなく、パッケージ/インストール動作を検証するため、独自の Dockerfile を維持します。

ライブモデル用 Docker ランナーは、現在のチェックアウトも読み取り専用で bind mount し、 コンテナ内の一時 workdir にステージします。これにより、ランタイム イメージをスリムに保ちながら、正確なローカルソース/設定に対して 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 プロキシ経由で実際のチャットリクエストを送信します。 ライブモデル完了を待たずに、Open WebUI サインインとモデル検出後に停止するべき リリースパス CI チェックでは、OPENWEBUI_SMOKE_MODE=models を設定してください。 初回実行は、Docker が Open WebUI イメージを pull する必要があり、 Open WebUI 自身のコールドスタートセットアップが完了する必要もあるため、目に見えて遅くなる場合があります。 このレーンには使用可能なライブモデルキーが必要です。プロセス 環境、ステージ済み auth プロファイル、または明示的な OPENCLAW_PROFILE_FILE 経由で指定してください。 成功した実行では、{ "ok": true, "model": "openclaw/default", ... } のような小さな JSON ペイロードが出力されます。 test:docker:mcp-channels は意図的に決定的であり、実際の Telegram、Discord、iMessage アカウントは必要ありません。シード済み Gateway コンテナを起動し、openclaw mcp serve を spawn する 2 つ目のコンテナを開始してから、 ルーティングされた会話の検出、transcript 読み取り、添付メタデータ、 ライブイベントキューの動作、アウトバウンド送信ルーティング、そして実際の stdio MCP bridge 上の Claude スタイルのチャンネル + 権限通知を検証します。通知チェックは raw stdio MCP フレームを直接検査するため、このスモークは 特定のクライアント SDK がたまたま表面化する内容だけでなく、bridge が実際に emit する内容を検証します。 test:docker:agent-bundle-mcp-tools は決定的であり、ライブ モデルキーは必要ありません。repo Docker イメージをビルドし、コンテナ内で実際の stdio MCP プローブサーバーを起動し、 埋め込み OpenClaw bundle MCP ランタイム経由でそのサーバーを materialize し、 ツールを実行してから、coding と messaging が bundle-mcp ツールを保持する一方で、minimal と tools.deny: ["bundle-mcp"] がそれらをフィルターすることを検証します。 test:docker:cron-mcp-cleanup は決定的であり、ライブモデル キーは必要ありません。実際の stdio MCP プローブサーバーを備えたシード済み Gateway を起動し、 隔離された cron turn と sessions_spawn one-shot child turn を実行してから、 各実行後に MCP child process が終了することを検証します。

手動 ACP プレーン言語スレッドスモーク（CI ではありません）:

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

有用な env vars:

• OPENCLAW_CONFIG_DIR=...（デフォルト: ~/.openclaw）は /home/node/.openclaw にマウントされます
• OPENCLAW_WORKSPACE_DIR=...（デフォルト: ~/.openclaw/workspace）は /home/node/.openclaw/workspace にマウントされます
• OPENCLAW_PROFILE_FILE=... はマウントされ、テスト実行前に source されます
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 は、一時 config/workspace dirs を使用し、外部 CLI auth マウントなしで、OPENCLAW_PROFILE_FILE から source された env vars のみを検証します
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=...（デフォルト: ~/.cache/openclaw/docker-cli-tools）は、Docker 内のキャッシュ済み CLI インストール用に /home/node/.npm-global にマウントされます
• $HOME 配下の外部 CLI auth dirs/files は /host-auth... 配下に読み取り専用でマウントされ、テスト開始前に /home/node/... にコピーされます
  • デフォルト dirs: .minimax
  • デフォルト files: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • 絞り込まれた provider 実行では、OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS から推論される必要な dirs/files のみがマウントされます
  • 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=... はコンテナ内の providers をフィルターします
• OPENCLAW_SKIP_DOCKER_BUILD=1 は、再ビルドを必要としない再実行で既存の openclaw:local-live イメージを再利用します
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 は、creds が env ではなく profile store から来ることを保証します
• OPENCLAW_OPENWEBUI_MODEL=... は、Open WebUI スモーク用に gateway が公開するモデルを選択します
• OPENCLAW_OPENWEBUI_PROMPT=... は、Open WebUI スモークで使用される nonce-check prompt を上書きします
• OPENWEBUI_IMAGE=... は、固定された Open WebUI イメージタグを上書きします

Docs サニティ

ドキュメント編集後に docs チェックを実行します: pnpm check:docs。 ページ内見出しチェックも必要な場合は、Mintlify の完全なアンカー検証を実行します: pnpm docs:check-links:anchors。

オフラインリグレッション（CI-safe）

これらは実際の providers なしの「実パイプライン」リグレッションです:

• Gateway ツール呼び出し（mock OpenAI、実 gateway + agent loop）: src/gateway/gateway.test.ts（case: "runs a mock OpenAI tool call end-to-end via gateway agent loop"）
• Gateway ウィザード（WS wizard.start/wizard.next、config 書き込み + auth enforcement）: src/gateway/gateway.test.ts（case: "runs wizard over ws and writes auth token config"）

Agent 信頼性 evals（skills）

「agent reliability evals」のように振る舞う CI-safe テストはすでにいくつかあります:

• 実 gateway + agent loop 経由の mock tool-calling（src/gateway/gateway.test.ts）。
• session wiring と config effects を検証する end-to-end ウィザードフロー（src/gateway/gateway.test.ts）。

Skills についてまだ不足しているもの（Skills を参照）:

• Decisioning: skills が prompt に列挙されているとき、agent は正しい skill を選ぶ（または無関係なものを避ける）か？
• Compliance: agent は使用前に SKILL.md を読み、必須 steps/args に従うか？
• Workflow contracts: tool order、session history carryover、sandbox boundaries を assert する multi-turn scenarios。

将来の evals は、まず決定的であるべきです:

• mock providers を使用して tool calls + order、skill file reads、session wiring を assert する scenario runner。
• skill-focused scenarios の小さな suite（use vs avoid、gating、prompt injection）。
• オプションの live evals（opt-in、env-gated）は、CI-safe suite が整ってからのみ。

Contract tests（Plugin とチャンネル shape）

Contract tests は、登録されたすべての Plugin とチャンネルが その interface contract に準拠していることを検証します。検出されたすべての plugins を反復し、 shape と behavior assertions の suite を実行します。デフォルトの pnpm test unit レーンは意図的に これらの共有 seam と smoke files をスキップします。共有チャンネルまたは provider surfaces に触れる場合は、 contract commands を明示的に実行してください。

コマンド

• すべての contracts: pnpm test:contracts
• チャンネル contracts のみ: pnpm test:contracts:channels
• Provider contracts のみ: pnpm test:contracts:plugins

チャンネル contracts

src/channels/plugins/contracts/*.contract.test.ts にあります:

• plugin - 基本的な plugin shape（id、name、capabilities）
• setup - セットアップウィザード contract
• session-binding - session binding behavior
• outbound-payload - メッセージ payload structure
• inbound - inbound message handling
• actions - チャンネル action handlers
• threading - thread ID handling
• directory - directory/roster API
• group-policy - group policy enforcement

Provider status contracts

src/plugins/contracts/*.contract.test.ts にあります。

• status - チャンネル status probes
• registry - Plugin registry shape

Provider contracts

src/plugins/contracts/*.contract.test.ts にあります:

• auth - Auth flow contract
• auth-choice - Auth choice/selection
• catalog - Model catalog API
• discovery - Plugin discovery
• loader - Plugin loading
• runtime - Provider runtime
• shape - Plugin shape/interface
• wizard - セットアップウィザード

実行するタイミング

• plugin-sdk exports または subpaths を変更した後
• チャンネルまたは provider plugin を追加または変更した後
• plugin registration または discovery をリファクタリングした後

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

リグレッションの追加（ガイダンス）

live で発見された provider/model issue を修正する場合:

• 可能であれば CI-safe リグレッションを追加します（mock/stub provider、または正確な request-shape transformation を capture）
• それが本質的に live-only の場合（rate limits、auth policies）、live test を狭く保ち、env vars 経由で opt-in にします
• バグを捕まえる最小の layer を target することを優先します:
  • provider request conversion/replay bug → direct models test
  • gateway session/history/tool pipeline bug → gateway live smoke または CI-safe gateway mock test
• SecretRef traversal guardrail:
  • src/secrets/exec-secret-ref-id-parity.test.ts は registry metadata（listSecretTargetRegistryEntries()）から SecretRef class ごとに 1 つの sampled target を derive し、traversal-segment exec ids が拒否されることを assert します。
  • src/secrets/target-registry-data.ts に新しい includeInPlan SecretRef target family を追加する場合は、その test の classifyTargetClass を更新してください。この test は unclassified target ids で意図的に失敗するため、新しい classes が黙ってスキップされることはありません。

関連

• ライブのテスト
• 更新と plugins のテスト
• CI