Testen

OpenClaw verfügt über drei Vitest-Suites (Unit/Integration, E2E, Live) und eine kleine Reihe von Docker-Runnern. Dieses Dokument ist ein Leitfaden dazu, „wie wir testen“:

• Was jede Suite abdeckt (und was sie bewusst nicht abdeckt).
• Welche Befehle Sie für gängige Workflows ausführen (lokal, vor dem Push, Debugging).
• Wie Live-Tests Zugangsdaten erkennen und Modelle/Provider auswählen.
• Wie Sie Regressionen für reale Modell-/Provider-Probleme hinzufügen.

# Schnellstart

An den meisten Tagen:

• Vollständiges Gate (vor dem Push erwartet): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Schnellerer lokaler Full-Suite-Lauf auf einer großzügig ausgestatteten Maschine: pnpm test:max
• Direkte Vitest-Watch-Schleife: pnpm test:watch
• Direktes Datei-Targeting routet jetzt auch Extension-/Channel-Pfade: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Bevorzugen Sie zuerst gezielte Läufe, wenn Sie an einem einzelnen Fehler iterieren.
• Docker-gestützte QA-Site: pnpm qa:lab:up
• Linux-VM-gestützte QA-Lane: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Wenn Sie Tests berühren oder zusätzliche Sicherheit möchten:

• Coverage-Gate: pnpm test:coverage
• E2E-Suite: pnpm test:e2e

Beim Debugging realer Provider/Modelle (erfordert echte Zugangsdaten):

• Live-Suite (Modelle + Gateway-Tool-/Bild-Probes): pnpm test:live
• Eine Live-Datei leise ansteuern: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Laufzeit-Performance-Berichte: dispatchen Sie OpenClaw Performance mit live_gpt54=true für einen echten openai/gpt-5.4-Agent-Turn oder deep_profile=true für Kova-CPU-/Heap-/Trace-Artefakte. Täglich geplante Läufe veröffentlichen Mock-Provider-, Deep-Profile- und GPT-5.4-Lane-Artefakte nach openclaw/clawgrit-reports, wenn CLAWGRIT_REPORTS_TOKEN konfiguriert ist. Der Mock-Provider-Bericht enthält außerdem Zahlen zu Source-Level-Gateway-Boot, Speicher, Plugin-Pressure, wiederholter Fake-Model-Hello-Schleife und CLI-Start.
• Docker-Live-Modell-Sweep: pnpm test:docker:live-models
  • Jedes ausgewählte Modell führt jetzt einen Text-Turn plus eine kleine Probe im Stil eines Datei-Lesevorgangs aus. Modelle, deren Metadaten image-Eingabe ausweisen, führen außerdem einen winzigen Bild-Turn aus. Deaktivieren Sie die zusätzlichen Probes mit OPENCLAW_LIVE_MODEL_FILE_PROBE=0 oder OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0, wenn Sie Provider-Fehler isolieren.
  • CI-Coverage: Die täglichen OpenClaw Scheduled Live And E2E Checks und die manuellen OpenClaw Release Checks rufen beide den wiederverwendbaren Live-/E2E-Workflow mit include_live_suites: true auf, der separate Docker-Live-Modell-Matrix-Jobs enthält, nach Provider geshardet.
  • Für fokussierte CI-Reruns dispatchen Sie OpenClaw Live And E2E Checks (Reusable) mit include_live_suites: true und live_models_only: true.
  • Fügen Sie neue signalstarke Provider-Secrets zu scripts/ci-hydrate-live-auth.sh sowie .github/workflows/openclaw-live-and-e2e-checks-reusable.yml und dessen geplanten/Release-Callern hinzu.
• Native Codex Bound-Chat-Smoke: pnpm test:docker:live-codex-bind
  • Führt eine Docker-Live-Lane gegen den Codex-App-Server-Pfad aus, bindet eine synthetische Slack-DM mit /codex bind, übt /codex fast und /codex permissions aus und verifiziert dann, dass eine einfache Antwort und eine Bildanlage über das native Plugin-Binding statt über ACP geroutet werden.
• Codex-App-Server-Harness-Smoke: pnpm test:docker:live-codex-harness
  • Führt Gateway-Agent-Turns durch das Plugin-eigene Codex-App-Server-Harness aus, verifiziert /codex status und /codex models und übt standardmäßig Bild-, Cron-MCP-, Sub-Agent- und Guardian-Probes aus. Deaktivieren Sie die Sub-Agent-Probe mit OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0, wenn Sie andere Codex-App-Server-Fehler isolieren. Für eine fokussierte Sub-Agent-Prüfung deaktivieren Sie die anderen Probes: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Dies beendet nach der Sub-Agent-Probe, sofern OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 nicht gesetzt ist.
• Crestodian-Rescue-Command-Smoke: pnpm test:live:crestodian-rescue-channel
  • Opt-in-Prüfung mit doppelter Absicherung für die Message-Channel-Rescue-Command-Oberfläche. Sie übt /crestodian status aus, stellt eine persistente Modelländerung in die Warteschlange, antwortet mit /crestodian yes und verifiziert den Audit-/Config-Schreibpfad.
• Crestodian-Planner-Docker-Smoke: pnpm test:docker:crestodian-planner
  • Führt Crestodian in einem configlosen Container mit einer Fake-Claude-CLI auf PATH aus und verifiziert, dass der Fuzzy-Planner-Fallback in einen auditierten typisierten Config-Schreibvorgang übersetzt wird.
• Crestodian-First-Run-Docker-Smoke: pnpm test:docker:crestodian-first-run
  • Startet aus einem leeren OpenClaw-State-Verzeichnis, routet bloßes openclaw an Crestodian, wendet Setup-/Modell-/Agent-/Discord-Plugin- und SecretRef-Schreibvorgänge an, validiert die Config und verifiziert Audit-Einträge. Derselbe Ring-0-Setup-Pfad wird außerdem in QA Lab durch pnpm openclaw qa suite --scenario crestodian-ring-zero-setup abgedeckt.
• Moonshot-/Kimi-Kosten-Smoke: Führen Sie bei gesetztem MOONSHOT_API_KEY openclaw models list --provider moonshot --json aus und danach einen isolierten openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json gegen moonshot/kimi-k2.6. Verifizieren Sie, dass das JSON Moonshot/K2.6 meldet und das Assistant-Transkript normalisierte usage.cost speichert.

# QA-spezifische Runner

Diese Befehle stehen neben den Haupt-Testsuites, wenn Sie QA-Lab-Realismus benötigen:

CI führt QA Lab in dedizierten Workflows aus. Agentic Parity ist unter QA-Lab - All Lanes und Release-Validierung verschachtelt, kein eigenständiger PR-Workflow. Breite Validierung sollte Full Release Validation mit rerun_group=qa-parity oder die QA-Gruppe der Release-Checks verwenden. Stabile/standardmäßige Release- Checks halten exhaustive Live-/Docker-Soak hinter run_release_soak=true; das full-Profil erzwingt Soak. QA-Lab - All Lanes läuft nächtlich auf main und per manuellem Dispatch mit der Mock-Parity-Lane, Live- Matrix-Lane, Convex-verwalteten Live-Telegram-Lane und Convex-verwalteten Live-Discord- Lane als parallelen Jobs. Geplante QA- und Release-Checks übergeben Matrix explizit --profile fast, während die Standardwerte der Matrix-CLI und der manuellen Workflow-Eingabe all bleiben; manueller Dispatch kann all in transport, media, e2ee-smoke, e2ee-deep und e2ee-cli-Jobs sharden. OpenClaw Release Checks führt vor der Release-Freigabe Parity plus die schnellen Matrix- und Telegram-Lanes aus und verwendet mock-openai/gpt-5.5 für Release-Transport-Checks, damit sie deterministisch bleiben und den normalen Start des Provider-Plugins vermeiden. Diese Live-Transport- Gateways deaktivieren Memory-Suche; Memory-Verhalten bleibt durch die QA-Parity- Suites abgedeckt.

Full-Release-Live-Media-Shards verwenden ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, das bereits ffmpeg und ffprobe enthält. Docker-Live-Modell-/Backend-Shards verwenden das gemeinsam genutzte ghcr.io/openclaw/openclaw-live-test:<sha>-Image, das einmal pro ausgewähltem Commit gebaut wird, und ziehen es dann mit OPENCLAW_SKIP_DOCKER_BUILD=1, statt es in jedem Shard neu zu bauen.

• pnpm openclaw qa suite
  • Führt repo-gestützte QA-Szenarien direkt auf dem Host aus.
  • Führt mehrere ausgewählte Szenarien standardmäßig parallel mit isolierten Gateway-Workern aus. qa-channel verwendet standardmäßig Parallelität 4 (begrenzt durch die Anzahl der ausgewählten Szenarien). Verwenden Sie --concurrency <count>, um die Worker-Anzahl anzupassen, oder --concurrency 1 für die ältere serielle Lane.
  • Beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie --allow-failures, wenn Sie Artefakte ohne fehlschlagenden Exit-Code wünschen.
  • Unterstützt die Provider-Modi live-frontier, mock-openai und aimock. aimock startet einen lokalen AIMock-gestützten Provider-Server für experimentelle Fixture- und Protokoll-Mock-Abdeckung, ohne die szenariofähige mock-openai-Lane zu ersetzen.
• pnpm test:plugins:kitchen-sink-live
  • Führt den Live-OpenAI-Kitchen-Sink-Plugin-Parcours über QA Lab aus. Er installiert das externe Kitchen-Sink-Paket, verifiziert das Inventar der Plugin-SDK-Oberfläche, prüft /healthz und /readyz, zeichnet Gateway-CPU/RSS-Nachweise auf, führt einen Live-OpenAI-Turn aus und prüft adversariale Diagnosen. Erfordert Live-OpenAI-Authentifizierung wie OPENAI_API_KEY. In hydratisierten Testbox-Sitzungen wird automatisch das Testbox-Live-Auth-Profil bezogen, wenn der Helper openclaw-testbox-env vorhanden ist.
• pnpm test:gateway:cpu-scenarios
  • Führt den Gateway-Startup-Benchmark sowie ein kleines Mock-QA-Lab-Szenariopaket (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) aus und schreibt eine kombinierte CPU-Beobachtungszusammenfassung unter .artifacts/gateway-cpu-scenarios/.
  • Markiert standardmäßig nur anhaltend hohe CPU-Beobachtungen (--cpu-core-warn plus --hot-wall-warn-ms), sodass kurze Startup-Spitzen als Metriken aufgezeichnet werden, ohne wie die minutenlange Gateway-Peg-Regression zu wirken.
  • Verwendet gebaute dist-Artefakte; führen Sie zuerst einen Build aus, wenn der Checkout noch keine frische Laufzeitausgabe enthält.
• pnpm openclaw qa suite --runner multipass
  • Führt dieselbe QA-Suite in einer kurzlebigen Multipass-Linux-VM aus.
  • Behält dasselbe Szenarioauswahlverhalten wie qa suite auf dem Host bei.
  • Verwendet dieselben Provider-/Modellauswahl-Flags wie qa suite.
  • Live-Läufe leiten die unterstützten QA-Auth-Eingaben weiter, die für den Gast praktikabel sind: env-basierte Provider-Schlüssel, den Pfad zur QA-Live-Provider-Konfiguration und CODEX_HOME, wenn vorhanden.
  • Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Gast über den gemounteten Workspace zurückschreiben kann.
  • Schreibt den normalen QA-Bericht und die Zusammenfassung plus Multipass-Logs unter .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Startet die Docker-gestützte QA-Site für operatorähnliche QA-Arbeit.
• pnpm test:docker:npm-onboard-channel-agent
  • Baut aus dem aktuellen Checkout einen npm-Tarball, installiert ihn global in Docker, führt nichtinteraktives Onboarding mit OpenAI-API-Schlüssel aus, konfiguriert standardmäßig Telegram, verifiziert, dass die paketierte Plugin-Laufzeit ohne Startup-Abhängigkeitsreparatur geladen wird, führt doctor aus und führt einen lokalen Agent-Turn gegen einen gemockten OpenAI-Endpunkt aus.
  • Verwenden Sie OPENCLAW_NPM_ONBOARD_CHANNEL=discord, um dieselbe Packaged-Install-Lane mit Discord auszuführen.
• pnpm test:docker:session-runtime-context
  • Führt einen deterministischen Built-App-Docker-Smoke für eingebettete Laufzeitkontext-Transkripte aus. Er verifiziert, dass versteckter OpenClaw-Laufzeitkontext als nicht angezeigte benutzerdefinierte Nachricht persistiert wird, statt in den sichtbaren Benutzer-Turn zu gelangen, legt anschließend eine betroffene defekte Sitzungs-JSONL an und verifiziert, dass openclaw doctor --fix sie mit Backup auf den aktiven Branch umschreibt.
• pnpm test:docker:npm-telegram-live
  • Installiert einen OpenClaw-Paketkandidaten in Docker, führt Installed-Package-Onboarding aus, konfiguriert Telegram über die installierte CLI und verwendet dann die Live-Telegram-QA-Lane mit diesem installierten Paket als SUT-Gateway erneut.
  • Standard ist OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; setzen Sie OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz oder OPENCLAW_CURRENT_PACKAGE_TGZ, um statt einer Installation aus der Registry einen aufgelösten lokalen Tarball zu testen.
  • Verwendet dieselben Telegram-env-Zugangsdaten oder dieselbe Convex-Zugangsdatenquelle wie pnpm openclaw qa telegram. Setzen Sie für CI-/Release-Automatisierung OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex plus OPENCLAW_QA_CONVEX_SITE_URL und das Rollen-Secret. Wenn OPENCLAW_QA_CONVEX_SITE_URL und ein Convex-Rollen-Secret in CI vorhanden sind, wählt der Docker-Wrapper automatisch Convex aus.
  • Der Wrapper validiert Telegram- oder Convex-Zugangsdaten-env auf dem Host, bevor Docker-Build-/Installationsarbeit beginnt. Setzen Sie OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 nur, wenn Sie bewusst das Setup vor den Zugangsdaten debuggen.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer überschreibt die gemeinsame OPENCLAW_QA_CREDENTIAL_ROLE nur für diese Lane.
  • GitHub Actions stellt diese Lane als manuellen Maintainer-Workflow NPM Telegram Beta E2E bereit. Sie läuft nicht bei Merge. Der Workflow verwendet die Umgebung qa-live-shared und Convex-CI-Zugangsdaten-Leases.
• GitHub Actions stellt außerdem Package Acceptance für seitlich ausgeführten Produktnachweis gegen ein einzelnes Kandidatenpaket bereit. Es akzeptiert einen vertrauenswürdigen Ref, eine veröffentlichte npm-Spezifikation, eine HTTPS-Tarball-URL plus SHA-256 oder ein Tarball-Artefakt aus einem anderen Lauf, lädt das normalisierte openclaw-current.tgz als package-under-test hoch und führt anschließend den bestehenden Docker-E2E-Scheduler mit den Lane-Profilen Smoke, Package, Product, Full oder Custom aus. Setzen Sie telegram_mode=mock-openai oder live-frontier, um den Telegram-QA-Workflow gegen dasselbe package-under-test-Artefakt auszuführen.
  • Neuester Beta-Produktnachweis:

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

• Nachweis mit exakter Tarball-URL erfordert einen Digest:

gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

• Artefaktnachweis lädt ein Tarball-Artefakt aus einem anderen Actions-Lauf herunter:

gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke

• pnpm test:docker:plugins

  • Paketiert und installiert den aktuellen OpenClaw-Build in Docker, startet den Gateway mit konfiguriertem OpenAI und aktiviert anschließend gebündelte Channels/Plugins über Konfigurationsänderungen.
  • Verifiziert, dass die Setup-Erkennung unkonfigurierte herunterladbare Plugins abwesend lässt, die erste konfigurierte doctor-Reparatur jedes fehlende herunterladbare Plugin explizit installiert und ein zweiter Neustart keine versteckte Abhängigkeitsreparatur ausführt.
  • Installiert außerdem eine bekannte ältere npm-Baseline, aktiviert Telegram vor der Ausführung von openclaw update --tag <candidate> und verifiziert, dass der doctor des Kandidaten nach dem Update Altlasten aus Plugin-Abhängigkeiten ohne harness-seitige Postinstall-Reparatur bereinigt.

• pnpm test:parallels:npm-update

  • Führt den nativen Packaged-Install-Update-Smoke über Parallels-Gäste aus. Jede ausgewählte Plattform installiert zuerst das angeforderte Baseline-Paket, führt dann im selben Gast den installierten Befehl openclaw update aus und verifiziert die installierte Version, den Update-Status, die Gateway-Bereitschaft und einen lokalen Agent-Turn.

  • Verwenden Sie --platform macos, --platform windows oder --platform linux, während Sie an einem Gast iterieren. Verwenden Sie --json für den Pfad zum Zusammenfassungsartefakt und den Status pro Lane.

  • Die OpenAI-Lane verwendet standardmäßig openai/gpt-5.5 für den Live-Agent-Turn-Nachweis. Übergeben Sie --model <provider/model> oder setzen Sie OPENCLAW_PARALLELS_OPENAI_MODEL, wenn Sie bewusst ein anderes OpenAI-Modell validieren.

  • Kapseln Sie lange lokale Läufe in ein Host-Timeout, damit Parallels-Transport-Stalls nicht den Rest des Testfensters verbrauchen:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    

  • Das Skript schreibt verschachtelte Lane-Logs unter /tmp/openclaw-parallels-npm-update.*. Prüfen Sie windows-update.log, macos-update.log oder linux-update.log, bevor Sie annehmen, dass der äußere Wrapper hängt.

  • Das Windows-Update kann auf einem kalten Gast 10 bis 15 Minuten mit doctor- und Paket-Update-Arbeit nach dem Update verbringen; das ist noch gesund, wenn das verschachtelte npm-Debug-Log fortschreitet.

  • Führen Sie diesen aggregierten Wrapper nicht parallel zu einzelnen Parallels-macOS-, Windows- oder Linux-Smoke-Lanes aus. Sie teilen sich den VM-Zustand und können bei Snapshot-Wiederherstellung, Paketbereitstellung oder Gast-Gateway-Zustand kollidieren.

  • Der Nachweis nach dem Update führt die normale gebündelte Plugin-Oberfläche aus, weil Capability-Facades wie Sprache, Bilderzeugung und Medienverständnis über gebündelte Laufzeit-APIs geladen werden, auch wenn der Agent-Turn selbst nur eine einfache Textantwort prüft.

• pnpm openclaw qa aimock

  • Startet nur den lokalen AIMock-Provider-Server für direktes Protokoll-Smoke-Testing.

• pnpm openclaw qa matrix

  • Führt die Matrix-Live-QA-Lane gegen einen kurzlebigen Docker-gestützten Tuwunel-Homeserver aus. Nur Source-Checkout - paketierte Installationen liefern qa-lab nicht mit.
  • Vollständige CLI, Profil-/Szenariokatalog, env vars und Artefaktlayout: Matrix-QA.

• pnpm openclaw qa telegram

  • Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe mit den Driver- und SUT-Bot-Tokens aus env aus.
  • Erfordert OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN und OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. Die Gruppen-ID muss die numerische Telegram-Chat-ID sein.
  • Unterstützt --credential-source convex für gemeinsame gepoolte Zugangsdaten. Verwenden Sie standardmäßig den env-Modus, oder setzen Sie OPENCLAW_QA_CREDENTIAL_SOURCE=convex, um gepoolte Leases zu verwenden.
  • Beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie --allow-failures, wenn Sie Artefakte ohne fehlschlagenden Exit-Code wünschen.
  • Erfordert zwei verschiedene Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellen muss.
  • Aktivieren Sie für stabile Bot-zu-Bot-Beobachtung den Bot-to-Bot Communication Mode in @BotFather für beide Bots und stellen Sie sicher, dass der Driver-Bot Gruppen-Bot-Verkehr beobachten kann.
  • Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter .artifacts/qa-e2e/.... Antwortszenarien enthalten RTT von der Sendeanforderung des Drivers bis zur beobachteten SUT-Antwort.

Live-Transport-Lanes teilen sich einen Standardvertrag, damit neue Transporte nicht abweichen; die Abdeckungsmatrix pro Lane befindet sich in QA-Übersicht → Live-Transport-Abdeckung. qa-channel ist die breite synthetische Suite und nicht Teil dieser Matrix.

# Gemeinsame Telegram-Zugangsdaten über Convex (v1)

Wenn --credential-source convex (oder OPENCLAW_QA_CREDENTIAL_SOURCE=convex) für openclaw qa telegram aktiviert ist, erhält QA Lab eine exklusive Lease aus einem Convex-gestützten Pool, heartbeated diese Lease, während die Lane läuft, und gibt die Lease beim Herunterfahren frei.

Referenz-Convex-Projektscaffold:

• qa/convex-credential-broker/

Erforderliche env vars:

• OPENCLAW_QA_CONVEX_SITE_URL (zum Beispiel https://your-deployment.convex.site)
• Ein Secret für die ausgewählte Rolle:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER für maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI für ci
• Auswahl der Zugangsdatenrolle:
  • CLI: --credential-role maintainer|ci
  • env-Standard: OPENCLAW_QA_CREDENTIAL_ROLE (standardmäßig ci in CI, sonst maintainer)

Optionale env vars:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (Standard 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (Standard 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (Standard 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (Standard 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (Standard /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (optionale Trace-ID)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 erlaubt loopback-http://-Convex-URLs für ausschließlich lokale Entwicklung.

OPENCLAW_QA_CONVEX_SITE_URL sollte im Normalbetrieb https:// verwenden.

Maintainer-Adminbefehle (pool add/remove/list) erfordern ausdrücklich OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

CLI-Hilfsbefehle für Maintainer:

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

Verwenden Sie doctor vor Live-Läufen, um die Convex-Site-URL, Broker-Secrets, Endpoint-Präfix, HTTP-Timeout und Admin-/Listen-Erreichbarkeit zu prüfen, ohne Secret-Werte auszugeben. Verwenden Sie --json für maschinenlesbare Ausgabe in Skripten und CI Hilfsprogrammen.

Standard-Endpoint-Vertrag (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Anfrage: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Erfolg: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Erschöpft/wiederholbar: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Anfrage: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Erfolg: { status: "ok" } (oder leeres 2xx)
• POST /release
  • Anfrage: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Erfolg: { status: "ok" } (oder leeres 2xx)
• POST /admin/add (nur Maintainer-Secret)
  • Anfrage: { kind, actorId, payload, note?, status? }
  • Erfolg: { status: "ok", credential }
• POST /admin/remove (nur Maintainer-Secret)
  • Anfrage: { credentialId, actorId }
  • Erfolg: { status: "ok", changed, credential }
  • Schutz bei aktiver Lease: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (nur Maintainer-Secret)
  • Anfrage: { kind?, status?, includePayload?, limit? }
  • Erfolg: { status: "ok", credentials, count }

Payload-Form für Telegram-Art:

• { groupId: string, driverToken: string, sutToken: string }
• groupId muss eine numerische Telegram-Chat-ID-Zeichenfolge sein.
• admin/add validiert diese Form für kind: "telegram" und lehnt fehlerhafte Payloads ab.

# Einen Kanal zu QA hinzufügen

Die Architektur- und Szenario-Hilfsnamen für neue Kanaladapter finden Sie unter QA-Übersicht → Kanal hinzufügen. Mindestanforderung: Implementieren Sie den Transport-Runner auf dem gemeinsamen qa-lab-Host-Seam, deklarieren Sie qaRunners im Plugin-Manifest, mounten Sie ihn als openclaw qa <runner> und erstellen Sie Szenarien unter qa/scenarios/.

# Test-Suites (was wo läuft)

Betrachten Sie die Suites als „zunehmenden Realismus“ (und zunehmende Instabilität/Kosten):

# Unit / Integration (Standard)

• Befehl: pnpm test
• Konfiguration: Ungezielte Läufe verwenden das vitest.full-*.config.ts-Shard-Set und können Multi-Projekt-Shards für parallele Planung in projektbezogene Konfigurationen erweitern
• Dateien: Core-/Unit-Inventare unter src/**/*.test.ts, packages/**/*.test.ts und test/**/*.test.ts; UI-Unit-Tests laufen im dedizierten unit-ui-Shard
• Umfang:
  • Reine Unit-Tests
  • In-Process-Integrationstests (Gateway-Authentifizierung, Routing, Tooling, Parsing, Konfiguration)
  • Deterministische Regressionen für bekannte Bugs
• Erwartungen:
  • Läuft in CI
  • Keine echten Schlüssel erforderlich
  • Sollte schnell und stabil sein
  • Resolver- und Public-Surface-Loader-Tests müssen das allgemeine api.js- und runtime-api.js-Fallback-Verhalten mit generierten kleinen Plugin-Fixtures belegen, nicht mit echten gebündelten Plugin-Quell-APIs. Echte Plugin-API-Ladevorgänge gehören in Plugin-eigene Vertrags-/Integrations-Suites.

# Stabilität (Gateway)

• Befehl: pnpm test:stability:gateway
• Konfiguration: vitest.gateway.config.ts, auf einen Worker erzwungen
• Umfang:
  • Startet einen echten Loopback-Gateway mit standardmäßig aktivierter Diagnose
  • Treibt synthetische Gateway-Nachrichten-, Memory- und Large-Payload-Last durch den Diagnose-Event-Pfad
  • Fragt diagnostics.stability über die Gateway-WS-RPC ab
  • Deckt Persistenzhelfer für Diagnose-Stabilitätsbundles ab
  • Prüft, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Pressure-Budget bleiben und Per-Session-Queue-Tiefen wieder auf null ablaufen
• Erwartungen:
  • CI-sicher und ohne Schlüssel
  • Schmale Lane für Stabilitätsregressions-Nachverfolgung, kein Ersatz für die vollständige Gateway-Suite

# E2E (Gateway-Smoke)

• Befehl: pnpm test:e2e
• Konfiguration: vitest.e2e.config.ts
• Dateien: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts und E2E-Tests gebündelter Plugins unter extensions/
• Laufzeit-Standardeinstellungen:
  • Verwendet Vitest threads mit isolate: false, passend zum Rest des Repos.
  • Verwendet adaptive Worker (CI: bis zu 2, lokal: standardmäßig 1).
  • Läuft standardmäßig im Silent-Modus, um Console-I/O-Overhead zu reduzieren.
• Nützliche Overrides:
  • OPENCLAW_E2E_WORKERS=<n>, um die Worker-Anzahl zu erzwingen (auf 16 begrenzt).
  • OPENCLAW_E2E_VERBOSE=1, um ausführliche Konsolenausgabe wieder zu aktivieren.
• Umfang:
  • End-to-End-Verhalten von Gateway-Mehrfachinstanzen
  • WebSocket/HTTP-Oberflächen, Node-Pairing und umfangreicheres Networking
• Erwartungen:
  • Läuft in CI (wenn in der Pipeline aktiviert)
  • Keine echten Schlüssel erforderlich
  • Mehr bewegliche Teile als Unit-Tests (kann langsamer sein)

# E2E: OpenShell-Backend-Smoke-Test

• Befehl: pnpm test:e2e:openshell
• Datei: extensions/openshell/src/backend.e2e.test.ts
• Umfang:
  • Startet ein isoliertes OpenShell-Gateway auf dem Host über Docker
  • Erstellt eine Sandbox aus einer temporären lokalen Dockerfile
  • Testet das OpenShell-Backend von OpenClaw über echtes sandbox ssh-config + SSH-Ausführung
  • Verifiziert remote-kanonisches Dateisystemverhalten über die Sandbox-fs-Bridge
• Erwartungen:
  • Nur per Opt-in; nicht Teil des standardmäßigen pnpm test:e2e-Laufs
  • Erfordert eine lokale openshell-CLI sowie einen funktionierenden Docker-Daemon
  • Verwendet isolierte HOME / XDG_CONFIG_HOME und entfernt danach das Test-Gateway und die Sandbox
• Nützliche Overrides:
  • OPENCLAW_E2E_OPENSHELL=1, um den Test beim manuellen Ausführen der breiteren E2E-Suite zu aktivieren
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell, um auf ein nicht standardmäßiges CLI-Binary oder Wrapper-Skript zu verweisen

# Live (echte Provider + echte Modelle)

• Befehl: pnpm test:live
• Konfiguration: vitest.live.config.ts
• Dateien: src/**/*.live.test.ts, test/**/*.live.test.ts und Live-Tests gebündelter Plugins unter extensions/
• Standard: durch pnpm test:live aktiviert (setzt OPENCLAW_LIVE_TEST=1)
• Umfang:
  • „Funktioniert dieser Provider/dieses Modell heute tatsächlich mit echten Zugangsdaten?“
  • Erkennt Provider-Formatänderungen, Besonderheiten beim Tool-Aufruf, Authentifizierungsprobleme und Rate-Limit-Verhalten
• Erwartungen:
  • Absichtlich nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Kontingente, Ausfälle)
  • Kostet Geld / nutzt Rate Limits
  • Führen Sie vorzugsweise eingegrenzte Teilmengen statt „alles“ aus
• Live-Läufe lesen ~/.profile ein, um fehlende API-Schlüssel zu übernehmen.
• Standardmäßig isolieren Live-Läufe weiterhin HOME und kopieren Konfigurations-/Authentifizierungsmaterial in ein temporäres Test-Home, damit Unit-Fixtures Ihr echtes ~/.openclaw nicht verändern können.
• Setzen Sie OPENCLAW_LIVE_USE_REAL_HOME=1 nur, wenn Live-Tests absichtlich Ihr echtes Home-Verzeichnis verwenden sollen.
• pnpm test:live verwendet jetzt standardmäßig einen ruhigeren Modus: Die [live] ...-Fortschrittsausgabe bleibt erhalten, aber der zusätzliche ~/.profile-Hinweis wird unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Rauschen werden stummgeschaltet. Setzen Sie OPENCLAW_LIVE_TEST_QUIET=0, wenn Sie die vollständigen Startlogs wieder haben möchten.
• API-Schlüsselrotation (Provider-spezifisch): Setzen Sie *_API_KEYS im Komma-/Semikolonformat oder *_API_KEY_1, *_API_KEY_2 (zum Beispiel OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) oder einen Live-spezifischen Override über OPENCLAW_LIVE_*_KEY; Tests wiederholen bei Rate-Limit-Antworten.
• Fortschritts-/Heartbeat-Ausgabe:
  • Live-Suites geben jetzt Fortschrittszeilen auf stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn die Vitest-Konsolenerfassung ruhig ist.
  • vitest.live.config.ts deaktiviert die Vitest-Konsoleninterception, damit Provider-/Gateway-Fortschrittszeilen während Live-Läufen sofort gestreamt werden.
  • Stimmen Sie Direct-Model-Heartbeats mit OPENCLAW_LIVE_HEARTBEAT_MS ab.
  • Stimmen Sie Gateway-/Probe-Heartbeats mit OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS ab.

# Welche Suite soll ich ausführen?

Verwenden Sie diese Entscheidungstabelle:

• Logik/Tests bearbeiten: Führen Sie pnpm test aus (und pnpm test:coverage, wenn Sie viel geändert haben)
• Gateway-Networking / WS-Protokoll / Pairing berühren: Fügen Sie pnpm test:e2e hinzu
• „Mein Bot ist ausgefallen“ / Provider-spezifische Fehler / Tool-Aufrufe debuggen: Führen Sie ein eingegrenztes pnpm test:live aus

# Live-Tests (mit Netzwerkzugriff)

Für die Live-Modellmatrix, CLI-Backend-Smoke-Tests, ACP-Smoke-Tests, den Codex-App-Server-Harness und alle Live-Tests für Medien-Provider (Deepgram, BytePlus, ComfyUI, Bild, Musik, Video, Medien-Harness) sowie den Umgang mit Zugangsdaten für Live-Läufe siehe Live-Suites testen. Für die dedizierte Checkliste zur Update- und Plugin-Validierung siehe Updates und Plugins testen.

# Docker-Runner (optionale „funktioniert unter Linux“-Prüfungen)

Diese Docker-Runner sind in zwei Gruppen aufgeteilt:

• Live-Modell-Runner: test:docker:live-models und test:docker:live-gateway führen nur ihre passende Live-Datei für Profil-Schlüssel innerhalb des Repo-Docker-Images aus (src/agents/models.profiles.live.test.ts und src/gateway/gateway-models.profiles.live.test.ts), mounten Ihr lokales Konfigurationsverzeichnis und Ihren Workspace (und lesen ~/.profile ein, falls gemountet). Die passenden lokalen Einstiegspunkte sind test:live:models-profiles und test:live:gateway-profiles.
• Docker-Live-Runner verwenden standardmäßig eine kleinere Smoke-Obergrenze, damit ein vollständiger Docker-Durchlauf praktikabel bleibt: test:docker:live-models verwendet standardmäßig OPENCLAW_LIVE_MAX_MODELS=12, und test:docker:live-gateway verwendet standardmäßig OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 und OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Überschreiben Sie diese Umgebungsvariablen, wenn Sie ausdrücklich den größeren vollständigen Scan wünschen.
• test:docker:all erstellt das Live-Docker-Image einmal über test:docker:live-build, packt OpenClaw einmal als npm-Tarball über scripts/package-openclaw-for-docker.mjs und erstellt/verwendet dann zwei scripts/e2e/Dockerfile-Images. Das Basis-Image ist nur der Node/Git-Runner für Installations-, Update- und Plugin-Abhängigkeits-Lanes; diese Lanes mounten den vorab erstellten Tarball. Das funktionale Image installiert denselben Tarball nach /app für Built-App-Funktionalitäts-Lanes. Docker-Lane-Definitionen liegen in scripts/lib/docker-e2e-scenarios.mjs; die Planner-Logik liegt in scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs führt den ausgewählten Plan aus. Das Aggregat verwendet einen gewichteten lokalen Scheduler: OPENCLAW_DOCKER_ALL_PARALLELISM steuert Prozess-Slots, während Ressourcenlimits verhindern, dass schwere Live-, npm-Installations- und Multi-Service-Lanes alle gleichzeitig starten. Wenn eine einzelne Lane schwerer ist als die aktiven Limits, kann der Scheduler sie trotzdem starten, wenn der Pool leer ist, und sie dann allein weiterlaufen lassen, bis wieder Kapazität verfügbar ist. Standardwerte sind 10 Slots, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=10 und OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; passen Sie OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT oder OPENCLAW_DOCKER_ALL_DOCKER_LIMIT nur an, wenn der Docker-Host mehr Spielraum hat. Der Runner führt standardmäßig einen Docker-Preflight aus, entfernt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Status aus, speichert erfolgreiche Lane-Zeiten in .artifacts/docker-tests/lane-timings.json und verwendet diese Zeiten, um bei späteren Läufen längere Lanes zuerst zu starten. Verwenden Sie OPENCLAW_DOCKER_ALL_DRY_RUN=1, um das gewichtete Lane-Manifest ohne Build oder Docker-Ausführung auszugeben, oder node scripts/test-docker-all.mjs --plan-json, um den CI-Plan für ausgewählte Lanes, Paket-/Image-Anforderungen und Zugangsdaten auszugeben.
• Package Acceptance ist das GitHub-native Paket-Gate für „Funktioniert dieser installierbare Tarball als Produkt?“ Es löst ein Kandidatenpaket aus source=npm, source=ref, source=url oder source=artifact auf, lädt es als package-under-test hoch und führt dann die wiederverwendbaren Docker-E2E-Lanes gegen genau diesen Tarball aus, statt den ausgewählten Ref neu zu packen. Profile sind nach Umfang geordnet: smoke, package, product und full. Siehe Updates und Plugins testen für den Paket-/Update-/Plugin-Vertrag, die Published-Upgrade-Survivor-Matrix, Release-Standardeinstellungen und Fehlertriage.
• Build- und Release-Prüfungen führen nach tsdown scripts/check-cli-bootstrap-imports.mjs aus. Der Guard durchläuft den statischen gebauten Graphen ab dist/entry.js und dist/cli/run-main.js und schlägt fehl, wenn Pre-Dispatch-Startup Paketabhängigkeiten wie Commander, Prompt-UI, undici oder Logging vor der Befehlsweiterleitung importiert; außerdem hält er den gebündelten Gateway-Run-Chunk innerhalb des Budgets und weist statische Importe bekannter kalter Gateway-Pfade zurück. Der Packaged-CLI-Smoke-Test deckt außerdem Root-Hilfe, Onboard-Hilfe, Doctor-Hilfe, Status, Konfigurationsschema und einen Modelllistenbefehl ab.
• Die Legacy-Kompatibilität von Package Acceptance ist auf 2026.4.25 begrenzt (2026.4.25-beta.* eingeschlossen). Bis zu diesem Stichtag toleriert der Harness nur Metadatenlücken ausgelieferter Pakete: ausgelassene private QA-Inventareinträge, fehlendes gateway install --wrapper, fehlende Patchdateien in der aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes update.channel, ältere Plugin-Install-Record-Speicherorte, fehlende Marketplace-Install-Record-Persistenz und Konfigurationsmetadaten-Migration während plugins update. Für Pakete nach 2026.4.25 sind diese Pfade strikte Fehler.
• Container-Smoke-Runner: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:pi-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix und test:docker:config-reload starten einen oder mehrere echte Container und verifizieren Integrationspfade auf höherer Ebene.

Die Live-Modell-Docker-Runner binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie anschließend vor dem Lauf in das Container-Home, damit externes CLI-OAuth Token aktualisieren kann, ohne den Auth-Speicher des Hosts zu verändern:

• Direkte Modelle: pnpm test:docker:live-models (Skript: scripts/test-live-models-docker.sh)
• ACP-Bind-Smoke-Test: pnpm test:docker:live-acp-bind (Skript: scripts/test-live-acp-bind-docker.sh; deckt standardmäßig Claude, Codex und Gemini ab, mit strenger Droid/OpenCode-Abdeckung über pnpm test:docker:live-acp-bind:droid und pnpm test:docker:live-acp-bind:opencode)
• CLI-Backend-Smoke-Test: pnpm test:docker:live-cli-backend (Skript: scripts/test-live-cli-backend-docker.sh)
• Codex-App-Server-Harness-Smoke-Test: pnpm test:docker:live-codex-harness (Skript: scripts/test-live-codex-harness-docker.sh)
• Gateway + Entwicklungsagent: pnpm test:docker:live-gateway (Skript: scripts/test-live-gateway-models-docker.sh)
• Observability-Smoke-Test: pnpm qa:otel:smoke ist ein privater QA-Prüfpfad für Source-Checkouts. Er ist absichtlich nicht Teil der Docker-Release-Prüfpfade für Pakete, weil der npm-Tarball das QA Lab auslässt.
• Open WebUI-Live-Smoke-Test: pnpm test:docker:openwebui (Skript: scripts/e2e/openwebui-docker.sh)
• Onboarding-Assistent (TTY, vollständiges Scaffolding): pnpm test:docker:onboard (Skript: scripts/e2e/onboard-docker.sh)
• npm-Tarball-Smoke-Test für Onboarding/Kanal/Agent: pnpm test:docker:npm-onboard-channel-agent installiert den gepackten OpenClaw-Tarball global in Docker, konfiguriert OpenAI über env-ref-Onboarding sowie standardmäßig Telegram, führt doctor aus und führt eine gemockte OpenAI-Agent-Interaktion aus. Verwenden Sie einen vorgebauten Tarball mit OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz erneut, überspringen Sie den Host-Neubuild mit OPENCLAW_NPM_ONBOARD_HOST_BUILD=0, oder wechseln Sie den Kanal mit OPENCLAW_NPM_ONBOARD_CHANNEL=discord oder OPENCLAW_NPM_ONBOARD_CHANNEL=slack.
• Smoke-Test für Update-Kanalwechsel: pnpm test:docker:update-channel-switch installiert den gepackten OpenClaw-Tarball global in Docker, wechselt vom Paketkanal stable zu Git dev, verifiziert den gespeicherten Kanal und die Plugin-Funktion nach dem Update, wechselt dann zurück zum Paketkanal stable und prüft den Update-Status.
• Upgrade-Survivor-Smoke-Test: pnpm test:docker:upgrade-survivor installiert den gepackten OpenClaw-Tarball über ein verunreinigtes Old-User-Fixture mit Agents, Kanalkonfiguration, Plugin-Allowlists, veraltetem Plugin-Abhängigkeitsstatus und vorhandenen Workspace-/Sitzungsdateien. Er führt ein Paket-Update plus nicht interaktiven doctor ohne Live-Provider- oder Kanalschlüssel aus, startet dann ein Loopback-Gateway und prüft die Erhaltung von Konfiguration/Zustand sowie Start-/Status-Budgets.
• Veröffentlichter Upgrade-Survivor-Smoke-Test: pnpm test:docker:published-upgrade-survivor installiert standardmäßig openclaw@latest, erzeugt realistische Existing-User-Dateien, konfiguriert diese Basislinie mit einem eingebetteten Befehlsrezept, validiert die resultierende Konfiguration, aktualisiert diese veröffentlichte Installation auf den Kandidaten-Tarball, führt den nicht interaktiven doctor aus, schreibt .artifacts/upgrade-survivor/summary.json, startet dann ein Loopback-Gateway und prüft konfigurierte Intents, Zustandserhaltung, Start, /healthz, /readyz und RPC-Status-Budgets. Überschreiben Sie eine Basislinie mit OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, weisen Sie den Aggregat-Scheduler an, exakte lokale Basislinien mit OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS wie [email protected] [email protected] [email protected] zu erweitern, und erweitern Sie issue-artige Fixtures mit OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS wie reported-issues; die Menge reported-issues enthält configured-plugin-installs für die automatische Reparatur externer OpenClaw-Plugin-Installationen. Package Acceptance stellt diese als published_upgrade_survivor_baseline, published_upgrade_survivor_baselines und published_upgrade_survivor_scenarios bereit, löst Meta-Basislinien-Token wie last-stable-4 oder all-since-2026.4.23 auf, und Full Release Validation erweitert den Package-Gate für den Release-Soak auf last-stable-4 2026.4.23 2026.5.2 2026.4.15 plus reported-issues.
• Smoke-Test für Sitzungslaufzeitkontext: pnpm test:docker:session-runtime-context verifiziert die Persistenz versteckter Laufzeitkontext-Transkripte sowie doctor-Reparatur betroffener duplizierter Prompt-Rewrite-Branches.
• Bun-Smoke-Test für globale Installation: bash scripts/e2e/bun-global-install-smoke.sh packt den aktuellen Baum, installiert ihn mit bun install -g in einem isolierten Home und verifiziert, dass openclaw infer image providers --json gebündelte Bild-Provider zurückgibt, statt hängen zu bleiben. Verwenden Sie einen vorgebauten Tarball mit OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz erneut, überspringen Sie den Host-Build mit OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0, oder kopieren Sie dist/ aus einem gebauten Docker-Image mit OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.
• Installer-Docker-Smoke-Test: bash scripts/test-install-sh-docker.sh teilt einen npm-Cache zwischen seinen Root-, Update- und direkten npm-Containern. Der Update-Smoke-Test verwendet standardmäßig npm latest als stabile Basislinie, bevor auf den Kandidaten-Tarball aktualisiert wird. Überschreiben Sie dies lokal mit OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 oder auf GitHub mit der Eingabe update_baseline_version des Install Smoke-Workflows. Nicht-Root-Installer-Prüfungen behalten einen isolierten npm-Cache, damit Root-eigene Cache-Einträge das benutzerlokale Installationsverhalten nicht verdecken. Setzen Sie OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache, um den Root-/Update-/direkten npm-Cache über lokale Wiederholungen hinweg erneut zu verwenden.
• Install Smoke CI überspringt das doppelte direkte globale npm-Update mit OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; führen Sie das Skript lokal ohne diese Env aus, wenn direkte npm install -g-Abdeckung benötigt wird.
• CLI-Smoke-Test für das Löschen eines gemeinsam genutzten Workspace durch Agents: pnpm test:docker:agents-delete-shared-workspace (Skript: scripts/e2e/agents-delete-shared-workspace-docker.sh) baut standardmäßig das Root-Dockerfile-Image, erzeugt zwei Agents mit einem Workspace in einem isolierten Container-Home, führt agents delete --json aus und verifiziert gültiges JSON sowie das Verhalten für beibehaltene Workspaces. Verwenden Sie das Install-Smoke-Image mit OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1 erneut.
• Gateway-Netzwerk (zwei Container, WS-Authentifizierung + Health): pnpm test:docker:gateway-network (Skript: scripts/e2e/gateway-network-docker.sh)
• Browser-CDP-Snapshot-Smoke-Test: pnpm test:docker:browser-cdp-snapshot (Skript: scripts/e2e/browser-cdp-snapshot-docker.sh) baut das Source-E2E-Image plus eine Chromium-Schicht, startet Chromium mit rohem CDP, führt browser doctor --deep aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, per Cursor hervorgehobene anklickbare Elemente, iframe-Referenzen und Frame-Metadaten abdecken.
• OpenAI Responses-Regression für web_search mit minimalem Reasoning: pnpm test:docker:openai-web-search-minimal (Skript: scripts/e2e/openai-web-search-minimal-docker.sh) führt einen gemockten OpenAI-Server über Gateway aus, verifiziert, dass web_search reasoning.effort von minimal auf low anhebt, erzwingt dann die Ablehnung durch das Provider-Schema und prüft, dass das rohe Detail in den Gateway-Logs erscheint.
• MCP-Kanal-Bridge (vorbereitetes Gateway + stdio-Bridge + roher Claude-Smoke-Test für Notification-Frames): pnpm test:docker:mcp-channels (Skript: scripts/e2e/mcp-channels-docker.sh)
• Pi-Bundle-MCP-Tools (echter stdio-MCP-Server + eingebetteter Pi-Profil-Allow-/Deny-Smoke-Test): pnpm test:docker:pi-bundle-mcp-tools (Skript: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Cron/Subagent-MCP-Bereinigung (echtes Gateway + Teardown des stdio-MCP-Child nach isolierten Cron- und einmaligen Subagent-Ausführungen): pnpm test:docker:cron-mcp-cleanup (Skript: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (Installations-/Update-Smoke-Test für lokalen Pfad, file:, npm-Registry mit hoisted Abhängigkeiten, bewegliche Git-Refs, ClawHub-Kitchen-Sink, Marketplace-Updates und Aktivieren/Prüfen des Claude-Bundles): pnpm test:docker:plugins (Skript: scripts/e2e/plugins-docker.sh) Setzen Sie OPENCLAW_PLUGINS_E2E_CLAWHUB=0, um den ClawHub-Block zu überspringen, oder überschreiben Sie das standardmäßige Kitchen-Sink-Paket-/Laufzeit-Paar mit OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC und OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Ohne OPENCLAW_CLAWHUB_URL/CLAWHUB_URL verwendet der Test einen hermetischen lokalen ClawHub-Fixture-Server.
• Smoke-Test für unverändertes Plugin-Update: pnpm test:docker:plugin-update (Skript: scripts/e2e/plugin-update-unchanged-docker.sh)
• Smoke-Test für Plugin-Lifecycle-Matrix: pnpm test:docker:plugin-lifecycle-matrix installiert den gepackten OpenClaw-Tarball in einem nackten Container, installiert ein npm-Plugin, schaltet Aktivieren/Deaktivieren um, aktualisiert es und führt ein Downgrade über eine lokale npm-Registry durch, löscht den installierten Code und verifiziert dann, dass die Deinstallation weiterhin veralteten Zustand entfernt, während RSS-/CPU-Metriken für jede Lifecycle-Phase protokolliert werden.
• Smoke-Test für Config-Reload-Metadaten: pnpm test:docker:config-reload (Skript: scripts/e2e/config-reload-source-docker.sh)
• Plugins: pnpm test:docker:plugins deckt Installations-/Update-Smoke-Tests für lokalen Pfad, file:, npm-Registry mit hoisted Abhängigkeiten, bewegliche Git-Refs, ClawHub-Fixtures, Marketplace-Updates und Aktivieren/Prüfen des Claude-Bundles ab. pnpm test:docker:plugin-update deckt unverändertes Update-Verhalten für installierte Plugins ab. pnpm test:docker:plugin-lifecycle-matrix deckt ressourcenverfolgte npm-Plugin-Installation, Aktivierung, Deaktivierung, Upgrade, Downgrade und Deinstallation bei fehlendem Code ab.

So bauen Sie das gemeinsam genutzte funktionale Image manuell vor und verwenden es erneut:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

Suite-spezifische Image-Overrides wie OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE haben weiterhin Vorrang, wenn sie gesetzt sind. Wenn OPENCLAW_SKIP_DOCKER_BUILD=1 auf ein entferntes gemeinsam genutztes Image verweist, ziehen die Skripte es, falls es noch nicht lokal vorhanden ist. Die QR- und Installer-Docker-Tests behalten ihre eigenen Dockerfiles, weil sie Paket-/Installationsverhalten statt der gemeinsam gebauten App-Laufzeit validieren.

Die Docker-Runner für Live-Modelle binden außerdem den aktuellen Checkout schreibgeschützt ein und stellen ihn in einem temporären Arbeitsverzeichnis innerhalb des Containers bereit. Dadurch bleibt das Laufzeit- Image schlank, während Vitest trotzdem gegen Ihre exakte lokale Source-/Konfigurationsversion läuft. Der Staging-Schritt überspringt große, nur lokal relevante Caches und App-Build-Ausgaben wie .pnpm-store, .worktrees, __openclaw_vitest__ sowie app-lokale .build- oder Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht minutenlang maschinenspezifische Artefakte kopieren. Sie setzen außerdem OPENCLAW_SKIP_CHANNELS=1, damit Gateway-Live-Probes keine echten Telegram-/Discord-/usw.-Kanal-Worker innerhalb des Containers starten. test:docker:live-models führt weiterhin pnpm test:live aus; geben Sie daher auch OPENCLAW_LIVE_GATEWAY_* durch, wenn Sie die Gateway-Live-Abdeckung in dieser Docker-Lane eingrenzen oder ausschließen müssen. test:docker:openwebui ist ein höherstufiger Kompatibilitäts-Smoke: Er startet einen OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, startet einen gepinnten Open WebUI-Container gegen dieses Gateway, meldet sich über Open WebUI an, verifiziert, dass /api/models openclaw/default bereitstellt, und sendet dann eine echte Chat-Anfrage über den /api/chat/completions-Proxy von Open WebUI. Der erste Lauf kann spürbar langsamer sein, weil Docker möglicherweise das Open WebUI-Image pullen muss und Open WebUI eventuell erst seine eigene Cold-Start-Einrichtung abschließen muss. Diese Lane erwartet einen nutzbaren Live-Model-Key, und OPENCLAW_PROFILE_FILE (standardmäßig ~/.profile) ist der primäre Weg, ihn in Dockerisierten Läufen bereitzustellen. Erfolgreiche Läufe geben eine kleine JSON-Nutzlast wie { "ok": true, "model": "openclaw/default", ... } aus. test:docker:mcp-channels ist absichtlich deterministisch und benötigt kein echtes Telegram-, Discord- oder iMessage-Konto. Es bootet einen geseedeten Gateway- Container, startet einen zweiten Container, der openclaw mcp serve spawnt, und verifiziert dann geroutete Konversationserkennung, Transkriptlesevorgänge, Anhangsmetadaten, Verhalten der Live-Event-Queue, Routing ausgehender Sends sowie Channel- und Berechtigungsbenachrichtigungen im Claude-Stil über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung inspiziert die rohen stdio-MCP-Frames direkt, sodass der Smoke validiert, was die Bridge tatsächlich ausgibt, nicht nur das, was ein bestimmtes Client-SDK zufällig sichtbar macht. test:docker:pi-bundle-mcp-tools ist deterministisch und benötigt keinen Live- Model-Key. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server innerhalb des Containers, materialisiert diesen Server über die eingebettete Pi-Bundle- MCP-Runtime, führt das Tool aus und verifiziert dann, dass coding und messaging bundle-mcp-Tools behalten, während minimal und tools.deny: ["bundle-mcp"] sie filtern. test:docker:cron-mcp-cleanup ist deterministisch und benötigt keinen Live-Model- Key. Es startet ein geseedetes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen isolierten Cron-Turn und einen /subagents spawn-One-Shot-Child-Turn aus und verifiziert dann, dass der MCP-Child-Prozess nach jedem Lauf beendet wird.

Manueller ACP-Plain-Language-Thread-Smoke (nicht CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Behalten Sie dieses Skript für Regressions-/Debug-Workflows. Es könnte erneut für die ACP-Thread-Routing-Validierung benötigt werden; löschen Sie es daher nicht.

Nützliche Umgebungsvariablen:

• OPENCLAW_CONFIG_DIR=... (Standard: ~/.openclaw) wird nach /home/node/.openclaw gemountet
• OPENCLAW_WORKSPACE_DIR=... (Standard: ~/.openclaw/workspace) wird nach /home/node/.openclaw/workspace gemountet
• OPENCLAW_PROFILE_FILE=... (Standard: ~/.profile) wird nach /home/node/.profile gemountet und vor der Testausführung eingelesen
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1, um nur Umgebungsvariablen zu verifizieren, die aus OPENCLAW_PROFILE_FILE eingelesen wurden, mit temporären Konfigurations-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (Standard: ~/.cache/openclaw/docker-cli-tools) wird nach /home/node/.npm-global für gecachte CLI-Installationen innerhalb von Docker gemountet
• Externe CLI-Auth-Verzeichnisse/-Dateien unter $HOME werden schreibgeschützt unter /host-auth... gemountet und dann vor Testbeginn nach /home/node/... kopiert
  • Standardverzeichnisse: .minimax
  • Standarddateien: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, die aus OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS abgeleitet werden
  • Manuelles Überschreiben mit OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none oder einer kommagetrennten Liste wie OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=..., um den Lauf einzugrenzen
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=..., um Provider im Container zu filtern
• OPENCLAW_SKIP_DOCKER_BUILD=1, um ein vorhandenes openclaw:local-live-Image für erneute Läufe wiederzuverwenden, die keinen Rebuild benötigen
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um sicherzustellen, dass Anmeldedaten aus dem Profil-Store stammen (nicht aus der Umgebung)
• OPENCLAW_OPENWEBUI_MODEL=..., um das vom Gateway für den Open WebUI-Smoke bereitgestellte Modell auszuwählen
• OPENCLAW_OPENWEBUI_PROMPT=..., um den vom Open WebUI-Smoke verwendeten Nonce-Check-Prompt zu überschreiben
• OPENWEBUI_IMAGE=..., um das gepinnte Open WebUI-Image-Tag zu überschreiben

# Docs-Sanity

Führen Sie nach Dokumentationsänderungen Docs-Prüfungen aus: pnpm check:docs. Führen Sie die vollständige Mintlify-Ankervalidierung aus, wenn Sie zusätzlich In-Page-Heading-Prüfungen benötigen: pnpm docs:check-links:anchors.

# Offline-Regression (CI-sicher)

Dies sind Regressionen mit einer „echten Pipeline“ ohne echte Provider:

• Gateway-Tool-Calling (Mock-OpenAI, echtes Gateway + Agent-Loop): src/gateway/gateway.test.ts (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Gateway-Assistent (WS wizard.start/wizard.next, schreibt Konfiguration + Auth erzwungen): src/gateway/gateway.test.ts (Fall: "runs wizard over ws and writes auth token config")

# Agent-Zuverlässigkeits-Evals (Skills)

Wir haben bereits einige CI-sichere Tests, die sich wie „Agent-Zuverlässigkeits-Evals“ verhalten:

• Mock-Tool-Calling über das echte Gateway + Agent-Loop (src/gateway/gateway.test.ts).
• End-to-End-Assistenten-Flows, die Session-Verdrahtung und Konfigurationseffekte validieren (src/gateway/gateway.test.ts).

Was für Skills noch fehlt (siehe Skills):

• Entscheidungsfindung: Wenn Skills im Prompt aufgeführt sind, wählt der Agent den richtigen Skill (oder vermeidet irrelevante)?
• Compliance: Liest der Agent SKILL.md vor der Nutzung und befolgt er erforderliche Schritte/Argumente?
• Workflow-Verträge: Multi-Turn-Szenarien, die Tool-Reihenfolge, Übernahme des Session-Verlaufs und Sandbox-Grenzen prüfen.

Zukünftige Evals sollten zuerst deterministisch bleiben:

• Ein Szenario-Runner mit Mock-Providern, der Tool-Aufrufe + Reihenfolge, Skill-Dateilesevorgänge und Session-Verdrahtung prüft.
• Eine kleine Suite skill-fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection).
• Optionale Live-Evals (Opt-in, env-gesteuert) erst, nachdem die CI-sichere Suite vorhanden ist.

# Vertragstests (Plugin- und Channel-Shape)

Vertragstests verifizieren, dass jedes registrierte Plugin und jeder registrierte Channel seinem Interface-Vertrag entspricht. Sie iterieren über alle gefundenen Plugins und führen eine Suite von Shape- und Verhaltensassertions aus. Die standardmäßige pnpm test-Unit-Lane überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Contract-Befehle explizit aus, wenn Sie gemeinsame Channel- oder Provider-Oberflächen berühren.

# Befehle

• Alle Verträge: pnpm test:contracts
• Nur Channel-Verträge: pnpm test:contracts:channels
• Nur Provider-Verträge: pnpm test:contracts:plugins

# Channel-Verträge

Befinden sich in src/channels/plugins/contracts/*.contract.test.ts:

• plugin - Grundlegender Plugin-Shape (ID, Name, Fähigkeiten)
• setup - Setup-Assistent-Vertrag
• session-binding - Verhalten der Session-Bindung
• outbound-payload - Nachrichten-Payload-Struktur
• inbound - Verarbeitung eingehender Nachrichten
• actions - Channel-Action-Handler
• threading - Verarbeitung von Thread-IDs
• directory - Directory-/Roster-API
• group-policy - Durchsetzung der Gruppenrichtlinie

# Provider-Status-Verträge

Befinden sich in src/plugins/contracts/*.contract.test.ts.

• status - Channel-Status-Probes
• registry - Plugin-Registry-Shape

# Provider-Verträge

Befinden sich in src/plugins/contracts/*.contract.test.ts:

• auth - Auth-Flow-Vertrag
• auth-choice - Auth-Auswahl/Selektion
• catalog - Modellkatalog-API
• discovery - Plugin-Erkennung
• loader - Plugin-Laden
• runtime - Provider-Runtime
• shape - Plugin-Shape/-Interface
• wizard - Setup-Assistent

# Ausführungszeitpunkt

• Nach Änderungen an plugin-sdk-Exports oder Subpaths
• Nach dem Hinzufügen oder Ändern eines Channel- oder Provider-Plugins
• Nach dem Refactoring von Plugin-Registrierung oder -Erkennung

Vertragstests laufen in CI und benötigen keine echten API-Keys.

# Regressionen hinzufügen (Anleitung)

Wenn Sie ein Provider-/Modellproblem beheben, das live entdeckt wurde:

• Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder Erfassung der exakten Request-Shape-Transformation)
• Wenn es von Natur aus nur live prüfbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test schmal und per Umgebungsvariablen opt-in
• Zielen Sie bevorzugt auf die kleinste Ebene, die den Fehler abfängt:
  • Provider-Request-Konvertierungs-/Replay-Bug → direkter Modelltest
  • Gateway-Session-/History-/Tool-Pipeline-Bug → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test
• SecretRef-Traversal-Guardrail:
  • src/secrets/exec-secret-ref-id-parity.test.ts leitet aus Registry-Metadaten (listSecretTargetRegistryEntries()) ein gesampeltes Ziel pro SecretRef-Klasse ab und assertet dann, dass Exec-IDs mit Traversal-Segmenten abgelehnt werden.
  • Wenn Sie eine neue includeInPlan-SecretRef-Zielfamilie in src/secrets/target-registry-data.ts hinzufügen, aktualisieren Sie classifyTargetClass in diesem Test. Der Test schlägt absichtlich bei unklassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden können.

# Verwandt

• Live testen
• Updates und Plugins testen
• CI