docs/docs/de/help/testing.md

read_when	summary	title	x-i18n
Tests lokal oder in CI ausführen Regressionen für Modell-/Provider-Fehler hinzufügen Gateway- und Agentenverhalten debuggen	Test-Kit: Unit-/E2E-/Live-Suiten, Docker-Runner und was jeder Test abdeckt	Tests	generated_at model provider source_hash source_path workflow 2026-04-23T14:02:23Z gpt-5.4 openai fe0e9bdea78cba7e512358d2e4d428da04a2071188e74af2d5419d2c85eafe15 help/testing.md 15

Tests

OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Gruppe von Docker-Runnern.

Dieses Dokument ist ein Leitfaden zu „wie wir testen“:

• Was jede Suite abdeckt (und was sie bewusst nicht abdeckt)
• Welche Befehle Sie für gängige Abläufe ausführen sollten (lokal, vor dem Push, Debugging)
• Wie Live-Tests Anmeldedaten 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 einer leistungsfähigen Maschine: pnpm test:max
• Direkte Vitest-Watch-Schleife: pnpm test:watch
• Direktes Targeting von Dateien leitet jetzt auch Pfade für Extensions/Kanäle 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 anfassen oder zusätzliche Sicherheit möchten:

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

Beim Debuggen realer Provider/Modelle (erfordert echte Anmeldedaten):

• Live-Suite (Modelle + Gateway-Tool-/Bild-Probes): pnpm test:live
• Eine einzelne Live-Datei still ausführen: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Docker-Live-Modell-Sweep: pnpm test:docker:live-models
  • CI-Abdeckung: Die täglichen OpenClaw Scheduled Live And E2E Checks und die manuell ausgelösten OpenClaw Release Checks rufen beide den wiederverwendbaren Live-/E2E-Workflow mit include_live_suites: true auf, der separate Docker-Live-Modell- Matrix-Jobs umfasst, nach Providern geshardet.
  • Für gezielte CI-Neustarts dispatchen Sie OpenClaw Live And E2E Checks (Reusable) mit include_live_suites: true und live_models_only: true.
  • Fügen Sie neue hochrelevante Provider-Secrets zu scripts/ci-hydrate-live-auth.sh sowie .github/workflows/openclaw-live-and-e2e-checks-reusable.yml und dessen geplanten/releasebezogenen Aufrufern hinzu.
• Moonshot/Kimi-Kosten-Smoke: Führen Sie mit gesetztem MOONSHOT_API_KEY openclaw models list --provider moonshot --json aus und danach ein isoliertes 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 JSON Moonshot/K2.6 meldet und das Assistant-Transkript normalisierte usage.cost speichert.

Tipp: Wenn Sie nur einen einzigen fehlschlagenden Fall benötigen, grenzen Sie Live-Tests bevorzugt über die unten beschriebenen Env-Zulassungslistenvariablen ein.

QA-spezifische Runner

Diese Befehle stehen neben den Haupttest-Suiten bereit, wenn Sie den Realismus von QA-Lab benötigen:

CI führt QA Lab in dedizierten Workflows aus. Parity gate läuft auf passenden PRs und bei manuellem Dispatch mit Mock-Providern. QA-Lab - All Lanes läuft nachts auf main und bei manuellem Dispatch mit dem Mock-Parity-Gate, der Live-Matrix-Lane und der Convex-verwalteten Live-Telegram-Lane als parallele Jobs. OpenClaw Release Checks führt dieselben Lanes vor der Freigabe aus.

• pnpm openclaw qa suite
  • Führt repo-gestützte QA-Szenarien direkt auf dem Host aus.
  • Führt standardmäßig mehrere ausgewählte Szenarien parallel mit isolierten Gateway-Workern aus. qa-channel verwendet standardmäßig Concurrency 4 (begrenzt durch die Zahl der ausgewählten Szenarien). Verwenden Sie --concurrency <count>, um die Worker- Zahl 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 möchten.
  • 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 szenariobewusste mock-openai-Lane zu ersetzen.
• pnpm openclaw qa suite --runner multipass
  • Führt dieselbe QA-Suite in einer flüchtigen Multipass-Linux-VM aus.
  • Behält dasselbe Verhalten zur Szenarioauswahl wie qa suite auf dem Host bei.
  • Verwendet dieselben Flags zur Provider-/Modellauswahl wie qa suite.
  • Live-Läufe leiten die unterstützten QA-Authentifizierungseingaben weiter, die für den Gast praktikabel sind: env-basierte Provider-Schlüssel, den QA-Live-Provider-Konfigurationspfad und CODEX_HOME, falls vorhanden.
  • Ausgabeverzeichnisse müssen unter dem Repo-Root bleiben, damit der Gast über den gemounteten Workspace zurückschreiben kann.
  • Schreibt den normalen QA-Report + die Zusammenfassung sowie 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
  • Baut ein npm-Tarball aus dem aktuellen Checkout, installiert es global in Docker, führt nicht interaktives Onboarding mit OpenAI-API-Key aus, konfiguriert standardmäßig Telegram, verifiziert, dass das Aktivieren des Plugins Laufzeitabhängigkeiten bei Bedarf installiert, führt doctor aus und führt einen lokalen Agent-Zug gegen einen gemockten OpenAI-Endpunkt aus.
  • Verwenden Sie OPENCLAW_NPM_ONBOARD_CHANNEL=discord, um dieselbe Lane für die verpackte Installation mit Discord auszuführen.
• pnpm test:docker:bundled-channel-deps
  • Packt und installiert den aktuellen OpenClaw-Build in Docker, startet das Gateway mit konfiguriertem OpenAI und aktiviert dann gebündelte Kanäle/Plugins über Konfigurationsbearbeitungen.
  • Verifiziert, dass die Setup-Erkennung nicht konfigurierte Plugin-Laufzeitabhängigkeiten nicht vorhanden lässt, dass der erste konfigurierte Gateway- oder doctor-Lauf die Laufzeitabhängigkeiten jedes gebündelten Plugins bei Bedarf installiert und dass ein zweiter Neustart keine bereits aktivierten Abhängigkeiten erneut installiert.
  • Installiert außerdem eine bekannte ältere npm-Basislinie, aktiviert Telegram vor dem Ausführen von openclaw update --tag <candidate> und verifiziert, dass doctor des Kandidaten nach dem Update Laufzeitabhängigkeiten gebündelter Kanäle ohne eine nachgelagerte Reparatur durch den Harness behebt.
• pnpm openclaw qa aimock
  • Startet nur den lokalen AIMock-Provider-Server für direkte Protokoll-Smoke- Tests.
• pnpm openclaw qa matrix
  • Führt die Matrix-Live-QA-Lane gegen einen flüchtigen, Docker-gestützten Tuwunel-Homeserver aus.
  • Dieser QA-Host ist derzeit nur für Repo/Entwicklung gedacht. Verpackte OpenClaw-Installationen liefern qa-lab nicht mit, daher stellen sie openclaw qa nicht bereit.
  • Repo-Checkouts laden den gebündelten Runner direkt; ein separater Plugin-Installations- Schritt ist nicht erforderlich.
  • Stellt drei temporäre Matrix-Nutzer (driver, sut, observer) sowie einen privaten Raum bereit und startet dann ein QA-Gateway-Kind mit dem echten Matrix-Plugin als SUT-Transport.
  • Verwendet standardmäßig das angeheftete stabile Tuwunel-Image ghcr.io/matrix-construct/tuwunel:v1.5.1. Überschreiben Sie dies mit OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE, wenn Sie ein anderes Image testen müssen.
  • Matrix stellt keine gemeinsamen Flags für Credential-Quellen bereit, da die Lane lokal flüchtige Nutzer bereitstellt.
  • Schreibt einen Matrix-QA-Report, eine Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes stdout/stderr-Ausgabelog unter .artifacts/qa-e2e/....
• pnpm openclaw qa telegram
  • Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe aus, unter Verwendung der Driver- und SUT-Bot-Tokens aus der Env.
  • 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 Env-Modus oder setzen Sie OPENCLAW_QA_CREDENTIAL_SOURCE=convex, um sich für gepoolte Leases zu entscheiden.
  • Beendet mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie --allow-failures, wenn Sie Artefakte ohne fehlschlagenden Exit-Code möchten.
  • Erfordert zwei verschiedene Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellen muss.
  • Für stabile Bot-zu-Bot-Beobachtung aktivieren Sie in @BotFather den Modus Bot-to-Bot Communication für beide Bots und stellen Sie sicher, dass der Driver-Bot Bot-Verkehr in der Gruppe beobachten kann.
  • Schreibt einen Telegram-QA-Report, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter .artifacts/qa-e2e/.... Antwortszenarien enthalten RTT von der Send-Anfrage des Drivers bis zur beobachteten SUT-Antwort.

Live-Transport-Lanes teilen einen gemeinsamen Standardvertrag, damit neue Transporte nicht auseinanderdriften:

qa-channel bleibt die breite synthetische QA-Suite und ist nicht Teil der Live- Transport-Abdeckungsmatrix.

Lane	Canary	Erwähnungs-Gating	Zulassungslisten-Block	Antwort auf oberster Ebene	Neustart-Fortsetzung	Thread-Follow-up	Thread-Isolation	Reaktionsbeobachtung	Help-Befehl
Matrix	x	x	x	x	x	x	x	x
Telegram	x								x

Gemeinsame Telegram-Anmeldedaten über Convex (v1)

Wenn --credential-source convex (oder OPENCLAW_QA_CREDENTIAL_SOURCE=convex) für openclaw qa telegram aktiviert ist, bezieht QA lab ein exklusives Lease aus einem Convex-gestützten Pool, sendet Heartbeats für dieses Lease, während die Lane läuft, und gibt das Lease beim Herunterfahren frei.

Referenzgerüst für das Convex-Projekt:

• qa/convex-credential-broker/

Erforderliche Env-Variablen:

• 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 Credential-Rolle:
  • CLI: --credential-role maintainer|ci
  • Env-Standard: OPENCLAW_QA_CREDENTIAL_ROLE (standardmäßig ci in CI, sonst maintainer)

Optionale Env-Variablen:

• 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 rein lokale Entwicklung.

OPENCLAW_QA_CONVEX_SITE_URL sollte im normalen Betrieb https:// verwenden.

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

CLI-Helfer für Maintainer:

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 --json für maschinenlesbare Ausgabe in Skripten und CI-Hilfsprogrammen.

Standard-Endpunktvertrag (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 mit Maintainer-Secret)
  • Anfrage: { kind, actorId, payload, note?, status? }
  • Erfolg: { status: "ok", credential }
• POST /admin/remove (nur mit Maintainer-Secret)
  • Anfrage: { credentialId, actorId }
  • Erfolg: { status: "ok", changed, credential }
  • Schutz bei aktivem Lease: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (nur mit Maintainer-Secret)
  • Anfrage: { kind?, status?, includePayload?, limit? }
  • Erfolg: { status: "ok", credentials, count }

Payload-Form für die Art Telegram:

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

Einen Kanal zu QA hinzufügen

Das Hinzufügen eines Kanals zum Markdown-QA-System erfordert genau zwei Dinge:

1. Einen Transport-Adapter für den Kanal.
2. Ein Szenariopaket, das den Kanalvertrag ausübt.

Fügen Sie keinen neuen QA-Befehls-Root auf oberster Ebene hinzu, wenn der gemeinsame Host qa-lab den Ablauf besitzen kann.

qa-lab besitzt die gemeinsame Host-Mechanik:

• den Befehls-Root openclaw qa
• Start und Herunterfahren der Suite
• Worker-Concurrency
• Schreiben von Artefakten
• Berichterstellung
• Szenarioausführung
• Kompatibilitäts-Aliasse für ältere qa-channel-Szenarien

Runner-Plugins besitzen den Transportvertrag:

• wie openclaw qa <runner> unter dem gemeinsamen Root qa eingehängt wird
• wie das Gateway für diesen Transport konfiguriert wird
• wie Bereitschaft geprüft wird
• wie eingehende Ereignisse injiziert werden
• wie ausgehende Nachrichten beobachtet werden
• wie Transkripte und normalisierter Transportzustand bereitgestellt werden
• wie transportgestützte Aktionen ausgeführt werden
• wie transportspezifisches Reset oder Cleanup behandelt wird

Die minimale Einführungsschwelle für einen neuen Kanal ist:

1. Behalten Sie qa-lab als Besitzer des gemeinsamen Root qa bei.
2. Implementieren Sie den Transport-Runner auf dem gemeinsamen Host-Seam von qa-lab.
3. Behalten Sie transportspezifische Mechanik im Runner-Plugin oder Kanal-Harness.
4. Hängen Sie den Runner als openclaw qa <runner> ein, statt einen konkurrierenden Root-Befehl zu registrieren. Runner-Plugins sollten qaRunners in openclaw.plugin.json deklarieren und ein passendes Array qaRunnerCliRegistrations aus runtime-api.ts exportieren. Halten Sie runtime-api.ts schlank; lazy CLI- und Runner-Ausführung sollte hinter separaten Entry-Points bleiben.
5. Verfassen oder passen Sie Markdown-Szenarien unter den thematischen Verzeichnissen qa/scenarios/ an.
6. Verwenden Sie die generischen Szenario-Helfer für neue Szenarien.
7. Halten Sie bestehende Kompatibilitäts-Aliasse funktionsfähig, sofern das Repo keine absichtliche Migration durchführt.

Die Entscheidungsregel ist strikt:

• Wenn Verhalten einmalig in qa-lab ausgedrückt werden kann, platzieren Sie es in qa-lab.
• Wenn Verhalten von einem Kanaltransport abhängt, behalten Sie es in diesem Runner-Plugin oder Plugin-Harness.
• Wenn ein Szenario eine neue Fähigkeit benötigt, die von mehr als einem Kanal genutzt werden kann, fügen Sie einen generischen Helper hinzu statt eines kanalspezifischen Zweigs in suite.ts.
• Wenn ein Verhalten nur für einen Transport sinnvoll ist, halten Sie das Szenario transportspezifisch und machen Sie das im Szenariovertrag ausdrücklich.

Bevorzugte generische Helper-Namen für neue Szenarien sind:

• waitForTransportReady
• waitForChannelReady
• injectInboundMessage
• injectOutboundMessage
• waitForTransportOutboundMessage
• waitForChannelOutboundMessage
• waitForNoTransportOutbound
• getTransportSnapshot
• readTransportMessage
• readTransportTranscript
• formatTransportTranscript
• resetTransport

Kompatibilitäts-Aliasse bleiben für bestehende Szenarien verfügbar, darunter:

• waitForQaChannelReady
• waitForOutboundMessage
• waitForNoOutbound
• formatConversationTranscript
• resetBus

Neue Kanalarbeit sollte die generischen Helper-Namen verwenden. Kompatibilitäts-Aliasse existieren, um eine Flag-Day-Migration zu vermeiden, nicht als Modell für neues Verfassen von Szenarien.

Test-Suiten (was wo läuft)

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

Unit / Integration (Standard)

• Befehl: pnpm test
• Konfiguration: Nicht gezielte Läufe verwenden das Shard-Set vitest.full-*.config.ts und können Multi-Project-Shards für paralleles Scheduling in Konfigurationen pro Projekt aufteilen
• Dateien: Core-/Unit-Inventare unter src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts und die per Whitelist zugelassenen ui-Node-Tests, die von vitest.unit.config.ts abgedeckt werden
• 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
  • Soll schnell und stabil sein
• Hinweis zu Projekten:
  • Nicht gezieltes pnpm test führt jetzt zwölf kleinere Shard-Konfigurationen aus (core-unit-fast, core-unit-src, core-unit-security, core-unit-ui, core-unit-support, core-support-boundary, core-contracts, core-bundled, core-runtime, agentic, auto-reply, extensions) statt eines riesigen nativen Root-Project-Prozesses. Das reduziert Peak-RSS auf ausgelasteten Maschinen und verhindert, dass Auto-Reply-/Extension-Arbeit nicht verwandte Suiten ausbremst.
  • pnpm test --watch verwendet weiterhin den nativen Root-Project-Graph vitest.config.ts, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist.
  • pnpm test, pnpm test:watch und pnpm test:perf:imports leiten explizite Datei-/Verzeichnisziele jetzt zuerst über eingegrenzte Lanes, sodass pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts nicht die vollständigen Startup-Kosten des Root-Projekts zahlen muss.
  • pnpm test:changed erweitert geänderte Git-Pfade in dieselben eingegrenzten Lanes, wenn der Diff nur routbare Quell-/Testdateien berührt; Konfigurations-/Setup-Bearbeitungen fallen weiterhin auf die breite Neuausführung des Root-Projekts zurück.
  • pnpm check:changed ist das normale intelligente lokale Gate für enge Arbeit. Es klassifiziert den Diff in Core, Core-Tests, Extensions, Extension-Tests, Apps, Docs, Release-Metadaten und Tooling und führt dann die passenden Typecheck-/Lint-/Test-Lanes aus. Änderungen am öffentlichen Plugin SDK und an Plugin-Verträgen umfassen Extension-Validierung, weil Extensions von diesen Core-Verträgen abhängen. Reine Versionsanhebungen in Release-Metadaten führen gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten aus statt der vollständigen Suite, mit einem Schutz, der Paketänderungen außerhalb des Versionsfelds auf oberster Ebene ablehnt.
  • Import-leichte Unit-Tests aus Agents, Commands, Plugins, Auto-Reply-Helpern, plugin-sdk und ähnlichen reinen Utility-Bereichen werden über die Lane unit-fast geleitet, die test/setup-openclaw-runtime.ts überspringt; zustandsbehaftete/laufzeitschwere Dateien bleiben auf den bestehenden Lanes.
  • Ausgewählte Helper-Quelldateien aus plugin-sdk und commands ordnen Changed-Mode-Läufe ebenfalls expliziten Nachbartests in diesen leichten Lanes zu, sodass Helper-Bearbeitungen keine erneute Ausführung der vollständigen schweren Suite für dieses Verzeichnis auslösen.
  • auto-reply hat jetzt drei dedizierte Buckets: Helper auf oberster Core-Ebene, Integrations-Tests auf oberster Ebene reply.* und den Teilbaum src/auto-reply/reply/**. Dadurch bleibt die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests getrennt.
• Hinweis zum Embedded Runner:
  • Wenn Sie Discovery-Eingaben des Message-Tools oder den Laufzeitkontext von Compaction ändern, behalten Sie beide Ebenen der Abdeckung bei.
  • Fügen Sie fokussierte Helper-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu.
  • Halten Sie auch die Embedded-Runner-Integrationssuiten gesund: src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts und src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
  • Diese Suiten verifizieren, dass Scoped-IDs und Compaction-Verhalten weiterhin durch die echten Pfade run.ts / compact.ts fließen; reine Helper-Tests sind kein ausreichender Ersatz für diese Integrationspfade.
• Hinweis zum Pool:
  • Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig threads.
  • Die gemeinsame Vitest-Konfiguration setzt außerdem isolate: false fest und verwendet den nicht isolierten Runner für Root-Projekte, E2E- und Live-Konfigurationen.
  • Die Root-UI-Lane behält ihr jsdom-Setup und ihren Optimizer bei, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner.
  • Jeder pnpm test-Shard erbt dieselben Standardwerte threads + isolate: false aus der gemeinsamen Vitest-Konfiguration.
  • Der gemeinsame Launcher scripts/run-vitest.mjs fügt für Vitest-Kindprozesse standardmäßig auch --no-maglev hinzu, um bei großen lokalen Läufen die V8-Compile-Churn zu reduzieren. Setzen Sie OPENCLAW_VITEST_ENABLE_MAGLEV=1, wenn Sie gegen das Standardverhalten von V8 vergleichen müssen.
• Hinweis zur schnellen lokalen Iteration:
  • pnpm changed:lanes zeigt, welche architektonischen Lanes ein Diff auslöst.
  • Der Pre-Commit-Hook führt nach gestagtem Format/Lint pnpm check:changed --staged aus, sodass reine Core-Commits keine Kosten für Extension-Tests verursachen, sofern sie keine öffentlichen, extensionseitigen Verträge berühren. Commits nur mit Release-Metadaten bleiben auf der gezielten Lane für Version/Konfiguration/Root-Abhängigkeiten.
  • Wenn genau dieselbe gestagte Änderungsmenge bereits mit gleich starken oder stärkeren Gates validiert wurde, verwenden Sie scripts/committer --fast "<message>" <files...>, um nur die erneute Ausführung des Changed-Scope-Hooks zu überspringen. Gestagtes Format/Lint läuft weiterhin. Erwähnen Sie die abgeschlossenen Gates in Ihrer Übergabe. Das ist auch nach einem isolierten flaky Hook-Fehler akzeptabel, der mit eingegrenztem Nachweis erneut ausgeführt wurde und bestanden hat.
  • pnpm test:changed leitet über eingegrenzte Lanes, wenn die geänderten Pfade sauber auf eine kleinere Suite abbilden.
  • pnpm test:max und pnpm test:changed:max behalten dasselbe Routing-Verhalten bei, nur mit einer höheren Worker-Obergrenze.
  • Die automatische lokale Worker-Skalierung ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten.
  • Die Basis-Vitest-Konfiguration markiert die Projekte-/Konfigurationsdateien als forceRerunTriggers, damit Reruns im Changed-Mode korrekt bleiben, wenn sich das Test-Wiring ändert.
  • Die Konfiguration hält OPENCLAW_VITEST_FS_MODULE_CACHE auf unterstützten Hosts aktiviert; setzen Sie OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path, wenn Sie einen expliziten Cache-Ort für direktes Profiling möchten.
• Hinweis zum Perf-Debug:
  • pnpm test:perf:imports aktiviert Vitest-Reporting zur Importdauer sowie Ausgabe der Import-Aufschlüsselung.
  • pnpm test:perf:imports:changed begrenzt dieselbe Profiling-Ansicht auf Dateien, die seit origin/main geändert wurden.
• pnpm test:perf:changed:bench -- --ref <git-ref> vergleicht das geroutete test:changed mit dem nativen Root-Project-Pfad für diesen festgeschriebenen Diff und gibt Wall Time sowie macOS-Max-RSS aus.
• pnpm test:perf:changed:bench -- --worktree benchmarkt den aktuellen unsauberen Tree, indem die Liste geänderter Dateien durch scripts/test-projects.mjs und die Root-Vitest-Konfiguration geroutet wird.
  • pnpm test:perf:profile:main schreibt ein CPU-Profil des Hauptthreads für Vitest/Vite-Startup und Transform-Overhead.
  • pnpm test:perf:profile:runner schreibt CPU-+Heap-Profile des Runners für die Unit-Suite bei deaktivierter Dateiparallelität.

Stabilität (Gateway)

• Befehl: pnpm test:stability:gateway
• Konfiguration: vitest.gateway.config.ts, auf einen Worker fest erzwungen
• Umfang:
  • Startet ein echtes Loopback-Gateway mit standardmäßig aktivierter Diagnostik
  • Treibt synthetische Churn für Gateway-Nachrichten, Memory und große Payloads durch den diagnostischen Ereignispfad
  • Fragt diagnostics.stability über Gateway-WS-RPC ab
  • Deckt Persistenz-Helper des diagnostischen Stabilitäts-Bundles ab
  • Stellt sicher, dass der Recorder begrenzt bleibt, synthetische RSS-Samples unter dem Druckbudget bleiben und Queuetiefen pro Sitzung wieder auf null zurücklaufen
• Erwartungen:
  • CI-sicher und ohne Schlüssel
  • Enge Lane für Follow-up bei Stabilitätsregressionen, 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/
• Laufzeitstandardwerte:
  • Verwendet Vitest-threads mit isolate: false, konsistent mit dem 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 Überschreibungen:
  • OPENCLAW_E2E_WORKERS=<n>, um die Worker-Zahl zu erzwingen (begrenzt auf 16).
  • OPENCLAW_E2E_VERBOSE=1, um ausführliche Konsolenausgabe wieder zu aktivieren.
• Umfang:
  • End-to-End-Verhalten mit mehreren Gateway-Instanzen
  • 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: OpenShell-Backend-Smoke

• 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 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 per Opt-in; nicht Teil des Standardlaufs pnpm test:e2e
  • Erfordert eine lokale openshell-CLI plus einen funktionierenden Docker-Daemon
  • Verwendet isoliertes HOME / XDG_CONFIG_HOME und zerstört danach Test-Gateway und Sandbox
• Nützliche Überschreibungen:
  • 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 eine nicht standardmäßige CLI-Binärdatei oder ein Wrapper-Skript zu zeigen

Live (reale Provider + reale 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: aktiviert durch pnpm test:live (setzt OPENCLAW_LIVE_TEST=1)
• Umfang:
  • „Funktioniert dieser Provider/dieses Modell heute tatsächlich mit echten Anmeldedaten?“
  • Erkennt Änderungen an Provider-Formaten, Eigenheiten bei Tool-Aufrufen, Auth-Probleme und Verhalten bei Rate Limits
• Erwartungen:
  • Von Natur aus nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Kontingente, Ausfälle)
  • Kostet Geld / verbraucht Rate Limits
  • Bevorzugen Sie eingegrenzte Teilmengen statt „alles“
• Live-Läufe sourcen ~/.profile, um fehlende API-Schlüssel aufzunehmen.
• Standardmäßig isolieren Live-Läufe weiterhin HOME und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, sodass Unit-Fixtures Ihr echtes ~/.openclaw nicht verändern können.
• Setzen Sie OPENCLAW_LIVE_USE_REAL_HOME=1 nur dann, wenn Sie absichtlich benötigen, dass Live-Tests Ihr echtes Home-Verzeichnis verwenden.
• pnpm test:live verwendet jetzt standardmäßig einen leiseren Modus: Es behält die Fortschrittsausgabe [live] ... bei, unterdrückt jedoch den zusätzlichen Hinweis zu ~/.profile und schaltet Gateway-Bootstrap-Logs/Bonjour-Chatter stumm. Setzen Sie OPENCLAW_LIVE_TEST_QUIET=0, wenn Sie die vollständigen Startlogs wieder sehen möchten.
• API-Key-Rotation (providerspezifisch): Setzen Sie *_API_KEYS im Komma-/Semikolon-Format oder *_API_KEY_1, *_API_KEY_2 (zum Beispiel OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) oder eine Live-Überschreibung pro Lauf über OPENCLAW_LIVE_*_KEY; Tests versuchen bei Antworten mit Rate Limit erneut.
• Fortschritts-/Heartbeat-Ausgabe:
  • Live-Suiten geben jetzt Fortschrittszeilen an stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn Vitests Console-Capture ruhig ist.
  • vitest.live.config.ts deaktiviert das Abfangen der Vitest-Konsole, sodass Fortschrittszeilen von Provider/Gateway bei Live-Läufen sofort gestreamt werden.
  • Passen Sie Heartbeats für direkte Modelle mit OPENCLAW_LIVE_HEARTBEAT_MS an.
  • Passen Sie Heartbeats für Gateway/Probes mit OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS an.

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-Networking / WS-Protokoll / Pairing berühren: Ergänzen Sie pnpm test:e2e
• Debugging von „mein Bot ist down“ / providerspezifischen Fehlern / Tool-Aufrufen: Führen Sie ein eingegrenztes pnpm test:live aus

Live: Android-Node-Fähigkeitssweep

• Test: src/gateway/android-node.capabilities.live.test.ts
• Skript: pnpm android:test:integration
• Ziel: Jeden aktuell beworbenen Befehl eines verbundenen Android-Node aufrufen und das Vertragsverhalten des Befehls validieren.
• Umfang:
  • Manuelle/vorkonfigurierte Voraussetzungen (die Suite installiert/startet/paart die App nicht).
  • Gateway-Validierung node.invoke Befehl für Befehl für den ausgewählten Android-Node.
• Erforderliches Vor-Setup:
  • Android-App bereits mit dem Gateway verbunden + gepairt.
  • App im Vordergrund halten.
  • Berechtigungen/Aufnahmezustimmung für Fähigkeiten gewähren, die bestehen sollen.
• Optionale Ziel-Überschreibungen:
  • OPENCLAW_ANDROID_NODE_ID oder OPENCLAW_ANDROID_NODE_NAME.
  • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
• Vollständige Details zum Android-Setup: Android App

Live: Modell-Smoke (Profil-Schlüssel)

Live-Tests sind in zwei Ebenen aufgeteilt, damit wir Fehler isolieren können:

• „Direktes Modell“ sagt uns, ob der Provider/das Modell mit dem gegebenen Schlüssel überhaupt antworten kann.
• „Gateway-Smoke“ sagt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.).

Ebene 1: Direkte Modell-Completion (ohne Gateway)

• Test: src/agents/models.profiles.live.test.ts
• Ziel:
  • Erkannte Modelle aufzählen
  • Mit getApiKeyForModel Modelle auswählen, für die Sie Anmeldedaten haben
  • Eine kleine Completion pro Modell ausführen (und gezielte Regressionen, wo nötig)
• So aktivieren Sie es:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn Sie Vitest direkt aufrufen)
• Setzen Sie OPENCLAW_LIVE_MODELS=modern (oder all, Alias für modern), um diese Suite tatsächlich auszuführen; sonst wird sie übersprungen, damit pnpm test:live auf Gateway-Smoke fokussiert bleibt
• So wählen Sie Modelle aus:
  • OPENCLAW_LIVE_MODELS=modern, um die moderne Zulassungsliste auszuführen (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_MODELS=all ist ein Alias für die moderne Zulassungsliste
  • oder OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (Komma-Zulassungsliste)
  • Moderne/alle Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie OPENCLAW_LIVE_MAX_MODELS=0 für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze.
• So wählen Sie Provider aus:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (Komma-Zulassungsliste)
• Woher die Schlüssel kommen:
  • Standardmäßig: Profilspeicher und Env-Fallbacks
  • Setzen Sie OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um nur den Profilspeicher zu erzwingen
• Warum das existiert:
  • Trennt „Provider-API ist kaputt / Schlüssel ist ungültig“ von „Gateway-Agent-Pipeline ist kaputt“
  • Enthält kleine, isolierte Regressionen (Beispiel: OpenAI-Responses/Codex-Responses Reasoning-Replay + Tool-Call-Flows)

Ebene 2: Gateway + Dev-Agent-Smoke (was "@openclaw" tatsächlich tut)

• Test: src/gateway/gateway-models.profiles.live.test.ts
• Ziel:
  • Ein In-Process-Gateway hochfahren
  • Eine Sitzung agent:dev:* erstellen/patchen (Modell-Override pro Lauf)
  • Modelle-mit-Schlüsseln iterieren und Folgendes validieren:
    • „sinnvolle“ Antwort (ohne Tools)
    • ein echter Tool-Aufruf funktioniert (Read-Probe)
    • optionale zusätzliche Tool-Probes (Exec+Read-Probe)
    • OpenAI-Regressionspfade (nur Tool-Call → Follow-up) bleiben funktionsfähig
• Probe-Details (damit Sie Fehler schnell erklären können):
  • read-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agenten auf, sie zu readen und die Nonce zurückzugeben.
  • exec+read-Probe: Der Test fordert den Agenten auf, per exec eine Nonce in eine Temp-Datei zu schreiben und sie dann per read zurückzulesen.
  • Bild-Probe: Der Test hängt ein generiertes PNG an (Katze + randomisierter Code) und erwartet, dass das Modell cat <CODE> zurückgibt.
  • Implementierungsreferenz: src/gateway/gateway-models.profiles.live.test.ts und src/gateway/live-image-probe.ts.
• So aktivieren Sie es:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn Sie Vitest direkt aufrufen)
• So wählen Sie Modelle aus:
  • Standard: moderne Zulassungsliste (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all ist ein Alias für die moderne Zulassungsliste
  • Oder setzen Sie OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (oder eine Komma-Liste) zur Eingrenzung
  • Moderne/alle Gateway-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze.
• So wählen Sie Provider aus (vermeiden Sie „alles von OpenRouter“):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (Komma-Zulassungsliste)
• Tool- + Bild-Probes sind in diesem Live-Test immer aktiv:
  • read-Probe + exec+read-Probe (Tool-Stress)
  • Die Bild-Probe läuft, wenn das Modell Unterstützung für Bild-Eingaben bewirbt
  • Ablauf (High Level):
    • Der Test erzeugt ein kleines PNG mit „CAT“ + zufälligem Code (src/gateway/live-image-probe.ts)
    • Sendet es über agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • Gateway parst Anhänge in images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • Der eingebettete Agent leitet eine multimodale Benutzernachricht an das Modell weiter
    • Validierung: Die Antwort enthält cat + den Code (OCR-Toleranz: kleine Fehler erlaubt)

Tipp: Um zu sehen, was Sie auf Ihrer Maschine testen können (und die exakten IDs provider/model), führen Sie aus:

openclaw models list
openclaw models list --json

Live: CLI-Backend-Smoke (Claude, Codex, Gemini oder andere lokale CLIs)

• Test: src/gateway/gateway-cli-backend.live.test.ts
• Ziel: Die Gateway- + Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration zu verändern.
• Backend-spezifische Smoke-Standardwerte liegen in der Definition cli-backend.ts der besitzenden Extension.
• Aktivieren:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn Sie Vitest direkt aufrufen)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Standardwerte:
  • Standard-Provider/-Modell: claude-cli/claude-sonnet-4-6
  • Befehl/Args/Bildverhalten stammen aus den Metadaten des besitzenden CLI-Backend-Plugins.
• Überschreibungen (optional):
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
  • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"
  • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1, um einen echten Bildanhang zu senden (Pfade werden in den Prompt injiziert).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image", um Bilddateipfade als CLI-Args statt per Prompt-Injektion zu übergeben.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (oder "list"), um zu steuern, wie Bild-Args übergeben werden, wenn IMAGE_ARG gesetzt ist.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1, um einen zweiten Zug zu senden und den Resume-Fluss zu validieren.
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0, um die standardmäßige Kontinuitätsprobe derselben Sitzung von Claude Sonnet → Opus zu deaktivieren (setzen Sie 1, um sie zu erzwingen, wenn das ausgewählte Modell ein Umschaltziel unterstützt).

Beispiel:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Docker-Rezept:

pnpm test:docker:live-cli-backend

Docker-Rezepte für einzelne Provider:

pnpm test:docker:live-cli-backend:claude
pnpm test:docker:live-cli-backend:claude-subscription
pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini

Hinweise:

• Der Docker-Runner befindet sich unter scripts/test-live-cli-backend-docker.sh.
• Er führt den Live-CLI-Backend-Smoke im Repo-Docker-Image als nicht-root Nutzer node aus.
• Er löst CLI-Smoke-Metadaten aus der besitzenden Extension auf und installiert dann das passende Linux-CLI-Paket (@anthropic-ai/claude-code, @openai/codex oder @google/gemini-cli) in ein gecachtes beschreibbares Präfix unter OPENCLAW_DOCKER_CLI_TOOLS_DIR (Standard: ~/.cache/openclaw/docker-cli-tools).
• pnpm test:docker:live-cli-backend:claude-subscription erfordert portables Claude-Code-Subscription-OAuth entweder über ~/.claude/.credentials.json mit claudeAiOauth.subscriptionType oder CLAUDE_CODE_OAUTH_TOKEN aus claude setup-token. Es beweist zuerst direktes claude -p in Docker und führt dann zwei Gateway-CLI-Backend-Züge aus, ohne Env-Variablen für Anthropic-API-Schlüssel beizubehalten. Diese Subscription-Lane deaktiviert standardmäßig die Claude-MCP-/Tool- und Bild-Probes, weil Claude derzeit die Nutzung durch Drittanbieter-Apps über zusätzliche Nutzungskosten statt über normale Subscription-Planlimits abrechnet.
• Der Live-CLI-Backend-Smoke übt jetzt denselben End-to-End-Fluss für Claude, Codex und Gemini aus: Text-Zug, Bildklassifizierungs-Zug, dann MCP-Tool-Aufruf cron, verifiziert über das Gateway CLI.
• Claudes Standard-Smoke patcht außerdem die Sitzung von Sonnet auf Opus und verifiziert, dass sich die fortgesetzte Sitzung weiterhin an eine frühere Notiz erinnert.

Live: ACP-Bind-Smoke (/acp spawn ... --bind here)

• Test: src/gateway/gateway-acp-bind.live.test.ts
• Ziel: den echten ACP-Konversations-Bind-Ablauf mit einem Live-ACP-Agenten validieren:
  • /acp spawn <agent> --bind here senden
  • eine synthetische Message-Channel-Konversation direkt binden
  • ein normales Follow-up in derselben Konversation senden
  • verifizieren, dass das Follow-up im Transkript der gebundenen ACP-Sitzung landet
• Aktivieren:
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Standardwerte:
  • ACP-Agents in Docker: claude,codex,gemini
  • ACP-Agent für direktes pnpm test:live ...: claude
  • Synthetischer Kanal: Slack-DM-artiger Konversationskontext
  • ACP-Backend: acpx
• Überschreibungen:
  • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
  • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
  • OPENCLAW_LIVE_ACP_BIND_AGENT=gemini
  • OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini
  • OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'
  • OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4
• Hinweise:
  • Diese Lane verwendet die Gateway-Oberfläche chat.send mit rein adminseitigen synthetischen Feldern für die Ursprungroute, damit Tests Message-Channel-Kontext anhängen können, ohne vorzugeben, extern zuzustellen.
  • Wenn OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND nicht gesetzt ist, verwendet der Test die eingebaute Agent-Registry des eingebetteten Plugins acpx für den ausgewählten ACP-Harness-Agenten.

Beispiel:

OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts

Docker-Rezept:

pnpm test:docker:live-acp-bind

Docker-Rezepte für einzelne Agenten:

pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini

Docker-Hinweise:

• Der Docker-Runner befindet sich unter scripts/test-live-acp-bind-docker.sh.
• Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen alle unterstützten Live-CLI-Agents aus: claude, codex, dann gemini.
• Verwenden Sie OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex oder OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini, um die Matrix einzugrenzen.
• Er sourct ~/.profile, staged das passende CLI-Auth-Material in den Container, installiert acpx in ein beschreibbares npm-Präfix und installiert dann bei Bedarf die angeforderte Live-CLI (@anthropic-ai/claude-code, @openai/codex oder @google/gemini-cli).
• Innerhalb von Docker setzt der Runner OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx, sodass acpx die Provider-Env-Variablen aus dem gesourcten Profil dem Kind-Harness-CLI verfügbar hält.

Live: Codex-App-Server-Harness-Smoke

• Ziel: den plugin-eigenen Codex-Harness über die normale Gateway- Methode agent validieren:
  • das gebündelte Plugin codex laden
  • OPENCLAW_AGENT_RUNTIME=codex auswählen
  • einen ersten Gateway-Agent-Zug an codex/gpt-5.4 senden
  • einen zweiten Zug an dieselbe OpenClaw-Sitzung senden und verifizieren, dass der App-Server- Thread fortgesetzt werden kann
  • /codex status und /codex models über denselben Gateway-Befehls- pfad ausführen
  • optional zwei von Guardian geprüfte eskalierte Shell-Probes ausführen: einen harmlosen Befehl, der genehmigt werden sollte, und einen Fake-Secret-Upload, der abgelehnt werden sollte, sodass der Agent nachfragt
• Test: src/gateway/gateway-codex-harness.live.test.ts
• Aktivieren: OPENCLAW_LIVE_CODEX_HARNESS=1
• Standardmodell: codex/gpt-5.4
• Optionale Bild-Probe: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Optionale MCP-/Tool-Probe: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• Optionale Guardian-Probe: OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1
• Der Smoke setzt OPENCLAW_AGENT_HARNESS_FALLBACK=none, sodass ein defekter Codex- Harness nicht bestehen kann, indem er stillschweigend auf PI zurückfällt.
• Auth: OPENAI_API_KEY aus der Shell/dem Profil sowie optional kopierte ~/.codex/auth.json und ~/.codex/config.toml

Lokales Rezept:

source ~/.profile
OPENCLAW_LIVE_CODEX_HARNESS=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts

Docker-Rezept:

source ~/.profile
pnpm test:docker:live-codex-harness

Docker-Hinweise:

• Der Docker-Runner befindet sich unter scripts/test-live-codex-harness-docker.sh.
• Er sourct das gemountete ~/.profile, übergibt OPENAI_API_KEY, kopiert bei Vorhandensein Codex-CLI- Auth-Dateien, installiert @openai/codex in ein beschreibbares gemountetes npm- Präfix, staged den Quellbaum und führt dann nur den Codex-Harness-Live-Test aus.
• Docker aktiviert standardmäßig die Bild-, MCP-/Tool- und Guardian-Probes. Setzen Sie OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 oder OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 oder OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0, wenn Sie einen engeren Debug- Lauf benötigen.
• Docker exportiert außerdem OPENCLAW_AGENT_HARNESS_FALLBACK=none, passend zur Live- Testkonfiguration, sodass openai-codex/*- oder PI-Fallback einen Codex-Harness- Regressionsfehler nicht verbergen kann.

Empfohlene Live-Rezepte

Enge, explizite Zulassungslisten sind am schnellsten und am wenigsten flaky:

• Einzelnes Modell, direkt (ohne Gateway):

  • OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts

• Einzelnes Modell, Gateway-Smoke:

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Tool-Aufrufe über mehrere Provider hinweg:

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Google-Fokus (Gemini-API-Key + Antigravity):

  • Gemini (API-Key): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Hinweise:

• google/... verwendet die Gemini-API (API-Key).
• google-antigravity/... verwendet die Antigravity-OAuth-Bridge (Cloud-Code-Assist-artiger Agent-Endpunkt).
• google-gemini-cli/... verwendet die lokale Gemini CLI auf Ihrer Maschine (separate Auth- und Tooling-Eigenheiten).
• Gemini-API vs. Gemini CLI:
  • API: OpenClaw ruft Googles gehostete Gemini-API über HTTP auf (API-Key / Profil-Auth); das meinen die meisten Nutzer mit „Gemini“.
  • CLI: OpenClaw ruft eine lokale Binärdatei gemini auf; sie hat ihre eigene Auth und kann sich anders verhalten (Streaming/Tool-Unterstützung/Versionsabweichung).

Live: Modellmatrix (was wir abdecken)

Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die empfohlenen Modelle, die regelmäßig auf einer Entwickler-Maschine mit Schlüsseln abgedeckt werden sollten.

Modernes Smoke-Set (Tool-Aufrufe + Bild)

Das ist der Lauf für die „gängigen Modelle“, der funktionsfähig bleiben soll:

• OpenAI (nicht Codex): openai/gpt-5.4 (optional: openai/gpt-5.4-mini)
• OpenAI Codex: openai-codex/gpt-5.4
• Anthropic: anthropic/claude-opus-4-6 (oder anthropic/claude-sonnet-4-6)
• Google (Gemini-API): google/gemini-3.1-pro-preview und google/gemini-3-flash-preview (vermeiden Sie ältere Gemini-2.x-Modelle)
• Google (Antigravity): google-antigravity/claude-opus-4-6-thinking und google-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

Gateway-Smoke mit Tools + Bild ausführen: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Basislinie: Tool-Aufrufe (Read + optional Exec)

Wählen Sie mindestens eins pro Provider-Familie:

• OpenAI: openai/gpt-5.4 (oder openai/gpt-5.4-mini)
• Anthropic: anthropic/claude-opus-4-6 (oder anthropic/claude-sonnet-4-6)
• Google: google/gemini-3-flash-preview (oder google/gemini-3.1-pro-preview)
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

Optionale zusätzliche Abdeckung (nice to have):

• xAI: xai/grok-4 (oder die neueste verfügbare Version)
• Mistral: mistral/… (wählen Sie ein „tools“-fähiges Modell, das Sie aktiviert haben)
• Cerebras: cerebras/… (falls Sie Zugriff haben)
• LM Studio: lmstudio/… (lokal; Tool-Aufrufe hängen vom API-Modus ab)

Vision: Bild senden (Anhang → multimodale Nachricht)

Nehmen Sie mindestens ein bildfähiges Modell in OPENCLAW_LIVE_GATEWAY_MODELS auf (Claude-/Gemini-/OpenAI-Varianten mit Vision-Fähigkeit usw.), um die Bild-Probe auszuüben.

Aggregatoren / alternative Gateways

Wenn Sie aktivierte Schlüssel haben, unterstützen wir Tests auch über:

• OpenRouter: openrouter/... (Hunderte von Modellen; verwenden Sie openclaw models scan, um Kandidaten mit Tool- + Bild-Unterstützung zu finden)
• OpenCode: opencode/... für Zen und opencode-go/... für Go (Auth über OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Anmeldedaten/Konfiguration haben):

• Eingebaut: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
• Über models.providers (benutzerdefinierte Endpunkte): minimax (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.)

Tipp: Versuchen Sie nicht, in der Dokumentation „alle Modelle“ fest einzucodieren. Die maßgebliche Liste ist, was discoverModels(...) auf Ihrer Maschine zurückgibt + welche Schlüssel verfügbar sind.

Anmeldedaten (niemals committen)

Live-Tests erkennen Anmeldedaten auf dieselbe Weise wie die CLI. Praktische Auswirkungen:

• Wenn die CLI funktioniert, sollten Live-Tests dieselben Schlüssel finden.

• Wenn ein Live-Test „keine Anmeldedaten“ meldet, debuggen Sie auf dieselbe Weise wie bei openclaw models list / Modellauswahl.

• Auth-Profile pro Agent: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (das ist mit „Profil-Schlüsseln“ in den Live-Tests gemeint)

• Konfiguration: ~/.openclaw/openclaw.json (oder OPENCLAW_CONFIG_PATH)

• Veraltetes State-Dir: ~/.openclaw/credentials/ (wird in das staged Live-Home kopiert, wenn vorhanden, aber nicht in den Hauptspeicher für Profil-Schlüssel)

• Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, auth-profiles.json pro Agent, veraltete credentials/ und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; staged Live-Homes überspringen workspace/ und sandboxes/, und Pfadüberschreibungen für agents.*.workspace / agentDir werden entfernt, sodass Probes Ihren realen Host-Workspace nicht berühren.

Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. exportiert in Ihrem ~/.profile), führen Sie lokale Tests nach source ~/.profile aus oder verwenden Sie die Docker-Runner unten (sie können ~/.profile in den Container mounten).

Deepgram live (Audio-Transkription)

• Test: extensions/deepgram/audio.live.test.ts
• Aktivieren: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts

BytePlus Coding-Plan live

• Test: extensions/byteplus/live.test.ts
• Aktivieren: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts
• Optionale Modellüberschreibung: BYTEPLUS_CODING_MODEL=ark-code-latest

ComfyUI-Workflow-Medien live

• Test: extensions/comfy/comfy.live.test.ts
• Aktivieren: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
• Umfang:
  • Übt die gebündelten Pfade für comfy-Bilder, -Video und music_generate aus
  • Überspringt jede Fähigkeit, sofern models.providers.comfy.<capability> nicht konfiguriert ist
  • Nützlich nach Änderungen an comfy-Workflow-Übermittlung, Polling, Downloads oder Plugin-Registrierung

Bildgenerierung live

• Test: test/image-generation.runtime.live.test.ts
• Befehl: pnpm test:live test/image-generation.runtime.live.test.ts
• Harness: pnpm test:live:media image
• Umfang:
  • Zählt jedes registrierte Plugin für Bildgenerierungs-Provider auf
  • Lädt fehlende Provider-Env-Variablen aus Ihrer Login-Shell (~/.profile), bevor Probes ausgeführt werden
  • Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in auth-profiles.json echte Shell-Anmeldedaten nicht verdecken
  • Überspringt Provider ohne nutzbare Auth/Profil/Modell
  • Führt die Standardvarianten der Bildgenerierung über die gemeinsame Laufzeit-Fähigkeit aus:
    • google:flash-generate
    • google:pro-generate
    • google:pro-edit
    • openai:default-generate
• Aktuell abgedeckte gebündelte Provider:
  • fal
  • google
  • minimax
  • openai
  • vydra
  • xai
• Optionale Eingrenzung:
  • OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"
  • OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"
  • OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"
• Optionales Auth-Verhalten:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren

Musikgenerierung live

• Test: extensions/music-generation-providers.live.test.ts
• Aktivieren: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
• Harness: pnpm test:live:media music
• Umfang:
  • Übt den gemeinsam gebündelten Pfad für Musikgenerierungs-Provider aus
  • Deckt derzeit Google und MiniMax ab
  • Lädt Provider-Env-Variablen aus Ihrer Login-Shell (~/.profile), bevor Probes ausgeführt werden
  • Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in auth-profiles.json echte Shell-Anmeldedaten nicht verdecken
  • Überspringt Provider ohne nutzbare Auth/Profil/Modell
  • Führt beide deklarierten Laufzeitmodi aus, wenn verfügbar:
    • generate mit reiner Prompt-Eingabe
    • edit, wenn der Provider capabilities.edit.enabled deklariert
  • Aktuelle Abdeckung der gemeinsamen Lane:
    • google: generate, edit
    • minimax: generate
    • comfy: separate Comfy-Live-Datei, nicht dieser gemeinsame Sweep
• Optionale Eingrenzung:
  • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
  • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
• Optionales Auth-Verhalten:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren

Videogenerierung live

• Test: extensions/video-generation-providers.live.test.ts
• Aktivieren: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
• Harness: pnpm test:live:media video
• Umfang:
  • Übt den gemeinsam gebündelten Pfad für Videogenerierungs-Provider aus
  • Verwendet standardmäßig den release-sicheren Smoke-Pfad: Nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Lobster-Prompt und eine Obergrenze pro Provider-Operation aus OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (standardmäßig 180000)
  • Überspringt FAL standardmäßig, weil providerseitige Queue-Latenz die Release-Zeit dominieren kann; übergeben Sie --video-providers fal oder OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal", um es explizit auszuführen
  • Lädt Provider-Env-Variablen aus Ihrer Login-Shell (~/.profile), bevor Probes ausgeführt werden
  • Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in auth-profiles.json echte Shell-Anmeldedaten nicht verdecken
  • Überspringt Provider ohne nutzbare Auth/Profil/Modell
  • Führt standardmäßig nur generate aus
  • Setzen Sie OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1, um bei Verfügbarkeit auch deklarierte Transformationsmodi auszuführen:
    • imageToVideo, wenn der Provider capabilities.imageToVideo.enabled deklariert und das ausgewählte Provider-/Modell in diesem gemeinsamen Sweep buffer-gestützte lokale Bildeingabe akzeptiert
    • videoToVideo, wenn der Provider capabilities.videoToVideo.enabled deklariert und das ausgewählte Provider-/Modell in diesem gemeinsamen Sweep buffer-gestützte lokale Videoeingabe akzeptiert
  • Aktuelle deklarierte, aber im gemeinsamen Sweep übersprungene imageToVideo-Provider:
    • vydra, weil das gebündelte veo3 nur Text unterstützt und das gebündelte kling eine entfernte Bild-URL erfordert
  • Provider-spezifische Vydra-Abdeckung:
    • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
    • diese Datei führt veo3 Text-zu-Video sowie eine kling-Lane aus, die standardmäßig ein Fixture mit entfernter Bild-URL verwendet
  • Aktuelle videoToVideo-Live-Abdeckung:
    • nur runway, wenn das ausgewählte Modell runway/gen4_aleph ist
  • Aktuelle deklarierte, aber im gemeinsamen Sweep übersprungene videoToVideo-Provider:
    • alibaba, qwen, xai, weil diese Pfade derzeit entfernte Referenz-URLs http(s) / MP4 erfordern
    • google, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale buffer-gestützte Eingabe verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird
    • openai, weil der aktuellen gemeinsamen Lane Garantien für org-spezifischen Zugriff auf Video-Inpaint/Remix fehlen
• Optionale Eingrenzung:
  • OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"
  • OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"
  • OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS="", um jeden Provider in den Standard-Sweep einzubeziehen, einschließlich FAL
  • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000, um die Obergrenze jeder Provider-Operation für einen aggressiven Smoke-Lauf zu senken
• Optionales Auth-Verhalten:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren

Medien-Live-Harness

• Befehl: pnpm test:live:media
• Zweck:
  • Führt die gemeinsamen Live-Suiten für Bild, Musik und Video über einen nativen Repo-Entry-Point aus
  • Lädt fehlende Provider-Env-Variablen automatisch aus ~/.profile
  • Grenzt jede Suite standardmäßig automatisch auf Provider ein, die aktuell nutzbare Auth haben
  • Verwendet erneut scripts/test-live.mjs, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben
• Beispiele:
  • pnpm test:live:media
  • pnpm test:live:media image video --providers openai,google,minimax
  • pnpm test:live:media video --video-providers openai,runway --all-providers
  • pnpm test:live:media music --quiet

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

Diese Docker-Runner teilen sich in zwei Gruppen:

• Live-Modell-Runner: test:docker:live-models und test:docker:live-gateway führen nur ihre jeweils passende Live-Datei mit Profil-Schlüsseln im Repo-Docker-Image aus (src/agents/models.profiles.live.test.ts und src/gateway/gateway-models.profiles.live.test.ts), wobei Ihr lokales Konfigurationsverzeichnis und Ihr Workspace gemountet werden (und ~/.profile gesourct wird, falls gemountet). Die passenden lokalen Entry-Points 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-Sweep 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 Env-Variablen, wenn Sie ausdrücklich den größeren vollständigen Scan wünschen.
• test:docker:all baut das Live-Docker-Image einmal über test:docker:live-build und verwendet es dann für die beiden Live-Docker-Lanes erneut. Außerdem baut es ein gemeinsames Image scripts/e2e/Dockerfile über test:docker:e2e-build und verwendet dieses für die E2E-Container-Smoke-Runner erneut, die die gebaute App ausüben.

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 dann vor dem Lauf in das Container-Home, damit OAuth externer CLI-Tools 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)
• 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)
• 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-/Kanal-/Agent-Smoke: pnpm test:docker:npm-onboard-channel-agent installiert das gepackte OpenClaw-Tarball global in Docker, konfiguriert OpenAI standardmäßig über Env-Ref-Onboarding plus Telegram, verifiziert, dass das Aktivieren des Plugins seine Laufzeit-Dependencies bei Bedarf installiert, führt doctor aus und führt einen gemockten OpenAI-Agent-Zug aus. Verwenden Sie ein vorgebautes Tarball erneut mit OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz, überspringen Sie den Host-Neubau mit OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 oder wechseln Sie den Kanal mit OPENCLAW_NPM_ONBOARD_CHANNEL=discord.
• Gateway-Networking (zwei Container, WS-Auth + Health): pnpm test:docker:gateway-network (Skript: scripts/e2e/gateway-network-docker.sh)
• Minimale Reasoning-Regression für OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (Skript: scripts/e2e/openai-web-search-minimal-docker.sh) führt einen gemockten OpenAI-Server durch 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 (geseedetes Gateway + stdio-Bridge + roher Claude-Notification-Frame-Smoke): 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): pnpm test:docker:pi-bundle-mcp-tools (Skript: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Cron-/Subagent-MCP-Cleanup (echtes Gateway + stdio-MCP-Kindprozess-Teardown nach isolierten Cron- und One-Shot-Subagent-Läufen): pnpm test:docker:cron-mcp-cleanup (Skript: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (Installations-Smoke + /plugin-Alias + Neustart-Semantik von Claude-Bundles): pnpm test:docker:plugins (Skript: scripts/e2e/plugins-docker.sh)
• Plugin-Update unverändert Smoke: pnpm test:docker:plugin-update (Skript: scripts/e2e/plugin-update-unchanged-docker.sh)
• Konfigurations-Reload-Metadaten-Smoke: pnpm test:docker:config-reload (Skript: scripts/e2e/config-reload-source-docker.sh)
• Laufzeit-Dependencies gebündelter Plugins: pnpm test:docker:bundled-channel-deps baut standardmäßig ein kleines Docker-Runner-Image, baut und packt OpenClaw einmal auf dem Host und mountet dann dieses Tarball in jedes Linux-Installationsszenario. Verwenden Sie das Image erneut mit OPENCLAW_SKIP_DOCKER_BUILD=1, überspringen Sie den Host-Neubau nach einem frischen lokalen Build mit OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0 oder zeigen Sie auf ein vorhandenes Tarball mit OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz.
• Grenzen Sie Laufzeit-Dependencies gebündelter Plugins während der Iteration ein, indem Sie nicht relevante Szenarien deaktivieren, zum Beispiel: OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps.

Um das gemeinsame Built-App-Image manuell vorzubauen und erneut zu verwenden:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e: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 gemeinsames Image zeigt, 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 gemeinsamen Laufzeit der gebauten App validieren.

Die Live-Modell-Docker-Runner mounten außerdem den aktuellen Checkout schreibgeschützt und stagen ihn in ein temporäres Arbeitsverzeichnis im Container. Dadurch bleibt das Laufzeit- Image schlank, während Vitest weiterhin gegen Ihren exakten lokalen Source/Config-Stand läuft. Der Staging-Schritt überspringt große lokale Caches und App-Build-Ausgaben wie .pnpm-store, .worktrees, __openclaw_vitest__ und app-lokale .build- oder Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht Minuten mit dem Kopieren maschinenspezifischer Artefakte verbringen. Sie setzen außerdem OPENCLAW_SKIP_CHANNELS=1, sodass Gateway-Live-Probes im Container keine echten Kanal-Worker für Telegram/Discord/etc. starten. test:docker:live-models führt weiterhin pnpm test:live aus, daher sollten Sie OPENCLAW_LIVE_GATEWAY_* ebenfalls durchreichen, wenn Sie Gateway- Live-Abdeckung in dieser Docker-Lane eingrenzen oder ausschließen müssen. test:docker:openwebui ist ein Smoke-Test für Kompatibilität auf höherer Ebene: Er 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 Open WebUIs Proxy /api/chat/completions. Der erste Lauf kann merklich langsamer sein, weil Docker möglicherweise das Open-WebUI-Image ziehen muss und Open WebUI eventuell zunächst seinen eigenen Cold-Start abschließen muss. Diese Lane erwartet einen nutzbaren Live-Modell-Schlüssel, und OPENCLAW_PROFILE_FILE (standardmäßig ~/.profile) ist der primäre Weg, ihn in Docker-Läufen bereitzustellen. Erfolgreiche Läufe geben eine kleine JSON-Payload wie { "ok": true, "model": "openclaw/default", ... } aus. test:docker:mcp-channels ist absichtlich deterministisch und benötigt weder ein echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen geseedeten Gateway- Container, startet einen zweiten Container, der openclaw mcp serve ausführt, und verifiziert dann geroutete Konversations-Discovery, Transkript-Lesevorgänge, Attachment-Metadaten, Verhalten der Live-Ereignisqueue, Routing ausgehender Sendungen und channel- + berechtigungsbezogene Benachrichtigungen im Claude-Stil über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoke das validiert, was die Bridge tatsächlich ausgibt, und 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- Modell-Schlüssel. Es baut das Repo-Docker-Image, startet einen echten stdio-MCP-Probe-Server im Container, materialisiert diesen Server über die eingebettete Pi-Bundle- MCP-Laufzeit, 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 herausfiltern. test:docker:cron-mcp-cleanup ist deterministisch und benötigt keinen Live-Modell- Schlüssel. Es startet ein geseedetes Gateway mit einem echten stdio-MCP-Probe-Server, führt einen isolierten Cron-Zug und einen /subagents spawn-One-Shot-Kindzug aus und verifiziert dann, dass der MCP-Kindprozess 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-Abläufe. Es kann erneut für die Validierung des ACP-Thread-Routings benötigt werden, also löschen Sie es nicht.

Nützliche Env-Variablen:

• OPENCLAW_CONFIG_DIR=... (Standard: ~/.openclaw), gemountet nach /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (Standard: ~/.openclaw/workspace), gemountet nach /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (Standard: ~/.profile), gemountet nach /home/node/.profile und vor dem Ausführen der Tests gesourct
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1, um nur Env-Variablen zu verifizieren, die aus OPENCLAW_PROFILE_FILE gesourct wurden, unter Verwendung temporärer Config-/Workspace-Verzeichnisse und ohne externe CLI-Auth-Mounts
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (Standard: ~/.cache/openclaw/docker-cli-tools), gemountet nach /home/node/.npm-global für gecachte CLI-Installationen innerhalb von Docker
• 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
  • Manuelle Überschreibung mit OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none oder einer Komma-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 Image openclaw:local-live für erneute Läufe zu verwenden, die keinen Neubau benötigen
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um sicherzustellen, dass Anmeldedaten aus dem Profilspeicher kommen (nicht aus Env)
• 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 Bearbeitungen an der Dokumentation die Docs-Prüfungen aus: pnpm check:docs. Führen Sie die vollständige Mintlify-Anchor-Validierung aus, wenn Sie zusätzlich In-Page-Heading-Prüfungen benötigen: pnpm docs:check-links:anchors.

Offline-Regression (CI-sicher)

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

• Gateway-Tool-Aufrufe (gemocktes 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 + erzwungene Auth): src/gateway/gateway.test.ts (Fall: "runs wizard over ws and writes auth token config")

Evaluierungen zur Agent-Zuverlässigkeit (Skills)

Wir haben bereits einige CI-sichere Tests, die sich wie „Evaluierungen zur Agent-Zuverlässigkeit“ verhalten:

• Gemockte Tool-Aufrufe durch den echten Gateway- + Agent-Loop (src/gateway/gateway.test.ts).
• End-to-End-Abläufe des Assistenten, die Session-Wiring und Konfigurationseffekte validieren (src/gateway/gateway.test.ts).

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

• Entscheidungsverhalten: Wenn Skills im Prompt aufgelistet sind, wählt der Agent die richtige Skill aus (oder vermeidet irrelevante)?
• Compliance: Liest der Agent SKILL.md vor der Verwendung und befolgt er die erforderlichen Schritte/Args?
• Workflow-Verträge: Multi-Turn-Szenarien, die Tool-Reihenfolge, Übernahme des Sitzungsverlaufs und Sandbox-Grenzen validieren.

Zukünftige Evaluierungen sollten zunächst deterministisch bleiben:

• Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, Reads von Skill-Dateien und Session-Wiring zu validieren.
• Eine kleine Suite von skill-fokussierten Szenarien (verwenden vs. vermeiden, Gating, Prompt-Injection).
• Optionale Live-Evaluierungen (Opt-in, per Env gegated) erst, nachdem die CI-sichere Suite vorhanden ist.

Vertragstests (Plugin- und Kanal-Shape)

Vertragstests verifizieren, dass jedes registrierte Plugin und jeder Kanal seinem Interface-Vertrag entspricht. Sie iterieren über alle erkannten Plugins und führen eine Suite von Shape- und Verhaltensvalidierungen aus. Die Standard-Unit-Lane pnpm test überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle explizit aus, wenn Sie gemeinsame Kanal- oder Provider-Oberflächen berühren.

Befehle

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

Kanalverträge

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

• plugin - Grundlegende Plugin-Shape (ID, Name, Fähigkeiten)
• setup - Vertrag des Setup-Assistenten
• session-binding - Verhalten der Sitzungsbindung
• outbound-payload - Struktur der Nachrichten-Payload
• inbound - Verarbeitung eingehender Nachrichten
• actions - Handler für Kanalaktionen
• threading - Umgang mit Thread-IDs
• directory - Verzeichnis-/Roster-API
• group-policy - Durchsetzung der Gruppenrichtlinie

Provider-Status-Verträge

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

• status - Kanal-Status-Probes
• registry - Shape der Plugin-Registry

Provider-Verträge

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

• auth - Vertrag des Auth-Flows
• auth-choice - Auth-Auswahl/-Selektion
• catalog - API des Modellkatalogs
• discovery - Plugin-Discovery
• loader - Plugin-Laden
• runtime - Provider-Laufzeit
• shape - Plugin-Shape/Interface
• wizard - Setup-Assistent

Wann ausführen

• Nach Änderungen an Plugin-SDK-Exporten oder Subpfaden
• Nach dem Hinzufügen oder Ändern eines Kanal- oder Provider-Plugins
• Nach Refactorings von Plugin-Registrierung oder Discovery

Vertragstests laufen in CI und erfordern keine echten API-Schlüssel.

Regressionen hinzufügen (Leitfaden)

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

• Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock/Stub-Provider oder die exakte Transformation der Request-Shape erfassen)
• Wenn es inhärent nur live testbar ist (Rate Limits, Auth-Richtlinien), halten Sie den Live-Test eng und per Env-Variablen opt-in
• Bevorzugen Sie die kleinste Ebene, die den Fehler erkennt:
  • Fehler bei Provider-Request-Konvertierung/-Replay → Test direkter Modelle
  • Fehler in Gateway-Sitzung/Verlauf/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test
• Guardrail für SecretRef-Traversal:
  • src/secrets/exec-secret-ref-id-parity.test.ts leitet aus Registry-Metadaten (listSecretTargetRegistryEntries()) ein gesampeltes Ziel pro SecretRef-Klasse ab und validiert dann, dass Traversal-Segment-Exec-IDs abgelehnt werden.
  • Wenn Sie in src/secrets/target-registry-data.ts eine neue SecretRef-Zielfamilie mit includeInPlan hinzufügen, aktualisieren Sie classifyTargetClass in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden.