Test

OpenClaw dispone di tre suite Vitest (unità/integrazione, e2e, live), oltre a runner Docker. Questa pagina descrive cosa copre ogni suite, quale comando eseguire per un determinato flusso di lavoro, come i test live individuano le credenziali e come aggiungere test di regressione per bug reali di provider/modelli.

Avvio rapido

Nella maggior parte dei casi:

• Controllo completo (previsto prima del push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Esecuzione locale più rapida dell'intera suite su una macchina con risorse abbondanti: pnpm test:max
• Ciclo di osservazione diretto di Vitest: pnpm test:watch
• Anche l'indicazione diretta dei file instrada correttamente i percorsi di Plugin/canali: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Durante l'iterazione su un singolo errore, preferire inizialmente esecuzioni mirate.
• Sito QA basato su Docker: pnpm qa:lab:up
• Corsia QA basata su VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Quando si modificano i test o si desidera maggiore sicurezza:

• Rapporto informativo sulla copertura V8: pnpm test:coverage
• Suite E2E: pnpm test:e2e

Directory temporanee dei test

Utilizzare gli helper condivisi in test/helpers/temp-dir.ts per le directory temporanee di proprietà dei test, in modo che la proprietà sia esplicita e la pulizia rimanga nel ciclo di vita del test:

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

useAutoCleanupTempDirTracker(afterEach) non espone intenzionalmente alcun metodo di pulizia manuale: Vitest gestisce la pulizia dopo ogni test. Gli helper meno astratti e precedenti (makeTempDir, cleanupTempDirs, createTempDirTracker) esistono ancora per i test non ancora migrati; evitare di usarli nel nuovo codice ed evitare nuove chiamate dirette a fs.mkdtemp*, a meno che un test non verifichi esplicitamente il comportamento grezzo delle directory temporanee. Quando una directory temporanea diretta è realmente necessaria, aggiungere un commento di autorizzazione verificabile che ne spieghi il motivo:

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

node scripts/report-test-temp-creations.mjs segnala la nuova creazione diretta di directory temporanee e il nuovo utilizzo manuale degli helper condivisi nelle righe aggiunte dalla differenza, senza bloccare gli stili di pulizia esistenti. Segue la stessa classificazione dei percorsi di test di scripts/changed-lanes.mjs e ignora l'implementazione dell'helper condiviso. check:changed esegue questo rapporto per i percorsi di test modificati come segnale CI costituito esclusivamente da avvisi (annotazioni di avviso di GitHub, non errori).

Flussi di lavoro live e Docker/Parallels

Durante il debug di provider/modelli reali (richiede credenziali reali):

• Suite live (modelli e verifiche di strumenti/immagini del Gateway): pnpm test:live
• Esecuzione silenziosa di un singolo file live: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Rapporti sulle prestazioni di runtime: avviare OpenClaw Performance con live_openai_candidate=true per un turno reale dell'agente openai/gpt-5.6-luna oppure deep_profile=true per gli artefatti CPU/heap/traccia di Kova. Le esecuzioni giornaliere pianificate pubblicano i rapporti delle corsie con provider simulato, profilazione approfondita e GPT-5.6 Luna in openclaw/clawgrit-reports tramite un processo di pubblicazione separato che utilizza gli artefatti; un'autenticazione del processo di pubblicazione mancante o non valida causa il fallimento delle esecuzioni pianificate e di quelle con profile=release. Le esecuzioni manuali non di rilascio conservano gli artefatti GitHub e considerano la pubblicazione del rapporto come facoltativa. Il rapporto del provider simulato include inoltre dati numerici relativi all'avvio del Gateway a livello di sorgente, alla memoria, alla pressione dei Plugin, al ciclo ripetuto di saluto del modello simulato e all'avvio della CLI.
• Analisi live dei modelli in Docker: pnpm test:docker:live-models
  • Ogni modello selezionato esegue un turno testuale e una piccola verifica simile alla lettura di un file. I modelli i cui metadati dichiarano input image eseguono anche un piccolo turno con immagine. Disabilitare le verifiche aggiuntive con OPENCLAW_LIVE_MODEL_FILE_PROBE=0 o OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 quando si isolano errori dei provider.
  • Copertura CI: sia l'esecuzione giornaliera OpenClaw Scheduled Live And E2E Checks sia quella manuale OpenClaw Release Checks richiamano il flusso di lavoro live/E2E riutilizzabile con include_live_suites: true, che include i processi della matrice di modelli live Docker suddivisi per provider.
  • Per riesecuzioni CI mirate, avviare OpenClaw Live And E2E Checks (Reusable) con include_live_suites: true e live_models_only: true.
  • Aggiungere i nuovi segreti dei provider ad alto valore informativo a scripts/ci-hydrate-live-auth.sh, a .github/workflows/openclaw-live-and-e2e-checks-reusable.yml e ai relativi chiamanti pianificati/di rilascio.
• Test rapido della chat associata nativa di Codex: pnpm test:docker:live-codex-bind
  • Esegue una corsia live Docker tramite il percorso app-server di Codex, associa un messaggio diretto Slack sintetico con /codex bind, esercita /codex fast e /codex permissions, quindi verifica che una risposta semplice e un allegato immagine siano instradati tramite l'associazione nativa del Plugin anziché tramite ACP.
• Test rapido dell'harness app-server di Codex: pnpm test:docker:live-codex-harness
  • Esegue turni dell'agente del Gateway tramite l'harness app-server di Codex di proprietà del Plugin, verifica /codex status e /codex models e, per impostazione predefinita, esercita verifiche di immagini, MCP Cron, sottoagenti e Guardian. Disabilitare la verifica dei sottoagenti con OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 quando si isolano altri errori. Per un controllo mirato dei sottoagenti, disabilitare le altre verifiche: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. L'esecuzione termina dopo la verifica dei sottoagenti, a meno che OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 non sia impostato.
• Test rapido dell'installazione su richiesta di Codex: pnpm test:docker:codex-on-demand
  • Installa in Docker il tarball pacchettizzato di OpenClaw, esegue la configurazione iniziale con chiave API OpenAI e verifica che il Plugin Codex e la dipendenza @openai/codex siano stati scaricati su richiesta nella radice gestita del progetto npm.
• Test rapido live delle dipendenze degli strumenti dei Plugin: pnpm test:docker:live-plugin-tool
  • Pacchettizza un Plugin fixture con una dipendenza reale da slugify, lo installa tramite npm-pack:, verifica la dipendenza nella radice gestita del progetto npm, quindi chiede a un modello OpenAI live di chiamare lo strumento del Plugin e restituire lo slug nascosto.
• Test rapido del comando di recupero di Crestodian: pnpm test:live:crestodian-rescue-channel
  • Controllo facoltativo e ridondante per la superficie dei comandi di recupero del canale di messaggistica. Esercita /crestodian status, accoda una modifica persistente del modello, risponde /crestodian yes e verifica il percorso di scrittura di controllo/configurazione.
• Test rapido Docker della prima esecuzione di Crestodian: pnpm test:docker:crestodian-first-run
  • Parte da una directory di stato OpenClaw vuota e dimostra innanzitutto che la CLI pacchettizzata openclaw crestodian termina in sicurezza senza inferenza. Successivamente verifica e attiva un Claude simulato tramite il modulo di attivazione pacchettizzato. Solo in seguito una richiesta approssimativa alla CLI pacchettizzata raggiunge il pianificatore e viene risolta in una configurazione tipizzata, seguita da operazioni singole su modello, agente, Plugin Discord e SecretRef. Convalida le voci di configurazione e controllo. Questa costituisce un'evidenza di supporto per controlli/operazioni, non una prova della configurazione iniziale interattiva o dell'agente/strumento/approvazione di Crestodian. La stessa corsia è disponibile in QA Lab tramite pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Test rapido dei costi Moonshot/Kimi: con MOONSHOT_API_KEY impostata, eseguire openclaw models list --provider moonshot --json, quindi eseguire un comando isolato openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json con moonshot/kimi-k2.6. Verificare che il JSON riporti Moonshot/K2.6 e che la trascrizione dell'assistente memorizzi il valore normalizzato usage.cost.

Runner specifici per la QA

Questi comandi affiancano le suite di test principali quando è necessario il realismo di QA Lab.

La CI esegue QA Lab in flussi di lavoro dedicati. La parità agentica è inclusa in QA-Lab - All Lanes e nella convalida del rilascio, non in un flusso di lavoro PR autonomo. Per una convalida ampia si deve utilizzare Full Release Validation con rerun_group=qa-parity oppure il gruppo QA dei controlli di rilascio. I controlli di rilascio stabili/predefiniti mantengono la verifica prolungata live/Docker completa dietro run_release_soak=true; il profilo full forza l'attivazione della verifica prolungata. QA-Lab - All Lanes viene eseguito ogni notte su main e tramite avvio manuale, con la corsia di parità simulata, la corsia Matrix live, la corsia Telegram live gestita da Convex e la corsia Discord live gestita da Convex come processi paralleli. La QA pianificata e i controlli di rilascio passano esplicitamente --profile fast a Matrix, mentre il valore predefinito della CLI Matrix e dell'input del flusso di lavoro manuale rimane all; l'avvio manuale può suddividere all nei processi transport, media, e2ee-smoke, e2ee-deep e e2ee-cli. OpenClaw Release Checks esegue la parità insieme alle corsie rapide Matrix e Telegram prima dell'approvazione del rilascio, utilizzando mock-openai/gpt-5.6-luna per i controlli del trasporto di rilascio, in modo che rimangano deterministici ed evitino il normale avvio dei Plugin dei provider. Questi Gateway di trasporto live disabilitano la ricerca in memoria; il comportamento della memoria rimane coperto dalle suite di parità QA.

Le suddivisioni multimediali live del rilascio completo utilizzano ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, che include già ffmpeg e ffprobe. Le suddivisioni live Docker per modelli/backend utilizzano l'immagine condivisa ghcr.io/openclaw/openclaw-live-test:<sha>, creata una sola volta per ogni commit selezionato e successivamente scaricata con OPENCLAW_SKIP_DOCKER_BUILD=1, anziché essere ricreata all'interno di ogni suddivisione.

• pnpm openclaw qa suite
  • Esegue direttamente sull'host gli scenari di QA supportati dal repository.
  • Scrive gli artefatti di primo livello qa-evidence.json, qa-suite-summary.json e qa-suite-report.md per l'insieme di scenari selezionato, incluse le selezioni di scenari con flussi misti, Vitest e Playwright.
  • Quando viene avviato da pnpm openclaw qa run --qa-profile <profile>, incorpora la scheda di valutazione del profilo tassonomico selezionato nello stesso qa-evidence.json. smoke-ci scrive evidenze ridotte (evidenceMode: "slim", senza execution per singola voce). release copre la selezione curata per verificare la preparazione al rilascio; all seleziona ogni categoria di maturità attiva ed è destinato agli avvii espliciti del workflow QA Profile Evidence quando è necessario un artefatto completo della scheda di valutazione.
  • Per impostazione predefinita, esegue in parallelo più scenari selezionati 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 precedente percorso seriale.
  • Termina con un codice diverso da zero se uno scenario non riesce. Usa --allow-failures per generare gli artefatti senza un codice di uscita di errore.
  • Supporta le modalità del provider live-frontier, mock-openai e aimock. aimock avvia un server provider locale basato su AIMock per la copertura sperimentale di fixture e mock del protocollo, senza sostituire il percorso mock-openai consapevole degli scenari.
• pnpm openclaw qa coverage --match <query>
  • Cerca negli ID degli scenari, nei titoli, nelle superfici, negli ID di copertura, nei riferimenti alla documentazione, nei riferimenti al codice, nei plugin e nei requisiti dei provider, quindi stampa gli obiettivi della suite corrispondenti.
  • Usalo prima di un'esecuzione di QA Lab quando conosci il comportamento interessato o il percorso del file, ma non lo scenario più piccolo. È solo indicativo: scegli comunque tra mock, live, Multipass, Matrix o una prova del trasporto in base al comportamento che viene modificato.
• pnpm test:plugins:kitchen-sink-live
  • Esegue tramite QA Lab la serie completa di prove live OpenAI del plugin Kitchen Sink. Installa il pacchetto esterno Kitchen Sink, verifica l'inventario delle superfici dell'SDK del plugin, controlla /healthz e /readyz, registra le evidenze relative a CPU/RSS del Gateway, esegue un turno OpenAI live e verifica la diagnostica avversariale. Richiede un'autenticazione OpenAI live, ad esempio OPENAI_API_KEY. Nelle sessioni Testbox predisposte carica automaticamente il profilo di autenticazione live di Testbox quando è presente l'helper openclaw-testbox-env.
• pnpm test:gateway:cpu-scenarios
  • Esegue il benchmark di avvio del Gateway insieme a un piccolo gruppo di scenari QA Lab simulati (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) e scrive un riepilogo combinato delle osservazioni sulla CPU in .artifacts/gateway-cpu-scenarios/.
  • Per impostazione predefinita segnala solo osservazioni prolungate di CPU elevata (--cpu-core-warn, valore predefinito 0.9; --hot-wall-warn-ms, valore predefinito 30000), così i brevi picchi di avvio vengono registrati come metriche senza sembrare la regressione che mantiene il Gateway al massimo per diversi minuti.
  • Viene eseguito sugli artefatti dist compilati; esegui prima una compilazione quando il checkout non contiene già output di runtime aggiornato.
• pnpm openclaw qa suite --runner multipass
  • Esegue la stessa suite di QA all'interno di una VM Linux Multipass usa e getta, mantenendo gli stessi flag di selezione degli scenari e del provider/modello di qa suite.
  • Le esecuzioni live inoltrano gli input di autenticazione QA utilizzabili dal guest: le chiavi dei provider basate su variabili di ambiente, il percorso della configurazione del provider QA live e CODEX_HOME, quando presente.
  • Le directory di output devono rimanere sotto la radice del repository, in modo che il guest possa riscrivere tramite lo spazio di lavoro montato.
  • Scrive il normale rapporto e riepilogo QA, oltre ai log di Multipass in .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Avvia il sito QA basato su Docker per attività di QA in stile operatore.
• pnpm test:docker:npm-onboard-channel-agent
  • Crea un tarball npm dal checkout corrente, lo installa globalmente in Docker, esegue l'onboarding non interattivo con chiave API OpenAI, configura Telegram per impostazione predefinita, verifica che il runtime del plugin incluso nel pacchetto venga caricato senza riparazione delle dipendenze all'avvio, esegue doctor ed esegue un turno dell'agente locale usando un endpoint OpenAI simulato.
  • Usa OPENCLAW_NPM_ONBOARD_CHANNEL=discord per eseguire lo stesso percorso di installazione del pacchetto con Discord.
• pnpm test:docker:session-runtime-context
  • Esegue uno smoke test Docker deterministico dell'applicazione compilata per le trascrizioni del contesto di runtime incorporato. Verifica che il contesto di runtime nascosto di OpenClaw persista come messaggio personalizzato non visualizzato, invece di trapelare nel turno visibile dell'utente; quindi prepara un JSONL di sessione danneggiato interessato e verifica che openclaw doctor --fix lo riscriva nel ramo attivo creando un backup.
• pnpm test:docker:npm-telegram-live
  • Installa in Docker un pacchetto OpenClaw candidato, esegue l'onboarding del pacchetto installato, configura Telegram tramite la CLI installata, quindi riutilizza il percorso QA live di Telegram usando il pacchetto installato come Gateway del sistema in prova.
  • Il wrapper monta dal checkout solo il sorgente dell'ambiente di test qa-lab; il pacchetto installato gestisce dist, openclaw/plugin-sdk e il runtime dei plugin inclusi, quindi il percorso non combina i plugin del checkout corrente con il pacchetto sottoposto a test.
  • Il valore predefinito è OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; imposta OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz oppure OPENCLAW_CURRENT_PACKAGE_TGZ per testare invece un tarball locale risolto, senza installarlo dal registro.
  • Per impostazione predefinita emette misurazioni ripetute dell'RTT in qa-evidence.json con OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20. Sovrascrivi OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES, OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS oppure OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES per regolare l'esecuzione. OPENCLAW_NPM_TELEGRAM_RTT_CHECKS accetta un elenco separato da virgole di ID dei controlli QA di Telegram da campionare; se non è impostato, il controllo predefinito compatibile con RTT è telegram-mentioned-message-reply.
  • Usa le stesse credenziali Telegram nelle variabili di ambiente o la stessa origine delle credenziali Convex di pnpm openclaw qa telegram. Per l'automazione CI/di rilascio, imposta OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex insieme a OPENCLAW_QA_CONVEX_SITE_URL e a un segreto di ruolo. Se OPENCLAW_QA_CONVEX_SITE_URL e un segreto di ruolo Convex sono presenti nella CI, il wrapper Docker seleziona automaticamente Convex.
  • Il wrapper convalida sull'host le variabili di ambiente delle credenziali Telegram o Convex prima delle operazioni di compilazione/installazione Docker. Imposta OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 solo quando esegui intenzionalmente il debug della configurazione precedente alle credenziali.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer sostituisce l'impostazione condivisa OPENCLAW_QA_CREDENTIAL_ROLE solo per questo percorso. Quando vengono selezionate credenziali Convex e non è impostato alcun ruolo, il wrapper usa ci nella CI e maintainer al di fuori della CI.
  • GitHub Actions espone questo percorso come workflow manuale per i manutentori NPM Telegram Beta E2E. Non viene eseguito al merge. Il workflow usa l'ambiente qa-live-shared e i lease delle credenziali CI di Convex.
• GitHub Actions espone inoltre Package Acceptance per la prova collaterale del prodotto su un singolo pacchetto candidato. Accetta un riferimento Git, una specifica npm pubblicata, un URL HTTPS di tarball con SHA-256, una policy per URL attendibili oppure un artefatto tarball di un'altra esecuzione (source=ref|npm|url|trusted-url|artifact), carica il file normalizzato openclaw-current.tgz come package-under-test, quindi esegue lo scheduler Docker E2E esistente con i profili di percorso smoke, package, product, full o custom. Imposta telegram_mode=mock-openai oppure live-frontier per eseguire il workflow QA di Telegram sullo stesso artefatto package-under-test.
  • Prova del prodotto con l'ultima beta:

gh workflow run package-acceptance.yml --ref main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=product \  -f telegram_mode=mock-openai

• La prova con un URL esatto del tarball richiede un digest e usa la policy di sicurezza per gli URL pubblici:

gh workflow run package-acceptance.yml --ref main \  -f source=url \  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

• I mirror di tarball aziendali/privati usano una policy esplicita per le origini attendibili:

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

source=trusted-url legge .github/package-trusted-sources.json dal riferimento attendibile del workflow e non accetta credenziali nell'URL né un bypass della rete privata fornito come input del workflow. Se la policy indicata dichiara l'autenticazione bearer, configura il segreto fisso OPENCLAW_TRUSTED_PACKAGE_TOKEN.

• La prova tramite artefatto scarica un artefatto tarball da un'altra esecuzione di Actions:

gh workflow run package-acceptance.yml --ref main \  -f source=artifact \  -f artifact_run_id=<run-id> \  -f artifact_name=<artifact-name> \  -f suite_profile=smoke

• pnpm test:docker:plugins

  • Crea il pacchetto della build OpenClaw corrente e lo installa in Docker, avvia il Gateway con OpenAI configurato, quindi abilita i canali/plugin inclusi tramite modifiche alla configurazione.
  • Verifica che il rilevamento durante la configurazione lasci assenti i plugin scaricabili non configurati, che la prima riparazione configurata di doctor installi esplicitamente ogni plugin scaricabile mancante e che un secondo riavvio non esegua riparazioni nascoste delle dipendenze.
  • Installa inoltre una versione di riferimento npm precedente nota, abilita Telegram prima di eseguire openclaw update --tag <candidate> e verifica che il doctor successivo all'aggiornamento del candidato rimuova i residui delle dipendenze dei plugin precedenti senza una riparazione postinstallazione da parte dell'ambiente di test.

• pnpm test:parallels:npm-update

  • Esegue lo smoke test nativo di aggiornamento dell'installazione del pacchetto nei guest Parallels. Ogni piattaforma selezionata installa prima il pacchetto di riferimento richiesto, quindi esegue il comando openclaw update installato nello stesso guest e verifica la versione installata, lo stato dell'aggiornamento, la disponibilità del Gateway e un turno dell'agente locale.

  • Usa --platform macos, --platform windows oppure --platform linux durante l'iterazione su un singolo guest. Usa --json per il percorso dell'artefatto di riepilogo e lo stato di ogni percorso.

  • Il percorso OpenAI usa per impostazione predefinita openai/gpt-5.6-luna per la prova live del turno dell'agente. Passa --model <provider/model> oppure imposta OPENCLAW_PARALLELS_OPENAI_MODEL per convalidare un altro modello OpenAI.

  • Racchiudi le esecuzioni locali lunghe in un timeout dell'host, affinché i blocchi del trasporto Parallels non consumino il resto della finestra di test:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --jsontimeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json

  • Lo script scrive log annidati dei percorsi in /tmp/openclaw-parallels-npm-update.*. Esamina windows-update.log, macos-update.log oppure linux-update.log prima di presumere che il wrapper esterno sia bloccato.

  • Su un guest non predisposto, l'aggiornamento di Windows può impiegare da 10 a 15 minuti nelle operazioni di doctor successive all'aggiornamento e di aggiornamento del pacchetto; il comportamento è comunque normale se il log di debug npm annidato continua ad avanzare.

  • Non eseguire questo wrapper aggregato in parallelo con i singoli percorsi smoke Parallels per macOS, Windows o Linux. Condividono lo stato della VM e possono entrare in conflitto durante il ripristino degli snapshot, la distribuzione dei pacchetti o la gestione dello stato del Gateway del guest.

  • La prova successiva all'aggiornamento esegue la normale superficie dei plugin inclusi, perché le facciate delle funzionalità, come sintesi vocale, generazione di immagini e comprensione dei contenuti multimediali, vengono caricate tramite le API di runtime incluse anche quando il turno dell'agente verifica soltanto una semplice risposta testuale.

• pnpm openclaw qa aimock

  • Avvia solo il server del provider AIMock locale per test smoke diretti del protocollo.

• pnpm openclaw qa matrix

  • Esegue il percorso QA live di Matrix su un homeserver Tuwunel temporaneo basato su Docker. Disponibile solo dal checkout dei sorgenti: le installazioni pacchettizzate non includono qa-lab.
  • CLI completa, catalogo di profili/scenari, variabili d'ambiente e struttura degli artefatti: QA di Matrix.

• pnpm openclaw qa telegram

  • Esegue il percorso QA live di Telegram su un gruppo privato reale usando i token del bot driver e del bot SUT forniti tramite l'ambiente.
  • 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 per impostazione predefinita la modalità basata sull'ambiente, oppure imposta OPENCLAW_QA_CREDENTIAL_SOURCE=convex per usare i lease del pool.
  • Le impostazioni predefinite coprono canary, controllo delle menzioni, indirizzamento dei comandi, /status, risposte menzionate da bot a bot e risposte ai comandi nativi principali. Le impostazioni predefinite di mock-openai coprono anche le regressioni deterministiche delle catene di risposta e dello streaming del messaggio finale di Telegram. Usa --list-scenarios per sonde facoltative come session_status.
  • Termina con un codice diverso da zero quando uno scenario non riesce. Usa --allow-failures per generare gli artefatti 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 da bot a 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 rapporto QA di Telegram, un riepilogo e qa-evidence.json in .artifacts/qa-e2e/.... Gli scenari con risposta includono l'RTT dalla richiesta di invio del driver alla risposta SUT osservata.

Mantis Telegram Live è il wrapper per le prove nelle PR relativo a questo percorso. Esegue il riferimento candidato con credenziali Telegram ottenute tramite lease da Convex, visualizza il pacchetto oscurato di rapporto/prove QA in un browser desktop Crabbox, registra una prova MP4, genera una GIF ritagliata in base al movimento, carica il pacchetto di artefatti e pubblica le prove direttamente nella PR tramite Mantis GitHub App quando è impostato pr_number. I manutentori possono avviarlo dall'interfaccia di Actions tramite Mantis Scenario (scenario_id: telegram-live) o direttamente da un commento in una pull request:

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

Mantis Telegram Desktop Proof è il wrapper agentico nativo di Telegram Desktop per le prove visive prima/dopo nelle PR. Avvialo dall'interfaccia di Actions con instructions in formato libero, tramite Mantis Scenario (scenario_id: telegram-desktop-proof) o da un commento in una PR:

@openclaw-mantis telegram desktop proof

L'agente Mantis legge la PR, decide quale comportamento visibile in Telegram dimostra la modifica, esegue il percorso di prova Crabbox con Telegram Desktop come utente reale sui riferimenti di base e candidato, ripete il processo finché le GIF native non risultano utili, scrive un manifesto motionPreview abbinato e pubblica la stessa tabella GIF a 2 colonne tramite Mantis GitHub App quando è impostato pr_number.

• pnpm openclaw qa mantis telegram-desktop-builder
  • Ottiene tramite lease o riutilizza un desktop Linux Crabbox, installa Telegram Desktop nativo, configura OpenClaw con un token del bot SUT Telegram ottenuto tramite lease, avvia il Gateway e registra prove in formato screenshot/MP4 dal desktop VNC visibile.
  • Usa per impostazione predefinita --credential-source convex, così i flussi di lavoro richiedono solo il segreto del broker Convex. Usa --credential-source env con le stesse variabili OPENCLAW_QA_TELEGRAM_* di pnpm openclaw qa telegram.
  • Telegram Desktop richiede comunque un accesso/profilo utente. Il token del bot configura solo OpenClaw. Usa --telegram-profile-archive-env <name> per un archivio del profilo .tgz in base64, oppure usa --keep-lease ed esegui una volta l'accesso manuale tramite VNC.
  • Scrive mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png e telegram-desktop-builder.mp4 nella directory di output.

I percorsi di trasporto live condividono un unico contratto standard, così i nuovi trasporti non divergono; la matrice di copertura per ciascun percorso si trova in Panoramica QA - Copertura dei trasporti live. qa-channel è l'ampia suite sintetica e non fa parte di tale matrice.

Credenziali Telegram condivise tramite Convex (v1)

Quando --credential-source convex (o OPENCLAW_QA_CREDENTIAL_SOURCE=convex) è abilitato per la QA dei trasporti live, il laboratorio QA acquisisce un lease esclusivo da un pool basato su Convex, invia Heartbeat per tale lease mentre il percorso è in esecuzione e rilascia il lease all'arresto. Il nome della sezione è precedente al supporto di Discord, Slack e WhatsApp; il contratto di lease è condiviso tra i diversi tipi.

Scaffold di riferimento del progetto Convex: qa/convex-credential-broker/

Variabili d'ambiente obbligatorie:

• OPENCLAW_QA_CONVEX_SITE_URL (ad esempio https://your-deployment.convex.site)
• Un segreto 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 dall'ambiente: OPENCLAW_QA_CREDENTIAL_ROLE (il valore predefinito è ci in CI, altrimenti maintainer)

Variabili d'ambiente facoltative:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (valore predefinito 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (valore predefinito 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (valore predefinito 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (valore predefinito 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (valore predefinito /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (ID di tracciamento facoltativo)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 consente URL Convex http:// su local loopback esclusivamente per lo sviluppo locale.

Durante il normale funzionamento, OPENCLAW_QA_CONVEX_SITE_URL deve usare https://.

I comandi amministrativi dei manutentori (aggiunta/rimozione/elenco del pool) richiedono specificamente OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

Helper CLI per i manutentori:

pnpm openclaw qa credentials doctorpnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.jsonpnpm openclaw qa credentials list --kind telegrampnpm openclaw qa credentials remove --credential-id <credential-id>

Usa doctor prima delle esecuzioni live per verificare l'URL del sito Convex, i segreti del broker, il prefisso dell'endpoint, il timeout HTTP e la raggiungibilità delle operazioni amministrative/di elenco senza stampare i valori dei segreti. Usa --json per un output leggibile dalle macchine negli script e nelle utilità CI.

Contratto predefinito dell'endpoint (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1). Le richieste eseguono l'autenticazione con un'intestazione Authorization: Bearer <role secret>; i corpi riportati di seguito omettono tale intestazione:

• POST /acquire
  • Richiesta: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Esito positivo: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Pool esaurito/operazione ripetibile: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Richiesta: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Esito positivo: { status: "ok", index, data }
• POST /heartbeat
  • Richiesta: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Esito positivo: { status: "ok" } (o 2xx vuoto)
• POST /release
  • Richiesta: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Esito positivo: { status: "ok" } (o 2xx vuoto)
• POST /admin/add (solo segreto del manutentore)
  • Richiesta: { kind, actorId, payload, note?, status? }
  • Esito positivo: { status: "ok", credential }
• POST /admin/remove (solo segreto del manutentore)
  • Richiesta: { credentialId, actorId }
  • Esito positivo: { status: "ok", changed, credential }
  • Protezione del lease attivo: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (solo segreto del manutentore)
  • Richiesta: { kind?, status?, includePayload?, limit? }
  • Esito positivo: { status: "ok", credentials, count }

Struttura del payload per il tipo Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId deve essere una stringa contenente un ID numerico di chat Telegram.
• admin/add convalida questa struttura per kind: "telegram" e rifiuta i payload non validi.

Struttura del payload per il tipo Telegram con utente reale:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId e telegramApiId devono essere stringhe numeriche.
• tdlibArchiveSha256 e desktopTdataArchiveSha256 devono essere stringhe esadecimali SHA-256.
• kind: "telegram-user" è riservato al flusso di lavoro delle prove con Telegram Desktop di Mantis. I percorsi generici del laboratorio QA non devono acquisirlo.

Payload multicanale convalidati dal broker:

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

Anche i percorsi Slack possono ottenere lease dal pool, ma la convalida dei payload Slack risiede attualmente nell'esecutore QA di Slack anziché nel broker. Usa { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string } per le righe Slack.

Aggiunta di un canale alla QA

L'architettura e i nomi degli helper degli scenari per i nuovi adattatori di canale si trovano in Panoramica QA - Aggiunta di un canale. I requisiti minimi sono: implementare l'esecutore del trasporto sull'interfaccia host condivisa qa-lab, aggiungere un adapterFactory per gli scenari condivisi, dichiarare qaRunners nel manifesto del Plugin, montarlo come openclaw qa <runner> e creare gli scenari in qa/scenarios/.

Suite di test (cosa viene eseguito e dove)

Considera le suite come livelli di «realismo crescente» (e anche di instabilità e costo crescenti).

Test unitari / di integrazione (impostazione predefinita)

• Comando: pnpm test
• Configurazione: le esecuzioni senza destinazione specifica usano il set di shard vitest.full-*.config.ts e possono espandere gli shard multiprogetto in configurazioni per singolo progetto per la pianificazione parallela
• File: inventari di test principali/unitari in src/**/*.test.ts, packages/**/*.test.ts e test/**/*.test.ts; i test unitari dell'interfaccia utente vengono eseguiti nello shard dedicato unit-ui
• Ambito:
  • Test unitari puri
  • Test di integrazione nello stesso processo (autenticazione del Gateway, instradamento, strumenti, analisi sintattica, configurazione)
  • Regressioni deterministiche per bug noti
• Aspettative:
  • Esecuzione in CI
  • Nessuna chiave reale richiesta
  • Devono essere rapidi e stabili
  • I test del resolver e del caricatore delle superfici pubbliche devono dimostrare il comportamento generale di fallback di api.js e runtime-api.js con piccole fixture di Plugin generate, non con le API dei sorgenti dei Plugin integrati reali. I caricamenti delle API di Plugin reali appartengono alle suite di contratto/integrazione gestite dai rispettivi Plugin.

Criteri per le dipendenze native:

• Le installazioni di test predefinite ignorano le build native facoltative di Opus per Discord. La voce Discord usa libopus-wasm integrato e @discordjs/opus resta disabilitato in allowBuilds, così i test locali e i percorsi Testbox non compilano l'add-on nativo.
• Confronta le prestazioni di Opus nativo nel repository di benchmark libopus-wasm, non nei cicli predefiniti di installazione/test di OpenClaw. Non impostare @discordjs/opus su true nel valore predefinito di allowBuilds; ciò farebbe compilare codice nativo a cicli di installazione/test non correlati.

Stabilità (Gateway)

• Comando: pnpm test:stability:gateway
• Configurazione: test/vitest/vitest.gateway.config.ts, test/vitest/vitest.logging.config.ts e test/vitest/vitest.infra.config.ts, ciascuna limitata a un worker
• Ambito:
  • Avvia un Gateway reale su local loopback con la diagnostica abilitata per impostazione predefinita
  • Genera traffico sintetico di messaggi del Gateway, memoria e payload di grandi dimensioni attraverso il percorso degli eventi diagnostici
  • Interroga diagnostics.stability tramite l'RPC WS del Gateway
  • Copre gli helper di persistenza del pacchetto diagnostico per la stabilità
  • Verifica che il registratore rimanga entro i limiti, che i campioni RSS sintetici restino al di sotto del budget di pressione e che le profondità delle code per sessione tornino a zero
• Aspettative:
  • Sicuro per la CI e senza necessità di chiavi
  • Corsia circoscritta per il monitoraggio delle regressioni di stabilità, non sostituisce l'intera suite del Gateway

End-to-end (aggregato del repository)

• Comando: pnpm test:e2e
• Ambito:
  • Esegue la corsia end-to-end di verifica di base del Gateway
  • Esegue la corsia end-to-end del browser con simulazione della Control UI
• Aspettative:
  • Sicuro per la CI e senza necessità di chiavi
  • Richiede l'installazione di Playwright Chromium

End-to-end (verifica di base del Gateway)

• Comando: pnpm test:e2e:gateway
• Configurazione: test/vitest/vitest.e2e.config.ts
• File: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts e i test end-to-end dei Plugin inclusi in extensions/
• Impostazioni predefinite di 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 il sovraccarico di I/O della console.
• Sostituzioni utili:
  • OPENCLAW_E2E_WORKERS=<n> per forzare il numero di worker (limitato a 16).
  • OPENCLAW_E2E_VERBOSE=1 per riabilitare l'output dettagliato della console.
• Ambito:
  • Comportamento end-to-end del Gateway con più istanze
  • Superfici WebSocket/HTTP, associazione dei Node e operazioni di rete più pesanti
• Aspettative:
  • Viene eseguito nella CI (quando abilitato nella pipeline)
  • Non richiede chiavi reali
  • Presenta più componenti mobili rispetto ai test unitari (può essere più lento)

End-to-end (browser simulato della Control UI)

• Comando: pnpm test:ui:e2e
• Configurazione: test/vitest/vitest.ui-e2e.config.ts
• File: ui/src/**/*.e2e.test.ts
• Ambito:
  • Avvia la Control UI di Vite
  • Controlla una pagina Chromium reale tramite Playwright
  • Sostituisce il WebSocket del Gateway con simulazioni deterministiche nel browser
• Aspettative:
  • Viene eseguito nella CI come parte di pnpm test:e2e
  • Non richiede un Gateway reale, agenti o chiavi dei provider
  • La dipendenza del browser deve essere presente (pnpm --dir ui exec playwright install chromium)

End-to-end: verifica di base del backend OpenShell

• Comando: pnpm test:e2e:openshell
• File: extensions/openshell/src/backend.e2e.test.ts
• Ambito:
  • Riutilizza un Gateway OpenShell locale attivo
  • Crea una sandbox da un Dockerfile locale temporaneo
  • Esercita il backend OpenShell di OpenClaw tramite sandbox ssh-config reale + esecuzione SSH
  • Verifica il comportamento canonico remoto del file system attraverso il bridge del file system della sandbox
• Aspettative:
  • Solo su esplicita abilitazione; non fa parte dell'esecuzione predefinita di pnpm test:e2e
  • Richiede una CLI openshell locale e un daemon Docker funzionante
  • Richiede un Gateway OpenShell locale attivo e la relativa origine di configurazione
  • Usa HOME / XDG_CONFIG_HOME isolati, quindi distrugge la sandbox di test
• Sostituzioni utili:
  • OPENCLAW_E2E_OPENSHELL=1 per abilitare il test durante l'esecuzione manuale della suite end-to-end più ampia
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell per indicare un file binario della CLI o uno script wrapper non predefinito
  • OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config per esporre la configurazione del Gateway registrato al test isolato
  • OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1 per sostituire l'indirizzo IP del Gateway Docker usato dal fixture dei criteri dell'host

Live (provider reali + modelli reali)

• Comando: pnpm test:live
• Configurazione: test/vitest/vitest.live.config.ts
• File: src/**/*.live.test.ts, test/**/*.live.test.ts e test live dei plugin inclusi in extensions/
• Impostazione predefinita: abilitata da pnpm test:live (imposta OPENCLAW_LIVE_TEST=1)
• Ambito:
  • "Questo provider/modello funziona davvero oggi con credenziali reali?"
  • Rilevare modifiche al formato del provider, peculiarità delle chiamate agli strumenti, problemi di autenticazione e comportamento dei limiti di frequenza
• Aspettative:
  • Per progettazione, non stabile in CI (reti reali, criteri reali dei provider, quote, interruzioni del servizio)
  • Ha un costo / utilizza i limiti di frequenza
  • È preferibile eseguire sottoinsiemi mirati anziché "tutto"
• Le esecuzioni live utilizzano chiavi API già esportate e profili di autenticazione predisposti.
• Per impostazione predefinita, le esecuzioni live isolano comunque HOME e copiano il materiale di configurazione/autenticazione in una directory home di test temporanea, in modo che le fixture dei test unitari non possano modificare la directory reale ~/.openclaw.
• Imposta OPENCLAW_LIVE_USE_REAL_HOME=1 solo quando vuoi intenzionalmente che i test live utilizzino la tua directory home reale.
• pnpm test:live usa per impostazione predefinita una modalità più silenziosa: mantiene l'output di avanzamento [live] ... e disattiva i log di bootstrap del Gateway e i messaggi Bonjour. Imposta OPENCLAW_LIVE_TEST_QUIET=0 se vuoi ripristinare i log completi di avvio.
• Rotazione delle chiavi API (specifica del 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), oppure usa una sostituzione specifica per le esecuzioni live tramite OPENCLAW_LIVE_*_KEY; i test riprovano in caso di risposte dovute ai limiti di frequenza.
• Output di avanzamento/Heartbeat:
  • Le suite live emettono righe di avanzamento su stderr, così le chiamate prolungate ai provider risultano visibilmente attive anche quando l'acquisizione della console di Vitest è silenziosa.
  • test/vitest/vitest.live.config.ts disabilita l'intercettazione della console di Vitest, così le righe di avanzamento del provider/Gateway vengono trasmesse immediatamente durante le esecuzioni live.
  • Regola gli Heartbeat dei modelli diretti con OPENCLAW_LIVE_HEARTBEAT_MS.
  • Regola gli Heartbeat del Gateway/delle sonde con OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Quale suite devo eseguire?

Usa questa tabella decisionale:

• Modifica della logica/dei test: esegui pnpm test (e pnpm test:coverage se hai apportato molte modifiche)
• Modifica della rete del Gateway / del protocollo WS / dell'associazione: aggiungi pnpm test:e2e
• Debug di "il mio bot non funziona" / errori specifici del provider / chiamate agli strumenti: esegui un pnpm test:live mirato

Test live (con accesso alla rete)

Per la matrice dei modelli live, gli smoke test del backend CLI, gli smoke test ACP, l'harness app-server di Codex e tutti i test live dei provider multimediali (Deepgram, BytePlus, ComfyUI, immagini, musica, video, harness multimediale), oltre alla gestione delle credenziali per le esecuzioni live

• consulta Test delle suite live. Per l'elenco di controllo dedicato alla convalida degli aggiornamenti e dei plugin, consulta Test degli aggiornamenti e dei plugin.

Runner Docker (controlli facoltativi "funziona su Linux")

Questi runner Docker si dividono in due categorie:

• Runner dei modelli live: test:docker:live-models e test:docker:live-gateway eseguono esclusivamente il file live corrispondente delle chiavi di profilo nell'immagine Docker del repository (src/agents/models.profiles.live.test.ts e src/gateway/gateway-models.profiles.live.test.ts), montando la directory di configurazione locale, l'area di lavoro e un file di ambiente del profilo facoltativo. I punti di ingresso locali corrispondenti sono test:live:models-profiles e test:live:gateway-profiles.
• I runner live Docker mantengono, dove necessario, i propri limiti pratici: test:docker:live-models usa per impostazione predefinita l'insieme selezionato di modelli supportati ad alto valore informativo, mentre 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. Imposta OPENCLAW_LIVE_MAX_MODELS o le variabili di ambiente del Gateway quando vuoi esplicitamente un limite inferiore o una scansione più ampia.
• test:docker:all crea una sola volta l'immagine Docker live tramite test:docker:live-build, impacchetta una sola volta OpenClaw come tarball npm tramite scripts/package-openclaw-for-docker.mjs, quindi crea/riutilizza due immagini scripts/e2e/Dockerfile. L'immagine di base è soltanto il runner Node/Git per i percorsi di installazione/aggiornamento/dipendenze dei plugin; questi percorsi montano il tarball precompilato. L'immagine funzionale installa lo stesso tarball in /app per i percorsi relativi alle funzionalità dell'applicazione compilata. Le definizioni dei percorsi Docker si trovano in scripts/lib/docker-e2e-scenarios.mjs; la logica di pianificazione si trova in scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs esegue il piano selezionato. L'aggregazione utilizza un pianificatore locale ponderato: OPENCLAW_DOCKER_ALL_PARALLELISM controlla gli slot dei processi, mentre i limiti delle risorse impediscono che i percorsi live pesanti, di installazione npm e multiservizio vengano avviati tutti contemporaneamente. Se un singolo percorso è più pesante dei limiti attivi, il pianificatore può comunque avviarlo quando il pool è vuoto e lo mantiene in esecuzione da solo finché non è nuovamente disponibile capacità. Le impostazioni predefinite sono 10 slot, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5 e OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; regola OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT o OPENCLAW_DOCKER_ALL_DOCKER_LIMIT (e le altre sostituzioni OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT) solo quando l'host Docker dispone di maggiore capacità. Il runner esegue per impostazione predefinita una verifica preliminare di Docker, rimuove i container E2E OpenClaw obsoleti, stampa lo stato ogni 30 secondi, memorizza i tempi dei percorsi completati correttamente in .artifacts/docker-tests/lane-timings.json e utilizza tali tempi per avviare prima i percorsi più lunghi nelle esecuzioni successive. Usa OPENCLAW_DOCKER_ALL_DRY_RUN=1 per stampare il manifesto ponderato dei percorsi senza creare immagini né eseguire Docker, oppure node scripts/test-docker-all.mjs --plan-json per stampare il piano CI dei percorsi selezionati, i requisiti di pacchetti/immagini e le credenziali.
• Package Acceptance è il controllo dei pacchetti nativo di GitHub per verificare "questo tarball installabile funziona come prodotto?". Risolve un singolo pacchetto candidato da source=npm, source=ref, source=url, source=trusted-url o source=artifact, lo carica come package-under-test, quindi esegue i percorsi E2E Docker riutilizzabili su quel tarball esatto anziché reimpacchettare il riferimento selezionato. I profili sono ordinati per ampiezza: smoke, package, product e full (oltre a custom per un elenco esplicito di percorsi). Consulta Test degli aggiornamenti e dei plugin per il contratto di pacchetto/aggiornamento/plugin, la matrice di persistenza dopo gli aggiornamenti pubblicati, le impostazioni predefinite delle versioni e la valutazione degli errori.
• I controlli di compilazione e rilascio eseguono scripts/check-cli-bootstrap-imports.mjs dopo tsdown. Il controllo esamina il grafo statico compilato a partire da dist/entry.js e dist/cli/run-main.js e non riesce se tale grafo di bootstrap precedente all'inoltro importa staticamente qualsiasi pacchetto esterno (Commander, interfaccia dei prompt, undici, registrazione e dipendenze analoghe pesanti in fase di avvio sono tutte incluse) prima dell'inoltro del comando; limita inoltre a 70 KB il frammento compilato di esecuzione del Gateway e rifiuta da tale frammento le importazioni statiche di percorsi Gateway notoriamente usati raramente (control-ui-assets, diagnostic-stability-bundle, onboard-helpers, process-respawn, restart-sentinel, server-close, server-reload-handlers). scripts/release-check.ts esegue separatamente smoke test sulla CLI impacchettata con --help, onboard --help, doctor --help, status --json --timeout 1, config schema e models list --provider openai.
• La compatibilità precedente di Package Acceptance è limitata alla versione 2026.4.25 (incluse le versioni 2026.4.25-beta.*). Fino a tale limite, l'harness tollera esclusivamente le lacune nei metadati dei pacchetti distribuiti: voci omesse nell'inventario QA privato, assenza di gateway install --wrapper, file patch mancanti nella fixture Git derivata dal tarball, assenza del valore persistente update.channel, percorsi precedenti dei record di installazione dei plugin, assenza della persistenza dei record di installazione del marketplace e migrazione dei metadati di configurazione durante plugins update. Per i pacchetti successivi alla versione 2026.4.25, tali percorsi causano errori rigorosi.
• Runner di smoke test dei container: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:release-user-journey, test:docker:release-typed-onboarding, test:docker:release-media-memory, test:docker:release-upgrade-user-journey, test:docker:release-plugin-marketplace, test:docker:skill-install, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:agent-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix e test:docker:config-reload avviano uno o più container reali e verificano percorsi di integrazione di livello superiore.
• I percorsi E2E Docker/Bash che installano il tarball OpenClaw impacchettato tramite scripts/lib/openclaw-e2e-instance.sh limitano npm install a OPENCLAW_E2E_NPM_INSTALL_TIMEOUT (valore predefinito 600s; imposta 0 per disabilitare il wrapper durante il debug).

I runner Docker dei modelli live montano inoltre in modalità bind esclusivamente le directory home di autenticazione CLI necessarie (o tutte quelle supportate quando l'esecuzione non è circoscritta), quindi le copiano nella directory home del container prima dell'esecuzione, in modo che OAuth della CLI esterna possa aggiornare i token senza modificare l'archivio di autenticazione dell'host:

• Modelli diretti: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)

• Smoke test del bind ACP: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh; include Claude, Codex e Gemini per impostazione predefinita, con copertura rigorosa di Droid/OpenCode tramite pnpm test:docker:live-acp-bind:droid e pnpm test:docker:live-acp-bind:opencode)

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

• Smoke test dell'harness app-server di Codex: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)

• Gateway + agente di sviluppo: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)

• Smoke test di osservabilità: pnpm qa:otel:smoke, pnpm qa:prometheus:smoke e pnpm qa:observability:smoke sono percorsi QA privati per i checkout del codice sorgente. Intenzionalmente non fanno parte dei percorsi di rilascio Docker dei pacchetti, perché il tarball npm omette QA Lab.

• Smoke test live di Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)

• Procedura guidata di onboarding (TTY, scaffolding completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)

• Smoke test di onboarding/canale/agente del tarball npm: pnpm test:docker:npm-onboard-channel-agent installa globalmente in Docker il tarball OpenClaw impacchettato, configura OpenAI tramite onboarding con riferimento a variabile di ambiente e Telegram per impostazione predefinita, esegue doctor ed esegue un turno simulato dell'agente OpenAI. Riutilizza un tarball precompilato con OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, ignora la ricompilazione sull'host con OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 oppure cambia canale con OPENCLAW_NPM_ONBOARD_CHANNEL=discord o OPENCLAW_NPM_ONBOARD_CHANNEL=slack.

• Smoke test del percorso utente di rilascio: pnpm test:docker:release-user-journey installa globalmente il tarball pacchettizzato di OpenClaw in una home Docker pulita, esegue l’onboarding, configura un provider OpenAI simulato, esegue un turno dell’agente, installa/disinstalla Plugin esterni, configura ClickClack rispetto a una fixture locale, verifica la messaggistica in uscita/in entrata, riavvia il Gateway ed esegue doctor.

• Smoke test dell’onboarding tipizzato di rilascio: pnpm test:docker:release-typed-onboarding installa il tarball pacchettizzato, esegue openclaw onboard tramite un TTY reale, configura OpenAI come provider con riferimento a una variabile d’ambiente, verifica che la chiave non venga salvata in forma non elaborata ed esegue un turno simulato dell’agente.

• Smoke test di contenuti multimediali/memoria del rilascio: pnpm test:docker:release-media-memory installa il tarball pacchettizzato, verifica la comprensione delle immagini da un allegato PNG, l’output della generazione di immagini compatibile con OpenAI, il recupero tramite ricerca nella memoria e la persistenza del recupero dopo il riavvio del Gateway.

• Smoke test del percorso utente di aggiornamento del rilascio: pnpm test:docker:release-upgrade-user-journey installa per impostazione predefinita la baseline pubblicata più recente precedente al tarball candidato, configura lo stato di provider/Plugin/ClickClack nel pacchetto pubblicato, esegue l’aggiornamento al tarball candidato, quindi ripete il percorso principale di agente/Plugin/canale. Se non esiste una baseline pubblicata precedente, riutilizza la versione candidata. Sostituisci la baseline con OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>.

• Smoke test del marketplace dei Plugin di rilascio: pnpm test:docker:release-plugin-marketplace esegue l’installazione da un marketplace di fixture locale, aggiorna il Plugin installato, lo disinstalla e verifica che la CLI del Plugin scompaia e che i metadati di installazione vengano rimossi.

• Smoke test dell’installazione di una Skill: pnpm test:docker:skill-install installa globalmente in Docker il tarball pacchettizzato di OpenClaw, disabilita nella configurazione le installazioni da archivi caricati, risolve dalla ricerca lo slug attuale della Skill ClawHub attiva, la installa con openclaw skills install e verifica la Skill installata insieme ai metadati di origine/blocco .clawhub.

• Smoke test del cambio del canale di aggiornamento: pnpm test:docker:update-channel-switch installa globalmente in Docker il tarball pacchettizzato di OpenClaw, passa dal pacchetto stable al repository git dev, verifica il canale persistente e il funzionamento del Plugin dopo l’aggiornamento, quindi torna al pacchetto stable e controlla lo stato dell’aggiornamento.

• Smoke test di sopravvivenza all’aggiornamento: pnpm test:docker:upgrade-survivor installa il tarball pacchettizzato di OpenClaw su una fixture non pulita di un vecchio utente contenente agenti, configurazione dei canali, elenchi di Plugin consentiti, stato obsoleto delle dipendenze dei Plugin e file di area di lavoro/sessione esistenti. Esegue l’aggiornamento del pacchetto e doctor in modalità non interattiva senza chiavi attive di provider o canali, quindi avvia un Gateway su local loopback e controlla la conservazione della configurazione/dello stato e i limiti temporali di avvio/stato.

• Smoke test pubblicato di sopravvivenza all’aggiornamento: pnpm test:docker:published-upgrade-survivor installa per impostazione predefinita openclaw@latest, prepara file realistici di un utente esistente, configura tale baseline con una procedura di comandi incorporata, convalida la configurazione risultante, aggiorna l’installazione pubblicata al tarball candidato, esegue doctor in modalità non interattiva, scrive .artifacts/upgrade-survivor/summary.json, quindi avvia un Gateway su local loopback e controlla gli intenti configurati, la conservazione dello stato, l’avvio, /healthz, /readyz e i limiti temporali dello stato RPC. Sostituisci una baseline con OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, richiedi allo scheduler aggregato di espandere le baseline locali esatte con OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS, ad esempio openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, ed espandi le fixture modellate sui problemi con OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS, ad esempio reported-issues; l’insieme dei problemi segnalati include configured-plugin-installs per la riparazione automatica dell’installazione di Plugin OpenClaw esterni. L’accettazione del pacchetto espone questi elementi come published_upgrade_survivor_baseline, published_upgrade_survivor_baselines e published_upgrade_survivor_scenarios, risolve token di meta-baseline come last-stable-4 o all-since-2026.4.23 e la convalida completa del rilascio espande il controllo prolungato del pacchetto di rilascio a last-stable-4 2026.4.23 2026.5.2 2026.4.15 più reported-issues.

• Smoke test del contesto di runtime della sessione: pnpm test:docker:session-runtime-context verifica la persistenza nascosta della trascrizione del contesto di runtime e la riparazione tramite doctor dei rami duplicati interessati che riscrivono il prompt.

• Smoke test dell’installazione globale con Bun: bash scripts/e2e/bun-global-install-smoke.sh pacchettizza l’albero corrente, lo installa con bun install -g in una home isolata e verifica che openclaw infer image providers --json restituisca i provider di immagini inclusi anziché bloccarsi. Riutilizza un tarball precompilato con OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, salta la compilazione sull’host con OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 oppure copia dist/ da un’immagine Docker compilata con OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.

• Smoke test Docker del programma di installazione: bash scripts/test-install-sh-docker.sh condivide una singola cache npm tra i container root, di aggiornamento e npm diretto. Per impostazione predefinita, lo smoke test di aggiornamento usa latest di npm come baseline stabile prima di passare al tarball candidato. Sostituiscila localmente con OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 oppure su GitHub con l’input update_baseline_version del flusso di lavoro Install Smoke. I controlli del programma di installazione non root mantengono una cache npm isolata, affinché le voci della cache appartenenti a root non mascherino il comportamento dell’installazione locale dell’utente. Imposta OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache per riutilizzare la cache root/aggiornamento/npm diretto nelle riesecuzioni locali.

• La CI Install Smoke salta l’aggiornamento globale duplicato tramite npm diretto con OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; esegui lo script localmente senza questa variabile d’ambiente quando è necessaria la copertura di npm install -g diretto.

• Smoke test della CLI per l’eliminazione da parte degli agenti di un’area di lavoro condivisa: pnpm test:docker:agents-delete-shared-workspace (script: scripts/e2e/agents-delete-shared-workspace-docker.sh) compila per impostazione predefinita l’immagine dal Dockerfile radice, prepara due agenti con una sola area di lavoro in una home isolata del container, esegue agents delete --json e verifica la validità del JSON e il comportamento di conservazione dell’area di lavoro. Riutilizza l’immagine dello smoke test di installazione con OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.

• Rete del Gateway e ciclo di vita dell’host: pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh) conserva lo smoke test di autenticazione/integrità WebSocket sulla LAN con due container, quindi usa l’HTTP di amministrazione su local loopback per dimostrare il blocco durante la preparazione, l’accesso con controllo conservato, il ripristino tramite ripresa e un arresto/avvio preparato nello stesso container. Il controllo del riavvio deve terminare prima della scadenza del lease originale, verifica che lo stato di sospensione sia locale al processo mentre la configurazione persistente del Gateway e l’identità del container rimangono intatte ed emette un JSON leggibile dalla macchina con i tempi delle fasi.

• Smoke test delle istantanee CDP del browser: pnpm test:docker:browser-cdp-snapshot (script: scripts/e2e/browser-cdp-snapshot-docker.sh) compila l’immagine E2E dal sorgente insieme a un livello Chromium, avvia Chromium con CDP non elaborato, esegue browser doctor --deep e verifica che le istantanee dei ruoli CDP includano gli URL dei collegamenti, gli elementi cliccabili promossi dal cursore, i riferimenti agli iframe e i metadati dei frame.

• Regressione di OpenAI Responses web_search con ragionamento minimo: pnpm test:docker:openai-web-search-minimal (script: scripts/e2e/openai-web-search-minimal-docker.sh) esegue un server OpenAI simulato tramite il Gateway, verifica che web_search aumenti reasoning.effort da minimal a low, quindi forza il rifiuto da parte dello schema del provider e controlla che il dettaglio non elaborato compaia nei log del Gateway.

• Bridge MCP dei canali (Gateway predisposto + bridge stdio + smoke test del frame di notifica Claude non elaborato): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)

• Strumenti MCP del bundle OpenClaw (server MCP stdio reale + smoke test consenti/nega del profilo OpenClaw incorporato): pnpm test:docker:agent-bundle-mcp-tools (script: scripts/e2e/agent-bundle-mcp-tools-docker.sh)

• Pulizia MCP di Cron/sottoagente (Gateway reale + terminazione del processo figlio MCP stdio dopo esecuzioni Cron isolate e singole esecuzioni del sottoagente): pnpm test:docker:cron-mcp-cleanup (script: scripts/e2e/cron-mcp-cleanup-docker.sh)

• Plugin (smoke test di installazione/aggiornamento per percorso locale, file:, registro npm con dipendenze sollevate, metadati malformati del pacchetto npm, riferimenti git mobili, pacchetto completo ClawHub, aggiornamenti del marketplace e attivazione/ispezione del bundle Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh) Imposta OPENCLAW_PLUGINS_E2E_CLAWHUB=0 per saltare il blocco ClawHub oppure sostituisci la coppia predefinita pacchetto/runtime completa con OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC e OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. In assenza di OPENCLAW_CLAWHUB_URL/CLAWHUB_URL, il test usa un server di fixture ClawHub locale ed ermetico.

• Smoke test dell’aggiornamento invariato del Plugin: pnpm test:docker:plugin-update (script: scripts/e2e/plugin-update-unchanged-docker.sh)

• Smoke test della matrice del ciclo di vita del Plugin: pnpm test:docker:plugin-lifecycle-matrix installa il tarball pacchettizzato di OpenClaw in un container essenziale, installa un Plugin npm, ne alterna l’attivazione/disattivazione, lo aggiorna e ne esegue il downgrade tramite un registro npm locale, elimina il codice installato, quindi verifica che la disinstallazione rimuova comunque lo stato obsoleto, registrando le metriche RSS/CPU per ogni fase del ciclo di vita.

• Smoke test dei metadati di ricaricamento della configurazione: pnpm test:docker:config-reload (script: scripts/e2e/config-reload-source-docker.sh)

• Plugin: pnpm test:docker:plugins copre lo smoke test di installazione/aggiornamento per percorso locale, file:, registro npm con dipendenze sollevate, riferimenti git mobili, fixture ClawHub, aggiornamenti del marketplace e attivazione/ispezione del bundle Claude. pnpm test:docker:plugin-update copre il comportamento degli aggiornamenti invariati dei Plugin installati. pnpm test:docker:plugin-lifecycle-matrix copre installazione, attivazione, disattivazione, aggiornamento, downgrade e disinstallazione con codice mancante di Plugin npm con monitoraggio delle risorse.

Per precompilare e riutilizzare manualmente l’immagine funzionale condivisa:

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

Le sostituzioni delle immagini specifiche delle suite, come OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE, hanno comunque la precedenza quando sono impostate. Quando OPENCLAW_SKIP_DOCKER_BUILD=1 punta a un’immagine remota condivisa, gli script la scaricano se non è già disponibile localmente. I test Docker del codice QR e del programma di installazione mantengono i propri Dockerfile perché convalidano il comportamento del pacchetto/dell’installazione anziché il runtime condiviso dell’applicazione compilata.

Gli esecutori Docker con modelli attivi montano inoltre in sola lettura il checkout corrente e lo preparano in una directory di lavoro temporanea all’interno del container. Ciò mantiene snella l’immagine di runtime, continuando al contempo a eseguire Vitest rispetto all’esatta configurazione e al codice sorgente locale. La fase di preparazione salta le cache di grandi dimensioni esclusivamente locali e gli output di compilazione dell’applicazione, come .pnpm-store, .worktrees, __openclaw_vitest__ e le directory di output .build locali dell’applicazione o di Gradle, affinché le esecuzioni Docker attive non impieghino minuti a copiare artefatti specifici della macchina. Impostano inoltre OPENCLAW_SKIP_CHANNELS=1 affinché le sonde attive del Gateway non avviino processi reali dei canali Telegram/Discord/ecc. all’interno del container. test:docker:live-models esegue comunque pnpm test:live, quindi inoltra anche OPENCLAW_LIVE_GATEWAY_* quando devi restringere o escludere la copertura attiva del Gateway da tale corsia Docker.

test:docker:openwebui è uno smoke test di compatibilità di livello superiore: avvia un container Gateway di OpenClaw con gli endpoint HTTP compatibili con OpenAI abilitati, avvia un container Open WebUI con versione fissata collegato a tale Gateway, esegue l'accesso tramite Open WebUI, verifica che /api/models esponga openclaw/default, quindi invia una richiesta di chat reale tramite il proxy /api/chat/completions di Open WebUI. Impostare OPENWEBUI_SMOKE_MODE=models per i controlli CI del percorso di rilascio che devono interrompersi dopo l'accesso a Open WebUI e il rilevamento del modello, senza attendere il completamento di un modello live. La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare l'immagine di Open WebUI e Open WebUI potrebbe dover completare la propria configurazione di avvio a freddo. Questa corsia richiede una chiave utilizzabile per un modello live, fornita tramite l'ambiente del processo, profili di autenticazione predisposti o un OPENCLAW_PROFILE_FILE esplicito. Le esecuzioni riuscite stampano un piccolo payload JSON come { "ok": true, "model": "openclaw/default", ... }.

test:docker:mcp-channels è intenzionalmente deterministico e non richiede un account Telegram, Discord o iMessage reale. Avvia un container Gateway con dati preimpostati, avvia un secondo container che esegue openclaw mcp serve, quindi verifica il rilevamento instradato delle conversazioni, la lettura delle trascrizioni, i metadati degli allegati, il comportamento della coda degli eventi live, l'instradamento degli invii in uscita e le notifiche in stile Claude relative a canali e autorizzazioni tramite il bridge MCP stdio reale. Il controllo delle notifiche esamina direttamente i frame MCP stdio non elaborati, affinché lo smoke test convalidi ciò che il bridge emette effettivamente, non soltanto ciò che uno specifico SDK client rende visibile.

test:docker:agent-bundle-mcp-tools è deterministico e non richiede una chiave per un modello live. Crea l'immagine Docker del repository, avvia un vero server di verifica MCP stdio all'interno del container, materializza tale server tramite il runtime MCP del bundle OpenClaw incorporato, esegue lo strumento, quindi verifica che coding e messaging mantengano gli strumenti bundle-mcp, mentre minimal e tools.deny: ["bundle-mcp"] li filtrano.

test:docker:cron-mcp-cleanup è deterministico e non richiede una chiave per un modello live. Avvia un Gateway con dati preimpostati e un vero server di verifica MCP stdio, esegue un turno Cron isolato e un turno figlio monouso sessions_spawn, quindi verifica che il processo figlio MCP termini dopo ogni esecuzione.

Smoke test manuale in linguaggio naturale dei thread ACP (non CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Conservare questo script per i flussi di lavoro di regressione/debug. Potrebbe essere nuovamente necessario per la convalida dell'instradamento dei thread ACP, quindi non eliminarlo.

Variabili di ambiente utili:

• OPENCLAW_CONFIG_DIR=... (predefinita: ~/.openclaw) montata in /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (predefinita: ~/.openclaw/workspace) montata in /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... montato e caricato prima di eseguire i test
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 per verificare esclusivamente le variabili di ambiente caricate da OPENCLAW_PROFILE_FILE, usando directory temporanee di configurazione/spazio di lavoro e senza montaggi esterni per l'autenticazione CLI
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (predefinita: ~/.cache/openclaw/docker-cli-tools, a meno che l'esecuzione non utilizzi già una directory di montaggio gestita/CI) montata in /home/node/.npm-global per le installazioni CLI memorizzate nella cache all'interno di Docker
• Le directory/i file di autenticazione CLI esterni sotto $HOME vengono montati in sola lettura sotto /host-auth..., quindi copiati in /home/node/... prima dell'avvio dei test
  • Directory predefinite (utilizzate quando l'esecuzione non è limitata a provider specifici): .factory, .gemini, .minimax
  • File predefiniti: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Le esecuzioni limitate a determinati provider montano soltanto le directory/i file necessari dedotti da OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Per eseguire manualmente l'override, usare 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 limitare 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 nelle riesecuzioni che non richiedono una nuova compilazione
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 per assicurare che le credenziali provengano dall'archivio dei profili (non dall'ambiente)
• OPENCLAW_OPENWEBUI_MODEL=... per scegliere il modello esposto dal Gateway per lo smoke test di Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... per sostituire il prompt di controllo del nonce usato dallo smoke test di Open WebUI
• OPENWEBUI_IMAGE=... per sostituire il tag fissato dell'immagine Open WebUI

Controlli di integrità della documentazione

Eseguire i controlli della documentazione dopo averla modificata: pnpm check:docs. Eseguire la convalida completa degli anchor Mintlify quando sono necessari anche i controlli delle intestazioni interne alla pagina: pnpm docs:check-links:anchors.

Regressione offline (sicura per CI)

Queste sono regressioni della "pipeline reale" senza provider reali:

• Chiamata degli strumenti del Gateway (OpenAI simulato, Gateway e ciclo dell'agente reali): src/gateway/gateway.test.ts (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Procedura guidata del Gateway (WS wizard.start/wizard.next, scrive la configurazione + autenticazione applicata): src/gateway/gateway.test.ts (caso: "runs wizard over ws and writes auth token config")

Valutazioni di affidabilità dell'agente (Skills)

Disponiamo già di alcuni test sicuri per CI che si comportano come "valutazioni di affidabilità dell'agente":

• Chiamata simulata degli strumenti tramite il Gateway e il ciclo dell'agente reali (src/gateway/gateway.test.ts).
• Flussi end-to-end della procedura guidata che convalidano il collegamento delle sessioni e gli effetti sulla configurazione (src/gateway/gateway.test.ts).

Cosa manca ancora per le Skills (vedere Skills):

• Processo decisionale: quando le Skills sono elencate nel prompt, l'agente seleziona quella corretta (o evita quelle irrilevanti)?
• Conformità: l'agente legge SKILL.md prima dell'uso e segue i passaggi/argomenti richiesti?
• Contratti dei flussi di lavoro: scenari con più turni che verificano l'ordine degli strumenti, la conservazione della cronologia della sessione e i confini della sandbox.

Le valutazioni future dovrebbero essere innanzitutto deterministiche:

• Un esecutore di scenari che utilizzi provider simulati per verificare chiamate e ordine degli strumenti, letture dei file delle Skills e collegamento delle sessioni.
• Una piccola suite di scenari incentrati sulle Skills (uso rispetto a esclusione, controlli di accesso, prompt injection).
• Valutazioni live facoltative (con adesione esplicita, vincolate da variabili di ambiente) soltanto dopo l'introduzione della suite sicura per CI.

Test dei contratti (struttura di Plugin e canali)

I test dei contratti verificano che ogni Plugin e canale registrato sia conforme al proprio contratto di interfaccia. Iterano su tutti i Plugin rilevati ed eseguono una suite di asserzioni sulla struttura e sul comportamento. La corsia di test unitari predefinita pnpm test esclude intenzionalmente questi file condivisi relativi ai punti di integrazione e agli smoke test; eseguire esplicitamente i comandi dei contratti quando si modificano superfici condivise di canali o provider.

Comandi

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

Contratti dei canali

Si trovano in src/channels/plugins/contracts/*.contract.test.ts. Le attuali categorie di livello superiore sono:

• channel-catalog - metadati delle voci del catalogo dei canali inclusi/del registro
• Plugin (basato sul registro, suddiviso in shard) - struttura di base della registrazione del Plugin
• soltanto superfici (basato sul registro, suddiviso in shard) - controlli della struttura per ciascuna superficie per actions, setup, status, outbound, messaging, threading, directory e gateway
• associazione delle sessioni (basato sul registro) - comportamento dell'associazione delle sessioni
• payload in uscita - struttura e normalizzazione del payload dei messaggi
• criterio dei gruppi (fallback) - applicazione del criterio di gruppo predefinito per ciascun canale
• threading (basato sul registro, suddiviso in shard) - gestione degli ID dei thread
• directory (basato sul registro, suddiviso in shard) - API della directory/dell'elenco
• registro e plugins-core.* - registro dei Plugin dei canali, caricatore e meccanismi interni di autorizzazione alla scrittura della configurazione

Gli helper dell'infrastruttura di acquisizione dell'instradamento in ingresso e dei payload in uscita utilizzati da queste suite sono esposti internamente tramite src/plugin-sdk/channel-contract-testing.ts (escluso da npm, non un percorso secondario pubblico dell'SDK); in questa directory non esiste un file inbound.contract.test.ts autonomo.

Contratti dei provider

Si trovano in src/plugins/contracts/*.contract.test.ts. Le categorie attuali includono:

• struttura - struttura del manifesto, dell'API e delle esportazioni di runtime del Plugin
• registrazione del Plugin (+ parallela) - casi di registrazione del manifesto
• manifesto del pacchetto - requisiti del manifesto del pacchetto
• caricatore - comportamento di configurazione/smontaggio del caricatore dei Plugin
• registro - contenuti e ricerca nel registro dei contratti dei Plugin
• provider - comportamento condiviso dei provider inclusi, oltre ai provider di ricerca Web
• scelta dell'autenticazione - metadati della scelta dell'autenticazione e comportamento di configurazione
• deprecazione del catalogo dei provider - metadati deprecati del catalogo dei provider
• wizard.choice-resolution, wizard.model-picker, wizard.setup-options - contratti della procedura guidata di configurazione dei provider
• provider di embedding, provider di embedding della memoria, provider di recupero Web, tts - contratti dei provider specifici per funzionalità
• azioni delle sessioni, allegati delle sessioni, proiezione delle voci di sessione - contratti dello stato delle sessioni di proprietà del Plugin
• turni pianificati - metadati dei turni pianificati del Plugin e limiti dei timestamp
• hook dell'host, ciclo di vita del contesto di esecuzione, effetti collaterali dell'importazione del runtime, punti di integrazione del runtime - ciclo di vita di host/runtime del Plugin e contratti dei confini di importazione
• dipendenze di runtime delle estensioni - collocazione delle dipendenze di runtime per le estensioni

Quando eseguirli

• Dopo aver modificato le esportazioni o i percorsi secondari di plugin-sdk
• Dopo aver aggiunto o modificato un Plugin di canale o provider
• Dopo aver rifattorizzato la registrazione o il rilevamento dei Plugin

I test dei contratti vengono eseguiti in CI e non richiedono chiavi API reali.

Aggiunta di regressioni (indicazioni)

Quando si corregge un problema di un provider/modello rilevato live:

• Aggiungere, se possibile, una regressione sicura per CI (provider simulato/stub oppure acquisizione dell'esatta trasformazione della struttura della richiesta)
• Se il problema è intrinsecamente solo live (limiti di frequenza, criteri di autenticazione), mantenere il test live circoscritto e facoltativo tramite variabili di ambiente
• Preferire il livello più piccolo in grado di rilevare il bug:
  • bug di conversione/riproduzione della richiesta del provider -> test diretto dei modelli
  • bug della pipeline di sessione/cronologia/strumenti del Gateway -> smoke test live del Gateway o test simulato del Gateway sicuro per CI
• Protezione per l'attraversamento SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts ricava un target di esempio per ogni classe SecretRef dai metadati del registro (listSecretTargetRegistryEntries()), quindi verifica che gli ID di esecuzione con segmenti di attraversamento vengano rifiutati.
  • Se si aggiunge una nuova famiglia di target SecretRef includeInPlan in src/secrets/target-registry-data.ts, aggiornare classifyTargetClass in quel test. Il test fallisce intenzionalmente per gli ID target non classificati, affinché le nuove classi non possano essere ignorate silenziosamente.

Contenuti correlati

• Test live
• Test di aggiornamenti e Plugin
• CI