release-openclaw-plugin-testing

OpenClaw のリリース前プラグインテスト

プラグインのリリースに向けた信頼性確認、プラグインのライフサイクル全体のテスト、パッケージ成果物でのプラグイン検証、または「リリース前にほかに何をテストすべきか」とユーザーが尋ねた場合は、このスキルを使用します。openclaw-testing を補完するスキルです。最も低コストで安全なランナーを選ぶ場合や、失敗したレーンをデバッグする場合は、そちらのスキルも使用してください。

目標

プラグインシステムをソーステストだけでなく、製品の機能として検証します。

• 同梱プラグインのライフサイクル：インストール、確認、有効化、無効化、アンインストール
• クリーンな HOME でのパッケージ成果物の動作
• doctor/fix/config の検証と冪等性
• 設定の検出と設定のラウンドトリップ
• ステータス／ログの可視性と診断
• プラグインのメタデータスナップショットを使ったゲートウェイの起動／ブートストラップ
• 実際の外部プラグインに対する公開 SDK の互換性
• 安全に使用できる認証情報がある場合に限った、実環境に近いプロバイダー／チャネルのプローブ

最初の確認事項

OpenClaw リポジトリのルートから実行します。

pnpm docs:list
git status --short --branch
pnpm changed:lanes --json

依存関係の所有元とローカルまたはリモートでの検証方法の選択については、openclaw-testing に従ってください。

ランナーの選択

次の順で優先してください。

1. インストール可能なパッケージの製品検証には GitHub Package Acceptance。
2. 必要な依存関係と機能がそろっている場合、信頼できるソース／パッケージ／Docker の検証には 現在の専用 Linux ワーカー。
3. Docker／パッケージのレーンで dist、dist-runtime、パッケージキャッシュのシードが必要な場合は ci-build-artifacts-testbox.yml Testbox。
4. ソースチェック、対象を絞った Vitest、パッケージ境界チェック、または特定の Docker レーンには ci-check-testbox.yml Testbox。
5. 小規模なフォーマット／静的解析／単体テストの確認に限り、ワークステーションで対象を絞ったコマンド。

古くて不完全なワークツリーから、長時間かかるパッケージ Docker 実行を行わないでください。Testbox の同期で変更ファイルが数百件報告される、またはパッケージ入力ファイルが削除され始める場合は、停止して最新の main から新しいボックスを準備するか、Package Acceptance に切り替えてください。

既存のベースライン

新たなカバレッジを追加する前に、次を実行するか、結果を確認してください。

OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile
pnpm test:docker:plugins
OPENCLAW_PLUGINS_E2E_CLAWHUB=0 pnpm test:docker:plugins
pnpm test:docker:plugin-update

同梱プラグインのインストール／アンインストールを一通り検証するには、パッケージのテストをシャードに分割します。

OPENCLAW_BUNDLED_PLUGIN_SWEEP_TOTAL=8 \
OPENCLAW_BUNDLED_PLUGIN_SWEEP_INDEX=<0-7> \
pnpm test:docker:bundled-plugin-install-uninstall

この例では、選択したパッケージのプラグイン一覧をシャード 0-7 に分割しています。パッケージに明示的に含まれていない場合、プライベート QA プラグインはソースモードでのみテストします。

信頼性マトリックス

リリース前の承認には、このマトリックスを使用してください。合否、実行 URL／Testbox ID、パッケージの SHA／バージョン、ライブテストをスキップした理由を記録してください。

対象	検証内容	推奨ランナー
パッケージ成果物	Package Acceptance の suite_profile=package またはカスタムレーン	GitHub Actions
同梱プラグインのライフサイクル	シャード分割した test:docker:bundled-plugin-install-uninstall	Testbox またはリリース用 Docker
外部プラグイン	test:docker:plugins と plugins-offline	Testbox／Package Acceptance
更新のノーオペレーション	test:docker:plugin-update	Testbox／Package Acceptance
doctor/fix	不正な設定を用意し、doctor --fix --non-interactive を実行	新しい Docker／Testbox ハーネス
設定のラウンドトリップ	config set/get、確認、doctor、再読み込み、差分ハッシュ	新しい Docker／Testbox ハーネス
ゲートウェイのブートストラップ	クリーンな HOME、有効／無効のプラグイングループ、ステータス JSON	新しい Docker／Testbox ハーネス
SDK の互換性	SDK のサブパスを使ったディレクトリ、tgz、file: の外部プラグイン	test:docker:plugins と新しいスモークテスト
実環境に近いテスト	環境変数がある場合に限り、秘匿化したプロバイダー／チャネルのプローブ	Testbox のライブレーン

Package Acceptance 計画

Full Release Validation が、Q=C および正確な公開用 tarball による最終候補の適格性確認を担当します。診断または公開後の信頼性確認には、単独の Package Acceptance を使用してください。候補の適格性確認の代わりには使用しないでください。

gh workflow run package-acceptance.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f workflow_ref=main \
  -f source=ref \
  -f package_ref=<branch-or-sha> \
  -f suite_profile=custom \
  -f docker_lanes='plugins-offline plugin-update doctor-switch update-channel-switch config-reload mcp-channels npm-onboard-channel-agent' \
  -f telegram_mode=mock-openai

公開済みベータ版の証明には、source=npm -f package_spec=openclaw@beta を使用してください。これらの単独の診断／信頼性確認の実行では、信頼できる最新のハーネスコードを使用できます。ただし、候補の適格性確認では、凍結された候補のハーネスを引き続き使用する必要があります。

extended-stable の共有公開では、Q=C において、許可された候補が所有する release-ci/* ハーネスからの、完全かつ正確なターゲットを対象とする Full Release Validation が必須です。信頼済みの P の受け入れと公開ツールは分離してください。正規ブランチや main から直接実行するプロデューサーは、保護されたパブリッシャーの要件を満たしません。Package Acceptance は公開後に実施するセレクターのスモークテストです。

gh workflow run package-acceptance.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@extended-stable \
  -f suite_profile=package \
  -f telegram_mode=mock-openai

解決されたバージョンを記録してください。タグの all-publishable インベントリにあるすべてのパッケージとセレクターも、引き続き検証してください。1回のスモークテストは、レジストリからの読み戻しの代わりにはなりません。

Plugin npm Artifact 適格性確認

公開候補では、Full Release Validation が plugin npm アーティファクトの適格性確認を担当します。ディスパッチ時に公開対象の選択内容を指定してください。all-group の親ワークフローは、正確な Release SHA を対象に、アーティファクト専用モードで plugin-npm-release.yml を実行し、tarball の読み戻しが成功することを確認して、不変の集約ディスクリプターを publicationArtifacts.pluginNpm に記録します。Release Prepare と公開では、プラグインを再パッケージせず、この正確なディスクリプターを採用する必要があります。

通常の公開候補の対象外となる、特定の診断や選択したプラグインの修復に限り、信頼済みワークフローによる単独の事前確認を使用してください。

release_sha="$(git rev-parse origin/release/2026.7.1)"
gh workflow run plugin-npm-release.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f preflight_only=true \
  -f publish_scope=selected \
  -f plugins=@openclaw/meta-provider \
  -f ref="${release_sha}" \
  -f npm_dist_tag=default

release_publish_run_id は渡さないでください。ワークフローが verify_plugin_npm_preflight を正常に完了することを必須とします。実行 URL、ワークフロー SHA、ソース SHA を記録してください。ワークフローはまず、npm-pack.json、preflight-manifest.json、tarball を含むステージング／読み戻し用アーティファクト plugin-npm-package-source-<source-sha>-<extension-id> を作成します。次に、tarball と plugin-publication-manifest.json を含む最終コンシューマーアーティファクト plugin-npm-package-<extension-id>-<version>-<route>-<run-id>-<attempt> をアップロードします。

最終アーティファクトの名前とダイジェストは、それぞれ別に記録してください。マニフェストは openclaw.plugin-publication-artifact/v1 を使用し、ターゲット SHA、パッケージマニフェストのハッシュ、公開ルートとポリシー、tarball のハッシュとインベントリを記録します。この単独の証明は検証専用であり、公開を許可したり、公開用にステージングしたりするものではありません。また、Full Release Validation のマニフェストに紐付いたディスクリプターの代わりにはなりません。セキュリティとパッケージ内容の境界は、展開済みのソースツリーではなくアーティファクトのインベントリです。ソースのみのフィクスチャーは対象外です。出荷されるランタイムおよびスキルアセットに含まれない、パッケージ所有のテスト用パスやフィクスチャーパスがある場合、適格性確認は失敗します。出荷されるランタイムには、引き続きセキュリティスキャンを実施します。同梱された node_modules は、プラグインソースのポリシーではなく、依存関係の証跡として扱います。

別途行う trusted_publisher_preflight=true の OIDC チェックでは、保護された release-publish/<tooling-sha12>-<epoch> ディスパッチタグが必要であり、npm-publish で実行されます。実際の公開にもそのツールタグが必要です。人による直接ディスパッチでは、公開前に npm-release 承認ジョブの完了を待ちます。

すでに公開済みのバージョンについては、npm の dist.integrity と dist.shasum が検証済みの tarball と一致することを必須とします。修復可能なものとして扱うのは、欠落している、または確実に古い dist-tag のみです。より新しいセレクターや比較できないセレクターは、ブロッカーです。

新しい Testbox ハーネス計画

確実性を高める必要がある場合は、1 つのパッケージ tarball と分割したプラグインリストを使用する plugin-lifecycle-matrix Docker レーンを追加または実行します。プラグインごとに、次の手順を行います。

1. クリーンな HOME から開始します。
2. plugins list --json を取得します。
3. plugins install <id> を実行します。
4. plugins inspect <id> --json を実行します。
5. plugins disable <id> を実行し、無効状態でも表示されることを確認します。
6. 設定が必須のプラグインで設定がない場合を除き、plugins enable <id> を実行します。
7. plugins registry --refresh を実行します。
8. doctor --non-interactive を実行します。
9. plugins uninstall <id> --force を実行します。
10. プラグインの plugins.entries の値が厳密に { enabled: false } であり、allow／deny エントリー、インストール記録、管理対象ディレクトリ、バンドル済みランタイムの読み込みパスが削除されていることを確認します。過去のターゲットについては、既存ハーネスのソースを基準としたアンインストール時の期待値を使用します。
11. 診断に level: "error" が含まれず、出力でシークレットらしき値が秘匿されていることを確認します。

memory-lancedb は設定が必須のため、特別扱いします。まず、埋め込み設定なしではインストールしても有効化されないことを確認し、その後、設定ありのケースを実行します。

Doctor／Fix マトリックス

不正な状態を用意し、doctor --fix --non-interactive で修復されることを確認したうえで、doctor を再実行し、冪等性を確認します。

• 古い plugins.allow
• 古い plugins.entries
• チャネルプラグインが存在しない場合の古いチャネル設定
• 無効な plugins.entries.<id>.config
• plugins.load.paths に含まれるパッケージ同梱のパス
• レガシーな plugins.installs
• ランタイム依存関係をステージングしてはならない、無効化されたチャネル／プラグインの設定
• 変更してはならない、root 所有のグローバルパッケージツリー

Gateway ブートストラップマトリックス

クリーンな状態で、パッケージ版 OpenClaw を Docker で起動します。

• プロバイダープラグインが有効で、認証情報がない場合：警告付きで ready になり、クラッシュしない
• チャネルプラグインが無効に設定されている場合：ランタイム依存関係がステージングされない
• 起動時に有効化されるプラグインが有効な場合：ready になり、ステータスに反映される
• 1 つのプラグイン設定が無効な場合：該当プラグインはスキップ／隔離され、ほかのプラグインはそのまま動作する

次のことを確認します。

• gateway が ready になる
• openclaw status --json にプラグイン診断が含まれる
• openclaw plugins inspect --all --json を解析できる
• パッケージツリーが変更されていない
• ログにトークンの生値が含まれない

設定の往復テストに使用する代表例

すべてのプラグインで設定の深い往復テストを行う代わりに、代表的なプラグインファミリーを使用します。

• プロバイダー：openai、anthropic、mistral、openrouter
• チャネル：telegram、discord、slack、whatsapp
• メモリ：memory-lancedb
• 機能／ランタイム：browser、acpx、tokenjuice

各代表例で、次の手順を行います。

1. 可能な場合は CLI から設定を書き込みます。
2. config get または JSON を介して設定を読み戻します。
3. plugins inspect を実行します。
4. doctor --non-interactive を実行します。
5. 該当する場合は、gateway の設定再読み込みを実行します。
6. 変更を行わないコマンドの前後で設定ハッシュを比較します。

外部 SDK のスモークテスト

パッケージ用 Docker レーンで小規模な外部プラグインを作成し、次の場所からインストールします。

• ローカルディレクトリ
• .tgz
• file: npm spec

CJS と ESM の形式に加え、openclaw/plugin-sdk/* の特定サブパスをインポートするプラグインを少なくとも 1 つ対象にします。plugins inspect でそのツール、gateway メソッド、CLI コマンド、またはサービスが認識されることを確認します。

ライブに近いプローブのルール

ライブに近いテストを行う前に、Testbox で許可された環境変数を読み込み、秘匿処理済みの利用可否マトリックスを作成します。表示するのは存在／不在のみとし、値は決して表示しません。

存在する認証情報に対してのみプローブを実行します。ユーザーに見えるメッセージの送信より、認証／カタログ／ステータスのプローブを優先します。プローブが外部のユーザー、チャネル、またはワークスペースに接触する可能性がある場合は、停止してユーザーに確認します。

レポート

次の形式でレポートします。

package/ref:
tbx ids / run urls:
matrix:
  bundled lifecycle:
  package acceptance:
  doctor/fix:
  gateway bootstrap:
  config round-trip:
  sdk external:
  live-ish:
failures:
skips:
next highest-value gap:

失敗が製品の動作ではなく Testbox の同期／環境の損傷によるものである場合は、その旨を明確に述べ、クリーンな再実行または現在の main との比較で証明します。