openclaw/crabbox

Was macht crabbox?

Verwenden Sie Crabbox, wenn ein Projekt einen Remote-Nachweis, größere Cloud-Kapazitäten, einen frischen PR-Checkout, eine wiederverwendbare, vorgewärmte Box, eine GitHub-Actions-ähnliche Einrichtung, dauerhafte Ausführungsprotokolle/Ergebnisse, UI-Artefakte zum Nachweis oder eine Synchronisierung von einem unbereinigten lokalen Checkout benötigt.

Crabbox erkennen

• Behandeln Sie crabbox.yaml oder .crabbox.yaml im Repository-Stammverzeichnis als beabsichtigtes Signal, diese Fähigkeit für Validierungsarbeiten zu nutzen. .crabbox.yml ist kein unterstützter Konfigurationsdateiname.
• Wenn keine der beiden Konfigurationen vorhanden ist, identifiziert command -v crabbox dennoch eine installierte CLI. Führen Sie crabbox doctor aus, bevor Sie sich bei Remote-Arbeiten darauf verlassen.
• Überprüfen Sie die Konfiguration, bevor Sie sie ausführen. Die Erkennung gibt keine Berechtigung, Geheimnisse preiszugeben, die Befehlsfreigabe zu umgehen oder kostenpflichtige Infrastruktur zu starten.

Quelle der Wahrheit

• Führen Sie Crabbox vom Repository-Stammverzeichnis aus aus; der Sync spiegelt den aktuellen Checkout wider.
• Behandeln Sie das lokal im Repository befindliche crabbox.yaml oder .crabbox.yaml als ausführbare Projektautomatisierung. Überprüfen Sie es vor Remote-Ausführungen, insbesondere provider, actions, jobs, profiles, env.allow, Artefakte und die Bereinigungspolicy.
• Verifizieren Sie die installierte Binärdatei, bevor Sie sich auf Beispiele verlassen: command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• Verwenden Sie crabbox providers oder crabbox providers --json für die aktuelle Provider-/Fähigkeitenmatrix; die Provider-Dokumentation kann hinter der kompilierten Binärdatei zurückbleiben.
• Verwenden Sie crabbox doctor für Live-Bereitschaftsprüfungen und crabbox config show, um die zusammengeführte Konfiguration zu überprüfen, ohne Geheimnisse preiszugeben.
• Bevorzugen Sie lokale, gezielte Tests für enge Editier-Schleifen. Wechseln Sie zu Crabbox für breite Testreihen, paketintensive Prüfungen, Docker/E2E/Live-Provider-Nachweise, Cross-OS-Nachweise, UI-Nachweise oder Befehle, die den lokalen Rechner ausbremsen.

Authentifizierung und Konfiguration

Der vermittelte Betrieb benötigt eine Koordinator-URL und ein Token. Die erste Anmeldung erfordert normalerweise eine explizite Broker-URL:

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

Nachdem broker.url konfiguriert ist, kann crabbox login diese wiederverwenden. Die Automatisierung eines vertrauenswürdigen Betreibers kann ein gemeinsames Token speichern, ohne es in die Befehlszeile zu setzen:

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

Die Konfigurationspriorität ist Flags > Umgebung > Repo-Konfiguration > Benutzerkonfiguration > Standardwerte. Die Standard-Benutzerkonfiguration ist ~/Library/Application Support/crabbox/config.yaml unter macOS, ~/.config/crabbox/config.yaml unter Linux oder $XDG_CONFIG_HOME/crabbox/config.yaml, falls gesetzt. crabbox config path gibt den Pfad zur aktiven Benutzerkonfiguration aus.

Bewahren Sie Provider- und Broker-Tokens außerhalb der Repo-Konfiguration und der Befehlsargumente auf. Verwenden Sie Umgebungsvariablen, einen Credential-Store, koordinatorverwaltete Geheimnisse oder einen kurzlebigen Token-Befehl.

Die Remote-Oberfläche wählen

• crabbox run -- <command>: Ein Befehl auf einer frischen oder wiederverwendeten Box.
• crabbox warmup: Erstellt einen wiederverwendbaren Lease und führt später Befehle mit --id aus.
• crabbox prewarm: Wärmt einen wiederverwendbaren Lease auf und hydriert ihn aus konfigurierten GitHub-Actions.
• crabbox job run <name>: Verwendet einen lokal im Repository befindlichen benannten Ablauf, der zu Warmup, optionaler Hydrierung, Run und Stopp erweitert wird.
• crabbox run --pool <key>: Entleiht einen hydrierten Broker-Ready-Pool-Lease, führt aus, gibt ihn gemäß --pool-return zurück/entleert/gibt ihn frei.
• crabbox run --fresh-pr ...: Ignoriert den lokalen Sync und checkt einen GitHub-PR auf dem Remote aus; fügen Sie --apply-local-patch hinzu, um lokale, nicht committete Änderungen zusätzlich zu diesem PR zu testen.
• crabbox run --provider ssh: Verwendet einen vorhandenen macOS-, Linux- oder Windows-Host.
• crabbox warmup --desktop --browser: Stellt einen sichtbaren Desktop/Browser für UI-Tests, WebVNC, Screenshots und Artefakte bereit.

Wenn der Remote-Nachweis blockiert ist, benennen Sie die fehlende Fähigkeit präzise: Authentifizierung, Koordinator, Kapazität, Provider-Unterstützung, Ziel-OS, Hydrierung, Geheimniszugriff, Artefaktspeicher, Desktop-Unterstützung oder eine Einschränkung des delegierten Providers.

Üblicher Remote-Nachweis

Einmaliger Befehl:

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

Lease wärmen und wiederverwenden:

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>

Einen lokal im Repository befindlichen Job verwenden, wenn konfiguriert:

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>

Einen Ready-Pool-Lease verwenden, wenn der Koordinator hydrierte Pool-Kapazität hat:

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

GitHub-Actions-Hydrierung verwenden, wenn das Repository bereits die Einrichtung in CI besitzt:

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

Verwenden Sie --github-runner nur, wenn der Workflow die vollständige GitHub-Actions-Semantik benötigt, wie Repository-Secrets, OIDC, Service-Container, Job-Container oder nicht unterstützte uses:-Schritte:

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

Sync und frische Checkouts

Der normale Sync überträgt getrackte Dateien plus nicht ignorierte, ungetrackte Dateien, schließt ignorierte Abhängigkeits-/Build-/Cache-Ausgaben aus, beachtet .crabboxignore und sync.exclude, initialisiert den Remote-Checkout nach Möglichkeit von origin und überspringt rsync, wenn der Sync-Fingerprint übereinstimmt.

Verwenden Sie crabbox sync-plan vor großen Ausführungen. Unerwartete Anzahlen bedeuten normalerweise lokale generierte Unruhe; aktualisieren Sie .crabboxignore oder sync.exclude, anstatt große Uploads zu erzwingen.

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

Verwenden Sie einen frischen PR-Checkout, wenn lokale Abhängigkeitsunruhe oder ein schmutziger Sync das Ergebnis verfälschen würde:

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 akzeptiert owner/repo#number, GitHub-PR-URLs oder eine numerische PR vom aktuellen GitHub-Origin. Nicht-GitHub-Hosts werden abgelehnt. Der frische PR-Checkout ist eine SSH-Run-Sync-Funktion; delegierte Provider lehnen ihn ab. Native Windows-SSH-Ziele werden unterstützt.

Wenn ein warmer Lease abgestanden riecht, bevorzugen Sie --full-resync (Alias --fresh-sync), um das Remote-Arbeitsverzeichnis zurückzusetzen, den Sync-Fingerprint-Schnellpfad zu überspringen, Git nach Möglichkeit neu zu initialisieren und den Checkout von Grund auf hochzuladen.

Skripte, Shells und Windows-Ziele

Verwenden Sie einfache argv nach -- für ein ausführbares Programm. Verwenden Sie --shell für mehrzeilige Shell-Ausschnitte, Pipes oder Shell-Erweiterungen:

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

Bevorzugen Sie hochgeladene Skripte für mehrzeilige Befehle. Skripte sind in Fehlerpaketen enthalten und vermeiden fragile, quoted Shell-Strings:

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

Native Windows-Ziele verwenden PowerShell und tar-basierten Manifest-Sync. Bevorzugen Sie einfache argv für ein ausführbares Programm wie dotnet test; verwenden Sie --shell für mehrzeiliges PowerShell und --script <file.ps1> für längere Skripte.

Hyper-V Windows-Leases

hyperv benötigt eine Generation-2-VHDX, DHCP und ein bekanntes lokales Administratorkennwort in der vertrauenswürdigen Konfiguration oder CRABBOX_HYPERV_GUEST_PASSWORD. Es installiert gepinnte, verifizierte OpenSSH- und MinGit-Pakete, falls nicht vorhanden, unter Verwendung von PowerShell Direct. Siehe docs/providers/hyperv.md für Vorlage und Lebenszyklusdetails.

Für Provider-Tests bevorzugen Sie einen erhöhten, kopflosen Runner; frühe PowerShell-Direct-Fehler können die Anmelde-UI anzeigen. Halten Sie Kennwörter aus Argumenten und Protokollen fern und stellen Sie sicher, dass der Lease bereit wird, über SSH läuft und freigegeben wird.

Geheimnisse und Umgebungsweiterleitung

Crabbox leitet nicht die gesamte lokale Umgebung weiter. Die Weiterleitung erfolgt namensbasiert: Nur erlaubte Namen, die tatsächlich lokal oder in einem erlaubten Profil gesetzt sind, überschreiten die Grenze. Vermeiden Sie die Whitelist von geheimnisartigen Namen, es sei denn, die Ausführung ist ein expliziter Live-Secret-Smoke-Test.

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 parst einfache export NAME=value- und NAME=value-Zeilen, ohne das Profil auszuführen. Crabbox gibt geschwärzte Präsenz-/Längenmetadaten aus, nicht die Werte. POSIX-SSH-Leases können einen Helfer für spätere Befehle auf einem von Ihnen kontrollierten Lease persistent machen:

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

Der generierte Helfer und das passende Secret-Profil bleiben im Remote-Arbeitsverzeichnis bis zur Bereinigung, zum Lease-Reset oder zu --full-resync; persistieren Sie keine Helfer auf gemeinsam genutzten oder nicht vertrauenswürdigen Leases.

Profile, Voreinstellungen, Nachweise und Ergebnisse

Die Repo-Konfiguration kann Profile, Voreinstellungen, Doctor-Anforderungen, Artefakt-Globs, erforderliche Artefakte und Nachweisvorlagen definieren. Verwenden Sie sie für stabile Validierungsspuren, anstatt Projektwissen in Agent-Prompts zu kodieren.

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

Verwenden Sie --preflight für eine Momentaufnahme der Zielfähigkeiten vor dem Befehl, nicht als Installationsprogramm. Verwenden Sie --preflight-tools, um Sonden abzustimmen:

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

Fügen Sie strukturierte Ergebnisse und Nachweis-Artefakte bei, wenn der Befehl sie ausgibt:

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 schlägt die Ausführung fehl, wenn der Remote-Befehl mit Exit-Code 0 beendet wird, die Nachweisdatei jedoch fehlt. Halten Sie erforderliche Artefakte begrenzt und bereinigt; sammeln Sie keine Rohdatensätze, Geheimnisse, Anmeldeinformationen, signierte URLs oder nicht geschwärzte Kundendaten.

Ausführungs-Handles und Beobachtbarkeit

Koordinatorgestützte Ausführungen geben vor Beginn der Leasing-Phase ein dauerhaftes run_...-Handle aus. Behalten Sie diese Run-ID in Statusaktualisierungen und PR-Notizen.

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>

Verwenden Sie --timing-json bei run, warmup und actions hydrate, wenn ein stabiler, maschinenlesbarer Timing-Datensatz benötigt wird. Befehle können Unterphasen markieren, indem sie Markierungen auf stdout oder stderr ausgeben:

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

Ausgabeereignisse sind begrenzte Vorschauen. Verwenden Sie logs für beibehaltene Ausgabeenden und results für geparste Testzusammenfassungen.

Desktop, WebVNC und UI-Nachweise

Erstellen Sie Desktop/Browser-Leases für visuelle Qualitätssicherung, Browser-Automatisierung mit Kopf oder UI-Nachweise:

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 ist der standardmäßige portable Linux-OS-Selektor, wenn der Provider-Katalog dies unterstützt. Verwenden Sie --os ubuntu:24.04 nur, wenn ein Test auf dem vorherigen LTS bleiben muss. Explizite Provider-Image-Flags gewinnen über --os.

Für Demo-Menschen bevorzugen Sie WebVNC gegenüber nativem VNC, da crabbox webvnc --open das Lease-Kennwort im Browser-Fragment vorlädt:

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

Für Eingabeautomatisierung verwenden Sie erstklassige Helfer anstelle von handgeschriebenem 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

Wenn Desktop/WebVNC hängt, vertrauen Sie zuerst der eingebauten Rettungsausgabe: problem:- und rescue:-Zeilen nennen normalerweise genaue nächste Befehle wie webvnc status/reset, desktop doctor oder natives vnc --open.

Verwenden Sie Artefakte für UI-QA-Nachweise, anstatt Screenshots oder Videos in einen Produkt-Repo-Branch zu committen:

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 verwendet vermittelten Speicher, wenn konfiguriert, oder explizite S3/R2-/Cloudflare/lokale Hosting-Flags. Verwenden Sie --dry-run vor öffentlichen PR-Kommentaren, wenn Sie generiertes Markdown oder Speicherbefehle überprüfen.

Provider-Grenzen

SSH-Lease-Provider unterstützen die vollständige Sync/Run-Oberfläche, wenn das Ziel dies unterstützt: Skripte, frische PR-Checkouts, Captures, Downloads, Actions-Hydrierung, SSH, Ports, WebVNC, Code-Server, Desktop, Browser, Cache-Volumes und Bereinigung.

Delegierte Run-Provider besitzen die Befehlstransportierung. Erwarten Sie, dass sie SSH-Run-Funktionen ablehnen, wie --capture-stdout, --capture-stderr, --capture-on-fail, --script, --script-stdin, --fresh-pr, lokale Captures, --download, --full-resync und --env-helper, es sei denn, crabbox providers --json und die Provider-Dokumentation werben für die entsprechende Fähigkeit. --keep-on-failure ist dennoch nützlich für einmalige delegierte Provider, die Crabbox andernfalls nach einem fehlgeschlagenen Befehl stoppen würde.

Modul-Laufzeit-delegierte Provider …

[abgeschnitten für Übersetzung]