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 / 即時提供者驗證、跨作業系統驗證、UI 驗證，或會拖慢本地機器的命令，則轉移到 Crabbox。

驗證與設定

代理操作需要協調器 URL 和令牌。首次登入通常需要明確的代理 URL：

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

在配置 broker.url 之後，crabbox login 可以重複使用它。受信任的操作者自動化可以儲存共享令牌，而無需將其放在命令列參數中：

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

設定優先順序為 標誌 > 環境變數 > 儲存庫設定 > 使用者設定 > 預設值。 使用者的預設設定檔位置：macOS 為 ~/Library/Application Support/crabbox/config.yaml，Linux 為 ~/.config/crabbox/config.yaml，或設定 $XDG_CONFIG_HOME 時為 $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、螢幕截圖和工件。

如果遠端驗證被阻斷，請精確指出缺失的能力：驗證、協調器、容量、提供者支援、目標作業系統、水合、機密存取、工件儲存、桌面支援或委派提供者的限制。

常見的遠端驗證

一次性命令：

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，並從頭開始上傳簽出。

腳本、Shell 與 Windows 目標

對於單一可執行檔，在 -- 之後使用純 argv。對於多語句的 Shell 片段、管道或 Shell 展開，請使用 --shell：

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

對於多行命令，優先使用上傳的腳本。腳本包含在失敗套件中，並避免脆弱的引號 Shell 字串：

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 需要第 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 要求、工件 glob 模式、必要工件和驗證範本。請使用它們來建立穩定的驗證通道，而不是將專案知識編碼到 agent 提示中。

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

如果遠端命令以退出碼 0 結束，但驗證檔案缺失，則 --require-artifact 會使執行失敗。保持必要工件的範圍和內容清理；不要收集原始資料集、機密、憑證、簽署的 URL 或未經遮罩處理的客戶資料。

執行控制代碼與可觀測性

由協調器支援的執行會在租賃開始之前列印一個持久的 run_... 控制代碼。請在狀態更新和 PR 註解中保留此執行 ID。

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。命令可以透過在標準輸出或標準錯誤上列印標記來標記子階段：

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

輸出事件是受限的預覽。請使用 logs 來獲取保留的輸出尾部，使用 results 來獲取解析後的測試摘要。

桌面、WebVNC 與 UI 驗證

建立桌面/瀏覽器租賃以進行視覺品質驗證、有頭瀏覽器自動化或 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 作業系統選擇器（如果提供者目錄支援）。僅當測試必須保留在先前的 LTS 版本上時，才使用 --os ubuntu:24.04。明確的提供者映像標誌仍然優先於 --os。

對於人工展示，優先使用 WebVNC 而非原生 VNC，因為 crabbox webvnc --open 會在瀏覽器片段中預先載入租賃密碼：

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、桌面、瀏覽器、快取磁碟區和清理。

委派執行提供者擁有命令傳輸的控制權。預期它們會拒絕 SSH 執行功能，例如 --capture-stdout、--capture-stderr、--capture-on-fail、--script、--script-stdin、--fresh-pr、本地擷取、--download、--full-resync 和 --env-helper，除非 crabbox providers --json 和提供者文件宣傳了匹配的能力。對於那些否則 Crabbox 會在失敗命令後停止的一次性委派提供者，--keep-on-failure 仍然很有用。

模組執行階段委派提供者，支援…

[已截斷以進行翻譯]