Testing

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

Dieses Dokument ist ein “Wie wir testen”-Leitfaden:

  • Was jede Suite abdeckt (und was sie bewusst nicht abdeckt)
  • Welche Befehle du für gängige Workflows ausführst (lokal, vor dem Push, Debugging)
  • Wie Live-Tests Credentials finden und Models/Provider auswählen
  • Wie du Regressionstests für reale Model/Provider-Probleme hinzufügst

Schnellstart

An den meisten Tagen:

  • Vollständiges Gate (vor dem Push erwartet): pnpm build && pnpm check && pnpm test

Wenn du Tests änderst oder zusätzliche Sicherheit willst:

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

Beim Debuggen echter Provider/Models (benötigt echte Credentials):

  • Live-Suite (Models + Gateway Tool/Image-Probes): pnpm test:live

Tipp: Wenn du nur einen fehlschlagenden Fall brauchst, nutze die Allowlist-Umgebungsvariablen (siehe unten), um Live-Tests einzugrenzen.

Test-Suites (was läuft wo)

Stell dir die Suites als “zunehmenden Realismus” vor (und zunehmende Flakiness/Kosten):

Unit / Integration (Standard)

  • Befehl: pnpm test
  • Config: vitest.config.ts
  • Dateien: src/**/*.test.ts
  • Umfang:
    • Reine Unit-Tests
    • In-Process-Integrationstests (Gateway Auth, Routing, Tooling, Parsing, Config)
    • Deterministische Regressionstests 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
  • Config: vitest.e2e.config.ts
  • Dateien: src/**/*.e2e.test.ts
  • Umfang:
    • Multi-Instanz-Gateway End-to-End-Verhalten
    • WebSocket/HTTP-Oberflächen, Node-Pairing und umfangreicheres Networking
  • Erwartungen:
    • Läuft in CI (wenn in der Pipeline aktiviert)
    • Keine echten Keys erforderlich
    • Mehr bewegliche Teile als Unit-Tests (kann langsamer sein)

Live (echte Provider + echte Models)

  • Befehl: pnpm test:live
  • Config: 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 Model heute tatsächlich mit echten Credentials?”
    • Erkennt Provider-Formatänderungen, Tool-Calling-Eigenheiten, Auth-Probleme und Rate-Limit-Verhalten
  • Erwartungen:
    • Nicht CI-stabil by Design (echte Netzwerke, echte Provider-Richtlinien, Quotas, Ausfälle)
    • Kostet Geld / nutzt Rate Limits
    • Führe lieber eingegrenzte Teilmengen aus statt “alles”
    • Live-Runs sourcen ~/.profile, um fehlende API-Keys zu finden
    • Anthropic Key-Rotation: Setze OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (oder OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) oder mehrere ANTHROPIC_API_KEY*-Variablen; Tests wiederholen bei Rate Limits

Welche Suite soll ich ausführen?

Nutze diese Entscheidungstabelle:

  • Logik/Tests bearbeiten: Führe pnpm test aus (und pnpm test:coverage, wenn du viel geändert hast)
  • Gateway-Networking / WS-Protokoll / Pairing anfassen: Füge pnpm test:e2e hinzu
  • “Mein Bot ist down” / Provider-spezifische Fehler / Tool-Calling debuggen: Führe ein eingegrenztes pnpm test:live aus

Live: Model-Smoke (Profile-Keys)

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

  • “Direct Model” sagt uns, ob der Provider/das Model überhaupt mit dem gegebenen Key antworten kann.
  • “Gateway-Smoke” sagt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Model funktioniert (Sessions, History, Tools, Sandbox-Policy usw.).

Ebene 1: Direkte Model-Completion (ohne Gateway)

  • Test: src/agents/models.profiles.live.test.ts
  • Ziel:
    • Entdeckte Models auflisten
    • getApiKeyForModel nutzen, um Models auszuwählen, für die du Credentials hast
    • Eine kleine Completion pro Model ausführen (und gezielte Regressionstests wo nötig)
  • Aktivierung:
    • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst)
  • Setze OPENCLAW_LIVE_MODELS=modern (oder all, Alias für modern), um diese Suite tatsächlich auszuführen; sonst wird sie übersprungen, um pnpm test:live auf Gateway-Smoke zu fokussieren
  • Model-Auswahl:
    • OPENCLAW_LIVE_MODELS=modern für die moderne Allowlist (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
    • OPENCLAW_LIVE_MODELS=all ist ein Alias für die moderne Allowlist
    • oder OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..." (Komma-Allowlist)
  • Provider-Auswahl:
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (Komma-Allowlist)
  • Woher kommen die Keys:
    • Standard: Profile-Store und Env-Fallbacks
    • Setze OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um nur Profile-Store zu erzwingen
  • Warum das existiert:
    • Trennt “Provider-API ist kaputt / Key ist ungültig” von “Gateway-Agent-Pipeline ist kaputt”
    • Enthält kleine, isolierte Regressionstests (Beispiel: OpenAI Responses/Codex Responses Reasoning-Replay + Tool-Call-Flows)

Ebene 2: Gateway + Dev-Agent-Smoke (was “@openclaw” tatsächlich macht)

  • Test: src/gateway/gateway-models.profiles.live.test.ts
  • Ziel:
    • Ein In-Process-Gateway starten
    • Eine agent:dev:*-Session erstellen/patchen (Model-Override pro Run)
    • Models-mit-Keys durchlaufen und prüfen:
      • “Sinnvolle” Antwort (ohne Tools)
      • Ein echter Tool-Aufruf funktioniert (Read-Probe)
      • Optionale zusätzliche Tool-Probes (Exec+Read-Probe)
      • OpenAI-Regressionspfade (Tool-Call-Only → Follow-up) funktionieren weiter
  • Probe-Details (damit du Fehler schnell erklären kannst):
    • read-Probe: Der Test schreibt eine Nonce-Datei im Workspace und bittet den Agent, sie zu read und die Nonce zurückzugeben.
    • exec+read-Probe: Der Test bittet den Agent, per exec eine Nonce in eine Temp-Datei zu schreiben und sie dann zu read.
    • Image-Probe: Der Test hängt ein generiertes PNG (Katze + randomisierter Code) an und erwartet, dass das Model 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)
  • Model-Auswahl:
    • Standard: Moderne Allowlist (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
    • OPENCLAW_LIVE_GATEWAY_MODELS=all ist ein Alias für die moderne Allowlist
    • Oder setze OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (oder Komma-Liste), um einzugrenzen
  • Provider-Auswahl (vermeide “OpenRouter alles”):
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (Komma-Allowlist)
  • Tool- + Image-Probes sind in diesem Live-Test immer aktiv:
    • read-Probe + exec+read-Probe (Tool-Stress)
    • Image-Probe läuft, wenn das Model Image-Input-Support anzeigt
    • Flow (High-Level):
      • Test generiert ein kleines 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)
      • Embedded Agent leitet eine multimodale User-Message an das Model weiter
      • Assertion: Antwort enthält cat + den Code (OCR-Toleranz: kleine Fehler erlaubt)

Tipp: Um zu sehen, was du auf deinem Rechner testen kannst (und die exakten provider/model-IDs), führe aus:

openclaw models list
openclaw models list --json

Live: Anthropic Setup-Token-Smoke

  • Test: src/agents/anthropic.setup-token.live.test.ts
  • Ziel: Prüfen, ob Claude Code CLI Setup-Token (oder ein eingefügtes Setup-Token-Profil) ein Anthropic-Prompt abschließen kann.
  • Aktivierung:
    • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst)
    • OPENCLAW_LIVE_SETUP_TOKEN=1
  • Token-Quellen (wähle eine):
    • Profil: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
    • Raw-Token: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
  • Model-Override (optional):
    • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

Setup-Beispiel:

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

Live: CLI-Backend-Smoke (Claude Code CLI oder andere lokale CLIs)

  • Test: src/gateway/gateway-cli-backend.live.test.ts
  • Ziel: Gateway + Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne deine Standard-Config anzufassen.
  • Aktivierung:
    • pnpm test:live (oder OPENCLAW_LIVE_TEST=1, wenn du Vitest direkt aufrufst)
    • OPENCLAW_LIVE_CLI_BACKEND=1
  • Standardwerte:
    • Model: claude-cli/claude-sonnet-4-5
    • Command: claude
    • Args: ["-p","--output-format","json","--dangerously-skip-permissions"]
  • Overrides (optional):
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"
    • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
    • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
    • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
    • 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 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_DISABLE_MCP_CONFIG=0, um Claude Code CLI MCP-Config aktiviert zu lassen (Standard deaktiviert MCP-Config mit einer temporären leeren Datei).

Beispiel:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Empfohlene Live-Rezepte

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

  • Einzelnes Model, direkt (ohne Gateway):

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

  • Einzelnes Model, Gateway-Smoke:

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

  • Tool-Calling über mehrere Provider:

    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" 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-5-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 (Cloud Code Assist-Style Agent-Endpoint).
  • google-gemini-cli/... nutzt das lokale Gemini CLI auf deinem Rechner (separate Auth + Tooling-Eigenheiten).
  • Gemini API vs. Gemini CLI:
    • API: OpenClaw ruft Googles gehostete Gemini API über HTTP auf (API-Key / Profil-Auth); das ist, was die meisten Nutzer mit “Gemini” meinen.
    • CLI: OpenClaw führt ein lokales gemini-Binary aus; es hat eigene Auth und kann sich anders verhalten (Streaming/Tool-Support/Versions-Skew).

Live: Model-Matrix (was wir abdecken)

Es gibt keine feste “CI-Model-Liste” (Live ist Opt-in), aber das sind die empfohlenen Models, die du regelmäßig auf einem Dev-Rechner mit Keys abdecken solltest.

Modernes Smoke-Set (Tool-Calling + Image)

Das ist der “Common Models”-Run, von dem wir erwarten, dass er funktioniert:

  • OpenAI (non-Codex): openai/gpt-5.2 (optional: openai/gpt-5.1)
  • OpenAI Codex: openai-codex/gpt-5.2 (optional: openai-codex/gpt-5.2-codex)
  • Anthropic: anthropic/claude-opus-4-5 (oder anthropic/claude-sonnet-4-5)
  • Google (Gemini API): google/gemini-3-pro-preview und google/gemini-3-flash-preview (vermeide ältere Gemini 2.x Models)
  • Google (Antigravity): google-antigravity/claude-opus-4-5-thinking und google-antigravity/gemini-3-flash
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1

Gateway-Smoke mit Tools + Image ausführen: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Baseline: Tool-Calling (Read + optionales Exec)

Wähle mindestens eins pro Provider-Familie:

  • OpenAI: openai/gpt-5.2 (oder openai/gpt-5-mini)
  • Anthropic: anthropic/claude-opus-4-5 (oder anthropic/claude-sonnet-4-5)
  • Google: google/gemini-3-flash-preview (oder google/gemini-3-pro-preview)
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/minimax-m2.1

Optionale zusätzliche Abdeckung (nice to have):

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

Vision: Image-Send (Attachment → multimodale Message)

Füge mindestens ein Image-fähiges Model in OPENCLAW_LIVE_GATEWAY_MODELS ein (Claude/Gemini/OpenAI Vision-fähige Varianten usw.), um die Image-Probe zu testen.

Aggregatoren / alternative Gateways

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

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

Weitere Provider, die du in die Live-Matrix aufnehmen kannst (falls du Credentials/Config hast):

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

Tipp: Versuche nicht, “alle Models” in Docs hardzucoden. Die autoritative Liste ist, was discoverModels(...) auf deinem Rechner zurückgibt + welche Keys verfügbar sind.

Credentials (niemals committen)

Live-Tests finden Credentials auf die gleiche Weise wie das CLI. Praktische Implikationen:

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

  • Wenn ein Live-Test “no creds” sagt, debugge auf die gleiche Weise wie openclaw models list / Model-Auswahl.

  • Profile-Store: ~/.openclaw/credentials/ (bevorzugt; das bedeutet “Profile-Keys” in den Tests)

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

Wenn du dich auf Env-Keys verlassen willst (z. B. exportiert in deiner ~/.profile), führe lokale Tests nach source ~/.profile aus, oder nutze die Docker-Runner unten (sie 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

Docker-Runner (optionale “funktioniert in Linux”-Checks)

Diese führen pnpm test:live im Repo-Docker-Image aus und mounten dein lokales Config-Verzeichnis und Workspace (und sourcen ~/.profile, falls gemountet):

  • Direkte Models: pnpm test:docker:live-models (Script: scripts/test-live-models-docker.sh)
  • Gateway + Dev-Agent: pnpm test:docker:live-gateway (Script: scripts/test-live-gateway-models-docker.sh)
  • Onboarding-Wizard (TTY, vollständiges Scaffolding): pnpm test:docker:onboard (Script: scripts/e2e/onboard-docker.sh)
  • Gateway-Networking (zwei Container, WS-Auth + Health): pnpm test:docker:gateway-network (Script: scripts/e2e/gateway-network-docker.sh)
  • Plugins (Custom-Extension-Load + Registry-Smoke): pnpm test:docker:plugins (Script: scripts/e2e/plugins-docker.sh)

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_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=..., um den Run einzugrenzen
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, um sicherzustellen, dass Credentials aus dem Profile-Store kommen (nicht Env)

Docs-Sanity

Führe Docs-Checks nach Doc-Edits aus: pnpm docs:list.

Offline-Regression (CI-safe)

Das sind “echte Pipeline”-Regressionstests ohne echte Provider:

  • Gateway Tool-Calling (Mock OpenAI, echtes Gateway + Agent-Loop): src/gateway/gateway.tool-calling.mock-openai.test.ts
  • Gateway-Wizard (WS wizard.start/wizard.next, schreibt Config + Auth erzwungen): src/gateway/gateway.wizard.e2e.test.ts

Agent-Reliability-Evals (Skills)

Wir haben bereits einige CI-safe Tests, die sich wie “Agent-Reliability-Evals” verhalten:

  • Mock Tool-Calling durch das echte Gateway + Agent-Loop (src/gateway/gateway.tool-calling.mock-openai.test.ts).
  • End-to-End-Wizard-Flows, die Session-Wiring und Config-Effekte validieren (src/gateway/gateway.wizard.e2e.test.ts).

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

  • Decisioning: Wenn Skills im Prompt aufgelistet sind, wählt der Agent das richtige Skill (oder vermeidet irrelevante)?
  • Compliance: Liest der Agent SKILL.md vor der Nutzung und folgt den erforderlichen Schritten/Args?
  • Workflow-Contracts: Multi-Turn-Szenarien, die Tool-Reihenfolge, Session-History-Carryover und Sandbox-Grenzen prüfen.

Zukünftige Evals sollten zuerst deterministisch bleiben:

  • Ein Szenario-Runner mit Mock-Providern, um Tool-Calls + Reihenfolge, Skill-File-Reads und Session-Wiring zu prüfen.
  • Eine kleine Suite von Skill-fokussierten Szenarien (nutzen vs. vermeiden, Gating, Prompt-Injection).
  • Optionale Live-Evals (Opt-in, Env-gated) erst, nachdem die CI-safe Suite vorhanden ist.

Regressionstests hinzufügen (Anleitung)

Wenn du ein Provider/Model-Problem behebst, das in Live entdeckt wurde:

  • Füge wenn möglich einen CI-safe Regressionstest hinzu (Mock/Stub-Provider oder erfasse die exakte Request-Shape-Transformation)
  • Wenn es inhärent Live-only ist (Rate Limits, Auth-Policies), halte den Live-Test eng und Opt-in via Env-Variablen
  • Ziele auf die kleinste Ebene, die den Bug fängt:
    • Provider-Request-Conversion/Replay-Bug → Direct-Models-Test
    • Gateway-Session/History/Tool-Pipeline-Bug → Gateway-Live-Smoke oder CI-safe Gateway-Mock-Test