openclaw/crabbox

crabbox は何をしますか？

プロジェクトがリモートでの検証、より大きなクラウドキャパシティ、新しいPRのチェックアウト、再利用可能なウォームボックス、GitHub Actions風のセットアップ、耐久性のある実行ログ/結果、UI証明アーティファクト、またはダーティなローカルチェックアウトからの同期を必要とする場合にCrabboxを使用します。

Crabboxの検出

• リポジトリルートにある crabbox.yaml または .crabbox.yaml は、検証作業にこのスキルを使用する意図的なシグナルとして扱います。.crabbox.yml はサポートされている設定ファイル名ではありません。
• どちらの設定ファイルも存在しない場合でも、command -v crabbox はインストールされたCLIを識別します。リモート作業に依存する前に crabbox doctor を実行してください。
• 設定を実行する前に検査してください。検出は、シークレットの公開、コマンド承認のバイパス、または有料インフラの起動を許可するものではありません。

信頼できる情報源

• リポジトリルートからCrabboxを実行します。同期は現在のチェックアウトをミラーリングします。
• リポジトリローカルの crabbox.yaml または .crabbox.yaml は、実行可能なプロジェクト自動化として扱います。リモート実行の前に、特に provider、actions、jobs、profiles、env.allow、アーティファクト、クリーンアップポリシーを確認してください。
• 例に依存する前に、インストールされたバイナリを確認します：command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'
• 現在のプロバイダー/機能マトリックスには crabbox providers または crabbox providers --json を使用します。プロバイダーのドキュメントはコンパイルされたバイナリより遅れる場合があります。
• ライブでの準備状態確認には crabbox doctor を、マージされた設定をシークレットを表示せずに検査するには crabbox config show を使用します。
• タイトな編集ループにはローカルのターゲットテストを優先します。広範なスイート、パッケージの重いチェック、Docker/E2E/ライブプロバイダーの証明、クロスOSの証明、UIの証明、またはローカルマシンの負荷になるコマンドにはCrabboxに移行します。

認証と設定

仲介操作にはコーディネーターのURLとトークンが必要です。初回ログインは通常、明示的なブローカーURLが必要です：

crabbox login --url <broker-url>
crabbox whoami
crabbox doctor

broker.url が設定された後は、crabbox login でそれを再利用できます。信頼できるオペレーター自動化では、共有トークンをargvに載せずに保存できます：

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" |
  crabbox login --url <broker-url> --provider aws --token-stdin

設定の優先順位は flags > env > repo config > user config > defaults です。デフォルトのユーザー設定は、macOSでは ~/Library/Application Support/crabbox/config.yaml、Linuxでは ~/.config/crabbox/config.yaml、または $XDG_CONFIG_HOME/crabbox/config.yaml が設定されている場合にそのパスになります。crabbox config path はアクティブなユーザー設定パスを出力します。

プロバイダーとブローカーのトークンは、リポジトリ設定やコマンド引数に保持しないでください。環境変数、資格情報ストア、コーディネーター管理のシークレット、または短期間のトークンコマンドを使用してください。

リモートサーフェスの選択

• crabbox run -- <command>：新しいまたは再利用されたボックスで単一のコマンドを実行します。
• crabbox warmup：再利用可能なリースを作成し、後で --id を使用してコマンドを実行します。
• crabbox prewarm：再利用可能なリースをウォームアップし、設定されたGitHub Actionsからハイドレートします。
• crabbox job run <name>：ウォームアップ、オプションのハイドレート、実行、停止に展開されるリポジトリローカルの名前付きフローを使用します。
• crabbox run --pool <key>：ハイドレートされたブローカーの準備プールリースを借用し、--pool-return に従って実行/返却/ドレイン/解放します。
• crabbox run --fresh-pr ...：ローカル同期を無視し、リモートでGitHub PRをチェックアウトします。--apply-local-patch を追加して、そのPRの上にローカルの未コミット変更をテストします。
• crabbox run --provider ssh：既存のmacOS、Linux、またはWindowsホストを使用します。
• crabbox warmup --desktop --browser：UIテスト、WebVNC、スクリーンショット、アーティファクトのために、可視のデスクトップ/ブラウザをプロビジョニングします。

リモート証明がブロックされた場合は、不足している機能を正確に指定します：認証、コーディネーター、キャパシティ、プロバイダーサポート、ターゲットOS、ハイドレーション、シークレットアクセス、アーティファクトストレージ、デスクトップサポート、または委任プロバイダーの制限。

一般的なリモート証明

ワンショットコマンド：

crabbox run --preflight --timing-json -- pnpm test

リースをウォームアップして再利用：

crabbox warmup --class beast --idle-timeout 90m
crabbox status --id <cbx_id-or-slug> --wait
crabbox run --id <cbx_id-or-slug> -- pnpm test:changed
crabbox run --id <cbx_id-or-slug> --full-resync -- pnpm test:changed
crabbox stop <cbx_id-or-slug>

設定されている場合はリポジトリローカルジョブを使用：

crabbox job list
crabbox job run --dry-run <job-name>
crabbox job run <job-name>
crabbox job run --id <cbx_id-or-slug> <job-name>

コーディネーターにハイドレートされたプールキャパシティがある場合は準備プールリースを使用：

crabbox pool ready
crabbox run --pool <pool-key> -- pnpm test
crabbox run --pool <pool-key> --pool-return drain -- pnpm test:flaky

リポジトリがCIですでにセットアップを所有している場合はGitHub Actionsハイドレーションを使用：

crabbox warmup --idle-timeout 90m
crabbox actions hydrate --id <cbx_id-or-slug>
crabbox run --id <cbx_id-or-slug> -- pnpm test

ワークフローが完全なGitHub Actionsセマンティクス（リポジトリシークレット、OIDC、サービスコンテナ、ジョブコンテナ、サポートされていない uses: ステップなど）を必要とする場合にのみ --github-runner を使用：

crabbox actions hydrate --github-runner --id <cbx_id-or-slug>

同期と新しいチェックアウト

通常の同期は、追跡されたファイルと無視されていない未追跡ファイルを転送し、無視された依存関係/ビルド/キャッシュ出力を除外し、.crabboxignore と sync.exclude を尊重し、可能な場合は origin からリモートチェックアウトをシードし、同期フィンガープリントが一致する場合はrsyncをスキップします。

大規模な実行の前に crabbox sync-plan を使用します。予期しないカウントは通常、ローカルの生成チャーンを意味します。巨大なアップロードを強制する代わりに、.crabboxignore または sync.exclude を更新してください。

crabbox sync-plan
crabbox run --debug --timing-json -- pnpm test
crabbox run --full-resync -- pnpm test

ローカルの依存関係チャーンやダーティ同期が結果を混乱させる場合は、新しいPRチェックアウトを使用：

crabbox run --fresh-pr example-org/my-app#123 --script ./scripts/e2e-smoke.sh
crabbox run --fresh-pr 123 --apply-local-patch -- pnpm test

--fresh-pr は owner/repo#number、GitHub PR URL、または現在のGitHub originからの数値PRを受け入れます。非GitHubホストは拒否されます。新しいPRチェックアウトはSSH実行同期機能です。委任プロバイダーはそれを拒否します。ネイティブWindows SSHターゲットはサポートされています。

ウォームリースが古くなったと思われる場合は、--full-resync（エイリアス --fresh-sync）を優先して、リモート作業ディレクトリをリセットし、同期フィンガープリントの高速パスをスキップし、可能な場合はGitを再シードし、チェックアウトをスクラッチからアップロードします。

スクリプト、シェル、およびWindowsターゲット

単一の実行可能ファイルには -- の後にプレーンなargvを使用します。複数ステートメントのシェルスニペット、パイプ、またはシェル展開には --shell を使用：

crabbox run --id <lease> -- go test ./...
crabbox run --id <lease> --shell 'corepack enable && pnpm install --frozen-lockfile && pnpm test'

複数行のコマンドにはアップロードされたスクリプトを優先します。スクリプトは失敗バンドルに含まれ、壊れやすい引用符付きシェル文字列を回避します：

crabbox run --script ./scripts/e2e-smoke.sh --timing-json
printf '%s\n' 'echo CRABBOX_PHASE:test' 'pnpm test' | crabbox run --script-stdin

ネイティブWindowsターゲットはPowerShellとtarベースのマニフェスト同期を使用します。単一の実行可能ファイル（dotnet test など）にはプレーンなargvを優先し、複数ステートメントのPowerShellには --shell を、長いスクリプトには --script <file.ps1> を使用します。

Hyper-V Windows リース

hyperv はGeneration 2 VHDX、DHCP、および信頼された設定または CRABBOX_HYPERV_GUEST_PASSWORD に既知のローカル管理者パスワードが必要です。不足している場合、PowerShell Directを使用して、固定され検証されたOpenSSHおよびMinGitパッケージをインストールします。テンプレートとライフサイクルの詳細については docs/providers/hyperv.md を参照してください。

プロバイダーテストの場合、昇格されたヘッドレスランナーを優先します。初期のPowerShell Directの失敗は、資格情報UIを表示する可能性があります。パスワードを引数やログに保持せず、リースが準備完了になり、SSH経由で実行され、解放されることを確認します。

シークレットと環境変数の転送

Crabboxはローカル環境全体を転送しません。転送は名前ベースです。実際にローカルまたは許可されたプロファイルで設定されている許可リストに登録された名前のみが境界を越えます。実行が明示的なライブシークレットスモークテストでない限り、シークレットの形状をした名前の許可リスト登録は避けてください。

crabbox run --allow-env CI,NODE_OPTIONS -- pnpm test
crabbox run \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --preflight \
  --script ./scripts/live-smoke.sh

--env-from-profile は、プロファイルを実行せずに、単純な export NAME=value および NAME=value 行を解析します。Crabboxは値ではなく、編集された存在/長さのメタデータを出力します。POSIX SSHリースは、制御するリース上で後続のコマンドのためにヘルパーを永続化できます：

crabbox run \
  --id <lease> \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --env-helper live \
  -- true
crabbox run --id <lease> -- ./.crabbox/env/live ./scripts/live-smoke.sh

生成されたヘルパーと一致するシークレットプロファイルは、クリーンアップ、リースリセット、または --full-resync までリモート作業ディレクトリに残ります。共有リースや信頼できないリースにヘルパーを永続化しないでください。

プロファイル、プリセット、証明、結果

リポジトリ設定は、プロファイル、プリセット、doctor要件、アーティファクトグロブ、必須アーティファクト、証明テンプレートを定義できます。これらをエージェントプロンプトにプロジェクト知識をエンコードする代わりに、安定した検証レーンに使用します。

crabbox run \
  --profile live-qa \
  --preset qa-live \
  --scenario login-regression \
  --emit-proof /tmp/proof.md \
  --stop-after success

--preflight は、インストーラーとしてではなく、コマンドの前にターゲット機能のスナップショットを取得するために使用します。--preflight-tools を使用してプローブを調整します：

crabbox run --preflight --preflight-tools node,bun,docker -- bun test
crabbox run --preflight --preflight-tools default,uv -- node --test

コマンドが構造化された結果と証明アーティファクトを出力する場合に添付します：

crabbox run --junit reports/junit.xml -- ./scripts/test-with-junit.sh
crabbox run --artifact-glob 'reports/**' --require-artifact reports/summary.json -- pnpm test:e2e
crabbox run --download reports/summary.json=.crabbox/logs/summary.json -- pnpm test:e2e

--require-artifact は、リモートコマンドが0で終了したが証明ファイルが欠落している場合、実行を失敗させます。必須アーティファクトは制限され、スクラブされた状態に保ってください。生データセット、シークレット、資格情報、署名付きURL、または編集されていない顧客行を収集しないでください。

実行ハンドルと可観測性

コーディネーターバックアップの実行は、リース開始前に耐久性のある run_... ハンドルを出力します。その実行IDをステータス更新やPRノートに保持します。

crabbox history --limit 20
crabbox history --lease <cbx_id-or-slug> --limit 20
crabbox attach <run_id>
crabbox attach <run_id> --after <seq>
crabbox events <run_id> --after <seq> --limit 100
crabbox events <run_id> --json
crabbox logs <run_id>
crabbox results <run_id>

run、warmup、actions hydrate で安定した機械可読なタイミングレコードが必要な場合は --timing-json を使用します。コマンドは、stdoutまたはstderrにマーカーを出力することでサブフェーズをマークできます：

echo CRABBOX_PHASE:install
pnpm install --frozen-lockfile
echo CRABBOX_PHASE:test
pnpm test

出力イベントは上限付きのプレビューです。保持された出力テールには logs を、解析されたテストサマリーには results を使用します。

デスクトップ、WebVNC、およびUI証明

ビジュアルQA、ヘッドブラウザ自動化、またはUI証明のためにデスクトップ/ブラウザリースを作成します：

crabbox warmup --desktop --browser
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env gnome

ubuntu:26.04 は、プロバイダーカタログがサポートする場合のデフォルトのポータブルLinux OSセレクターです。テストが前のLTSに留まる必要がある場合にのみ --os ubuntu:24.04 を使用します。明示的なプロバイダーイメージフラグは引き続き --os よりも優先されます。

人間のデモでは、crabbox webvnc --open がブラウザフラグメントにリースパスワードをプリロードするため、ネイティブVNCよりもWebVNCを優先します：

crabbox webvnc --id <lease> --open --take-control
crabbox webvnc status --id <lease>
crabbox webvnc reset --id <lease> --open --take-control
crabbox vnc --id <lease> --open

入力自動化には、手書きの xdotool ではなく、ファーストクラスのヘルパーを使用します：

crabbox desktop doctor --id <lease>
crabbox desktop launch --id <lease> --browser --url https://example.com --webvnc --open --take-control
crabbox desktop click --id <lease> --x 640 --y 420
crabbox desktop paste --id <lease> --text "[email protected]"
printf '[email protected]' | crabbox desktop paste --id <lease>
crabbox desktop type --id <lease> --text "[email protected]"
crabbox desktop key --id <lease> ctrl+l
crabbox screenshot --id <lease> --output desktop.png

デスクトップ/WebVNCがハングした場合は、まずインラインの回復出力を信頼します。problem: および rescue: 行は通常、webvnc status/reset、desktop doctor、またはネイティブ vnc --open など、正確な次のコマンドを指定します。

UI証明のアーティファクトには、スクリーンショットやビデオを製品リポジトリブランチにコミットする代わりに、アーティファクトを使用します：

crabbox artifacts collect --id <lease> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <number>
crabbox artifacts list <artifact-manifest-url-or-dir>
crabbox artifacts pull <artifact-manifest-url-or-dir> --output /tmp/<slug>-proof

artifacts publish は、設定されている場合は仲介ストレージを使用し、そうでない場合は明示的なS3/R2 / Cloudflare/ローカルホスティングフラグを使用します。生成されたMarkdownやストレージコマンドをレビューする場合は、公開PRコメントの前に --dry-run を使用します。

プロバイダーの境界

SSHリースプロバイダーは、ターゲットがサポートする場合、完全な同期/実行サーフェスをサポートします：スクリプト、新しいPRチェックアウト、キャプチャ、ダウンロード、Actionsハイドレーション、SSH、ポート、WebVNC、code-server、デスクトップ、ブラウザ、キャッシュボリューム、クリーンアップ。

委任実行プロバイダーはコマンドトランスポートを所有します。crabbox providers --json とプロバイダードキュメントが一致する機能を宣伝しない限り、--capture-stdout、--capture-stderr、--capture-on-fail、--script、--script-stdin、--fresh-pr、ローカルキャプチャ、--download、--full-resync、--env-helper などのSSH実行機能を拒否することが予想されます。--keep-on-failure は、Crabboxが失敗したコマンドの後に停止するワンショット委任プロバイダーには依然として役立ちます。

モジュールランタイム委任プロバイダーは…

[翻訳のため省略]