OpenClaw Test-Guide: Vitest-Suites effizient ausführen

Schnellstart

Die meisten Tage verbringst du mit diesen Befehlen:

1. Vollständiger Gate-Check (vor dem Push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
2. Schnellerer lokaler Durchlauf der gesamten Suite auf einem leistungsstarken Rechner: pnpm test:max
3. Direkte Vitest-Watch-Schleife: pnpm test:watch
4. Gezielte Dateiausführung, die jetzt auch Erweiterungs- und Kanalpfade unterstützt: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
5. Bevorzuge bei der Fehlersuche an einzelnen Stellen immer gezielte Testläufe.
6. Docker-basierte QA-Umgebung: pnpm qa:lab:up
7. Linux-VM-basierte QA-Umgebung: pnpm openclaw qa suite —runner multipass —scenario channel-chat-baseline

Wenn du Tests anpasst oder zusätzliche Sicherheit benötigst:

1. Coverage-Gate: pnpm test:coverage
2. E2E-Suite: pnpm test:e2e

Wenn du echte Provider oder Modelle debuggst (erfordert echte Zugangsdaten):

1. Live-Suite (Modelle + Gateway-Tool/Image-Probes): pnpm test:live
2. Gezielte Ausführung einer Live-Testdatei: pnpm test:live — src/agents/models.profiles.live.test.ts

Tipp: Wenn du nur einen fehlschlagenden Fall isolieren musst, schränke die Live-Tests über die unten beschriebenen Allowlist-Umgebungsvariablen ein.

QA-spezifische Runner

Diese Befehle ergänzen die Haupt-Testsuiten, wenn du die Realitätsnähe des QA-Labs benötigst:

1. pnpm openclaw qa suite
   • Führt Repository-basierte QA-Szenarien direkt auf dem Host aus.
   • Führt standardmäßig mehrere ausgewählte Szenarien parallel mit isolierten Gateway-Workern aus. qa-channel nutzt standardmäßig eine Konkurrenz von 4 (begrenzt durch die Anzahl der Szenarien). Nutze —concurrency <count>, um die Anzahl der Worker anzupassen, oder —concurrency 1 für den älteren seriellen Modus.
   • Beendet den Prozess mit einem Fehlercode, wenn ein Szenario fehlschlägt. Nutze —allow-failures, wenn du Artefakte ohne einen fehlschlagenden Exit-Code erhalten möchtest.
   • Unterstützt die Provider-Modi live-frontier, mock-openai und aimock. aimock startet einen lokalen AIMock-basierten Provider-Server für experimentelle Fixture- und Protokoll-Mock-Abdeckung, ohne die szenariobewusste mock-openai-Spur zu ersetzen.
2. pnpm openclaw qa suite —runner multipass
   • Führt dieselbe QA-Suite innerhalb einer wegwerfbaren Multipass Linux-VM aus.
   • Behält das gleiche Szenario-Auswahlverhalten wie qa suite auf dem Host bei.
   • Verwendet dieselben Provider-/Modell-Auswahl-Flags wie qa suite.
   • Live-Läufe leiten die unterstützten QA-Auth-Eingaben weiter, die für den Gast praktikabel sind: umgebungsbasierte Provider-Keys, den QA-Live-Provider-Konfigurationspfad und CODEX_HOME, falls vorhanden.
   • Ausgabeverzeichnisse müssen innerhalb des Repository-Roots bleiben, damit der Gast durch den gemounteten Workspace zurückschreiben kann.
   • Schreibt den normalen QA-Bericht + Zusammenfassung sowie Multipass-Logs unter .artifacts/qa-e2e/....
3. pnpm qa:lab:up
   • Startet die Docker-basierte QA-Seite für operator-orientierte QA-Arbeit.
4. pnpm openclaw qa aimock
   • Startet nur den lokalen AIMock-Provider-Server für direkte Protokoll-Smoke-Tests.
5. pnpm openclaw qa matrix
   • Führt die Matrix Live-QA-Spur gegen einen wegwerfbaren, Docker-basierten Tuwunel-Homeserver aus.
   • Dieser QA-Host ist aktuell nur für Repository/Dev-Zwecke gedacht. Paketierte OpenClaw-Installationen liefern kein qa-lab aus, daher ist openclaw qa dort nicht verfügbar.
   • Repository-Checkouts laden den gebündelten Runner direkt; kein separater Plugin-Installationsschritt ist nötig.
   • Stellt drei temporäre Matrix-Benutzer (driver, sut, observer) plus einen privaten Raum bereit und startet dann ein QA-Gateway-Kind mit dem echten Matrix-Plugin als SUT-Transport.
   • Verwendet standardmäßig das fixierte, stabile Tuwunel-Image ghcr.io/matrix-construct/tuwunel:v1.5.1. Überschreibe dies mit OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE, wenn du ein anderes Image testen musst.
   • Matrix bietet keine geteilten Credential-Source-Flags, da die Spur wegwerfbare Benutzer lokal bereitstellt.
   • Schreibt einen Matrix-QA-Bericht, eine Zusammenfassung, ein Observed-Events-Artefakt und ein kombiniertes stdout/stderr-Ausgabeprotokoll unter .artifacts/qa-e2e/....
6. pnpm openclaw qa telegram
   • Führt die Telegram Live-QA-Spur gegen eine echte private Gruppe unter Verwendung der Driver- und SUT-Bot-Token aus der Umgebung aus.
   • Erfordert OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN und OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. Die Gruppen-ID muss die numerische Telegram-Chat-ID sein.
   • Unterstützt —credential-source convex für geteilte, gepoolte Zugangsdaten. Nutze standardmäßig den Umgebungsmodus oder setze OPENCLAW_QA_CREDENTIAL_SOURCE=convex, um gepoolte Leases zu nutzen.
   • Beendet den Prozess mit einem Fehlercode, wenn ein Szenario fehlschlägt. Nutze —allow-failures, wenn du Artefakte ohne einen fehlschlagenden Exit-Code erhalten möchtest.
   • Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen offenlegen muss.
   • Aktiviere für eine stabile Bot-zu-Bot-Beobachtung den Bot-zu-Bot-Kommunikationsmodus in @BotFather für beide Bots und stelle sicher, dass der Driver-Bot den Gruppen-Bot-Verkehr beobachten kann.
   • Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Observed-Messages-Artefakt unter .artifacts/qa-e2e/....

Test-Suiten (was läuft wo)

Betrachte die Suiten als eine Skala von „steigender Realitätsnähe“ (und damit steigender Flakiness/Kosten):

Unit / Integration (Standard)

• Befehl: pnpm test
• Konfiguration: Zehn sequentielle Shard-Läufe (vitest.full-*.config.ts) über die bestehenden, eingegrenzten Vitest-Projekte.
• Dateien: Core/Unit-Inventare unter src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts sowie die erlaubten ui Node-Tests, die durch vitest.unit.config.ts abgedeckt sind.
• Umfang:
  • Reine Unit-Tests
  • In-Process-Integrationstests (Gateway-Auth, Routing, Tooling, Parsing, Konfiguration)
  • Deterministische Regressionen für bekannte Bugs
• Erwartungen:
  • Läuft in CI
  • Keine echten Keys erforderlich
  • Sollte schnell und stabil sein

E2E (Gateway-Smoke)

• Befehl: pnpm test:e2e
• Konfiguration: vitest.e2e.config.ts
• Dateien: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
• Laufzeit-Defaults:
  • Nutzt Vitest threads mit isolate: false, passend zum Rest des Repositorys.
  • Nutzt adaptive Worker (CI: bis zu 2, lokal: standardmäßig 1).
  • Läuft standardmäßig im Silent-Modus, um den Overhead der Konsolenausgabe zu reduzieren.
• Umfang:
  • End-to-End-Verhalten des Gateways bei mehreren Instanzen
  • WebSocket/HTTP-Oberflächen, Node-Pairing und intensivere Netzwerkaktivitäten

E2E: OpenShell Backend-Smoke

• Befehl: pnpm test:e2e:openshell
• Datei: test/openshell-sandbox.e2e.test.ts
• Umfang:
  • Startet ein isoliertes OpenShell-Gateway auf dem Host via Docker.
  • Erstellt eine Sandbox aus einem temporären lokalen Dockerfile.
  • Testet das OpenClaw OpenShell-Backend über echtes sandbox ssh-config + SSH-Exec.
  • Verifiziert das Verhalten des remote-kanonischen Dateisystems durch die Sandbox-FS-Bridge.

Live (echte Provider + echte Modelle)

• Befehl: pnpm test:live
• Konfiguration: vitest.live.config.ts
• Dateien: src/**/*.live.test.ts
• Standard: aktiviert durch pnpm test:live (setzt OPENCLAW_LIVE_TEST=1).
• Umfang:
  • „Funktioniert dieser Provider/dieses Modell heute wirklich mit echten Zugangsdaten?“
  • Erkennt Änderungen am Provider-Format, Eigenheiten beim Tool-Calling, Auth-Probleme und Ratenbegrenzungen.
• Erwartungen:
  • Nicht CI-stabil (echte Netzwerke, Provider-Richtlinien, Quotas, Ausfälle).
  • Kostet Geld / verbraucht Ratenlimits.
  • Bevorzuge eingeschränkte Teilmengen gegenüber „allem“.

Welche Suite sollte ich ausführen?

Nutze diese Entscheidungstabelle:

• Bearbeitung von Logik/Tests: Führe pnpm test aus (und pnpm test:coverage, wenn du viel geändert hast).
• Änderungen an Gateway-Netzwerk / WS-Protokoll / Pairing: Füge pnpm test:e2e hinzu.
• Debugging von „mein Bot ist down“ / Provider-spezifische Fehler / Tool-Calling: Führe ein eingeschränktes pnpm test:live aus.

AI Setup Assistant

Live: Android-Node-Funktionsprüfung

Hier testen wir, ob dein verbundenes Android-Gerät alle erwarteten Befehle korrekt ausführt. Diese Tests stellen sicher, dass die Kommunikation zwischen dem Gateway und deinem Gerät einwandfrei funktioniert.

1. Test: src/gateway/android-node.capabilities.live.test.ts
2. Skript: pnpm android:test:integration
3. Ziel: Rufe jeden Befehl auf, der aktuell von einem verbundenen Android-Node beworben wird, und prüfe das Verhalten des Befehlsvertrags.
4. Umfang:
   • Vorausgesetztes/manuelles Setup (die Testsuite installiert, startet oder koppelt die App nicht selbst).
   • Validierung der Gateway-node.invoke-Funktion pro Befehl für den ausgewählten Android-Node.
5. Erforderliches Pre-Setup:
   • Android-App ist bereits verbunden und mit dem Gateway gekoppelt.
   • App befindet sich im Vordergrund.
   • Berechtigungen/Erfassungszustimmungen für die Funktionen, die erfolgreich sein sollen, wurden erteilt.
6. Optionale Ziel-Overrides:
   • OPENCLAW_ANDROID_NODE_ID oder OPENCLAW_ANDROID_NODE_NAME.
   • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
7. Vollständige Android-Setup-Details: Android App

Live: Modell-Smoke-Tests (Profil-Keys)

Live-Tests sind in zwei Ebenen unterteilt, damit wir Fehler gezielt isolieren können.

• „Direct model“ zeigt uns, ob der Anbieter/das Modell mit dem gegebenen Key überhaupt antworten kann.
• „Gateway smoke“ zeigt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sessions, Verlauf, Tools, Sandbox-Richtlinien usw.).

Ebene 1: Direkte Modell-Completion (ohne Gateway)

• Test: src/agents/models.profiles.live.test.ts
• Ziel:
  • Erkannte Modelle auflisten.
  • getApiKeyForModel verwenden, um Modelle auszuwählen, für die du Anmeldedaten hast.
  • Eine kleine Completion pro Modell ausführen (und gezielte Regressionen, wo nötig).
• Aktivierung:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst).
• Setze OPENCLAW_LIVE_MODELS=modern (oder all, ein Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit sich pnpm test:live auf den Gateway-Smoke-Test konzentriert.
• Modellauswahl:
  • OPENCLAW_LIVE_MODELS=modern führt die moderne Allowlist aus (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 Allowlist.
  • Oder OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (Kommaseparierte Allowlist).
  • Moderne/All-Sweeps nutzen standardmäßig ein kuratiertes High-Signal-Cap; setze OPENCLAW_LIVE_MAX_MODELS=0 für einen erschöpfenden modernen Sweep oder eine positive Zahl für ein kleineres Limit.
• Anbieterauswahl:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (Kommaseparierte Allowlist).
• Herkunft der Keys:
  • Standardmäßig: Profilspeicher und Env-Fallbacks.
  • Setze OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um ausschließlich den Profilspeicher zu erzwingen.
• Warum das existiert:
  • Trennt „Provider-API ist defekt / Key ist ungültig“ von „Gateway-Agent-Pipeline ist defekt“.
  • 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 starten.
  • Eine agent:dev:*-Session erstellen/patchen (Modell-Override pro Lauf).
  • Modelle mit Keys iterieren und Folgendes bestätigen:
    • „Sinnvolle“ Antwort (keine Tools).
    • Ein echter Tool-Aufruf funktioniert (Read-Probe).
    • Optionale zusätzliche Tool-Probes (Exec+Read-Probe).
    • OpenAI-Regressionspfade (nur Tool-Call → Follow-up) funktionieren weiterhin.
• Probe-Details (damit du Fehler schnell erklären kannst):
  • read-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und bittet den Agenten, sie zu readen und die Nonce zurückzugeben.
  • exec+read-Probe: Der Test bittet den Agenten, eine Nonce per exec in eine temporäre Datei zu schreiben und sie dann zurückzulesen.
  • Image-Probe: Der Test hängt ein generiertes PNG (Katze + zufälliger Code) an 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.
• Aktivierung:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst).
• Modellauswahl:
  • Standard: Moderne Allowlist (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 Allowlist.
  • Oder setze OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (oder eine Liste mit Kommas), um die Auswahl einzugrenzen.
  • Moderne/All-Gateway-Sweeps nutzen standardmäßig ein kuratiertes High-Signal-Cap; setze OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 für einen erschöpfenden modernen Sweep oder eine positive Zahl für ein kleineres Limit.
• Anbieterauswahl (vermeide „OpenRouter alles“):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (Kommaseparierte Allowlist).
• Tool- + Image-Probes sind in diesem Live-Test immer aktiv:
  • read-Probe + exec+read-Probe (Tool-Stress).
  • Image-Probe läuft, wenn das Modell Image-Input-Unterstützung bewirbt.
  • Ablauf (grob):
    • Test generiert ein winziges PNG mit „CAT“ + zufälligem Code (src/gateway/live-image-probe.ts).
    • Sendet es via agent attachments: [{ mimeType: "image/png", content: "<base64>" }].
    • Gateway parst Attachments in images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts).
    • Eingebetteter Agent leitet eine multimodale Benutzernachricht an das Modell weiter.
    • Assertion: Antwort enthält cat + den Code (OCR-Toleranz: kleine Fehler erlaubt).

Tipp: Um zu sehen, was du auf deiner Maschine testen kannst (und die exakten provider/model-IDs), führe 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: Validierung der Gateway- + Agent-Pipeline unter Verwendung eines lokalen CLI-Backends, ohne deine Standardkonfiguration zu berühren.
• Backend-spezifische Smoke-Defaults liegen bei der cli-backend.ts-Definition der jeweiligen Extension.
• Aktivierung:
  • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst).
  • OPENCLAW_LIVE_CLI_BACKEND=1.
• Defaults:
  • Standard-Provider/Modell: claude-cli/claude-sonnet-4-6.
  • Befehl/Args/Image-Verhalten stammen aus den Metadaten des CLI-Backend-Plugins.
• Overrides (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 ein echtes Image-Attachment zu senden (Pfade werden in den Prompt injiziert).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image", um Image-Dateipfade als CLI-Args statt per Prompt-Injection zu übergeben.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (oder "list"), um zu steuern, wie Image-Args übergeben werden, wenn IMAGE_ARG gesetzt ist.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1, um einen zweiten Turn zu senden und den Resume-Flow zu validieren.
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0, um die standardmäßige Claude Sonnet → Opus Same-Session-Continuity-Probe zu deaktivieren (setze auf 1, um sie zu erzwingen, wenn das gewählte Modell ein Switch-Ziel 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

Single-Provider-Docker-Rezepte:

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 innerhalb des Repo-Docker-Images als nicht-root node-Benutzer aus.
• Er löst CLI-Smoke-Metadaten von der zugehörigen 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 von claude setup-token. Er beweist zuerst direktes claude -p in Docker und führt dann zwei Gateway-CLI-Backend-Turns aus, ohne Anthropic-API-Key-Env-Vars beizubehalten. Diese Subscription-Spur deaktiviert die Claude-MCP/Tool- und Image-Probes standardmäßig, da Claude die Nutzung durch Drittanbieter-Apps derzeit über Extra-Usage-Billing statt über normale Subscription-Plan-Limits abrechnet.
• Der Live-CLI-Backend-Smoke führt nun denselben End-to-End-Flow für Claude, Codex und Gemini aus: Text-Turn, Image-Classification-Turn, dann MCP-cron-Tool-Aufruf, verifiziert durch das Gateway-CLI.
• Claudes Standard-Smoke patcht außerdem die Session von Sonnet auf Opus und verifiziert, dass die fortgesetzte Session sich noch an eine frühere Notiz erinnert.

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

• Test: src/gateway/gateway-acp-bind.live.test.ts
• Ziel: Validierung des echten ACP-Conversation-Bind-Flows mit einem Live-ACP-Agenten:
  • Sende /acp spawn <agent> --bind here.
  • Binde eine synthetische Message-Channel-Konversation an Ort und Stelle.
  • Sende ein normales Follow-up in derselben Konversation.
  • Verifiziere, dass das Follow-up im gebundenen ACP-Session-Transkript landet.
• Aktivierung:
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Defaults:
  • ACP-Agenten in Docker: claude,codex,gemini.
  • ACP-Agent für direktes pnpm test:live ...: claude.
  • Synthetischer Channel: Slack-DM-Stil Konversationskontext.
  • ACP-Backend: acpx.
• Overrides:
  • 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>'
• Hinweise:
  • Diese Spur nutzt die Gateway-chat.send-Oberfläche mit Admin-only synthetischen Originating-Route-Feldern, sodass Tests Message-Channel-Kontext anhängen können, ohne extern liefern zu müssen.
  • Wenn OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND nicht gesetzt ist, verwendet der Test das integrierte Agent-Register des acpx-Plugins 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

Single-Agent-Docker-Rezepte:

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 gegen alle unterstützten Live-CLI-Agenten nacheinander aus: claude, codex, dann gemini.
• Nutze OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex oder OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini, um die Matrix einzugrenzen.
• Er lädt ~/.profile, stellt das passende CLI-Auth-Material in den Container, installiert acpx in ein beschreibbares npm-Präfix und installiert dann das angeforderte Live-CLI (@anthropic-ai/claude-code, @openai/codex oder @google/gemini-cli), falls es fehlt.
• Innerhalb von Docker setzt der Runner OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx, damit acpx die Provider-Env-Vars aus dem geladenen Profil für das Child-Harness-CLI verfügbar hält.

Live: Codex app-server harness smoke

Das Ziel ist es, den zum Plugin gehörenden Codex-Harness über das normale Gateway zu validieren. Hierbei wird der agent-Prozess genutzt, um das gebündelte codex-Plugin zu laden und die Laufzeitumgebung entsprechend zu konfigurieren.

1. Lade das gebündelte codex-Plugin.
2. Wähle OPENCLAW_AGENT_RUNTIME=codex aus.
3. Sende einen ersten Gateway-Agent-Turn an codex/gpt-5.4.
4. Sende einen zweiten Turn an dieselbe OpenClaw-Sitzung und verifiziere, dass der app-server-Thread fortgesetzt werden kann.
5. Führe /codex status und /codex models über denselben Gateway-Befehlspfad aus.

• Test: src/gateway/gateway-codex-harness.live.test.ts
• Aktivierung: OPENCLAW_LIVE_CODEX_HARNESS=1
• Standardmodell: codex/gpt-5.4
• Optionaler Image-Probe: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Optionaler MCP/Tool-Probe: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• Der Smoke-Test setzt OPENCLAW_AGENT_HARNESS_FALLBACK=none, damit ein defekter Codex-Harness nicht unbemerkt auf PI zurückfällt.
• Authentifizierung: OPENAI_API_KEY aus der Shell/dem Profil, plus 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_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 lädt die gemountete ~/.profile, übergibt den OPENAI_API_KEY, kopiert bei Vorhandensein die Codex CLI-Auth-Dateien, installiert @openai/codex in ein beschreibbares gemountetes npm-Präfix, bereitet den Quellbaum vor und führt dann nur den Codex-Harness-Live-Test aus.
• Docker aktiviert die Image- und MCP/Tool-Probes standardmäßig. Setze OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 oder OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0, wenn du einen eingeschränkteren Debug-Lauf benötigst.
• Docker exportiert zudem OPENCLAW_AGENT_HARNESS_FALLBACK=none, passend zur Live-Test-Konfiguration, damit openai-codex/* oder PI-Fallback keine Codex-Harness-Regression verdecken können.

Empfohlene Live-Rezepte:

Schmale, explizite Allows sind am schnellsten und am wenigsten fehleranfällig:

• Einzelnes Modell, direkt (kein 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-Calling über mehrere Anbieter:

  • 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/... nutzt die Gemini API (API-Key).
• google-antigravity/... nutzt die Antigravity OAuth-Bridge (Agent-Endpunkt im Stil von Cloud Code Assist).
• google-gemini-cli/... nutzt die lokale Gemini CLI auf deinem Rechner (separate Auth + Tooling-Besonderheiten).
• Gemini API vs. Gemini CLI:
  • API: OpenClaw ruft Googles gehostete Gemini API über HTTP auf (API-Key / Profil-Auth); das ist es, was die meisten Nutzer unter „Gemini“ verstehen.
  • CLI: OpenClaw führt ein lokales gemini-Binary aus; es hat eine eigene Auth und kann sich anders verhalten (Streaming/Tool-Support/Versionsunterschiede).

Live: Modell-Matrix (was wir abdecken)

Es gibt keine feste „CI-Modellliste“ (Live-Tests sind optional), aber dies sind die empfohlenen Modelle, die du regelmäßig auf einer Entwicklungsmaschine mit vorhandenen Keys abdecken solltest.

Modernes Smoke-Set (Tool-Calling + Image):

Dies ist der Lauf für „gängige Modelle“, bei dem wir erwarten, dass er stabil bleibt:

• 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 (vermeide ä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

Führe den Gateway-Smoke mit Tools + Image aus: 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

Baseline: Tool-Calling (Lesen + optional Ausführen):

Wähle mindestens eines pro Anbieter-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 (gut zu haben):

• xAI: xai/grok-4 (oder das neueste verfügbare)
• Mistral: mistral/… (wähle ein „Tools“-fähiges Modell, das du aktiviert hast)
• Cerebras: cerebras/… (falls du Zugriff hast)
• LM Studio: lmstudio/… (lokal; Tool-Calling hängt vom API-Modus ab)

Vision: Image-Versand (Anhang → multimodale Nachricht):

Füge mindestens ein bildfähiges Modell in OPENCLAW_LIVE_GATEWAY_MODELS hinzu (Claude/Gemini/OpenAI Vision-fähige Varianten, etc.), um den Image-Probe zu testen.

Aggregatoren / alternative Gateways:

Wenn du Keys aktiviert hast, unterstützen wir auch Tests über:

• OpenRouter: openrouter/... (hunderte Modelle; nutze openclaw models scan, um Tool+Image-fähige Kandidaten zu finden)
• OpenCode: opencode/... für Zen und opencode-go/... für Go (Auth via OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Weitere Anbieter, die du in die Live-Matrix aufnehmen kannst (wenn du Zugangsdaten/Konfiguration hast):

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

Tipp: Versuche nicht, „alle Modelle“ in den Dokumenten hart zu codieren. Die maßgebliche Liste ist das, was discoverModels(...) auf deiner Maschine zurückgibt + alle verfügbaren Keys.

Credentials (niemals committen)

Live-Tests entdecken Zugangsdaten auf die gleiche Weise wie die CLI. Praktische Auswirkungen:

• Wenn die CLI funktioniert, sollten die Live-Tests dieselben Keys finden.

• Wenn ein Live-Test „no creds“ meldet, debugge auf die gleiche Weise, wie du openclaw models list / Modellauswahl debuggen würdest.

• Auth-Profile pro Agent: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (das ist es, was „Profil-Keys“ in den Live-Tests bedeutet)

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

• Legacy-Status-Verzeichnis: ~/.openclaw/credentials/ (wird in das gestagete Live-Home kopiert, wenn vorhanden, aber nicht der Haupt-Profil-Key-Speicher)

• Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, auth-profiles.json pro Agent, Legacy-credentials/ und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; gestagete Live-Homes überspringen workspace/ und sandboxes/, und Pfad-Overrides für agents.*.workspace / agentDir werden entfernt, damit Probes nicht dein echtes Host-Workspace beeinflussen.

Wenn du dich auf Env-Keys verlassen möchtest (z. B. exportiert in deiner ~/.profile), führe lokale Tests nach source ~/.profile aus oder nutze die Docker-Runner weiter unten (diese können ~/.profile in den Container mounten).

Deepgram live (Audio-Transkription)

• Test: src/media-understanding/providers/deepgram/audio.live.test.ts
• Aktivierung: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

AI Setup Assistant

BytePlus coding plan live

Hier erfährst du, wie du deine OpenClaw BytePlus coding plan Integrationen mit Live-Daten testest. Diese Tests stellen sicher, dass deine Anbindung an die API korrekt funktioniert.

1. Test: src/agents/byteplus.live.test.ts
2. Aktivieren: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
3. Optionales Modell überschreiben: BYTEPLUS_CODING_MODEL=ark-code-latest

ComfyUI workflow media live

Mit diesen Tests kannst du deine OpenClaw ComfyUI workflow media Integrationen validieren. Dies ist besonders hilfreich, wenn du Änderungen an der Übermittlung, dem Polling oder dem Download von Workflows vorgenommen hast.

1. Test: extensions/comfy/comfy.live.test.ts
2. Aktivieren: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
3. Umfang:
   • Führt die gebündelten Comfy-Pfade für Bild, Video und music_generate aus.
   • Überspringt jede Funktion, sofern sie nicht unter models.providers.comfy.<capability> konfiguriert ist.
   • Nützlich nach Anpassungen an der Workflow-Übermittlung, dem Polling, Downloads oder der Plugin-Registrierung.

Image generation live

Hier kannst du deine OpenClaw Image generation Provider testen, um sicherzustellen, dass alle registrierten Plugins korrekt mit der API kommunizieren.

1. Test: src/image-generation/runtime.live.test.ts
2. Befehl: pnpm test:live src/image-generation/runtime.live.test.ts
3. Harness: pnpm test:live:media image
4. Umfang:
   • Listet jeden registrierten Image-generation Provider-Plugin auf.
   • Lädt fehlende Provider-Umgebungsvariablen aus deiner Login-Shell (~/.profile), bevor die Prüfung beginnt.
   • Verwendet standardmäßig Live/Env API keys anstelle von gespeicherten Auth-Profilen, damit veraltete Test-Keys in auth-profiles.json deine Shell-Anmeldedaten nicht überschreiben.
   • Überspringt Provider ohne nutzbare Auth/Profile/Modelle.
   • Führt die Standard-Varianten der Image-generation über die gemeinsame Runtime-Fähigkeit aus:
     • google:flash-generate
     • google:pro-generate
     • google:pro-edit
     • openai:default-generate
5. Aktuell abgedeckte Provider:
   • openai
   • google
6. Optionale Eingrenzung:
   • OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"
   • OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"
   • OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"
7. Optionales Auth-Verhalten:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um die Auth über den Profil-Speicher zu erzwingen und Env-only Overrides zu ignorieren.

Music generation live

Dieser Abschnitt deckt die Tests für deine OpenClaw Music generation Provider ab, um eine reibungslose Generierung und Bearbeitung von Musikdateien zu gewährleisten.

1. Test: extensions/music-generation-providers.live.test.ts
2. Aktivieren: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
3. Harness: pnpm test:live:media music
4. Umfang:
   • Führt den gemeinsamen Pfad für gebündelte Music-generation Provider aus.
   • Deckt aktuell Google und MiniMax ab.
   • Lädt Provider-Umgebungsvariablen aus deiner Login-Shell (~/.profile), bevor die Prüfung beginnt.
   • Verwendet standardmäßig Live/Env API keys anstelle von gespeicherten Auth-Profilen, damit veraltete Test-Keys in auth-profiles.json deine Shell-Anmeldedaten nicht überschreiben.
   • Überspringt Provider ohne nutzbare Auth/Profile/Modelle.
   • Führt beide deklarierten Runtime-Modi aus, sofern verfügbar:
     • generate mit reiner Prompt-Eingabe
     • edit, wenn der Provider capabilities.edit.enabled deklariert
   • Aktuelle Abdeckung:
     • google: generate, edit
     • minimax: generate
     • comfy: separate Comfy Live-Datei, kein Teil dieses gemeinsamen Durchlaufs
5. Optionale Eingrenzung:
   • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
   • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
6. Optionales Auth-Verhalten:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um die Auth über den Profil-Speicher zu erzwingen und Env-only Overrides zu ignorieren.

AI Setup Assistant

Video generation live

Mit OpenClaw kannst du die Video-Generierung direkt in deiner Umgebung testen, um sicherzustellen, dass die Integrationen mit den verschiedenen Anbietern einwandfrei funktionieren.

1. Test ausführen: extensions/video-generation-providers.live.test.ts
2. Aktivieren: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
3. Harness nutzen: pnpm test:live:media video
4. Umfang:
   • Prüft den gemeinsam genutzten Pfad für Video-Generierungs-Provider.
   • Standardmäßig wird der sichere Release-Pfad verwendet: Nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Lobster-Prompt und ein pro-Provider-Limit gemäß OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (standardmäßig 180000).
   • FAL wird standardmäßig übersprungen, da die Warteschlangen-Latenz auf Provider-Seite die Release-Zeit zu stark beeinflussen kann; nutze --video-providers fal oder OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal", um es explizit auszuführen.
   • Lädt Provider-Umgebungsvariablen aus deiner Login-Shell (~/.profile), bevor die Tests starten.
   • Verwendet standardmäßig Live/Env-API-Keys anstelle von gespeicherten Auth-Profilen, damit veraltete Test-Keys in auth-profiles.json keine echten Shell-Anmeldedaten überschreiben.
   • Überspringt Provider ohne nutzbare Auth, Profile oder Modelle.
   • Führt standardmäßig nur generate aus.
   • Setze OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1, um bei Verfügbarkeit auch definierte Transform-Modi auszuführen:
     • imageToVideo, wenn der Provider capabilities.imageToVideo.enabled deklariert und das gewählte Modell lokale Bild-Inputs im gemeinsamen Durchlauf akzeptiert.
     • videoToVideo, wenn der Provider capabilities.videoToVideo.enabled und das gewählte Modell lokale Video-Inputs im gemeinsamen Durchlauf akzeptiert.
   • Aktuell deklarierte, aber im gemeinsamen Durchlauf übersprungene imageToVideo-Provider:
     • vydra, da das gebündelte veo3 nur Text unterstützt und das gebündelte kling eine Remote-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 einen kling-Durchlauf aus, der standardmäßig ein Remote-Bild-URL-Fixture verwendet.
   • Aktuelle videoToVideo-Live-Abdeckung:
     • runway nur, wenn das gewählte Modell runway/gen4_aleph ist.
   • Aktuelle deklarierte, aber im gemeinsamen Durchlauf übersprungene videoToVideo-Provider:
     • alibaba, qwen, xai, da diese Pfade derzeit Remote-http(s) / MP4-Referenz-URLs erfordern.
     • google, da der aktuelle gemeinsame Gemini/Veo-Durchlauf lokale Puffer-Inputs verwendet, was im gemeinsamen Durchlauf nicht akzeptiert wird.
     • openai, da dem aktuellen gemeinsamen Durchlauf die Garantien für organisationsspezifische Video-Inpaint/Remix-Zugriffe fehlen.
5. Optionale Einschränkung:
   • 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-Durchlauf einzubeziehen, einschließlich FAL.
   • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000, um das Limit pro Provider-Operation für einen schnellen Smoke-Test zu reduzieren.
6. Optionales Auth-Verhalten:
   • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um die Auth über den Profil-Speicher zu erzwingen und Env-Only-Overrides zu ignorieren.

Media live harness

Mit dem Media live harness kannst du verschiedene Medien-Testsuiten zentral verwalten und ausführen.

1. Befehl: pnpm test:live:media
2. Zweck:
   • Führt die Live-Testsuiten für Bild, Musik und Video über einen einzigen Repository-nativen Einstiegspunkt aus.
   • Lädt automatisch fehlende Provider-Umgebungsvariablen aus ~/.profile.
   • Schränkt jede Suite automatisch auf Provider ein, die standardmäßig über nutzbare Auth verfügen.
   • Verwendet scripts/test-live.mjs wieder, sodass das Verhalten bei Heartbeat und im Quiet-Modus konsistent bleibt.
3. 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 “works in Linux”-Prüfungen)

Diese Docker Runner unterteilen sich in zwei Kategorien:

1. Live-Modell-Runner: test:docker:live-models und test:docker:live-gateway führen nur ihre jeweils passenden Live-Dateien mit Profil-Key innerhalb des Docker-Images aus (src/agents/models.profiles.live.test.ts und src/gateway/gateway-models.profiles.live.test.ts). Dabei werden dein lokales Konfigurationsverzeichnis und dein Workspace eingebunden (und ~/.profile wird geladen, falls gemountet). Die entsprechenden lokalen Entrypoints sind test:live:models-profiles und test:live:gateway-profiles.
2. Docker Live-Runner verwenden standardmäßig ein kleineres Smoke-Limit, damit ein vollständiger Docker-Durchlauf praktikabel bleibt: test:docker:live-models nutzt standardmäßig OPENCLAW_LIVE_MAX_MODELS=12, und test:docker:live-gateway nutzt 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. Überschreibe diese Umgebungsvariablen, wenn du explizit einen umfassenderen Scan durchführen möchtest.
3. test:docker:all erstellt das Live-Docker-Image einmal über test:docker:live-build und verwendet es dann für die beiden Live-Docker-Lanes wieder.
4. Container-Smoke-Runner: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels und test:docker:plugins starten einen oder mehrere echte Container und verifizieren Integrationspfade auf höherer Ebene.

Die Live-Modell Docker Runner binden zudem nur die benötigten CLI-Auth-Verzeichnisse ein (oder alle unterstützten, wenn der Lauf nicht eingeschränkt ist) und kopieren diese vor dem Start in das Home-Verzeichnis des Containers. So kann externes CLI-OAuth Token aktualisieren, ohne den Auth-Speicher des Hosts zu verändern:

1. Direkte Modelle: pnpm test:docker:live-models (Skript: scripts/test-live-models-docker.sh)
2. ACP Bind-Smoke: pnpm test:docker:live-acp-bind (Skript: scripts/test-live-acp-bind-docker.sh)
3. CLI Backend-Smoke: pnpm test:docker:live-cli-backend (Skript: scripts/test-live-cli-backend-docker.sh)
4. Codex App-Server Harness-Smoke: pnpm test:docker:live-codex-harness (Skript: scripts/test-live-codex-harness-docker.sh)
5. Gateway + Dev-Agent: pnpm test:docker:live-gateway (Skript: scripts/test-live-gateway-models-docker.sh)
6. Open WebUI Live-Smoke: pnpm test:docker:openwebui (Skript: scripts/e2e/openwebui-docker.sh)
7. Onboarding-Assistent (TTY, vollständiges Scaffolding): pnpm test:docker:onboard (Skript: scripts/e2e/onboard-docker.sh)
8. Gateway-Netzwerk (zwei Container, WS-Auth + Health): pnpm test:docker:gateway-network (Skript: scripts/e2e/gateway-network-docker.sh)
9. MCP Channel-Bridge (gefülltes Gateway + stdio-Bridge + roher Claude-Benachrichtigungs-Frame-Smoke): pnpm test:docker:mcp-channels (Skript: scripts/e2e/mcp-channels-docker.sh)
10. Plugins (Installations-Smoke + /plugin-Alias + Claude-Bundle-Neustart-Semantik): pnpm test:docker:plugins (Skript: scripts/e2e/plugins-docker.sh)

Die Live-Modell Docker Runner binden den aktuellen Checkout schreibgeschützt ein und stagen ihn in ein temporäres Arbeitsverzeichnis innerhalb des Containers. Dies hält das Runtime-Image schlank, während Vitest weiterhin gegen deinen exakten lokalen Quellcode und deine Konfiguration läuft. Der Staging-Schritt überspringt große lokale Caches und App-Build-Outputs wie .pnpm-store, .worktrees, __openclaw_vitest__ sowie app-lokale .build oder Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht unnötig Zeit mit dem Kopieren maschinenspezifischer Artefakte verbringen. Sie setzen außerdem OPENCLAW_SKIP_CHANNELS=1, damit Gateway-Live-Probes keine echten Telegram/Discord/etc.-Channel-Worker innerhalb des Containers starten. test:docker:live-models führt weiterhin pnpm test:live aus, also leite OPENCLAW_LIVE_GATEWAY_* weiter, wenn du die Gateway-Live-Abdeckung in diesem Docker-Durchlauf einschränken oder ausschließen möchtest. test:docker:openwebui ist ein Kompatibilitäts-Smoke auf höherer Ebene: Er startet einen OpenClaw Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, startet einen fest definierten Open WebUI-Container gegen dieses Gateway, meldet sich über Open WebUI an, verifiziert, dass /api/models den Wert openclaw/default ausgibt, und sendet dann eine echte Chat-Anfrage über den /api/chat/completions-Proxy von Open WebUI. Der erste Durchlauf kann spürbar langsamer sein, da Docker möglicherweise das Open WebUI-Image herunterladen muss und Open WebUI sein eigenes Cold-Start-Setup abschließen muss. Diese Lane erfordert einen gültigen Live-Modell-Key, und OPENCLAW_PROFILE_FILE (standardmäßig ~/.profile) ist der primäre Weg, diesen in Docker-Läufen bereitzustellen. Erfolgreiche Läufe geben ein kleines JSON-Payload aus, wie etwa { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels ist bewusst deterministisch und benötigt kein echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen gefüllten Gateway-Container, startet einen zweiten Container, der openclaw mcp serve ausführt, und verifiziert dann die Erkennung gerouteter Konversationen, Transkript-Lesevorgänge, Attachment-Metadaten, das Verhalten der Live-Event-Queue, das ausgehende Sende-Routing und Claude-artige Channel- sowie Berechtigungsbenachrichtigungen über die echte stdio MCP-Bridge. Die Benachrichtigungsprüfung untersucht die rohen stdio MCP-Frames direkt, sodass der Smoke validiert, was die Bridge tatsächlich ausgibt, und nicht nur, was ein spezifisches Client-SDK zufällig anzeigt.

Manueller ACP-Klartext-Thread-Smoke (nicht CI):

bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...

Behalte dieses Skript für Regression- oder Debug-Workflows bei. Es könnte für die Validierung des ACP-Thread-Routings erneut benötigt werden, also lösche es nicht.

Nützliche Umgebungsvariablen:

• 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 Testlauf geladen
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 um nur Umgebungsvariablen zu verifizieren, die aus OPENCLAW_PROFILE_FILE geladen wurden, unter Verwendung temporärer Konfigurations-/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 zwischengespeicherte 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
  • Eingeschränkte 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 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 existierendes openclaw:local-live-Image für erneute Läufe wiederzuverwenden, die keinen Rebuild benötigen
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 um sicherzustellen, dass Anmeldedaten aus dem Profilspeicher stammen (nicht aus der Umgebung)
• OPENCLAW_OPENWEBUI_MODEL=... um das Modell zu wählen, das vom Gateway für den Open WebUI-Smoke bereitgestellt wird
• OPENCLAW_OPENWEBUI_PROMPT=... um den Nonce-Check-Prompt zu überschreiben, der vom Open WebUI-Smoke verwendet wird
• OPENWEBUI_IMAGE=... um das fest definierte Open WebUI-Image-Tag zu überschreiben

Dokumentationsprüfung

Führe nach Änderungen an der Dokumentation die Prüfungen aus: pnpm check:docs. Führe die vollständige Mintlify-Anker-Validierung aus, wenn du auch In-Page-Überschriften prüfen musst: pnpm docs:check-links:anchors.

AI Setup Assistant

Offline Regression (CI-safe)

Hierbei handelt es sich um „echte Pipeline“-Regressionen, die ohne echte Provider auskommen. OpenClaw Offline Regression stellt sicher, dass deine Abläufe auch ohne externe Abhängigkeiten stabil bleiben.

1. Gateway Tool-Aufrufe (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”)
2. Gateway Wizard (WS wizard.start/wizard.next, schreibt Konfiguration + erzwungene Authentifizierung): src/gateway/gateway.test.ts (Fall: “runs wizard over ws and writes auth token config”)

src/gateway/gateway.test.ts

Agent-Zuverlässigkeitsbewertungen (Skills)

Wir verfügen bereits über einige CI-sichere Tests, die wie „Agent-Zuverlässigkeitsbewertungen“ funktionieren. OpenClaw Agent-Zuverlässigkeit hilft dir dabei, die Leistung deiner Skills systematisch zu prüfen.

1. Mock-Tool-Aufrufe durch das echte Gateway + Agent-Loop (src/gateway/gateway.test.ts).
2. End-to-End-Wizard-Abläufe, die die Sitzungsanbindung und Konfigurationseffekte validieren (src/gateway/gateway.test.ts).

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

1. Entscheidungsfindung: Wenn Skills im Prompt aufgelistet sind, wählt der Agent den richtigen Skill aus (oder vermeidet irrelevante)?
2. Compliance: Liest der Agent die SKILL.md vor der Verwendung und befolgt er die erforderlichen Schritte/Argumente?
3. Workflow-Verträge: Szenarien mit mehreren Durchläufen, die die Tool-Reihenfolge, die Übertragung der Sitzungshistorie und die Sandbox-Grenzen sicherstellen.

Zukünftige Bewertungen sollten zunächst deterministisch bleiben:

1. Ein Szenario-Runner, der Mock-Provider verwendet, um Tool-Aufrufe + Reihenfolge, das Lesen von Skill-Dateien und die Sitzungsanbindung zu überprüfen.
2. Eine kleine Suite von Skill-fokussierten Szenarien (Verwendung vs. Vermeidung, Gating, Prompt-Injection).
3. Optionale Live-Bewertungen (Opt-in, umgebungsgesteuert) erst, nachdem die CI-sichere Suite implementiert wurde.

AI Setup Assistant

Contract Tests (Plugin- und Channel-Struktur)

Contract Tests stellen sicher, dass jedes registrierte Plugin und jeder Channel den definierten Schnittstellen-Vertrag einhält. Sie gehen alle gefundenen Plugins durch und führen eine Reihe von Prüfungen bezüglich Struktur und Verhalten aus. Der standardmäßige pnpm test Unit-Test-Durchlauf überspringt diese gemeinsamen Schnittstellen- und Smoke-Dateien bewusst; führe die Contract-Befehle daher explizit aus, wenn du an gemeinsamen Channel- oder Provider-Oberflächen arbeitest.

Befehle

Hier sind die verfügbaren Befehle, um die OpenClaw Contract Tests auszuführen:

1. Alle Verträge prüfen: pnpm test:contracts
2. Nur Channel-Verträge prüfen: pnpm test:contracts:channels
3. Nur Provider-Verträge prüfen: pnpm test:contracts:plugins

Channel-Verträge

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

1. plugin - Grundlegende Plugin-Struktur (ID, Name, Fähigkeiten)
2. setup - Vertrag für den Setup-Assistenten
3. session-binding - Verhalten der Session-Bindung
4. outbound-payload - Struktur der ausgehenden Nachrichten-Payload
5. inbound - Verarbeitung eingehender Nachrichten
6. actions - Handler für Channel-Aktionen
7. threading - Handhabung von Thread-IDs
8. directory - Directory/Roster API
9. group-policy - Durchsetzung von Gruppenrichtlinien

Provider-Status-Verträge

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

1. status - Sonden für den Channel-Status
2. registry - Struktur der Plugin-Registry

Provider-Verträge

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

1. auth - Vertrag für den Authentifizierungs-Ablauf
2. auth-choice - Auswahl der Authentifizierung
3. catalog - Modell-Katalog API
4. discovery - Plugin-Erkennung
5. loader - Plugin-Ladevorgang
6. runtime - Provider-Laufzeitumgebung
7. shape - Plugin-Struktur/Schnittstelle
8. wizard - Setup-Assistent

Wann du diese Tests ausführen solltest

1. Nach Änderungen an den Exports oder Subpaths des Plugin-SDK
2. Nach dem Hinzufügen oder Ändern eines Channel- oder Provider-Plugins
3. Nach dem Refactoring der Plugin-Registrierung oder -Erkennung

Contract Tests laufen in der CI und benötigen keine echten API-Keys.

Hinzufügen von Regressionen (Anleitung)

Wenn du ein Problem mit einem Provider oder Modell behebst, das im Live-Betrieb entdeckt wurde, befolge diese Richtlinien für die Qualitätssicherung.

1. Füge nach Möglichkeit eine CI-sichere Regression hinzu (z. B. durch einen Mock/Stub des Providers oder durch das Abfangen der exakten Transformation der Request-Struktur).
2. Wenn das Problem nur im Live-Betrieb auftritt (z. B. Rate Limits oder Authentifizierungs-Richtlinien), halte den Live-Test klein und aktiviere ihn nur über Umgebungsvariablen.
3. Ziele bevorzugt auf die kleinste Ebene ab, die den Fehler abfängt:
   • Bei Fehlern in der Provider-Request-Konvertierung oder beim Replay: direkter Modell-Test.
   • Bei Fehlern in der Gateway-Session, Historie oder Tool-Pipeline: Gateway Live-Smoke-Test oder CI-sicherer Gateway-Mock-Test.
4. Sicherheitsvorkehrungen für das SecretRef-Traversal:
   • src/secrets/exec-secret-ref-id-parity.test.ts leitet pro SecretRef-Klasse ein Beispielziel aus den Registry-Metadaten (listSecretTargetRegistryEntries()) ab und stellt sicher, dass Exec-IDs in Traversal-Segmenten abgelehnt werden.
   • Wenn du eine neue includeInPlan SecretRef-Zielfamilie in src/secrets/target-registry-data.ts hinzufügst, aktualisiere classifyTargetClass in diesem Test. Der Test schlägt bei nicht klassifizierten Ziel-IDs absichtlich fehl, damit neue Klassen nicht unbemerkt übersprungen werden können.

AI Setup Assistant

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>