openclaw-parallels-smoke

OpenClaw Parallels スモーク

Parallels ゲストのワークフローとスモークテストの解釈に、このスキルを使用してください。通常のリポジトリ作業では読み込まないでください。

グローバルルール

• Parallels はデフォルトでは postpublish-confidence coverage であり、bounded beta-publish フェーズの前提条件ではありません。1 つの正確に公開されたパッケージバージョンに対して実行し、そのパッケージを承認した Validation SHA + Tooling SHA の実行タプルを記録します。Validation SHA はその Code SHA または Release SHA に対応するものであり、3 つ目のリリース識別子ではありません。
• postpublish Parallels レーンの失敗は、ベータを遡って非公開にするものではありません。product、harness/tooling/provenance、infrastructure/credential、または wrapper の失敗として分類します。確認された product の欠陥のみが次のベータに進みます。
• 独立したゲストファミリーごとに 1 つのコーディネーターと 1 つのレーンを使用します。失敗したファミリーを 1 回診断して再試行し、その後再評価します。集約マトリクスを自動的に再起動しないでください。
• 何かをプロビジョニングする前に、既存の VM とスナップショットをインベントリします。事前設定された pristine スナップショットが要求されたベースラインと一致する場合は、それに切り替えて、そのユーザー、ツール、およびベースセットアップを再利用します。「fresh」な実行のために新しい VM を作成したり、macOS を再インストールしたり、ゲストベースラインを再構築したりしないでください。
• 「Fresh」とは、最も近い既存の pristine スナップショットを復元することを意味し、別のスナップショットを作成することではありません。ユーザーが明示的に要求した場合、または適切なベースラインが存在しない場合を除き、アドホックなスナップショットを作成しないでください。アドホックな実行の後は、元のスナップショットを復元し、ゲストを停止したままにします。
• スナップショットを復元する前に、そのスナップショットの状態を確認します。pristine な poweron スナップショットには、事前設定されたログイン済みセッションが含まれていることがあります。Parallels がそのセッションを再開するように、通常どおりそれに切り替えます。実行が保存されたセッションを意図的に破棄してログインウィンドウから起動する必要がある場合を除き、テスト開始時に --skip-resume を渡さないでください。--skip-resume は、復元されたソースゲストを停止したままにしなければならない最終クリーンアップでは許容されます。
• スモーク実行におけるゲートウェイ検証では、確認対象の安定版がまだサポートしていない場合を除き、openclaw gateway status --deep --require-rpc を使用する必要があります。
• 安定版 2026.3.12 のアップグレード前診断では、プレーンな gateway status --deep へのフォールバックが必要になる場合があります。
• その安定版のアップグレード前レーンにおける precheck=latest-ref-fail は、ベースラインとして扱い、自動的にリグレッションとは見なしません。
• 機械可読なサマリーのために --json を渡します。
• フェーズごとのログはデフォルトで .artifacts/parallels/openclaw-parallels-* の下に配置されます。実行で別のアーティファクトボリュームが必要な場合は OPENCLAW_PARALLELS_ARTIFACT_ROOT でオーバーライドします。
• 同じ fresh ワークスペースまたはセッション上で、ローカルとゲートウェイのエージェントターンを並列に実行しないでください。
• すべてのトップレベル Parallels レーンに、ホストの timeout --foreground (または利用可能なバイナリがそれであれば gtimeout --foreground) でハードキャップを設定し、インストールの停止、スナップショットの切り替え、または prlctl exec トランスポートが残りのテスト時間を消費しないようにします。デフォルト:
  • macOS: 75m
  • Linux: 75m
  • Windows: 90m
  • 集約 npm-update ラッパー: 150m レーンがキャップに達した場合は、そこで停止し、最新の /tmp/openclaw-parallels-* 実行ディレクトリとフェーズログを確認してから、影響を受ける最小のレーンを修正または再実行します。キャップに達したレーンを待ち続けないでください。
• 実際の OpenClaw npm install/update フェーズは、レーン全体のキャップよりも厳格なシグナルです。install フェーズは通常 7 分以内に完了し、update フェーズは通常 5 分以内に意味のある進捗を示すはずです。install-main、install-latest、install-baseline、または install-baseline-package という名前のフェーズが 420 秒を超える場合、または update-dev / 同じゲストの openclaw update という名前のフェーズが新しいマーカーなしで 300 秒を超える場合は、そのフェーズログとゲストのプロセス状態から診断を開始します。現在の Windows の update フェーズは、doctor --fix がバンドルされたプラグインランタイム依存関係をインストールする可能性があるため、約 10〜15 分後にまだ成功する可能性があります。ログが本当に古くない限り、スクリプトのハードキャップを 20 分付近に保ちます。
• 完全な OS マトリクスの場合、ホストの容量が許せば、独立したゲストファミリーレーンを並列に実行することを優先します:
  • timeout --foreground 75m pnpm test:parallels:macos -- --json
  • timeout --foreground 90m pnpm test:parallels:windows -- --json
  • timeout --foreground 75m pnpm test:parallels:linux -- --json 各レーンを独自のシェル/セッションに保ち、それぞれの実行ディレクトリを追跡します。マトリクスを開始する前に、必要なホストのビルド/パッケージゲートを完了まで実行します。current-main の tgz パッケージングが必要な場合、スモークスクリプトは pnpm build、inventory/staging、および npm pack を通じて共有パッケージロックを保持します。そのロックが欠落しているか壊れている場合は、並行した dist の変更を受け入れるのではなく、マトリクスを直列化します。
• 同じゲストファミリーに対して複数のスモークレーンを同時に実行しないでください。Tahoe レーンはホストの HTTP ポートを共有し、Windows/Linux レーンは 2 つのジョブが同じ VM に同時に触れると、スナップショットの復元/起動状態で衝突する可能性があります。
• 集約 pnpm test:parallels:npm-update ラッパーを、個別の macOS/Windows/Linux スモークレーンと並列に実行しないでください。それは同じゲストファミリーとスナップショットに触れます。
• 無関係なホストコマンドが dist を再ビルド、クリーン、または再ステージングする可能性がある間は、Parallels レーンを開始しないでください (pnpm build、pnpm ui:build、pnpm release:check、pnpm test:install:smoke、npm pack/install スモーク、またはパッケージ/ビルド準備を実行する Docker レーン)。無関係なビルド/パッケージゲートを先に実行し、それらが完了するのを待ってから、VM マトリクスを開始します。並行した dist の変更は、ホストの npm pack を欠落ファイルで失敗させ、VM サイクル全体を無駄にする可能性があります。
• マトリクスを実行または最適化している間は、レーンごとの実時間と /tmp/openclaw-parallels-* ログから最も遅いフェーズを記録します。スモークの順序、タイムアウト、またはヘルパーの動作を変更する前に、そのタイミングを使用します。
• ホストのビルドが src/canvas-host/a2ui/.bundle.hash のような追跡対象の生成ファイルを変更する場合は、VM 時間を費やす前に停止します。生成されたアーティファクトを別途コミットするか、ジェネレーターのドリフトを修正してから、影響を受ける最小のレーンを再実行します。
• main が活発なマルチエージェント作業の下で動いている場合は、長い Parallels スイートには 1 つのコミットに固定されたデタッチド worktree を優先します。スモークスクリプトは現在、ライブの git rev-parse HEAD ではなく、パックされた tgz コミットを検証しますが、固定された worktree は再実行中のノイズの多い再ビルド/バージョンドリフトを依然として回避します。
• openclaw update --channel dev レーンの場合、ゲストはローカルの worktree ではなく GitHub の main をクローンすることに注意してください。ローカルの修正が存在しても、再実行がクローンされた dev チェックアウト内でまだ失敗する場合は、ブランチがプッシュされるまでそれを修正の反証として扱わないでください。
• prlctl exec では、VM 名を --current-user の前に渡します (prlctl exec "$VM" --current-user ...)。逆にしないでください。
• ワークフローがサイトインストーラー/npm リリースではなくリポジトリチェックアウトから OpenClaw をインストールする場合は、最後に実際のゲスト CLI シムをインストールし、新しいゲストシェルで検証します。リポジトリ内の pnpm openclaw ... だけではハンドオフの同等性には不十分です。
• macOS ゲストでは、ユーザーグローバルインストールと、PATH から見える安定したシムを優先します:
  • NPM_CONFIG_PREFIX="$HOME/.npm-global" npm install -g . でインストールします
  • ~/.local/bin/openclaw が存在するか、~/.npm-global/bin が PATH にあることを確認します
  • まったく新しいゲストシェルから which openclaw と openclaw --version で検証します

npm をインストールしてから更新

• 推奨エントリポイント: pnpm test:parallels:npm-update
• macOS 専用の公開リリース更新チェックには、次を使用します:
  • timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@<old-version> --update-target <target-version-or-tag> --json これは同一ゲストでの openclaw update --tag ... カバレッジを維持し、Windows/Linux レーンを起動せずに共有の macOS current-user/sudo フォールバックを使用します。
• 必須カバレッジ: すべてのリリース/更新リグレッション実行には、次の両方のレーンを含める必要があります:
  • フレッシュスナップショット -> 要求されたパッケージ/ベースラインをインストール -> スモーク
  • 同一ゲストのベースライン -> ゲストにインストールされた openclaw update ... コマンドを実行 -> 再度スモーク
• 更新レーンでは、OpenClaw の内部アップデーターを必ず実行する必要があります。直接的な npm install -g <tgz-or-spec> やハーネス側のパッケージ入れ替えを更新フローのカバレッジとしてカウントしないでください。これらはインストールスモークにすぎません。
• 公開済みターゲットの場合、まず古いベースラインパッケージ（たとえば [email protected]）をインストールし、次にインストール済みのゲスト CLI を意図したチャネル/タグ（たとえば openclaw update --channel beta --yes --json）で実行し、コマンド後に openclaw --version、openclaw update status --json、ゲートウェイ RPC、およびエージェントターンを検証します。
• 未公開ターゲットの場合、候補をホスト上でパックし、.tgz をハーネス HTTP サーバー経由で配信し、ゲストのアップデーターをその配信されたパッケージに向けます。openclaw update --tag http://<host-ip>:<port>/openclaw-<version>.tgz --yes --json を推奨します。チャネルの永続化も重要な場合は、--channel <stable|beta> を渡し、ゲスト更新環境の OPENCLAW_UPDATE_PACKAGE_SPEC に同じ配信 URL を設定します。テスト対象のコマンドは依然として openclaw update である必要があり、直接の npm ではありません。
• 未公開のローカル修正検証では、古いベースラインのアップデーターコードが依然として最初のホップを制御していることを忘れないでください。新しいアップデーターコードにのみ存在する修正は、すでに実行中の古いプロセスを変更できません。配信される候補は、ベースラインホストと互換性のあるパッケージ/プラグインメタデータを維持するか、ベースライン自体にアップデーター修正が含まれている必要があります。
• beta/stable の検証では、実行直前にタグを解決します（npm view openclaw@beta version dist.tarball または npm view openclaw@latest ...）。長時間の VM マトリクスがすでに実行されている間にタグは移動する可能性があります。以前のレジストリ 404/タグ遅延チェックの後に意図したプレリリースが現れた場合は、マトリクスを再起動してください。
• 設定済みのシークレットワークフローを使用して、OpenAI/Anthropic レーンに必要なプロバイダーキーのみを注入します。シークレットや環境変数ダンプを出力しないでください。プロバイダーシークレットはゲスト exec 環境を通じて渡します。
• 同一ゲストの更新検証では、エージェントターンの前にデフォルトモデルを明示的に openai/gpt-5.4 に設定し、古いセッションモデル状態がチェックに漏れないよう、新しい明示的な --session-id を使用する必要があります。
• 集約 npm-update ラッパーは、フレッシュレーンと更新レーンの両方の前に、parallels-linux-smoke.sh と同じ Ubuntu フォールバックポリシーで Linux VM を解決する必要があります。正確なデフォルト VM が見つからない場合、メジャーバージョン >= 24 の Ubuntu ゲストを許容可能として扱い、フレッシュな poweroff スナップショットを持つ最新のバージョン付き Ubuntu ゲストを優先します。本日時点の Peter の現在のホストでは、Ubuntu 26.04 を使用します。
• macOS の同一ゲスト更新チェックでは、npm アップグレード後に gateway status / agent の前にゲートウェイを再起動します。そうしないと、launchd が古いプロセスは終了済みで新しいプロセスはまだ RPC 対応していないのに、ロード済みサービスとして報告する可能性があります。
• npm-update 集約の macOS 更新レッグは、ゲスト更新スクリプトを root として書き込み、その後デスクトップユーザーとして実行します。prlctl exec "$MACOS_VM" --current-user ... が認証できない場合は、プレーンな root の prlctl exec に加えて sudo -u <desktop-user> /usr/bin/env HOME=/Users/<desktop-user> USER=<desktop-user> LOGNAME=<desktop-user> PATH=/opt/homebrew/bin:/opt/homebrew/opt/node/bin:/usr/bin:/bin:/usr/sbin:/sbin ... で再試行してください。これは Parallels トランスポートのフォールバックです。それでも更新後に openclaw --version、ゲートウェイ RPC、およびエージェントターンを検証してください。
• Windows の同一ゲスト更新チェックでは、npm アップグレード後に gateway status / agent の前にゲートウェイを再起動します。そうしないと、インプレースのグローバル npm 更新により、実行中のサービスに古いハッシュ付き dist/* モジュールインポートが残ったままになる可能性があります。
• これらの Windows 同一ゲスト更新チェックでは、1 回の非ゼロの openclaw gateway restart を決定的な失敗として扱わないでください。現在のログイン項目の再起動では、バックグラウンドサービスが再び観測可能になる前に失敗を報告する可能性があります。より長い RPC 対応待機を続け、それでもレディネスが戻らない場合にのみ gateway start をリカバリ手順として使用してください。
• その Windows 再起動後、固定スリープ後の 1 回の gateway status --deep --require-rpc 呼び出しを信用しないでください。RPC 対応プローブを約 30 秒間再試行し、各試行をログに記録します。現在のゲストでは、新しい RPC エンドポイントがまだ起動中でもポート 18789 がバインドされたままになる可能性があります。
• Windows の同一ゲスト更新チェックでは、長時間存続する prlctl exec ... powershell -EncodedCommand ... トランスポートよりも、done-file/ログドレイン方式の PowerShell ランナーパターンを優先します。外側の prlctl exec がまだハングしている間に、ゲストが正常に完了する可能性があります。
• Windows 同一ゲスト更新ヘルパーは、tgz ダウンロードや npm install -g などの長いステップの前にステージマーカーをログに書き込むべきです。そうすることで、外側の進捗モニターが、正常だが静かなインストール中に waiting for first log line のまま留まることがなくなります。
• Linux の同一ゲスト更新検証では、HOME=/root をエクスポートし、prlctl exec ... /usr/bin/env 経由で OPENAI_API_KEY を渡し、openclaw agent --local を使用する必要もあります。フレッシュな Linux ベースラインは永続化されたゲートウェイ認証情報に依存しません。
• npm-update ラッパーは現在、ネストされたログファイルからレーンごとの進捗を出力します。レーンがまだスタックしているように見える場合は、外側のラッパーがハングしたと決めつける前に、まず runDir 内のネストされたログ（macos-fresh.log、windows-fresh.log、linux-fresh.log、macos-update.log、windows-update.log、linux-update.log）を確認してください。
• 各実行は summary.json と summary.md の両方を書き込みます。迅速な人手によるトリアージにはまず markdown を読み、自動化には JSON/タイミングを読みます。
• タグ公開後の完全な beta 検証には、1 つのコマンドを推奨します:
  • timeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta3 --json これは beta3 を最新の *-beta.3 バージョンに解決し、latest->そのバージョンの同一ゲスト更新カバレッジを実行し、次に同じ選択された OS マトリクス上でその正確な公開ターゲットのフレッシュインストールスモークを実行します。再実行を絞り込むには --platform macos|windows|linux を使用します。
• エージェントターンを伴う beta 4 npm 検証の既知の正常な形式は次のとおりです:
  • gtimeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta4 --model openai/gpt-5.4 --json 特定のプレリリース番号を検証する場合は、openclaw@beta よりも明示的な beta4 エイリアスを優先してください。npm タグは移動する可能性があります。
• ラッパーがレーンを失敗させた場合、まず自動ダンプされた tail を読み、次に .artifacts/parallels/openclaw-parallels-npm-update.* 配下の完全なネストされたレーンログを読みます。
• フォールバックが欠落しているかバイパスされている場合の、現在知られている macOS 更新レーンのトランスポートシグネチャ: Unable to authenticate the user. Make sure that the specified credentials are correct and try again. これは npm や OpenClaw を疑う前に、Parallels の current-user 認証として扱ってください。
• グローバルパッケージディレクトリやバンドルファイルのモードが 0777 の macOS パッケージ版フレッシュインストールは、通常、ハーネスが寛容な umask の下で root の prlctl exec フォールバックを使用したことを意味します。POSIX ゲストトランスポートは umask 022 を先頭に付加する必要があります。npm を疑う前に、フェーズのプリフライト行を確認してください。

CLI 呼び出し時の注意点

• Parallels のスモークテスト用シェルスクリプトでは、単独のリテラル -- 引数を受け入れる必要があります。これにより、pnpm test:parallels:* -- --json などの引数転送を伴う呼び出しが、bash scripts/e2e/... を直接実行しなくても機能します。

macOS ゲストコマンドの転送

macOS のスモークテストと同一ゲスト内での更新レーンでは、 scripts/e2e/parallels/parallels-exec.py を通じてゲストコマンドを実行します。 macOS ホストには、標準ライブラリを含む python3 が必要です。検証済みの Parallels 27.0.0（58628）および 27.0.2（58673）の Apple シリコン搭載環境では、 クライアントが結果の抽出まで SDK のログインジョブハンドルを保持するため、 ホスト CLI で断続的に発生する PrlJob_GetRetCode: Invalid argument エラーを回避できます。このエラーは、ゲストの再インストールや Parallels Tools の再更新が必要であることを示すものではありません。

選択時には、実行前に PATH 上の実際の prlctl とインストール済み CLI のダイジェストを確認します。ほかのバイナリでは通常の prlctl を使い、SDK の失敗後に別の転送方式で再試行することはありません。root／現在のユーザーの選択、シェル引数のそのままの結合、stdin、stdout／stderr、ゲストの終了ステータスは維持されます。シェルのクォートは引き続き呼び出し元が行います。UUID を単独で指定した場合は、CLI の中括弧付き検索形式を使います。その UUID が見つからない場合、クライアントはゲストコマンドを実行する前に、元のリテラルな VM 名を一度だけ確認します。それ以外の検索失敗は処理を終了します。スナップショットの作成／開始／停止／入力／キャプチャ、および Linux／Windows での実行に変更はありません。

所有権がすでにあり、実行中の macOS ゲストでは、同じ転送方式を直接確認できます。

python3 -B scripts/e2e/parallels/parallels-exec.py --timeout-ms 30000 -- exec "<owned-macos-vm>" --current-user /bin/echo ready

レーン全体には、引き続き外側のホスト側タイムアウトを設定してください。SDK の待機期限は、ゲストプロセスの終了を示すものではありません。これは範囲を限定した回避策であり、サポート対象の公開 SDK 統合ではありません。インストール済みバイナリのダイジェストを追加する前に、ABI と実際のコマンド／stdio／クリーンアップ動作を再検証してください。ベンダーが修正した CLI を検証した後は、この回避策を削除してください。アドホックな検証後は、元のスナップショットに戻し、ゲストを停止してください。

macOS のフロー

• 推奨するエントリーポイント：pnpm test:parallels:macos
• parallels-macos-smoke.sh --mode fresh --target-package-spec openclaw@<version>は、インストールのスモークテストのみを行います。macOSで公開済みの旧バージョンから新バージョンへの更新を検証する場合は、--platform macosを指定したnpm更新ラッパーを優先してください。parallels-macos-smoke.sh --mode upgrade --target-package-spec ...は対象パッケージをインストールしますが、ベースラインCLIのアップデーターは検証しません。
• macOSでのデフォルトの更新検証には、次の手順を含めるようにしてください。新規スナップショット -> 最新の安定版タグを固定したサイトインストーラー -> ゲスト上でのopenclaw update --channel dev。これはオプションの追加作業ではなく、デフォルトのTahoe回帰テスト計画の一部として扱ってください。
• parallels-macos-smoke.sh --mode upgradeでは、デフォルトでこのリリースからdevへのレーンを実行してください。従来のホストtgz更新パスを維持するのは、呼び出し元が--target-package-specを明示的に指定した場合のみです。
• デフォルトの更新レーンではホストtgzが不要になったため、--target-package-specが設定されていない場合は、--mode upgradeでnpm packとホストHTTPサーバーの起動をスキップしてください。freshとbothでは、pack／サーバーのパスを維持してください。
• このリリースからdevへのレーンがreason=preflight-no-good-commitで失敗し、preflight buildの末尾にsh: pnpm: command not foundが繰り返し出る場合は、まずアップデーターの回帰として扱ってください。修正すべき箇所はGit/devアップデーターのブートストラップパスであり、Parallelsのリトライロジックではありません。
• 公開版の安定リリースにこのアップデーターのブートストラップ修正が含まれるまでは、macOSのリリースからdevへのレーンで、openclaw update --channel devの直前にゲスト内の一時的なpnpmシムを配置してもかまいません。この回避策はスモークテスト用ハーネスに限定し、最新の安定版で不要になったら削除してください。
• Tahoeでprlctl exec --current-userを実行する場合、リリースからdevへの引き継ぎと更新後の検証には、明示的なnode .../openclaw.mjs ...の呼び出しを優先してください。shebang付きのグローバルopenclawラッパーはenv: node: No such file or directoryで失敗することがあります。また、ラッパーを通じた自己更新は、固定したnodeの下でエントリーポイントを呼び出す方法より確実性の低いレーンです。
• macOS 26.5 latestに最も近いスナップショットをデフォルトにしてください。
• PeterのTahoe VMでは、fresh-latest-march-2026のprlctl snapshot-switchがハングすることがあります。復元がタイムアウトした場合は、認証やハーネスを疑う前に、--snapshot-hint 'macOS 26.5 latest'を指定して再実行してください。
• parallels-macos-smoke.shは、実行中または一時停止中のゲストを強制終了した後、snapshot-switchを1回リトライするようになりました。この復旧手順を実行してもTahoeがタイムアウトする場合は、実際のParallels／ホストの問題として扱い、手動で再実行してください。
• macOSのスモークテストには、ゲートウェイのヘルスチェック後にダッシュボードの読み込みフェーズを含めてください。トークン付きURLをopenclaw dashboard --no-openで解決し、配信されたHTMLにControl UIのタイトルとルートシェルが含まれていることを確認してからSafariを開き、Safariからゲートウェイポートへのlocalhost TCP接続が確立されていることを必須条件にしてください。
• Tahoeのfresh.gateway-statusでは、非TTYのprlctl exec --current-user ... openclaw gateway status ...を使い、短いリトライを数回行う方法を優先してください。CLI自体が正常でも、prlctl enterはTTY制御バイトを大量に出力し、フェーズのログを停止させることがあります。
• Tahoeのレーンがfresh.first-agent-turnでタイムアウトし、models setからの__OPENCLAW_RC__:0の直後にフェーズログが止まる場合は、認証やモデルのレーンを疑う前に、prlctl enter／expectラッパーを疑ってください。このパターンは、ゲスト内の最初のコマンドが完了したものの、次のguest_current_user_cli呼び出しに進む前にトランスポートが解放されていないことを示します。
• パッケージ済みインストールでfresh.install-mainまたはupgrade.install-mainの後に/、/healthz、または__openclaw/control-ui-config.jsonが500を返すようになった場合は、バンドルされたプラグインの実行時依存関係がdist/extensions/*/node_modulesではなくパッケージルートのnode_modulesから解決されている可能性を疑ってください。ダッシュボードの認証やSafariを疑う前に、実際のnpm pack／グローバルインストールのレーンですぐに再現を確認してください。
• 決定論的なリポジトリコマンドにはprlctl execを使って問題ありませんが、インストーラーとの同等性やシェルに依存する動作が重要な場合は、ゲストのターミナルまたはprlctl enterを使用してください。
• 複数の単語を含むopenclaw agent --message ...のチェックは、ゲストのシェルラッパー（guest_current_user_sh／guest_current_user_cliまたは/bin/sh -lc ...）経由で実行してください。prlctl exec ... node openclaw.mjs ...を直接使うと、メッセージが複数のargvトークンに分割され、Commanderがtoo many arguments for 'agent'を報告することがあります。
• --current-userを回避する場合も、同じラッパーのルールが適用されます。ゲスト上に小さな/tmp/*.shファイルを書き込み、sudoのデスクトップユーザー環境を通じて/bin/bash /tmp/*.shを実行してください。openclaw agent --message '...'を1つのコマンドとして、prlctl execに直接渡してはいけません。
• refモードのオンボーディングでOPENAI_API_KEYを環境変数のシークレット参照として保存する場合、オンボーディング後のエージェント検証コマンドでもOPENAI_API_KEYをエクスポートしてください。ゲートウェイがpairing-requiredを返して埋め込み実行にフォールバックすることがあります。そのフォールバックでは、シェルから環境変数経由の認証情報を利用できる必要があります。
• Tahoeの新規スナップショットではbrewは存在しますが、非対話型のexecではnodeがPATHにないことがあります。必要に応じて/opt/homebrew/bin/nodeを使用してください。
• ホスト配信の新規tgzインストールは、ゲストのrootとしてHOME=/var/rootを設定してインストールし、その後prlctl exec --current-user経由でデスクトップユーザーとしてオンボーディングを実行してください。
• rootでインストールしたtgzのスモークテストでは、extensions/*が全ユーザーに書き込み可能なため、プラグインブロックがログに出ることがあります。プラグインの読み込み自体がタスクでない限り、オンボーディングやゲートウェイの失敗として扱わないでください。

Windows フロー

• このリポジトリは、リモートの prlctl による管理、クリーン状態の確認、WSL 2、Git／Node、スナップショットの作成と復元、OpenClaw のスモークテストなど、Windows VM の一般的なライフサイクルを担います。Parallels Desktop がインストールされてライセンス認証済みで、Windows 11 VM がダウンロード済みであることを前提として、次を実行します。

  pnpm test:parallels:windows:prepare -- inventory
  pnpm test:parallels:windows:prepare -- prepare
  pnpm test:parallels:windows:prepare -- verify
  

• prepare は変更を加える前に状態を調査し、Parallels Tools とログイン済みのデスクトップセッションを必須とします。また、OpenClaw CLI／アプリ／トレイ／プロセスの状態と WSL ディストリビューションが存在する場合は処理を拒否し、未準備のゲストに限り、日付入りの電源オフ状態のクリーン OS スナップショットを作成します。さらに、WSL／Virtual Machine Platform を有効にし、署名済みの Microsoft WSL パッケージをインストールして、WSL 2 を既定に設定し、Git と Node／npm をインストールします。その後、Windows ハイパーバイザーが有効で再起動が保留されていないことを確認し、電源オフ状態の pre-openclaw-native-e2e-<date> スナップショットを作成します。

• 本日の E2E スナップショットがすでに存在する場合、prepare は名前をそのまま信頼せず、そのスナップショットを復元して検証します。明示的な復元と同様に、prepare はスナップショット作成後にゲストへ加えられた変更を破棄する操作として扱ってください。

• パッケージの昇格処理では、Microsoft の公式 WinGet マニフェストから正確なバージョンと SHA-256 を取得し、想定される Authenticode の発行元を検証してから、新たに ACL を制限した SYSTEM ディレクトリへコピーして実行します。この汎用的な仕組みはここで維持し、コンパニオン固有のパッケージ選定は Windows アプリのリポジトリに置いてください。

• clean、e2e、正確な名前、または ID を指定して復元します。

  pnpm test:parallels:windows:prepare -- restore --snapshot e2e
  

• 復元すると、スナップショット以降の変更はすべて破棄されます。まずインベントリを確認し、別の開発者やレーンが VM を使用している間は復元しないでください。e2e は最新の pre-openclaw-native-e2e-* を選択します。過去の状態を再現する場合は、正確なスナップショット名を指定してください。

• ネイティブコンパニオンの作業では、../../../../openclaw-windows-node/.agents/skills/openclaw-proof-validation/PARALLELS.md を読んでください。このオプションの macOS サイドカーは同じコントローラーを再利用し、.NET、Windows SDK、WebView2、アプリのチェックアウト、アプリレイヤーのスナップショット、ビルド／テスト、ネイティブの検証のみを追加します。

• 推奨エントリーポイント：pnpm test:parallels:windows

• 最新の検証済み pre-openclaw-native-e2e-* スナップショットを使用し、その正確な名前を --snapshot-hint で渡してください。

• Windows でのデフォルトのアップグレードテストには、今後、次の内容を含めてください：新規スナップショット -> 指定された安定版タグに固定したサイトインストーラー -> ゲスト上での openclaw update --channel dev。呼び出し元が明示的に --target-package-spec を渡した場合に限り、従来のホスト側 tgz アップグレードパスを使用してください。

• Windows で npm タグを正確に指定するオプションのベースライン：bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --target-package-spec openclaw@<tag> --json。このレーンでは、公開済みの npm tarball をベースラインとしてインストールした後、openclaw update --channel dev を実行します。

• Windows のフォワードフィックス検証（オプション）：bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --upgrade-from-packed-main --json。このレーンでは、パックした現在の main の npm tgz をベースラインとしてインストールした後、openclaw update --channel dev を実行します。

• 必ず prlctl exec --current-user を使用してください。通常の prlctl exec では NT AUTHORITY\\SYSTEM で実行されます。

• npm.cmd と openclaw.cmd を明示的に指定することを推奨します。

• PowerShell は -ExecutionPolicy Bypass を指定したトランスポートとしてのみ使用し、その中から .cmd シムを呼び出してください。

• 現在の Windows Node インストールでは、corepack は .cmd シムとして公開されています。リリースから dev へのレーンで PATH 上に corepack があるのに openclaw update --channel dev が corepack が見つからないかのように動作する場合は、まず exec シムのリグレッションとして扱ってください。

• npm タグを正確に指定した Windows レーンで、npm run build と 'pnpm' is not recognized によりプリフライト中に失敗した場合は、ゲストがまだ古い公開済みアップデーターを実行していることに注意してください。--upgrade-from-packed-main で修正を検証し、過去のタグのレーンが成功することを期待する前に、次の npm タグ付きリリースを待ってください。

• 複数語の openclaw agent --message ... チェックは、PowerShell 内で Start-Process ... -ArgumentList を使って openclaw.cmd を呼び出すのではなく、& $openclaw ... を使用してください。そうしないと Commander が argv の分割を誤認し、too many arguments for 'agent' をスローすることがあります。

• Windows インストーラー／tgz フェーズでは、ゲストの準備完了を再確認した後に 1 回再試行するようになりました。新しい Windows スモーク手順は冪等にし、トランスポートの一時的な不具合があっても安全に再試行できるようにしてください。

• Windows の再試行時に VM が suspended または stopped になっていた場合は、次の prlctl exec の前に再開または起動してください。そうしないと、2 回目の試行でも同じ rc=255 が繰り返されます。

• Windows のグローバルな npm install -g フェーズは、正常でも 1 分以上出力がない場合があります。ハングと判断する前にフェーズログを確認し、再試行ラッパーまたはタイムアウトが作動した場合にのみリグレッションとして扱ってください。

• Windows のグローバルインストールで出力がない間、有用な進捗情報はヘルパーのフェーズログではなく、ゲストの npm デバッグログにあることがよくあります。スモークスクリプトは、ベースライン／パッケージのインストールが長時間にわたる間、npm-cache/_logs/*-debug-0.log の差分をフェーズログへ逐次出力するようになりました。レーンが停止したと判断する前に、その行を確認してください。

• Windows のベースラインパッケージヘルパーは、タイムアウト時またはゼロ以外のコードで完了した際に、最新のゲストの npm-cache/_logs/*-debug-0.log の末尾を自動的に出力するようになりました。2 つ目のゲストシェルを開く前に、フェーズログでその末尾を確認してください。

• 同じ npm デバッグログの逐次出力は、--upgrade-from-packed-main／パッケージインストールのベースラインフェーズにも適用されます。フェーズログに install.start、install.download-tgz、install.install-tgz だけが表示されていても、npm デバッグログにレジストリーからの取得やバンドルされたプラグインの postinstall 処理が記録されていれば、正常に進行している場合があります。

• Windows の新規 tgz インストールフェーズでも、バックグラウンド PowerShell ランナーと完了ファイル／ログ排出パターンを使用してください。パッケージのインストールに、長時間稼働する単一の prlctl exec ... powershell ... npm install -g トランスポートを使用しないでください。

• Windows のリリースから dev へのヘルパーでは、更新の前後に where pnpm を記録し、更新後にも where pnpm が成功することを必須にしてください。これにより、アップデーター自体が pnpm をインストールまたは有効化したことを確認でき、スモークテスト専用のブートストラップに依存していないことを証明できます。

• Windows の新規 ref モードのオンボーディングでは、npm 更新ヘルパーと同じバックグラウンド PowerShell ランナーと完了ファイル／ログ排出パターンを使用してください。起動時のマテリアライズ確認、短いポーリングの prlctl exec 呼び出しに対するホスト側タイムアウト、一時的なトランスポートの不具合に対するポーリング失敗時の再試行動作も含めてください。

• Windows の新規デーモンヘルス到達可能性チェックでは、より長いタイムアウトを設定した openclaw gateway probe --json を使用し、ok: true を成功として扱ってください。現行 main では、初回起動時に完全な gateway status --require-rpc チェックを行うと性急すぎます。

• Windows の新規 ref モードのエージェント検証では、macOS と同じペアリング必須のフォールバック理由により、openclaw.cmd agent の呼び出し前に PowerShell の環境変数として OPENAI_API_KEY を設定してください。

• スタンドアロンの Windows アップグレードスモークレーンでは、upgrade.install-main の後、upgrade.onboard-ref の前に、管理対象のゲートウェイを停止してください。オンボーディング前に再起動すると、古いプロセスがオンボーディング前のトークンで実行されたままになり、オンボーディングによって ~/.openclaw/openclaw.json が書き換えられ、その後 gateway-health が unauthorized: gateway token mismatch で失敗することがあります。

• スタンドアロンの Windows アップグレードがゲートウェイトークンの不一致で失敗しても、pnpm test:parallels:npm-update が成功する場合は、まず不一致をスタンドアロンの ref オンボーディング順序のバグとして扱ってください。npm 更新ヘルパーは同じゲスト上で ref モードのオンボーディングを再実行しません。

• ログのオンボーディングおよびステータス出力は ASCII のみを使用してください。現在のキャプチャーパスでは、装飾的な句読点が文字化けします。

• 古い実行で rc=255 が発生し、fresh.install-main.log または upgrade.install-main.log が空の場合は、npm／パッケージの失敗を示す証拠と即断せず、ゲストの起動後に prlctl exec のトランスポートが切断された可能性が高いと判断してください。

• WSL の機能が有効なのに wsl.exe --version が失敗する場合は、prepare を再実行してください。標準搭載の機能と署名済み WSL パッケージは別々の前提条件です。既定値が 1 に戻る場合は、wsl.exe --set-default-version 2 を設定して verify を再実行してください。

• winget が切断される、または prlctl 経由で何も出力されない場合は、cmd.exe /d /s /c 経由で呼び出してください。リモート UAC は避けてください。デスクトップユーザーとしてダウンロードした後、コントローラーで信頼済みマニフェストのハッシュ／発行元を検証し、保護された SYSTEM ステージングディレクトリからインストールしてください。

• スナップショットの復元で保存済み CPU 状態との互換性がないと報告された場合は、既知の正常なディスク状態から電源オフ状態の代替スナップショットを作成し、その正確な名前を使用してください。2 レーンの新規インストール＋アップグレードの検証を主張する場合に、スナップショットの復元を決して回避しないでください。

• ベースライン検証で OpenClaw の状態が報告された場合は、clean を復元するか、製品の状態を意図的に削除してください。汚れたゲストを正常なものとして扱わないでください。安定版と dev の両方のコンパニオン ID、および Inno のアンインストール登録について、%APPDATA% と %LOCALAPPDATA% を確認してください。

• Windows のインストーラーは、正常でも長時間出力がない場合があります。ハングと判断する前に tasklist とインストーラー／MSI ログを確認してください。長時間の操作は、ホスト側で時間を制限した短いポーリング呼び出しを使うバックグラウンドランナーで実行してください。

Linux フロー

• 推奨エントリーポイント：pnpm test:parallels:linux
• 最新バージョンの Ubuntu ゲストを使用し、電源オフ直後のスナップショットを使います。Peter のホストでは現在、Ubuntu 26.04 です。
• 指定された Ubuntu VM がホストにない場合は、メジャーバージョンが 24 以上の Ubuntu ゲストであれば使用できます。古いフォールバックスナップショットより、最新バージョンの Ubuntu ゲストを優先してください。
• prlctl exec をそのまま使用してください。このスナップショットでは --current-user は適切なトランスポートではありません。
• 新しいスナップショットには curl がない場合があり、時刻のずれによって apt-get update が失敗することがあります。apt-get -o Acquire::Check-Date=false update でブートストラップし、curl ca-certificates をインストールしてください。
• 新しい main の tgz スモークでは、ブートストラップ前のスナップショットに Node も npm もないため、まず最新リリースのインストーラーを実行する必要があります。
• このスナップショットには利用可能な systemd --user セッションがありません。マネージドデーモンのインストールには対応していません。
• Linux のスモークでは、HOME=/root を設定し、プロバイダーのシークレットをエクスポートしたうえで、手動の setsid openclaw gateway run --bind loopback --port 18789 --force 起動にフォールバックするようになりました。その後、利用可能な場合は gateway status --deep --require-rpc を検証します。
• Linux の手動ゲートウェイ起動では、gateway-start フェーズ内で gateway status --deep --require-rpc の結果を待つ必要があります。そうしないと、最初のステータス確認がバックグラウンドのバインドと競合し、正常なレーンでも失敗することがあります。
• Linux のゲートウェイ起動に失敗した場合は、まずゲストのフェーズログにある /tmp/openclaw-parallels-linux-gateway.log を確認してください。よくある失敗原因は、起動したゲートウェイ環境にプロバイダーのシークレットがないことです。

Discord のラウンドトリップ

• Discord のラウンドトリップは任意です。次のオプションを指定して有効にしてください。
  • --discord-token-env
  • --discord-guild-id
  • --discord-channel-id
• Discord のスモーク／ラウンドトリップが成功したら、引き渡し前にゲスト VM をシャットダウンしてください（prlctl stop "$VM_NAME" または具体的な VM 名を指定します）。macOS のスモークハーネスは、Discord の証明が成功した後に自動でシャットダウンする必要があります。それでも、アドホックな Discord チェックの後は手動で VM を停止してください。Discord を設定したゲストを起動したままにしないでください。証明が完了した後も #maintainer の読み取りや投稿を続け、Discord にスパムを送る可能性があります。
• Discord トークンはホストの環境変数にのみ保持してください。
• node openclaw.mjs message ... ではなく、インストール済みの openclaw message send/read を使用してください。
• channels.discord.guilds は、snowflake を使ったドット区切りの設定パスではなく、1 つの JSON オブジェクトとして設定してください。
• 長時間実行される prlctl enter や expect 主導の Discord 設定スクリプトは避け、短いコマンドで prlctl exec --current-user /bin/sh -lc ... を使用してください。
• macOS のみを対象とする、より範囲を絞った Discord の証明を実行する場合は、既存の parallels-discord-roundtrip スキルを詳細調査用の補助資料として利用できます。