Testen

OpenClaw hat 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 sollten (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
• Schnellere lokale Ausführung der vollständigen Suite auf einem großzügig ausgestatteten Rechner: pnpm test:max
• Direkte Vitest-Watch-Schleife: pnpm test:watch
• Direktes Datei-Targeting leitet jetzt auch Extension-/Kanal-Pfade weiter: 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 wünschen:

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

Temporäre Testverzeichnisse

Bevorzugen Sie die gemeinsamen Hilfsfunktionen in test/helpers/temp-dir.ts für testeigene temporäre Verzeichnisse. Sie machen die Zuständigkeit explizit und halten die Bereinigung im selben Test-Lebenszyklus:

  const tempDirs = useAutoCleanupTempDirTracker(afterEach); it("uses a temp workspace", () => {  const workspace = tempDirs.make("openclaw-example-");  // use workspace});

useAutoCleanupTempDirTracker(afterEach) stellt absichtlich keine manuelle Bereinigungsmethode bereit; Vitest übernimmt die Bereinigung nach jedem Test. Bestehende Hilfsfunktionen auf niedrigerer Ebene bleiben für Tests erhalten, die noch nicht migriert wurden, aber neue und migrierte Tests sollten den automatisch bereinigenden Tracker verwenden. Vermeiden Sie neue manuelle Verwendungen von makeTempDir, cleanupTempDirs oder createTempDirTracker und vermeiden Sie neue direkte fs.mkdtemp*-Aufrufe in Tests, außer ein Fall verifiziert ausdrücklich das rohe Temp-Dir-Verhalten. Fügen Sie einen auditierbaren Allow-Kommentar mit einem konkreten Grund hinzu, wenn ein Test absichtlich ein direktes temporäres Verzeichnis benötigt:

// openclaw-temp-dir: allow verifies raw fs cleanup behaviorconst workspace = fs.mkdtempSync(prefix);

Für Migrationssichtbarkeit meldet node scripts/report-test-temp-creations.mjs neue direkte Temp-Dir-Erstellung und neue manuelle Nutzung gemeinsamer Hilfsfunktionen in hinzugefügten Diff-Zeilen, ohne bestehende Bereinigungsstile zu blockieren. Sein Dateiscope folgt absichtlich derselben Testpfad-Klassifizierung, die von scripts/changed-lanes.mjs verwendet wird, statt eine separate Test-Hilfsdateinamen-Heuristik zu pflegen, überspringt dabei aber die Implementierung der gemeinsamen Hilfsfunktion selbst. check:changed führt diesen Bericht für geänderte Testpfade als reines Warnsignal in CI aus; Befunde sind GitHub-Warnannotationen, keine Fehler.

Beim Debuggen echter Provider/Modelle (erfordert echte Zugangsdaten):

• Live-Suite (Modelle + Gateway-Tool-/Bild-Probes): pnpm test:live
• Eine Live-Datei gezielt und ruhig ausführen: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Laufzeit-Performance-Berichte: Dispatchen Sie OpenClaw Performance mit live_openai_candidate=true für einen echten openai/gpt-5.5-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.5-Lane-Artefakte nach openclaw/clawgrit-reports, wenn CLAWGRIT_REPORTS_TOKEN konfiguriert ist. Der Mock-Provider-Bericht enthält außerdem Zahlen zu Gateway-Start auf Source-Ebene, Speicher, Plugin-Pressure, wiederholter Fake-Model-Hello-Loop 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 File-Read-artige Probe aus. Modelle, deren Metadaten image-Eingaben ausweisen, führen zusätzlich einen kleinen 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: Tägliche OpenClaw Scheduled Live And E2E Checks und manuelle OpenClaw Release Checks rufen beide den wiederverwendbaren Live-/E2E-Workflow mit include_live_suites: true auf, der separate Docker-Live-Modell- Matrix-Jobs nach Provider geshardet enthält.
  • 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 hochsignalige Provider-Secrets zu scripts/ci-hydrate-live-auth.sh plus .github/workflows/openclaw-live-and-e2e-checks-reusable.yml und seinen geplanten/Release-Aufrufern 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 anschließend eine einfache Antwort und eine Bildanhang- Route über die native Plugin-Bindung statt ACP.
• Codex-App-Server-Harness-Smoke: pnpm test:docker:live-codex-harness
  • Führt Gateway-Agent-Turns über 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 einen fokussierten Sub-Agent-Check 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 sich nach der Sub-Agent-Probe, sofern OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 nicht gesetzt ist.
• Codex-On-Demand-Install-Smoke: pnpm test:docker:codex-on-demand
  • Installiert den gepackten OpenClaw-Tarball in Docker, führt das OpenAI-API-Key- Onboarding aus und verifiziert, dass das Codex-Plugin plus die @openai/codex-Abhängigkeit bei Bedarf in den verwalteten npm-Projekt-Root heruntergeladen wurden.
• Live-Plugin-Tool-Abhängigkeits-Smoke: pnpm test:docker:live-plugin-tool
  • Packt ein Fixture-Plugin mit einer echten slugify-Abhängigkeit, installiert es über npm-pack:, verifiziert die Abhängigkeit unter dem verwalteten npm-Projekt-Root, fordert dann ein Live-OpenAI-Modell auf, das Plugin-Tool aufzurufen und den versteckten Slug zurückzugeben.
• Crestodian-Rescue-Command-Smoke: pnpm test:live:crestodian-rescue-channel
  • Opt-in-Belt-and-Suspenders-Prüfung für die Rescue-Command- Oberfläche des Nachrichtenkanals. Sie übt /crestodian status aus, reiht eine persistente Modell- Änderung ein, antwortet mit /crestodian yes und verifiziert den Audit-/Config-Schreibpfad.
• Crestodian-Planner-Docker-Smoke: pnpm test:docker:crestodian-planner
  • Führt Crestodian in einem konfigurationslosen 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-Dir, verifiziert den modernen Onboard- Crestodian-Einstiegspunkt, wendet Setup-/Modell-/Agent-/Discord-Plugin- + SecretRef- Schreibvorgänge an, validiert die Config und verifiziert Audit-Einträge. Derselbe Ring-0-Setup- Pfad ist auch in QA Lab durch pnpm openclaw qa suite --scenario crestodian-ring-zero-setup abgedeckt.
• Moonshot-/Kimi-Kosten-Smoke: Führen Sie mit gesetztem MOONSHOT_API_KEY openclaw models list --provider moonshot --json aus, dann 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 Assistenten-Transkript normalisierte usage.cost speichert.

QA-spezifische Runner

Diese Befehle stehen neben den Haupt-Test-Suites, 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, nicht als 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 manueller Dispatch mit der Mock-Parity-Lane, Live- Matrix-Lane, Convex-verwalteter Live-Telegram-Lane und Convex-verwalteter Live-Discord- Lane als parallele Jobs. Geplante QA- und Release-Checks übergeben Matrix --profile fast explizit, während die Matrix-CLI und die manuelle Workflow-Eingabe standardmäßig all bleiben; manuelle Dispatches können 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 normalen Provider-Plugin-Start vermeiden. Diese Live-Transport- Gateways deaktivieren die Speichersuche; Speicherverhalten bleibt durch die QA-Parity- Suites abgedeckt.

Vollständige 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 gemeinsame 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 innerhalb jedes Shards neu zu bauen.

• pnpm openclaw qa suite
  • Führt repo-gestützte QA-Szenarien direkt auf dem Host aus.
  • Schreibt Artefakte auf oberster Ebene: qa-evidence.json, qa-suite-summary.json und qa-suite-report.md für die ausgewählte Szenariomenge, einschließlich Auswahlen für gemischte Flows, Vitest- und Playwright-Szenarien.
  • Wenn der Befehl durch pnpm openclaw qa run --qa-profile <profile> ausgelöst wird, bettet er die ausgewählte Taxonomie-Profil-Scorecard in dieselbe qa-evidence.json ein. smoke-ci schreibt schlanke Evidenz, setzt evidenceMode: "slim" und lässt execution pro Eintrag aus. release deckt den kuratierten Release-Readiness-Ausschnitt ab; all wählt jede aktive Reifegradkategorie aus und ist für explizite QA-Profile-Evidence-Workflow-Auslösungen gedacht, wenn ein vollständiges Scorecard-Artefakt benötigt wird.
  • Führt standardmäßig mehrere ausgewählte Szenarien 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 sich 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 Protocol-Mock-Abdeckung, ohne die szenariobewusste mock-openai-Lane zu ersetzen.
• pnpm openclaw qa coverage --match <query>
  • Durchsucht Szenario-IDs, Titel, Oberflächen, Coverage-IDs, Dokumentationsreferenzen, Code-Referenzen, Plugins und Provider-Anforderungen und gibt dann passende Suite-Ziele aus.
  • Verwenden Sie dies vor einem QA-Lab-Lauf, wenn Sie das geänderte Verhalten oder den Dateipfad kennen, aber nicht das kleinste Szenario. Es ist nur eine Empfehlung; wählen Sie weiterhin Mock-, Live-, Multipass-, Matrix- oder Transport-Evidenz anhand des geänderten Verhaltens.
• 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-Evidenz 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 lädt er automatisch das Testbox-Live-Auth-Profil, wenn der openclaw-testbox-env-Helper 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 anhaltende Hot-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 auszusehen.
  • Verwendet gebaute dist-Artefakte; führen Sie zuerst einen Build aus, wenn der Checkout noch keine frische Runtime-Ausgabe enthält.
• pnpm openclaw qa suite --runner multipass
  • Führt dieselbe QA-Suite innerhalb einer wegwerfbaren 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 QA-Live-Provider-Konfigurationspfad 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 operatorartige QA-Arbeit.
• pnpm test:docker:npm-onboard-channel-agent
  • Erstellt einen npm-Tarball aus dem aktuellen Checkout, installiert ihn global in Docker, führt nicht-interaktives Onboarding mit OpenAI-API-Schlüssel aus, konfiguriert standardmäßig Telegram, verifiziert, dass die gepackte Plugin-Runtime ohne Startup- Dependency-Reparatur lädt, 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 Docker-Smoke der gebauten App für eingebettete Runtime-Kontext- Transkripte aus. Er verifiziert, dass versteckter OpenClaw-Runtime-Kontext als nicht angezeigte benutzerdefinierte Nachricht persistiert wird, statt in den sichtbaren User-Turn zu gelangen, seedet anschließend eine betroffene defekte Session-JSONL 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 Onboarding für das installierte Paket aus, konfiguriert Telegram über die installierte CLI und verwendet dann die Live-Telegram-QA-Lane mit diesem installierten Paket als SUT-Gateway erneut.
  • Der Wrapper mountet nur den qa-lab-Harness-Quellcode aus dem Checkout; das installierte Paket besitzt dist, openclaw/plugin-sdk und die gebündelte Plugin- Runtime, damit die Lane keine aktuellen Checkout-Plugins in das zu testende Paket mischt.
  • 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 stattdessen einen aufgelösten lokalen Tarball zu testen, statt aus der Registry zu installieren.
  • Gibt standardmäßig wiederholtes RTT-Timing in qa-evidence.json mit OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20 aus. Überschreiben Sie OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES, OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS oder OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES, um den RTT-Lauf anzupassen. OPENCLAW_NPM_TELEGRAM_RTT_CHECKS akzeptiert eine kommagetrennte Liste von Telegram-QA-Check-IDs für das Sampling; wenn nicht gesetzt, ist der standardmäßige RTT-fähige Check telegram-mentioned-message-reply.
  • Verwendet dieselben Telegram-env-Anmeldedaten oder dieselbe Convex-Anmeldedatenquelle wie pnpm openclaw qa telegram. Für CI-/Release-Automatisierung setzen Sie OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex plus OPENCLAW_QA_CONVEX_SITE_URL und ein Rollen-Secret. Wenn OPENCLAW_QA_CONVEX_SITE_URL und ein Convex-Rollen-Secret in CI vorhanden sind, wählt der Docker-Wrapper automatisch Convex.
  • Der Wrapper validiert Telegram- oder Convex-Anmeldedaten-env auf dem Host vor Docker-Build-/Installationsarbeit. Setzen Sie OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 nur, wenn Sie bewusst das Setup vor den Anmeldedaten debuggen.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer überschreibt die gemeinsame OPENCLAW_QA_CREDENTIAL_ROLE nur für diese Lane. Wenn Convex-Anmeldedaten ausgewählt sind und keine Rolle gesetzt ist, verwendet der Wrapper ci in CI und maintainer außerhalb von CI.
  • GitHub Actions stellt diese Lane als manuellen Maintainer-Workflow NPM Telegram Beta E2E bereit. Er läuft nicht bei Merge. Der Workflow verwendet die qa-live-shared-Umgebung und Convex-CI-Anmeldedaten-Leases.
• GitHub Actions stellt außerdem Package Acceptance für seitlich laufende Produkt-Evidenz gegen ein Kandidatenpaket bereit. Es akzeptiert eine vertrauenswürdige 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 dann den bestehenden Docker-E2E-Scheduler mit Smoke-, Package-, Product-, Full- oder Custom- Lane-Profilen aus. Setzen Sie telegram_mode=mock-openai oder live-frontier, um den Telegram-QA-Workflow gegen dasselbe package-under-test-Artefakt auszuführen.
  • Neueste Beta-Produkt-Evidenz:

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

• Evidenz mit exakter Tarball-URL erfordert einen Digest und verwendet die Sicherheitsrichtlinie für öffentliche URLs:

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

• Enterprise-/private Tarball-Spiegel verwenden eine explizite Richtlinie für vertrauenswürdige Quellen:

gh workflow run package-acceptance.yml --ref main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

source=trusted-url liest .github/package-trusted-sources.json aus der vertrauenswürdigen Workflow-Ref und akzeptiert keine URL-Anmeldedaten oder Umgehung für private Netzwerke per Workflow-Eingabe. Wenn die benannte Richtlinie Bearer-Auth deklariert, konfigurieren Sie das feste Secret OPENCLAW_TRUSTED_PACKAGE_TOKEN.

• Artefakt-Evidenz 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

  • Packt und installiert den aktuellen OpenClaw-Build in Docker, startet den Gateway mit konfiguriertem OpenAI und aktiviert dann gebündelte Channels/Plugins über Konfigurations- Änderungen.
  • Verifiziert, dass Setup-Discovery unkonfigurierte herunterladbare Plugins abwesend lässt, die erste konfigurierte doctor-Reparatur jedes fehlende herunterladbare Plugin explizit installiert und ein zweiter Neustart keine versteckte Dependency- Reparatur 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 Post-Update- doctor des Kandidaten Legacy-Plugin-Dependency-Reste 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 den installierten Befehl openclaw update im selben Gast 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 Zusammenfassungsartefaktpfad und den Status pro Lane.

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

  • Umschließen Sie lange lokale Läufe mit einem Host-Timeout, damit Parallels-Transport-Hänger nicht den Rest des Testfensters verbrauchen können:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --jsontimeout --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.

  • Windows-Update kann auf einem kalten Gast 10 bis 15 Minuten mit Post-Update-doctor- und Paket- Update-Arbeit verbringen; das ist weiterhin gesund, wenn das verschachtelte npm- Debug-Log voranschreitet.

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

  • Die Post-Update-Evidenz führt die normale gebündelte Plugin-Oberfläche aus, da Capability-Fassaden wie Sprache, Bildgenerierung und Medienverständnis über gebündelte Runtime-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 direkte Smoke-Tests des Protokolls.

• pnpm openclaw qa matrix

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

• pnpm openclaw qa telegram

  • Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe aus und verwendet dabei die Driver- und SUT-Bot-Token aus der Umgebung.
  • 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 gemeinsam genutzte gepoolte Anmeldedaten. Verwenden Sie standardmäßig den Umgebungsmodus, oder setzen Sie OPENCLAW_QA_CREDENTIAL_SOURCE=convex, um gepoolte Leases zu aktivieren.
  • Die Defaults decken Canary, Mention-Gating, Befehlsadressierung, /status, erwähnte Bot-zu-Bot-Antworten und native Kernbefehlsantworten ab. mock-openai-Defaults decken außerdem deterministische Reply-Chain- und Telegram-Final-Message-Streaming-Regressionen ab. Verwenden Sie --list-scenarios für optionale Probes wie session_status.
  • Beendet mit einem Wert ungleich null, wenn ein Szenario fehlschlägt. Verwenden Sie --allow-failures, wenn Sie Artefakte ohne fehlschlagenden Exit-Code möchten.
  • Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellt.
  • 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 Bot-Traffic in der Gruppe beobachten kann.
  • Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und qa-evidence.json unter .artifacts/qa-e2e/.... Antwortszenarien enthalten RTT von der Send-Anfrage des Drivers bis zur beobachteten SUT-Antwort.

Mantis Telegram Live ist der PR-Evidence-Wrapper um diese Lane. Er führt den Kandidaten-Ref mit von Convex geleasten Telegram-Anmeldedaten aus, rendert das redigierte QA- Bericht-/Evidence-Bundle in einem Crabbox-Desktop-Browser, zeichnet MP4-Evidence auf, erzeugt ein bewegungsgetrimmtes GIF, lädt das Artefakt-Bundle hoch und postet Inline-PR- Evidence über die Mantis GitHub App, wenn pr_number gesetzt ist. Maintainer können ihn über die Actions UI mit Mantis Scenario (scenario_id: telegram-live) starten oder direkt aus einem Pull-Request-Kommentar:

@openclaw-mantis telegram@openclaw-mantis telegram scenario=telegram-status-command@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

Mantis Telegram Desktop Proof ist der agentische native Telegram-Desktop- Vorher-/Nachher-Wrapper für visuelle PR-Nachweise. Starten Sie ihn über die Actions UI mit freiformatigen instructions, über Mantis Scenario (scenario_id: telegram-desktop-proof) oder aus einem PR-Kommentar:

@openclaw-mantis telegram desktop proof

Der Mantis-Agent liest den PR, entscheidet, welches Telegram-sichtbare Verhalten die Änderung belegt, führt die Crabbox-Telegram-Desktop-Proof-Lane mit echtem Benutzer auf Baseline- und Kandidaten-Refs aus, iteriert, bis die nativen GIFs nützlich sind, schreibt ein gepaartes motionPreview-Manifest und postet dieselbe zweispaltige GIF-Tabelle über die Mantis GitHub App, wenn pr_number gesetzt ist.

• pnpm openclaw qa mantis telegram-desktop-builder
  • Least einen Crabbox-Linux-Desktop oder verwendet ihn erneut, installiert natives Telegram Desktop, konfiguriert OpenClaw mit einem geleasten Telegram-SUT-Bot-Token, startet das Gateway und zeichnet Screenshot-/MP4-Evidence vom sichtbaren VNC-Desktop auf.
  • Verwendet standardmäßig --credential-source convex, sodass Workflows nur das Convex-Broker-Secret benötigen. Verwenden Sie --credential-source env mit denselben OPENCLAW_QA_TELEGRAM_*-Variablen wie bei pnpm openclaw qa telegram.
  • Telegram Desktop benötigt weiterhin ein Benutzer-Login/-Profil. Das Bot-Token konfiguriert nur OpenClaw. Verwenden Sie --telegram-profile-archive-env <name> für ein base64-kodiertes .tgz-Profilarchiv, oder verwenden Sie --keep-lease und melden Sie sich einmal manuell über VNC an.
  • Schreibt mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png und telegram-desktop-builder.mp4 unter dem Ausgabeverzeichnis.

Live-Transport-Lanes teilen 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 ist nicht Teil dieser Matrix.

Gemeinsame Telegram-Anmeldedaten über Convex (v1)

Wenn --credential-source convex (oder OPENCLAW_QA_CREDENTIAL_SOURCE=convex) für Live-Transport-QA aktiviert ist, erwirbt QA Lab einen exklusiven Lease aus einem Convex-gestützten Pool, sendet Heartbeats für diesen Lease, während die Lane läuft, und gibt den Lease beim Herunterfahren frei. Der Abschnittsname stammt aus der Zeit vor Discord-, Slack- und WhatsApp-Unterstützung; der Lease-Vertrag wird typenübergreifend geteilt.

Referenz-Scaffold für das Convex-Projekt:

• qa/convex-credential-broker/

Erforderliche Umgebungsvariablen:

• 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 Anmeldedatenrolle:
  • CLI: --credential-role maintainer|ci
  • Umgebungs-Default: OPENCLAW_QA_CREDENTIAL_ROLE (standardmäßig ci in CI, sonst maintainer)

Optionale Umgebungsvariablen:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (Default 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (Default 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (Default 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (Default 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (Default /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (optionale Trace-ID)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 erlaubt Loopback-Convex-URLs mit http:// nur für lokale Entwicklung.

OPENCLAW_QA_CONVEX_SITE_URL sollte im Normalbetrieb https:// verwenden.

Admin-Befehle für Maintainer (Pool hinzufügen/entfernen/auflisten) erfordern speziell OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

CLI-Helfer für Maintainer:

pnpm openclaw qa credentials doctorpnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.jsonpnpm openclaw qa credentials list --kind telegrampnpm 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-/List-Erreichbarkeit zu prüfen, ohne Secret-Werte auszugeben. Verwenden Sie --json für maschinenlesbare Ausgabe in Skripten und CI- Dienstprogrammen.

Default-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 /payload-chunk
  • Anfrage: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Erfolg: { status: "ok", index, data }
• 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 aktivem 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 den Telegram-Typ:

• { groupId: string, driverToken: string, sutToken: string }
• groupId muss ein numerischer Telegram-Chat-ID-String sein.
• admin/add validiert diese Form für kind: "telegram" und weist fehlerhafte Payloads zurück.

Payload-Form für den Telegram-Echtbenutzertyp:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId und telegramApiId müssen numerische Strings sein.
• tdlibArchiveSha256 und desktopTdataArchiveSha256 müssen SHA-256-Hex-Strings sein.
• kind: "telegram-user" ist für den Workflow Mantis Telegram Desktop Proof reserviert. Generische QA-Lab-Lanes dürfen ihn nicht erwerben.

Vom Broker validierte Mehrkanal-Payloads:

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Slack-Lanes können ebenfalls aus dem Pool leasen, aber die Slack-Payload-Validierung liegt derzeit im Slack-QA-Runner statt im Broker. Verwenden Sie { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string } für Slack-Zeilen.

Einen Kanal zu QA hinzufügen

Die Architektur und Szenario-Helfernamen für neue Kanaladapter befinden sich in QA-Übersicht → Einen Kanal hinzufügen. Die Mindestanforderung: Implementieren Sie den Transport-Runner auf der 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/.

Testsuiten (was wo läuft)

Betrachten Sie die Suiten als „zunehmender Realismus“ (und zunehmende Flakiness/Kosten):

Unit / Integration (Default)

• Befehl: pnpm test
• Konfiguration: Nicht zielgerichtete Läufe verwenden das Shard-Set vitest.full-*.config.ts und können Multi-Project-Shards für parallele Planung in Pro-Project-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 Fehler
• Erwartungen:
  • Läuft in CI
  • Keine echten Schlüssel erforderlich
  • Sollte schnell und stabil sein
  • Resolver- und Public-Surface-Loader-Tests müssen breites api.js- und runtime-api.js-Fallback-Verhalten mit generierten kleinen Plugin-Fixtures nachweisen, nicht mit echten gebündelten Plugin-Source-APIs. Echte Plugin-API-Ladevorgänge gehören in Plugin-eigene Contract-/Integrationssuiten.

Richtlinie für native Abhängigkeiten:

• Default-Testinstallationen überspringen optionale native Discord-Opus-Builds. Discord Voice verwendet gebündeltes libopus-wasm, und @discordjs/opus bleibt in allowBuilds deaktiviert, damit lokale Tests und Testbox-Lanes das native Add-on nicht kompilieren.
• Vergleichen Sie native Opus-Performance im libopus-wasm-Benchmark-Repo, nicht in den Default-Installations-/Test-Loops von OpenClaw. Setzen Sie @discordjs/opus in den Default-allowBuilds nicht auf true; dadurch würden unabhängige Installations-/Test-Loops nativen Code kompilieren.

Stabilität (Gateway)

• Befehl: pnpm test:stability:gateway
• Konfiguration: vitest.gateway.config.ts, auf einen Worker erzwungen
• Umfang:
  • Startet einen echten local loopback Gateway mit standardmäßig aktivierter Diagnose
  • Treibt synthetischen Gateway-Message-, Memory- und Large-Payload-Churn durch den Diagnoseereignispfad
  • Fragt diagnostics.stability über das Gateway-WS-RPC ab
  • Deckt Persistenz-Helper für Diagnostic-Stability-Bundles ab
  • Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Pressure-Budget bleiben und Queue-Tiefen pro Sitzung wieder auf null ablaufen
• Erwartungen:
  • CI-sicher und schlüssellos
  • Schmale Lane für Stabilitätsregressions-Nachverfolgung, kein Ersatz für die vollständige Gateway-Suite

E2E (Repo-Aggregat)

• Befehl: pnpm test:e2e
• Umfang:
  • Führt die Gateway-Smoke-E2E-Lane aus
  • Führt die gemockte Control-UI-Browser-E2E-Lane aus
• Erwartungen:
  • CI-sicher und schlüssellos
  • Erfordert, dass Playwright Chromium installiert ist

E2E (Gateway-Smoke)

• Befehl: pnpm test:e2e:gateway
• Konfiguration: vitest.e2e.config.ts
• Dateien: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts und gebündelte Plugin-E2E-Tests unter extensions/
• Runtime-Standards:
  • 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 Multi-Instance-Gateways
  • WebSocket-/HTTP-Oberflächen, Node-Pairing und schwereres 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 (gemockter Control-UI-Browser)

• Befehl: pnpm test:ui:e2e
• Konfiguration: test/vitest/vitest.ui-e2e.config.ts
• Dateien: ui/src/**/*.e2e.test.ts
• Umfang:
  • Startet die Vite Control UI
  • Steuert eine echte Chromium-Seite über Playwright
  • Ersetzt den Gateway-WebSocket durch deterministische In-Browser-Mocks
• Erwartungen:
  • Läuft in CI als Teil von pnpm test:e2e
  • Kein echter Gateway, keine Agents und keine Provider-Schlüssel erforderlich
  • Browser-Abhängigkeit muss vorhanden sein (pnpm --dir ui exec playwright install chromium)

E2E: OpenShell-Backend-Smoke

• Befehl: pnpm test:e2e:openshell
• Datei: extensions/openshell/src/backend.e2e.test.ts
• Umfang:
  • Verwendet einen aktiven lokalen OpenShell-Gateway wieder
  • Erstellt eine Sandbox aus einem temporären lokalen Dockerfile
  • Übt OpenClaws OpenShell-Backend über echtes sandbox ssh-config + SSH exec aus
  • Verifiziert Remote-Canonical-Dateisystemverhalten über die Sandbox-fs-Bridge
• Erwartungen:
  • Nur Opt-in; nicht Teil des standardmäßigen pnpm test:e2e-Laufs
  • Erfordert eine lokale openshell-CLI plus einen funktionierenden Docker-Daemon
  • Erfordert einen aktiven lokalen OpenShell-Gateway und dessen Config-Quelle
  • Verwendet isolierte HOME / XDG_CONFIG_HOME und zerstört anschließend die Test-Sandbox
• Nützliche Overrides:
  • OPENCLAW_E2E_OPENSHELL=1, um den Test zu aktivieren, wenn die breitere e2e-Suite manuell ausgeführt wird
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell, um auf ein nicht standardmäßiges CLI-Binary oder Wrapper-Skript zu verweisen
  • OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config, um die registrierte Gateway-Konfiguration dem isolierten Test verfügbar zu machen
  • OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1, um die vom Host-Policy-Fixture verwendete Docker-Gateway-IP zu überschreiben

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 Anmeldedaten?“
  • Erkennt Änderungen am Provider-Format, Besonderheiten beim Tool-Aufruf, Authentifizierungsprobleme und Verhalten bei Rate Limits
• Erwartungen:
  • Absichtlich nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Kontingente, Ausfälle)
  • Kostet Geld / nutzt Rate Limits
  • Bevorzugen Sie eingegrenzte Teilmengen statt „alles“
• Live-Läufe verwenden bereits exportierte API-Schlüssel und vorbereitete Authentifizierungsprofile.
• 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 standardmäßig einen ruhigeren Modus: Die Fortschrittsausgabe [live] ... bleibt erhalten, während Gateway-Bootstrap-Logs/Bonjour-Ausgaben stummgeschaltet werden. Setzen Sie OPENCLAW_LIVE_TEST_QUIET=0, wenn Sie die vollständigen Start-Logs wieder sehen möchten.
• API-Schlüssel-Rotation (Provider-spezifisch): Setzen Sie *_API_KEYS mit Komma-/Semikolonformat oder *_API_KEY_1, *_API_KEY_2 (zum Beispiel OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) oder eine Live-spezifische Überschreibung über OPENCLAW_LIVE_*_KEY; Tests wiederholen bei Rate-Limit-Antworten.
• Fortschritts-/Heartbeat-Ausgabe:
  • Live-Suites geben jetzt Fortschrittszeilen nach stderr aus, sodass lange Provider-Aufrufe sichtbar aktiv sind, auch wenn die Vitest-Konsolenerfassung ruhig ist.
  • vitest.live.config.ts deaktiviert die Vitest-Konsolenabfangung, damit Provider-/Gateway-Fortschrittszeilen während Live-Läufen sofort gestreamt werden.
  • Stimmen Sie Heartbeats für direkte Modelle mit OPENCLAW_LIVE_HEARTBEAT_MS ab.
  • Stimmen Sie Gateway-/Probe-Heartbeats mit OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS ab.

Welche Suite sollte 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-Netzwerk / WS-Protokoll / Pairing berühren: Ergänzen Sie pnpm test:e2e
• „Mein Bot ist ausgefallen“ debuggen / Provider-spezifische Fehler / Tool-Aufrufe: Führen Sie ein eingegrenztes pnpm test:live aus

Live-Tests (mit Netzwerkzugriff)

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

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

Diese Docker-Runner teilen sich in zwei Gruppen auf:

• Live-Modell-Runner: test:docker:live-models und test:docker:live-gateway führen nur ihre passende Live-Datei mit Profilschlüsseln innerhalb des Repo-Docker-Images aus (src/agents/models.profiles.live.test.ts und src/gateway/gateway-models.profiles.live.test.ts) und mounten dabei Ihr lokales Konfigurationsverzeichnis, den Workspace und optional eine Profil-Env-Datei. Die passenden lokalen Einstiegspunkte sind test:live:models-profiles und test:live:gateway-profiles.
• Docker-Live-Runner behalten bei Bedarf eigene praktische Obergrenzen bei: test:docker:live-models verwendet standardmäßig die kuratierte unterstützte High-Signal-Auswahl, 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. Setzen Sie OPENCLAW_LIVE_MAX_MODELS oder die Gateway-Env-Vars, wenn Sie ausdrücklich eine kleinere Obergrenze oder einen größeren Scan wünschen.
• test:docker:all baut das Live-Docker-Image einmal über test:docker:live-build, packt OpenClaw einmal als npm-Tarball über scripts/package-openclaw-for-docker.mjs und baut/verwendet dann zwei scripts/e2e/Dockerfile-Images erneut. Das Bare-Image ist nur der Node-/Git-Runner für Installations-, Update- und Plugin-Abhängigkeits-Lanes; diese Lanes mounten den vorgebauten Tarball. Das Functional-Image installiert denselben Tarball in /app für Lanes zur Funktionalität der gebauten App. Docker-Lane-Definitionen befinden sich in scripts/lib/docker-e2e-scenarios.mjs; die Planner-Logik befindet sich 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 Ressourcengrenzen verhindern, dass schwere Live-, npm-Installations- und Multi-Service-Lanes alle gleichzeitig starten. Wenn eine einzelne Lane schwerer ist als die aktiven Obergrenzen, kann der Scheduler sie trotzdem starten, wenn der Pool leer ist, und sie dann allein laufen lassen, bis wieder Kapazität verfügbar ist. Standardwerte sind 10 Slots, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5 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 eine Docker-Preflight-Prüfung 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 Anmeldedaten 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 die ausgewählte Ref erneut zu packen. Profile sind nach Breite geordnet: smoke, package, product und full. Siehe Updates und Plugins testen für den Paket-/Update-/Plugin-Vertrag, die Survivor-Matrix für veröffentlichte Upgrades, Release-Standards und Fehlert triage.
• Build- und Release-Prüfungen führen scripts/check-cli-bootstrap-imports.mjs nach tsdown aus. Der Guard durchläuft den statischen gebauten Graphen ab dist/entry.js und dist/cli/run-main.js und schlägt fehl, wenn der Start vor dem Dispatch Paketabhängigkeiten wie Commander, Prompt-UI, undici oder Logging vor dem Command-Dispatch 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 gepackte CLI-Smoke deckt außerdem Root-Hilfe, Onboard-Hilfe, Doctor-Hilfe, Status, Konfigurationsschema und einen Modelllisten-Befehl 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 Patch-Dateien im aus dem Tarball abgeleiteten Git-Fixture, fehlendes persistiertes update.channel, Legacy-Speicherorte für Plugin-Installationsdatensätze, fehlende Persistenz von Marketplace-Installationsdatensätzen 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:release-user-journey, test:docker:release-typed-onboarding, test:docker:release-media-memory, test:docker:release-upgrade-user-journey, test:docker:release-plugin-marketplace, test:docker:skill-install, 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:agent-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 übergeordnete Integrationspfade.
• Docker-/Bash-E2E-Lanes, die den gepackten OpenClaw-Tarball über scripts/lib/openclaw-e2e-instance.sh installieren, begrenzen npm install auf OPENCLAW_E2E_NPM_INSTALL_TIMEOUT (Standard 600s; setzen Sie 0, um den Wrapper zum Debuggen zu deaktivieren).

Die Docker-Runner für Live-Modelle binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit OAuth externer CLIs Tokens 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: pnpm test:docker:live-acp-bind (Skript: scripts/test-live-acp-bind-docker.sh; deckt standardmäßig Claude, Codex und Gemini ab, mit strikter Droid-/OpenCode-Abdeckung über pnpm test:docker:live-acp-bind:droid und pnpm test:docker:live-acp-bind:opencode)

• CLI-Backend-Smoke: pnpm test:docker:live-cli-backend (Skript: scripts/test-live-cli-backend-docker.sh)

• Codex-App-Server-Harness-Smoke: pnpm test:docker:live-codex-harness (Skript: scripts/test-live-codex-harness-docker.sh)

• Gateway + Dev-Agent: pnpm test:docker:live-gateway (Skript: scripts/test-live-gateway-models-docker.sh)

• Observability-Smokes: pnpm qa:otel:smoke, pnpm qa:prometheus:smoke und pnpm qa:observability:smoke sind private QA-Lanes für Source-Checkouts. Sie sind absichtlich nicht Teil der Paket-Docker-Release-Lanes, weil der npm-Tarball QA Lab auslässt.

• Open WebUI-Live-Smoke: 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-Onboarding-/Channel-/Agent-Smoke: pnpm test:docker:npm-onboard-channel-agent installiert den gepackten OpenClaw-Tarball global in Docker, konfiguriert OpenAI über Env-Ref-Onboarding plus standardmäßig Telegram, führt Doctor aus und führt einen gemockten OpenAI-Agent-Turn aus. Verwenden Sie einen vorgebauten Tarball mit OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz erneut, überspringen Sie den Host-Rebuild mit OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 oder wechseln Sie den Channel mit OPENCLAW_NPM_ONBOARD_CHANNEL=discord oder OPENCLAW_NPM_ONBOARD_CHANNEL=slack.

• Release-Benutzerreise-Smoke-Test: pnpm test:docker:release-user-journey installiert den gepackten OpenClaw-Tarball global in einem sauberen Docker-Home, führt Onboarding aus, konfiguriert einen gemockten OpenAI-Provider, führt einen Agent-Turn aus, installiert/deinstalliert externe Plugins, konfiguriert ClickClack gegen ein lokales Fixture, verifiziert ausgehende/eingehende Nachrichten, startet Gateway neu und führt Doctor aus.

• Release-Smoke-Test für typisiertes Onboarding: pnpm test:docker:release-typed-onboarding installiert den gepackten Tarball, steuert openclaw onboard über ein echtes TTY, konfiguriert OpenAI als env-ref-Provider, verifiziert, dass kein Rohschlüssel persistiert wird, und führt einen gemockten Agent-Turn aus.

• Release-Media-/Memory-Smoke-Test: pnpm test:docker:release-media-memory installiert den gepackten Tarball, verifiziert Bildverständnis aus einem PNG-Anhang, OpenAI-kompatible Ausgabe zur Bildgenerierung, Memory-Suchabruf und das Überleben des Abrufs über einen Gateway-Neustart hinweg.

• Release-Upgrade-Benutzerreise-Smoke-Test: pnpm test:docker:release-upgrade-user-journey installiert standardmäßig die neueste veröffentlichte Baseline, die älter als der Kandidaten-Tarball ist, konfiguriert Provider-/Plugin-/ClickClack-State im veröffentlichten Paket, aktualisiert auf den Kandidaten-Tarball und führt dann die Kern-Agent-/Plugin-/Kanal-Reise erneut aus. Wenn keine ältere veröffentlichte Baseline vorhanden ist, wird die Kandidatenversion wiederverwendet. Überschreiben Sie die Baseline mit OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>.

• Release-Plugin-Marketplace-Smoke-Test: pnpm test:docker:release-plugin-marketplace installiert aus einem lokalen Fixture-Marketplace, aktualisiert das installierte Plugin, deinstalliert es und verifiziert, dass die Plugin-CLI verschwindet, während Installationsmetadaten bereinigt werden.

• Skill-Install-Smoke-Test: pnpm test:docker:skill-install installiert den gepackten OpenClaw-Tarball global in Docker, deaktiviert hochgeladene Archivinstallationen in der Konfiguration, löst den aktuellen Live-ClawHub-Skill-Slug aus der Suche auf, installiert ihn mit openclaw skills install und verifiziert den installierten Skill sowie .clawhub-Origin-/Lock-Metadaten.

• Update-Kanalwechsel-Smoke-Test: pnpm test:docker:update-channel-switch installiert den gepackten OpenClaw-Tarball global in Docker, wechselt vom Paketkanal stable zu Git dev, verifiziert den persistierten 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 verschmutztes Altbenutzer-Fixture mit Agents, Kanalkonfiguration, Plugin-Allowlists, veraltetem Plugin-Abhängigkeits-State und vorhandenen Workspace-/Session-Dateien. Er führt Paket-Update plus nicht-interaktiven Doctor ohne Live-Provider- oder Kanalschlüssel aus, startet dann ein loopback-Gateway und prüft Konfigurations-/State-Erhaltung sowie Start-/Statusbudgets.

• Published-Upgrade-Survivor-Smoke-Test: pnpm test:docker:published-upgrade-survivor installiert standardmäßig openclaw@latest, befüllt realistische Bestandsbenutzerdateien, konfiguriert diese Baseline mit einem eingebauten Befehlsrezept, validiert die resultierende Konfiguration, aktualisiert diese veröffentlichte Installation auf den Kandidaten-Tarball, führt nicht-interaktiven Doctor aus, schreibt .artifacts/upgrade-survivor/summary.json, startet dann ein loopback-Gateway und prüft konfigurierte Intents, State-Erhaltung, Start, /healthz, /readyz und RPC-Statusbudgets. Überschreiben Sie eine Baseline mit OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, weisen Sie den aggregierten Scheduler an, exakte lokale Baselines mit OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS zu erweitern, etwa openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, und issue-förmige Fixtures mit OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS zu erweitern, etwa reported-issues; der Satz reported-issues enthält configured-plugin-installs für 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-Baseline-Tokens wie last-stable-4 oder all-since-2026.4.23 auf, und Full Release Validation erweitert das Release-Soak-Paket-Gate auf last-stable-4 2026.4.23 2026.5.2 2026.4.15 plus reported-issues.

• Session-Runtime-Kontext-Smoke-Test: pnpm test:docker:session-runtime-context verifiziert die Persistenz versteckter Runtime-Kontext-Transkripte plus Doctor-Reparatur betroffener duplizierter Prompt-Rewrite-Branches.

• Bun-Global-Install-Smoke-Test: 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 wieder, ü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 direct-npm-Containern. Der Update-Smoke-Test verwendet standardmäßig npm latest als stabile Baseline, 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-/direct-npm-Cache bei lokalen Wiederholungen wiederzuverwenden.

• 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 Abdeckung für direktes npm install -g benötigt wird.

• Agents-delete-shared-workspace-CLI-Smoke-Test: pnpm test:docker:agents-delete-shared-workspace (Skript: scripts/e2e/agents-delete-shared-workspace-docker.sh) baut standardmäßig das Root-Dockerfile-Image, befüllt zwei Agents mit einem Workspace in einem isolierten Container-Home, führt agents delete --json aus und verifiziert gültiges JSON sowie Verhalten mit beibehaltenem Workspace. 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 wieder.

• Gateway-Netzwerk (zwei Container, WS-Auth + 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 hochgestufte Clickables, iframe-Refs und Frame-Metadaten abdecken.

• OpenAI-Responses-web_search-Regression für minimales 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 eine Provider-Schema-Ablehnung und prüft, dass das rohe Detail in den Gateway-Logs erscheint.

• MCP-Kanal-Bridge (vorgefülltes Gateway + stdio-Bridge + roher Claude-Notification-Frame-Smoke-Test): pnpm test:docker:mcp-channels (Skript: scripts/e2e/mcp-channels-docker.sh)

• OpenClaw-Bundle-MCP-Tools (echter stdio-MCP-Server + eingebetteter OpenClaw-Profil-Allow-/Deny-Smoke-Test): pnpm test:docker:agent-bundle-mcp-tools (Skript: scripts/e2e/agent-bundle-mcp-tools-docker.sh)

• Cron-/Subagent-MCP-Cleanup (echtes Gateway + stdio-MCP-Child-Teardown nach isolierten Cron- und einmaligen Subagent-Läufen): pnpm test:docker:cron-mcp-cleanup (Skript: scripts/e2e/cron-mcp-cleanup-docker.sh)

• Plugins (Install-/Update-Smoke-Test für lokalen Pfad, file:, npm-Registry mit hoisted Abhängigkeiten, fehlerhafte npm-Paketmetadaten, bewegliche Git-Refs, ClawHub-Kitchen-Sink, Marketplace-Updates und Claude-Bundle-Aktivierung/-Inspektion): 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-/Runtime-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.

• Plugin-update-unchanged-Smoke-Test: pnpm test:docker:plugin-update (Skript: scripts/e2e/plugin-update-unchanged-docker.sh)

• Plugin-Lifecycle-Matrix-Smoke-Test: pnpm test:docker:plugin-lifecycle-matrix installiert den gepackten OpenClaw-Tarball in einem nackten Container, installiert ein npm-Plugin, schaltet Aktivieren/Deaktivieren um, führt Upgrade und Downgrade über eine lokale npm-Registry aus, löscht den installierten Code und verifiziert dann, dass die Deinstallation weiterhin veralteten State entfernt, während RSS-/CPU-Metriken für jede Lifecycle-Phase protokolliert werden.

• Config-reload-metadata-Smoke-Test: pnpm test:docker:config-reload (Skript: scripts/e2e/config-reload-source-docker.sh)

• Plugins: pnpm test:docker:plugins deckt Install-/Update-Smoke-Tests für lokalen Pfad, file:, npm-Registry mit hoisted Abhängigkeiten, bewegliche Git-Refs, ClawHub-Fixtures, Marketplace-Updates und Claude-Bundle-Aktivierung/-Inspektion 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 wieder:

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

Suite-spezifische Image-Überschreibungen 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-Runtime 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 im Container bereit. Dadurch bleibt das Runtime- Image schlank, während Vitest weiterhin gegen Ihre exakte lokale Quelle/Konfiguration ausgeführt wird. Der Bereitstellungsschritt ü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.-Channel-Worker im Container starten. test:docker:live-models führt weiterhin pnpm test:live aus. Reichen 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 übergeordneter Kompatibilitäts-Smoke: Es startet einen OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, startet einen angehefteten 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. Setzen Sie OPENWEBUI_SMOKE_MODE=models für CI-Prüfungen im Release-Pfad, die nach der Open WebUI-Anmeldung und Modellerkennung stoppen sollen, ohne auf eine Live-Modell- Vervollständigung zu warten. Der erste Lauf kann spürbar langsamer sein, weil Docker eventuell das Open WebUI-Image abrufen muss und Open WebUI möglicherweise seine eigene Cold-Start-Einrichtung abschließen muss. Diese Lane erwartet einen nutzbaren Live-Modellschlüssel. Stellen Sie ihn über die Prozess- Umgebung, bereitgestellte Auth-Profile oder eine explizite OPENCLAW_PROFILE_FILE bereit. 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 vorbefüllten Gateway- Container, startet einen zweiten Container, der openclaw mcp serve erzeugt, 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, was ein bestimmtes Client-SDK zufällig sichtbar macht. test:docker:agent-bundle-mcp-tools ist deterministisch und benötigt keinen Live- Modellschlüssel. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server im Container, materialisiert diesen Server über die eingebettete OpenClaw-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-Modell- Schlüssel. Es startet ein vorbefülltes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen isolierten Cron-Turn und einen sessions_spawn-One-Shot-Child-Turn aus und verifiziert anschließend, 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 kann für die Validierung des ACP-Thread-Routings erneut benötigt werden, löschen Sie es daher nicht.

Nützliche Umgebungsvariablen:

• OPENCLAW_CONFIG_DIR=... (Standard: ~/.openclaw) eingehängt unter /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (Standard: ~/.openclaw/workspace) eingehängt unter /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... wird eingehängt und vor dem Ausführen der Tests eingelesen
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1, um nur aus OPENCLAW_PROFILE_FILE eingelesene Umgebungsvariablen zu verifizieren, mit temporären Konfigurations-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (Standard: ~/.cache/openclaw/docker-cli-tools) eingehängt unter /home/node/.npm-global für zwischengespeicherte CLI-Installationen in Docker
• Externe CLI-Auth-Verzeichnisse/-Dateien unter $HOME werden schreibgeschützt unter /host-auth... eingehängt 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 hängen nur die benötigten Verzeichnisse/Dateien ein, die aus OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS abgeleitet werden
  • Manuelle Überschreibung 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 Wiederholungsläufe wiederzuverwenden, die keinen Neuaufbau benötigen
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um sicherzustellen, dass Zugangsdaten aus dem Profilspeicher kommen (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-Prüf-Prompt zu überschreiben
• OPENWEBUI_IMAGE=..., um das angeheftete Open WebUI-Image-Tag zu überschreiben

Docs-Sanity

Führen Sie nach Docs-Änderungen Docs-Prüfungen aus: pnpm check:docs. Führen Sie die vollständige Mintlify-Ankervalidierung aus, wenn Sie auch Prüfungen von Überschriften innerhalb der Seite benötigen: pnpm docs:check-links:anchors.

Offline-Regression (CI-sicher)

Dies sind Regressionen der „echten Pipeline“ ohne echte Provider:

• Gateway-Tool-Aufruf (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-Wizard (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-Aufruf durch das echte Gateway + den Agent-Loop (src/gateway/gateway.test.ts).
• End-to-End-Wizard-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 vor der Verwendung SKILL.md und befolgt er die erforderlichen Schritte/Argumente?
• Workflow-Verträge: Mehrstufige 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, um Tool-Aufrufe + Reihenfolge, Skill-Dateilesevorgänge und Session-Verdrahtung zu prüfen.
• Eine kleine Suite Skill-fokussierter Szenarien (Verwenden vs. Vermeiden, Gating, Prompt-Injection).
• Optionale Live-Evals (Opt-in, über Umgebung abgesichert) erst, nachdem die CI-sichere Suite vorhanden ist.

Vertragstests (Plugin- und Channel-Form)

Vertragstests verifizieren, dass jedes registrierte Plugin und jeder registrierte Channel seinem Schnittstellenvertrag entspricht. Sie iterieren über alle entdeckten Plugins und führen eine Suite aus Form- und Verhaltensassertions aus. Die standardmäßige pnpm test-Unit-Lane überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle explizit aus, wenn Sie gemeinsam genutzte 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 - Grundlegende Plugin-Form (ID, Name, Fähigkeiten)
• setup - Setup-Wizard-Vertrag
• session-binding - Session-Binding-Verhalten
• outbound-payload - Nachrichten-Nutzlaststruktur
• inbound - Verarbeitung eingehender Nachrichten
• actions - Channel-Action-Handler
• threading - Thread-ID-Verarbeitung
• directory - Verzeichnis-/Roster-API
• group-policy - Durchsetzung der Gruppenrichtlinie

Provider-Statusverträge

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

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

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-Form/-Schnittstelle
• wizard - Setup-Wizard

Wann ausführen

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

Vertragstests laufen in CI und benötigen keine echten API-Schlüssel.

Regressionen hinzufügen (Leitfaden)

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 Erfassen der exakten Request-Shape-Transformation)
• Wenn es von Natur aus nur live testbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test eng begrenzt und per Umgebungsvariablen Opt-in
• Zielen Sie bevorzugt auf die kleinste Ebene, die den Fehler abfängt:
  • Fehler bei Provider-Request-Konvertierung/Replays → direkter Modelltest
  • Fehler in Gateway-Session/History/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test
• SecretRef-Traversal-Guardrail:
  • src/secrets/exec-secret-ref-id-parity.test.ts leitet pro SecretRef-Klasse ein gesampeltes Ziel aus Registry-Metadaten (listSecretTargetRegistryEntries()) ab und prüft dann, dass Exec-IDs mit Traversal-Segment 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 bei nicht klassifizierten Ziel-IDs absichtlich fehl, damit neue Klassen nicht stillschweigend übersprungen werden können.

Verwandt

• Live testen
• Updates und Plugins testen
• CI