​

Test

• Cosa copre ciascuna suite (e cosa deliberatamente non copre)
• Quali comandi eseguire per i flussi di lavoro comuni (locale, pre-push, debug)
• Come i test live rilevano le credenziali e selezionano modelli/provider
• Come aggiungere regressioni per problemi reali di modelli/provider

​

Avvio rapido

• Gate completo (previsto prima del push): pnpm build && pnpm check && pnpm test
• Esecuzione locale più rapida dell’intera suite su una macchina capiente: pnpm test:max
• Loop di watch Vitest diretto: pnpm test:watch
• Il targeting diretto dei file ora instrada anche i percorsi extension/channel: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Quando stai iterando su un singolo errore, preferisci prima esecuzioni mirate.
• Sito QA basato su Docker: pnpm qa:lab:up
• Lane QA basata su VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

• Gate di copertura: pnpm test:coverage
• Suite E2E: pnpm test:e2e

• Suite live (modelli + probe tool/immagini del Gateway): pnpm test:live
• Esegui in modo silenzioso un solo file live: pnpm test:live -- src/agents/models.profiles.live.test.ts

​

Runner specifici per QA

• pnpm openclaw qa suite
  • Esegue scenari QA supportati dal repository direttamente sull’host.
  • Esegue più scenari selezionati in parallelo per impostazione predefinita con worker Gateway isolati. qa-channel usa per impostazione predefinita una concorrenza pari a 4 (limitata dal numero di scenari selezionati). Usa --concurrency <count> per regolare il numero di worker, oppure --concurrency 1 per il vecchio lane seriale.
  • Termina con codice diverso da zero quando uno scenario fallisce. Usa --allow-failures quando vuoi ottenere gli artifact senza un codice di uscita di errore.
  • Supporta le modalità provider live-frontier, mock-openai e aimock. aimock avvia un server provider locale basato su AIMock per copertura sperimentale di fixture e mock di protocollo senza sostituire il lane mock-openai basato sugli scenari.
• pnpm openclaw qa suite --runner multipass
  • Esegue la stessa suite QA all’interno di una VM Linux Multipass usa e getta.
  • Mantiene lo stesso comportamento di selezione degli scenari di qa suite sull’host.
  • Riutilizza gli stessi flag di selezione provider/modello di qa suite.
  • Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per il guest: chiavi provider basate su env, il percorso di configurazione del provider live QA e CODEX_HOME quando presente.
  • Le directory di output devono rimanere sotto la root del repository affinché il guest possa scrivere di nuovo tramite il workspace montato.
  • Scrive il report QA normale + il riepilogo più i log Multipass sotto .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Avvia il sito QA basato su Docker per il lavoro QA in stile operatore.
• pnpm openclaw qa aimock
  • Avvia solo il server provider AIMock locale per smoke test diretti del protocollo.
• pnpm openclaw qa matrix
  • Esegue il lane QA live di Matrix contro un homeserver Tuwunel usa e getta basato su Docker.
  • Questo host QA oggi è solo per repo/dev. Le installazioni OpenClaw pacchettizzate non distribuiscono qa-lab, quindi non espongono openclaw qa.
  • I checkout del repository caricano direttamente il runner incluso; non è necessario un passaggio separato di installazione del plugin.
  • Effettua il provisioning di tre utenti Matrix temporanei (driver, sut, observer) più una stanza privata, quindi avvia un processo figlio del gateway QA con il vero plugin Matrix come trasporto del SUT.
  • Usa per impostazione predefinita l’immagine Tuwunel stabile fissata ghcr.io/matrix-construct/tuwunel:v1.5.1. Sostituiscila con OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE quando devi testare un’immagine diversa.
  • Matrix non espone flag condivisi di origine credenziali perché il lane effettua localmente il provisioning di utenti usa e getta.
  • Scrive un report QA Matrix, un riepilogo, un artifact degli eventi osservati e un log combinato stdout/stderr sotto .artifacts/qa-e2e/....
• pnpm openclaw qa telegram
  • Esegue il lane QA live di Telegram contro un gruppo privato reale usando i token bot del driver e del SUT dall’env.
  • Richiede OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN e OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. L’id del gruppo deve essere l’id numerico della chat Telegram.
  • Supporta --credential-source convex per credenziali condivise in pool. Usa la modalità env per impostazione predefinita, oppure imposta OPENCLAW_QA_CREDENTIAL_SOURCE=convex per attivare i lease in pool.
  • Termina con codice diverso da zero quando uno scenario fallisce. Usa --allow-failures quando vuoi ottenere gli artifact senza un codice di uscita di errore.
  • Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone un nome utente Telegram.
  • Per un’osservazione stabile bot-to-bot, abilita Bot-to-Bot Communication Mode in @BotFather per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo.
  • Scrive un report QA Telegram, un riepilogo e un artifact dei messaggi osservati sotto .artifacts/qa-e2e/....

​

Credenziali Telegram condivise tramite Convex (v1)

• qa/convex-credential-broker/

• OPENCLAW_QA_CONVEX_SITE_URL (ad esempio https://your-deployment.convex.site)
• Un secret per il ruolo selezionato:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER per maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI per ci
• Selezione del ruolo delle credenziali:
  • CLI: --credential-role maintainer|ci
  • Valore predefinito env: OPENCLAW_QA_CREDENTIAL_ROLE (in CI il valore predefinito è ci, altrimenti maintainer)

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (predefinito 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (predefinito 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (predefinito 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (predefinito 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (predefinito /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (id di tracciamento opzionale)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 consente URL Convex http:// loopback per sviluppo solo locale.

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>

• POST /acquire
  • Richiesta: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Successo: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Esaurito/riprovabile: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Richiesta: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Successo: { status: "ok" } (o 2xx vuoto)
• POST /release
  • Richiesta: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Successo: { status: "ok" } (o 2xx vuoto)
• POST /admin/add (solo secret maintainer)
  • Richiesta: { kind, actorId, payload, note?, status? }
  • Successo: { status: "ok", credential }
• POST /admin/remove (solo secret maintainer)
  • Richiesta: { credentialId, actorId }
  • Successo: { status: "ok", changed, credential }
  • Guardia contro lease attivo: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (solo secret maintainer)
  • Richiesta: { kind?, status?, includePayload?, limit? }
  • Successo: { status: "ok", credentials, count }

• { groupId: string, driverToken: string, sutToken: string }
• groupId deve essere una stringa id numerica della chat Telegram.
• admin/add convalida questa forma per kind: "telegram" e rifiuta payload malformati.

​

Aggiungere un canale a QA

1. Un adapter di trasporto per il canale.
2. Un pacchetto di scenari che eserciti il contratto del canale.

• la root di comando openclaw qa
• avvio e teardown della suite
• concorrenza dei worker
• scrittura degli artifact
• generazione dei report
• esecuzione degli scenari
• alias di compatibilità per i vecchi scenari qa-channel

• come openclaw qa <runner> viene montato sotto la root condivisa qa
• come viene configurato il gateway per quel trasporto
• come viene verificata la readiness
• come vengono iniettati gli eventi in ingresso
• come vengono osservati i messaggi in uscita
• come vengono esposti transcript e stato normalizzato del trasporto
• come vengono eseguite le azioni supportate dal trasporto
• come viene gestito il reset o la pulizia specifici del trasporto

1. Mantenere qa-lab come proprietario della root condivisa qa.
2. Implementare il runner di trasporto sulla seam dell’host condiviso qa-lab.
3. Mantenere i meccanismi specifici del trasporto all’interno del plugin runner o dell’harness del canale.
4. Montare il runner come openclaw qa <runner> invece di registrare una root di comando concorrente. I plugin runner devono dichiarare qaRunners in openclaw.plugin.json ed esportare un array corrispondente qaRunnerCliRegistrations da runtime-api.ts. Mantieni runtime-api.ts leggero; la CLI lazy e l’esecuzione del runner devono restare dietro entrypoint separati.
5. Creare o adattare scenari markdown nelle directory tematiche qa/scenarios/.
6. Usare gli helper di scenario generici per i nuovi scenari.
7. Mantenere funzionanti gli alias di compatibilità esistenti a meno che il repository non stia eseguendo una migrazione intenzionale.

• Se un comportamento può essere espresso una sola volta in qa-lab, mettilo in qa-lab.
• Se un comportamento dipende da un trasporto di canale, mantienilo in quel plugin runner o harness del plugin.
• Se uno scenario richiede una nuova capacità che può essere usata da più di un canale, aggiungi un helper generico invece di un ramo specifico del canale in suite.ts.
• Se un comportamento ha senso solo per un trasporto, mantieni lo scenario specifico del trasporto e rendilo esplicito nel contratto dello scenario.

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

• waitForQaChannelReady
• waitForOutboundMessage
• waitForNoOutbound
• formatConversationTranscript
• resetBus

​

Suite di test (cosa viene eseguito dove)

​

Unit / integration (predefinita)

• Comando: pnpm test
• Configurazione: dieci esecuzioni shard sequenziali (vitest.full-*.config.ts) sui progetti Vitest con ambito esistenti
• File: inventari core/unit in src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts e i test node ui in allowlist coperti da vitest.unit.config.ts
• Ambito:
  • Test unitari puri
  • Test di integrazione in-process (autenticazione gateway, instradamento, tooling, parsing, configurazione)
  • Regressioni deterministiche per bug noti
• Aspettative:
  • Viene eseguita in CI
  • Non richiede chiavi reali
  • Dovrebbe essere veloce e stabile
• Nota sui progetti:
  • pnpm test senza target ora esegue undici configurazioni shard più piccole (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) invece di un unico enorme processo nativo root-project. Questo riduce il picco di RSS su macchine cariche ed evita che il lavoro di auto-reply/extension penalizzi suite non correlate.
  • pnpm test --watch continua a usare il grafo di progetto nativo root vitest.config.ts, perché un loop watch multi-shard non è pratico.
  • pnpm test, pnpm test:watch e pnpm test:perf:imports instradano prima i target espliciti di file/directory attraverso lane con ambito, quindi pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts evita di pagare il costo completo di avvio del progetto root.
  • pnpm test:changed espande i percorsi git modificati negli stessi lane con ambito quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup ricadono comunque sulla riesecuzione ampia del progetto root.
  • I test unitari leggeri in termini di import provenienti da agent, comandi, plugin, helper auto-reply, plugin-sdk e aree simili di pura utilità vengono instradati attraverso il lane unit-fast, che salta test/setup-openclaw-runtime.ts; i file con stato/runtime pesante restano sui lane esistenti.
  • Alcuni file sorgente helper selezionati di plugin-sdk e commands mappano anche le esecuzioni in modalità changed verso test sibling espliciti in quei lane leggeri, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory.
  • auto-reply ora ha tre bucket dedicati: helper core di primo livello, test di integrazione reply.* di primo livello e il sottoalbero src/auto-reply/reply/**. Questo mantiene il lavoro più pesante dell’harness reply fuori dai test economici su status/chunk/token.
• Nota sul runner incorporato:
  • Quando modifichi gli input di rilevamento dei message-tool o il contesto runtime di Compaction, mantieni entrambi i livelli di copertura.
  • Aggiungi regressioni helper mirate per boundary puri di routing/normalizzazione.
  • Mantieni sane anche le suite di integrazione del runner incorporato: src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts e src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
  • Queste suite verificano che gli id con ambito e il comportamento di Compaction continuino a fluire attraverso i percorsi reali run.ts / compact.ts; i test solo helper non sono un sostituto sufficiente per questi percorsi di integrazione.
• Nota sul pool:
  • La configurazione base di Vitest ora usa threads come predefinito.
  • La configurazione Vitest condivisa fissa inoltre isolate: false e usa il runner non isolato nei progetti root, e2e e live.
  • Il lane UI root mantiene la propria configurazione jsdom e optimizer, ma ora viene eseguito anch’esso sul runner condiviso non isolato.
  • Ogni shard pnpm test eredita gli stessi valori predefiniti threads + isolate: false dalla configurazione Vitest condivisa.
  • Il launcher condiviso scripts/run-vitest.mjs ora aggiunge anche --no-maglev per impostazione predefinita ai processi Node figli di Vitest per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta OPENCLAW_VITEST_ENABLE_MAGLEV=1 se devi confrontare il comportamento V8 standard.
• Nota sull’iterazione locale veloce:
  • pnpm test:changed instrada attraverso lane con ambito quando i percorsi modificati mappano chiaramente a una suite più piccola.
  • pnpm test:max e pnpm test:changed:max mantengono lo stesso comportamento di instradamento, solo con un limite di worker più alto.
  • L’auto-scaling locale dei worker ora è intenzionalmente conservativo e riduce anche l’attività quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita.
  • La configurazione base Vitest contrassegna i file projects/config come forceRerunTriggers così le riesecuzioni in modalità changed restano corrette quando cambia il cablaggio dei test.
  • La configurazione mantiene OPENCLAW_VITEST_FS_MODULE_CACHE abilitato sugli host supportati; imposta OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path se desideri una posizione cache esplicita per il profiling diretto.
• Nota sul debug delle prestazioni:
  • pnpm test:perf:imports abilita la reportistica sulla durata degli import di Vitest più l’output di dettaglio degli import.
  • pnpm test:perf:imports:changed limita la stessa vista di profiling ai file modificati rispetto a origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> confronta test:changed instradato con il percorso nativo root-project per quel diff commitato e stampa wall time più macOS max RSS.
• pnpm test:perf:changed:bench -- --worktree esegue il benchmark dell’albero sporco corrente instradando l’elenco dei file modificati attraverso scripts/test-projects.mjs e la configurazione root Vitest.
  • pnpm test:perf:profile:main scrive un profilo CPU del thread principale per l’overhead di avvio e trasformazione di Vitest/Vite.
  • pnpm test:perf:profile:runner scrive profili CPU+heap del runner per la suite unit con parallelismo file disabilitato.

​

E2E (smoke del gateway)

• Comando: pnpm test:e2e
• Configurazione: vitest.e2e.config.ts
• File: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
• Valori predefiniti runtime:
  • Usa threads di Vitest con isolate: false, in linea con il resto del repository.
  • Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita).
  • Viene eseguito in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O sulla console.
• Override utili:
  • OPENCLAW_E2E_WORKERS=<n> per forzare il numero di worker (limitato a 16).
  • OPENCLAW_E2E_VERBOSE=1 per riattivare un output console dettagliato.
• Ambito:
  • Comportamento end-to-end del gateway multiistanza
  • Superfici WebSocket/HTTP, associazione Node e networking più pesante
• Aspettative:
  • Viene eseguito in CI (quando abilitato nella pipeline)
  • Non richiede chiavi reali
  • Ha più parti in movimento rispetto ai test unitari (può essere più lento)

​

E2E: smoke del backend OpenShell

• Comando: pnpm test:e2e:openshell
• File: test/openshell-sandbox.e2e.test.ts
• Ambito:
  • Avvia un gateway OpenShell isolato sull’host tramite Docker
  • Crea una sandbox da un Dockerfile locale temporaneo
  • Esercita il backend OpenShell di OpenClaw tramite sandbox ssh-config reale + esecuzione SSH
  • Verifica il comportamento del filesystem canonico remoto tramite il bridge fs della sandbox
• Aspettative:
  • Solo opt-in; non fa parte dell’esecuzione predefinita pnpm test:e2e
  • Richiede una CLI openshell locale più un demone Docker funzionante
  • Usa HOME / XDG_CONFIG_HOME isolati, quindi distrugge il gateway di test e la sandbox
• Override utili:
  • OPENCLAW_E2E_OPENSHELL=1 per abilitare il test quando si esegue manualmente la suite e2e più ampia
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell per puntare a un binario CLI non predefinito o a uno script wrapper

​

Live (provider reali + modelli reali)

• Comando: pnpm test:live
• Configurazione: vitest.live.config.ts
• File: src/**/*.live.test.ts
• Predefinito: abilitato da pnpm test:live (imposta OPENCLAW_LIVE_TEST=1)
• Ambito:
  • “Questo provider/modello funziona davvero oggi con credenziali reali?”
  • Intercetta cambiamenti di formato del provider, stranezze di tool-calling, problemi di auth e comportamento dei rate limit
• Aspettative:
  • Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage)
  • Costa denaro / usa rate limit
  • È preferibile eseguire sottoinsiemi ristretti invece di “tutto”
• Le esecuzioni live leggono ~/.profile per recuperare eventuali chiavi API mancanti.
• Per impostazione predefinita, le esecuzioni live continuano a isolare HOME e a copiare materiale config/auth in una home di test temporanea così i fixture unit non possono modificare il tuo ~/.openclaw reale.
• Imposta OPENCLAW_LIVE_USE_REAL_HOME=1 solo quando hai intenzionalmente bisogno che i test live usino la tua directory home reale.
• pnpm test:live ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento [live] ..., ma sopprime l’avviso extra su ~/.profile e silenzia i log di bootstrap del gateway / il chatter Bonjour. Imposta OPENCLAW_LIVE_TEST_QUIET=0 se vuoi ripristinare i log completi di avvio.
• Rotazione delle chiavi API (specifica per provider): imposta *_API_KEYS con formato separato da virgole/punto e virgola oppure *_API_KEY_1, *_API_KEY_2 (ad esempio OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) o override per-live tramite OPENCLAW_LIVE_*_KEY; i test ritentano in caso di risposte rate limit.
• Output di avanzamento/heartbeat:
  • Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa.
  • vitest.live.config.ts disabilita l’intercettazione console di Vitest così le righe di avanzamento provider/gateway vengono trasmesse immediatamente durante le esecuzioni live.
  • Regola gli heartbeat direct-model con OPENCLAW_LIVE_HEARTBEAT_MS.
  • Regola gli heartbeat gateway/probe con OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

​

Quale suite dovrei eseguire?

• Se modifichi logica/test: esegui pnpm test (e pnpm test:coverage se hai modificato molto)
• Se tocchi networking del gateway / protocollo WS / associazione: aggiungi pnpm test:e2e
• Se stai facendo debug di “il mio bot non funziona” / errori specifici del provider / tool calling: esegui un pnpm test:live ristretto

​

Live: sweep delle capacità del Node Android

• Test: src/gateway/android-node.capabilities.live.test.ts
• Script: pnpm android:test:integration
• Obiettivo: invocare ogni comando attualmente pubblicizzato da un Node Android connesso e verificare il comportamento del contratto del comando.
• Ambito:
  • Setup manuale/precondizionato (la suite non installa/esegue/associa l’app).
  • Validazione node.invoke del gateway comando per comando per il Node Android selezionato.
• Preconfigurazione richiesta:
  • App Android già connessa e associata al gateway.
  • App mantenuta in foreground.
  • Permessi/consenso alla cattura concessi per le capacità che prevedi debbano passare.
• Override target opzionali:
  • OPENCLAW_ANDROID_NODE_ID oppure OPENCLAW_ANDROID_NODE_NAME.
  • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
• Dettagli completi della configurazione Android: Android App

​

Live: smoke del modello (chiavi di profilo)

• “Direct model” ci dice se il provider/modello può rispondere in assoluto con la chiave data.
• “Gateway smoke” ci dice se l’intera pipeline gateway+agent funziona per quel modello (sessioni, cronologia, tool, policy sandbox, ecc.).

​

Livello 1: completamento direct model (senza gateway)

• Test: src/agents/models.profiles.live.test.ts
• Obiettivo:
  • Enumerare i modelli rilevati
  • Usare getApiKeyForModel per selezionare i modelli per cui hai credenziali
  • Eseguire un piccolo completamento per modello (e regressioni mirate dove necessario)
• Come abilitarlo:
  • pnpm test:live (oppure OPENCLAW_LIVE_TEST=1 se invochi Vitest direttamente)
• Imposta OPENCLAW_LIVE_MODELS=modern (oppure all, alias di modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere pnpm test:live focalizzato sullo smoke del gateway
• Come selezionare i modelli:
  • OPENCLAW_LIVE_MODELS=modern per eseguire l’allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_MODELS=all è un alias per l’allowlist modern
  • oppure OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (allowlist separata da virgole)
  • Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta OPENCLAW_LIVE_MAX_MODELS=0 per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo.
• Come selezionare i provider:
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (allowlist separata da virgole)
• Da dove provengono le chiavi:
  • Per impostazione predefinita: archivio profili e fallback env
  • Imposta OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per imporre solo l’archivio profili
• Perché esiste:
  • Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline gateway agent è rotta”
  • Contiene regressioni piccole e isolate (esempio: replay del reasoning di OpenAI Responses/Codex Responses + flussi di tool-call)

​

Livello 2: smoke di Gateway + agent di sviluppo (cosa fa davvero “@openclaw”)

• Test: src/gateway/gateway-models.profiles.live.test.ts
• Obiettivo:
  • Avviare un gateway in-process
  • Creare/modificare una sessione agent:dev:* (override del modello per esecuzione)
  • Iterare sui modelli con chiavi e verificare:
    • risposta “significativa” (senza tool)
    • che una vera invocazione di tool funzioni (probe di lettura)
    • probe tool extra opzionali (probe exec+read)
    • che i percorsi di regressione OpenAI (solo tool-call → follow-up) continuino a funzionare
• Dettagli delle probe (così puoi spiegare rapidamente i fallimenti):
  • probe read: il test scrive un file nonce nel workspace e chiede all’agent di read leggerlo e restituire il nonce.
  • probe exec+read: il test chiede all’agent di scrivere tramite exec un nonce in un file temporaneo, quindi di read leggerlo di nuovo.
  • probe immagine: il test allega un PNG generato (gatto + codice casuale) e si aspetta che il modello restituisca cat <CODE>.
  • Riferimento implementativo: src/gateway/gateway-models.profiles.live.test.ts e src/gateway/live-image-probe.ts.
• Come abilitarlo:
  • pnpm test:live (oppure OPENCLAW_LIVE_TEST=1 se invochi Vitest direttamente)
• Come selezionare i modelli:
  • Predefinito: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all è un alias per l’allowlist modern
  • Oppure imposta OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (o elenco separato da virgole) per restringere
  • Gli sweep gateway modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo.
• Come selezionare i provider (evita “tutto OpenRouter”):
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (allowlist separata da virgole)
• Le probe tool + immagine sono sempre attive in questo test live:
  • probe read + probe exec+read (stress dei tool)
  • la probe immagine viene eseguita quando il modello dichiara supporto per input immagine
  • Flusso (alto livello):
    • Il test genera un piccolo PNG con “CAT” + codice casuale (src/gateway/live-image-probe.ts)
    • Lo invia tramite agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • Gateway analizza gli allegati in images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • L’agent incorporato inoltra al modello un messaggio utente multimodale
    • Verifica: la risposta contiene cat + il codice (tolleranza OCR: piccoli errori consentiti)

openclaw models list
openclaw models list --json

​

Live: smoke del backend CLI (Claude, Codex, Gemini o altre CLI locali)

• Test: src/gateway/gateway-cli-backend.live.test.ts
• Obiettivo: convalidare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la configurazione predefinita.
• I valori predefiniti smoke specifici del backend si trovano nella definizione cli-backend.ts dell’extension proprietaria.
• Abilitazione:
  • pnpm test:live (oppure OPENCLAW_LIVE_TEST=1 se invochi Vitest direttamente)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Valori predefiniti:
  • Provider/modello predefinito: claude-cli/claude-sonnet-4-6
  • Il comportamento di command/args/image proviene dai metadati del plugin backend CLI proprietario.
• Override (opzionali):
  • 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 per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" per passare i percorsi dei file immagine come argomenti CLI invece che tramite iniezione nel prompt.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (oppure "list") per controllare come vengono passati gli argomenti immagine quando IMAGE_ARG è impostato.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 per inviare un secondo turno e convalidare il flusso di ripresa.
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0 per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (imposta 1 per forzarla quando il modello selezionato supporta un target di switch).

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

pnpm test:docker:live-cli-backend

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

• Il runner Docker si trova in scripts/test-live-cli-backend-docker.sh.
• Esegue lo smoke live del backend CLI dentro l’immagine Docker del repository come utente node non root.
• Risolve i metadati smoke CLI dall’extension proprietaria, quindi installa il pacchetto CLI Linux corrispondente (@anthropic-ai/claude-code, @openai/codex oppure @google/gemini-cli) in un prefisso scrivibile in cache in OPENCLAW_DOCKER_CLI_TOOLS_DIR (predefinito: ~/.cache/openclaw/docker-cli-tools).
• pnpm test:docker:live-cli-backend:claude-subscription richiede OAuth portabile della sottoscrizione Claude Code tramite ~/.claude/.credentials.json con claudeAiOauth.subscriptionType oppure CLAUDE_CODE_OAUTH_TOKEN da claude setup-token. Prima dimostra claude -p diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env della chiave API Anthropic. Questo lane di sottoscrizione disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude al momento instrada l’uso di app di terze parti tramite fatturazione di utilizzo extra invece che tramite i normali limiti del piano di sottoscrizione.
• Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno testuale, turno di classificazione immagine, quindi chiamata al tool MCP cron verificata tramite la CLI del gateway.
• Lo smoke predefinito di Claude modifica inoltre la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente.

​

Live: smoke del bind ACP (/acp spawn ... --bind here)

• Test: src/gateway/gateway-acp-bind.live.test.ts
• Obiettivo: convalidare il vero flusso di conversation-bind ACP con un agent ACP live:
  • inviare /acp spawn <agent> --bind here
  • associare in-place una conversazione sintetica del canale messaggi
  • inviare un normale follow-up sulla stessa conversazione
  • verificare che il follow-up finisca nel transcript della sessione ACP associata
• Abilitazione:
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Valori predefiniti:
  • Agent ACP in Docker: claude,codex,gemini
  • Agent ACP per pnpm test:live ... diretto: claude
  • Canale sintetico: contesto conversazione in stile DM Slack
  • Backend ACP: acpx
• Override:
  • 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>'
• Note:
  • Questo lane usa la superficie gateway chat.send con campi synthetic originating-route riservati agli admin così i test possono allegare il contesto del canale messaggi senza fingere una consegna esterna.
  • Quando OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND non è impostato, il test usa il registro agent integrato del plugin acpx incorporato per l’agent harness ACP selezionato.

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

pnpm test:docker:live-acp-bind

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

• Il runner Docker si trova in scripts/test-live-acp-bind-docker.sh.
• Per impostazione predefinita, esegue in sequenza lo smoke ACP bind contro tutti gli agent CLI live supportati: claude, codex, poi gemini.
• Usa OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex oppure OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini per restringere la matrice.
• Legge ~/.profile, prepara nel container il materiale di autenticazione CLI corrispondente, installa acpx in un prefisso npm scrivibile, quindi installa la CLI live richiesta (@anthropic-ai/claude-code, @openai/codex oppure @google/gemini-cli) se mancante.
• Dentro Docker, il runner imposta OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider provenienti dal profilo caricato.

​

Live: smoke dell’harness app-server Codex

• Obiettivo: convalidare l’harness Codex del plugin proprietario tramite il normale metodo gateway agent:
  • caricare il plugin codex incluso
  • selezionare OPENCLAW_AGENT_RUNTIME=codex
  • inviare un primo turno gateway agent a codex/gpt-5.4
  • inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread app-server possa riprendere
  • eseguire /codex status e /codex models tramite lo stesso percorso di comando del gateway
• Test: src/gateway/gateway-codex-harness.live.test.ts
• Abilitazione: OPENCLAW_LIVE_CODEX_HARNESS=1
• Modello predefinito: codex/gpt-5.4
• Probe immagine opzionale: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Probe MCP/tool opzionale: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• Lo smoke imposta OPENCLAW_AGENT_HARNESS_FALLBACK=none così un harness Codex rotto non può passare ricadendo silenziosamente su PI.
• Auth: OPENAI_API_KEY dalla shell/profilo, più eventuali ~/.codex/auth.json e ~/.codex/config.toml copiati

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

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

• Il runner Docker si trova in scripts/test-live-codex-harness-docker.sh.
• Legge il ~/.profile montato, passa OPENAI_API_KEY, copia i file di auth della CLI Codex quando presenti, installa @openai/codex in un prefisso npm montato e scrivibile, prepara l’albero dei sorgenti, quindi esegue solo il test live dell’harness Codex.
• Docker abilita per impostazione predefinita le probe immagine e MCP/tool. Imposta OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 oppure OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 quando ti serve un’esecuzione di debug più ristretta.
• Docker esporta anche OPENCLAW_AGENT_HARNESS_FALLBACK=none, in linea con la configurazione del test live così il fallback openai-codex/* o PI non può nascondere una regressione dell’harness Codex.

​

Ricette live consigliate

• Modello singolo, diretto (senza gateway):
  • OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts
• Modello singolo, smoke del gateway:
  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
• Tool calling su diversi provider:
  • 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
• Focus Google (chiave API Gemini + Antigravity):
  • Gemini (chiave API): 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

• google/... usa l’API Gemini (chiave API).
• google-antigravity/... usa il bridge OAuth Antigravity (endpoint agent in stile Cloud Code Assist).
• google-gemini-cli/... usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità degli strumenti).
• API Gemini vs CLI Gemini:
  • API: OpenClaw chiama l’API Gemini ospitata da Google via HTTP (auth con chiave API / profilo); è ciò che la maggior parte degli utenti intende con “Gemini”.
  • CLI: OpenClaw esegue una shell verso un binario gemini locale; ha una propria auth e può comportarsi in modo diverso (streaming/supporto tool/disallineamento di versione).

​

Live: matrice dei modelli (cosa copriamo)

​

Insieme smoke modern (tool calling + immagine)

• OpenAI (non-Codex): openai/gpt-5.4 (opzionale: openai/gpt-5.4-mini)
• OpenAI Codex: openai-codex/gpt-5.4
• Anthropic: anthropic/claude-opus-4-6 (oppure anthropic/claude-sonnet-4-6)
• Google (API Gemini): google/gemini-3.1-pro-preview e google/gemini-3-flash-preview (evita i vecchi modelli Gemini 2.x)
• Google (Antigravity): google-antigravity/claude-opus-4-6-thinking e google-antigravity/gemini-3-flash
• Z.AI (GLM): zai/glm-4.7
• MiniMax: minimax/MiniMax-M2.7

​

Baseline: tool calling (Read + Exec opzionale)

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

• xAI: xai/grok-4 (oppure l’ultima disponibile)
• Mistral: mistral/… (scegli un modello con capacità “tools” che hai abilitato)
• Cerebras: cerebras/… (se hai accesso)
• LM Studio: lmstudio/… (locale; il tool calling dipende dalla modalità API)

​

Vision: invio immagine (allegato → messaggio multimodale)

​

Aggregatori / gateway alternativi

• OpenRouter: openrouter/... (centinaia di modelli; usa openclaw models scan per trovare candidati con capacità tool+image)
• OpenCode: opencode/... per Zen e opencode-go/... per Go (auth tramite OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

• Integrati: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
• Tramite models.providers (endpoint personalizzati): minimax (cloud/API), più qualsiasi proxy compatibile OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.)

​

Credenziali (non fare mai commit)

• Se la CLI funziona, i test live dovrebbero trovare le stesse chiavi.
• Se un test live dice “nessuna credenziale”, esegui il debug come faresti con openclaw models list / selezione del modello.
• Profili auth per agent: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (questo è il significato di “profile keys” nei test live)
• Configurazione: ~/.openclaw/openclaw.json (oppure OPENCLAW_CONFIG_PATH)
• Directory di stato legacy: ~/.openclaw/credentials/ (copiata nella home live preparata quando presente, ma non è l’archivio principale delle chiavi profilo)
• Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file auth-profiles.json per agent, la directory legacy credentials/ e le directory di auth CLI esterne supportate in una home di test temporanea; le home live preparate saltano workspace/ e sandboxes/, e gli override di percorso agents.*.workspace / agentDir vengono rimossi così le probe restano fuori dal tuo workspace host reale.

​

Live Deepgram (trascrizione audio)

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

​

Live BytePlus coding plan

• Test: src/agents/byteplus.live.test.ts
• Abilitazione: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
• Override modello opzionale: BYTEPLUS_CODING_MODEL=ark-code-latest

​

Live media workflow ComfyUI

• Test: extensions/comfy/comfy.live.test.ts
• Abilitazione: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
• Ambito:
  • Esercita i percorsi inclusi di immagine, video e music_generate di comfy
  • Salta ogni capacità a meno che models.providers.comfy.<capability> non sia configurato
  • Utile dopo modifiche all’invio dei workflow comfy, al polling, ai download o alla registrazione del plugin

​

Live generazione immagini

• Test: src/image-generation/runtime.live.test.ts
• Comando: pnpm test:live src/image-generation/runtime.live.test.ts
• Harness: pnpm test:live:media image
• Ambito:
  • Enumera ogni plugin provider di generazione immagini registrato
  • Carica le variabili env dei provider mancanti dalla tua shell di login (~/.profile) prima dell’esecuzione delle probe
  • Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in auth-profiles.json non mascherano le vere credenziali della shell
  • Salta i provider senza auth/profilo/modello utilizzabile
  • Esegue le varianti standard di generazione immagini tramite la capacità runtime condivisa:
    • google:flash-generate
    • google:pro-generate
    • google:pro-edit
    • openai:default-generate
• Provider inclusi attualmente coperti:
  • openai
  • google
• Restrizione opzionale:
  • 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"
• Comportamento auth opzionale:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per imporre l’auth del profile store e ignorare gli override solo env

​

Live generazione musicale

• Test: extensions/music-generation-providers.live.test.ts
• Abilitazione: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
• Harness: pnpm test:live:media music
• Ambito:
  • Esercita il percorso condiviso incluso del provider di generazione musicale
  • Attualmente copre Google e MiniMax
  • Carica le variabili env dei provider dalla tua shell di login (~/.profile) prima dell’esecuzione delle probe
  • Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in auth-profiles.json non mascherano le vere credenziali della shell
  • Salta i provider senza auth/profilo/modello utilizzabile
  • Esegue entrambe le modalità runtime dichiarate quando disponibili:
    • generate con input solo prompt
    • edit quando il provider dichiara capabilities.edit.enabled
  • Copertura attuale del lane condiviso:
    • google: generate, edit
    • minimax: generate
    • comfy: file live Comfy separato, non questo sweep condiviso
• Restrizione opzionale:
  • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
  • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
• Comportamento auth opzionale:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per imporre l’auth del profile store e ignorare gli override solo env

​

Live generazione video

• Test: extensions/video-generation-providers.live.test.ts
• Abilitazione: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
• Harness: pnpm test:live:media video
• Ambito:
  • Esercita il percorso condiviso incluso del provider di generazione video
  • Usa per impostazione predefinita il percorso smoke sicuro per il rilascio: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un limite per operazione per provider da OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 per impostazione predefinita)
  • Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di rilascio; passa --video-providers fal oppure OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal" per eseguirlo esplicitamente
  • Carica le variabili env dei provider dalla tua shell di login (~/.profile) prima dell’esecuzione delle probe
  • Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in auth-profiles.json non mascherano le vere credenziali della shell
  • Salta i provider senza auth/profilo/modello utilizzabile
  • Esegue solo generate per impostazione predefinita
  • Imposta OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 per eseguire anche le modalità transform dichiarate quando disponibili:
    • imageToVideo quando il provider dichiara capabilities.imageToVideo.enabled e il provider/modello selezionato accetta input immagine locale con buffer-backed nello sweep condiviso
    • videoToVideo quando il provider dichiara capabilities.videoToVideo.enabled e il provider/modello selezionato accetta input video locale con buffer-backed nello sweep condiviso
  • Provider imageToVideo attualmente dichiarati ma saltati nello sweep condiviso:
    • vydra perché il veo3 incluso è solo testo e il kling incluso richiede un URL immagine remoto
  • Copertura Vydra specifica del provider:
    • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
    • quel file esegue veo3 text-to-video più un lane kling che usa per impostazione predefinita un fixture con URL immagine remoto
  • Copertura live videoToVideo attuale:
    • solo runway quando il modello selezionato è runway/gen4_aleph
  • Provider videoToVideo attualmente dichiarati ma saltati nello sweep condiviso:
    • alibaba, qwen, xai perché quei percorsi richiedono attualmente URL di riferimento remoti http(s) / MP4
    • google perché l’attuale lane Gemini/Veo condiviso usa input locale con buffer-backed e quel percorso non è accettato nello sweep condiviso
    • openai perché l’attuale lane condiviso non garantisce accesso specifico dell’organizzazione a video inpaint/remix
• Restrizione opzionale:
  • 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="" per includere ogni provider nello sweep predefinito, incluso FAL
  • OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000 per ridurre il limite di operazione di ciascun provider per un’esecuzione smoke aggressiva
• Comportamento auth opzionale:
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per imporre l’auth del profile store e ignorare gli override solo env

​

Harness live media

• Comando: pnpm test:live:media
• Scopo:
  • Esegue le suite live condivise di immagine, musica e video tramite un unico entrypoint nativo del repository
  • Carica automaticamente le variabili env dei provider mancanti da ~/.profile
  • Restringe automaticamente per impostazione predefinita ogni suite ai provider che attualmente hanno auth utilizzabile
  • Riutilizza scripts/test-live.mjs, così il comportamento heartbeat e quiet-mode resta coerente
• Esempi:
  • 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

​

Runner Docker (controlli opzionali “funziona su Linux”)

• Runner live-model: test:docker:live-models e test:docker:live-gateway eseguono solo il rispettivo file live con chiavi profilo all’interno dell’immagine Docker del repository (src/agents/models.profiles.live.test.ts e src/gateway/gateway-models.profiles.live.test.ts), montando la tua directory di configurazione locale e il workspace (e leggendo ~/.profile se montato). Gli entrypoint locali corrispondenti sono test:live:models-profiles e test:live:gateway-profiles.
• I runner live Docker usano per impostazione predefinita un limite smoke più piccolo così uno sweep Docker completo resta pratico: test:docker:live-models usa per impostazione predefinita OPENCLAW_LIVE_MAX_MODELS=12, e test:docker:live-gateway usa per impostazione predefinita OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 e OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Sostituisci quelle variabili env quando desideri esplicitamente la scansione esaustiva più ampia.
• test:docker:all costruisce una volta l’immagine Docker live tramite test:docker:live-build, poi la riutilizza per i due lane live Docker.
• Runner smoke del container: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels e test:docker:plugins avviano uno o più container reali e verificano percorsi di integrazione di livello superiore.

• Modelli diretti: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Smoke ACP bind: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh)
• Smoke backend CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Smoke harness app-server Codex: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
• Gateway + agent di sviluppo: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Smoke live Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Wizard di onboarding (TTY, scaffolding completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Networking del gateway (due container, auth WS + health): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Bridge canale MCP (Gateway inizializzato + bridge stdio + smoke raw Claude notification-frame): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Plugin (smoke di installazione + alias /plugin + semantica di riavvio del bundle Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Mantieni questo script per flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione dell’instradamento dei thread ACP, quindi non eliminarlo.

• OPENCLAW_CONFIG_DIR=... (predefinito: ~/.openclaw) montata in /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (predefinito: ~/.openclaw/workspace) montata in /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (predefinito: ~/.profile) montata in /home/node/.profile e caricata prima di eseguire i test
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 per verificare solo le variabili env caricate da OPENCLAW_PROFILE_FILE, usando directory config/workspace temporanee e nessun mount auth CLI esterno
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (predefinito: ~/.cache/openclaw/docker-cli-tools) montata in /home/node/.npm-global per installazioni CLI in cache dentro Docker
• Directory/file di auth CLI esterni sotto $HOME vengono montati in sola lettura sotto /host-auth..., poi copiati in /home/node/... prima dell’avvio dei test
  • Directory predefinite: .minimax
  • File predefiniti: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Le esecuzioni con provider ristretti montano solo directory/file necessari dedotti da OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Sostituisci manualmente con OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none o un elenco separato da virgole come OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... per restringere l’esecuzione
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... per filtrare i provider nel container
• OPENCLAW_SKIP_DOCKER_BUILD=1 per riutilizzare un’immagine openclaw:local-live esistente per riesecuzioni che non richiedono una ricostruzione
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per assicurare che le credenziali provengano dal profile store (non da env)
• OPENCLAW_OPENWEBUI_MODEL=... per scegliere il modello esposto dal gateway per lo smoke Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... per sostituire il prompt di controllo nonce usato dallo smoke Open WebUI
• OPENWEBUI_IMAGE=... per sostituire il tag immagine Open WebUI fissato

​

Integrità della documentazione

​

Regressione offline (sicura per CI)

• Tool calling del gateway (mock OpenAI, vero gateway + loop agent): src/gateway/gateway.test.ts (caso: “runs a mock OpenAI tool call end-to-end via gateway agent loop”)
• Wizard del gateway (WS wizard.start/wizard.next, scrittura di config + auth imposta): src/gateway/gateway.test.ts (caso: “runs wizard over ws and writes auth token config”)

​

Valutazioni di affidabilità degli agent (Skills)

• Mock tool-calling tramite il vero gateway + loop agent (src/gateway/gateway.test.ts).
• Flussi wizard end-to-end che convalidano il cablaggio della sessione e gli effetti della configurazione (src/gateway/gateway.test.ts).

• Decisioning: quando Skills sono elencate nel prompt, l’agent sceglie la Skill giusta (o evita quelle irrilevanti)?
• Compliance: l’agent legge SKILL.md prima dell’uso e segue i passaggi/gli argomenti richiesti?
• Workflow contracts: scenari multi-turno che verificano l’ordine degli strumenti, il riporto della cronologia della sessione e i confini della sandbox.

• Un runner di scenari che usa provider mock per verificare chiamate agli strumenti + ordine, letture dei file Skill e cablaggio della sessione.
• Una piccola suite di scenari focalizzati sulle Skill (usare vs evitare, gating, prompt injection).
• Valutazioni live opzionali (opt-in, controllate da env) solo dopo che la suite sicura per CI è pronta.

​

Test di contratto (forma di plugin e canale)

​

Comandi

• Tutti i contratti: pnpm test:contracts
• Solo contratti dei canali: pnpm test:contracts:channels
• Solo contratti dei provider: pnpm test:contracts:plugins

​

Contratti dei canali

• plugin - Forma base del plugin (id, nome, capacità)
• setup - Contratto del wizard di configurazione
• session-binding - Comportamento del binding della sessione
• outbound-payload - Struttura del payload del messaggio
• inbound - Gestione dei messaggi in ingresso
• actions - Handler delle azioni del canale
• threading - Gestione dell’ID del thread
• directory - API directory/roster
• group-policy - Applicazione delle policy di gruppo

​

Contratti di stato del provider

• status - Probe di stato del canale
• registry - Forma del registro dei plugin

​

Contratti dei provider

• auth - Contratto del flusso di auth
• auth-choice - Scelta/selezione dell’auth
• catalog - API del catalogo dei modelli
• discovery - Rilevamento dei plugin
• loader - Caricamento dei plugin
• runtime - Runtime del provider
• shape - Forma/interfaccia del plugin
• wizard - Wizard di configurazione

​

Quando eseguirli

• Dopo aver modificato export o sottopercorsi del plugin-sdk
• Dopo aver aggiunto o modificato un plugin canale o provider
• Dopo aver rifattorizzato la registrazione o il rilevamento dei plugin

​

Aggiungere regressioni (linee guida)

• Aggiungi una regressione sicura per CI se possibile (provider mock/stub, oppure cattura l’esatta trasformazione della forma della richiesta)
• Se è intrinsecamente solo live (rate limit, policy di auth), mantieni il test live ristretto e opt-in tramite variabili env
• Preferisci prendere di mira il livello più piccolo che intercetta il bug:
  • bug di conversione/replay della richiesta del provider → test direct models
  • bug della pipeline gateway session/history/tool → smoke live del gateway o test mock del gateway sicuro per CI
• Guardrail sull’attraversamento SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts deriva un target campione per classe SecretRef dai metadati del registro (listSecretTargetRegistryEntries()), quindi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati.
  • Se aggiungi una nuova famiglia di target SecretRef includeInPlan in src/secrets/target-registry-data.ts, aggiorna classifyTargetClass in quel test. Il test fallisce intenzionalmente sugli id target non classificati così le nuove classi non possono essere saltate in silenzio.