Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw ha tre canali di rilascio pubblici:
  • stabile: rilasci con tag pubblicati su npm beta per impostazione predefinita, oppure su npm latest quando richiesto esplicitamente
  • beta: tag prerelease pubblicati su npm beta
  • sviluppo: l’head mobile di main

​
Denominazione delle versioni

  • Versione di rilascio stabile: YYYY.M.D
    • Tag Git: vYYYY.M.D
  • Versione di rilascio correttivo stabile: YYYY.M.D-N
    • Tag Git: vYYYY.M.D-N
  • Versione prerelease beta: YYYY.M.D-beta.N
    • Tag Git: vYYYY.M.D-beta.N
  • Non aggiungere zeri iniziali al mese o al giorno
  • latest indica l’attuale rilascio stabile npm promosso
  • beta indica l’attuale destinazione di installazione beta
  • I rilasci stabili e correttivi stabili vengono pubblicati su npm beta per impostazione predefinita; gli operatori di rilascio possono puntare esplicitamente a latest, oppure promuovere in seguito una build beta verificata
  • Ogni rilascio stabile di OpenClaw distribuisce insieme il pacchetto npm e l’app macOS; i rilasci beta normalmente convalidano e pubblicano prima il percorso npm/pacchetto, con build/firma/notarizzazione dell’app mac riservati allo stabile salvo richiesta esplicita

​
Cadenza dei rilasci

  • I rilasci procedono prima in beta
  • Lo stabile segue solo dopo che l’ultima beta è stata convalidata
  • I manutentori normalmente preparano i rilasci da un branch release/YYYY.M.D creato dall’attuale main, così la convalida del rilascio e le correzioni non bloccano il nuovo sviluppo su main
  • Se un tag beta è stato inviato o pubblicato e necessita di una correzione, i manutentori creano il tag -beta.N successivo invece di eliminare o ricreare il vecchio tag beta
  • La procedura di rilascio dettagliata, le approvazioni, le credenziali e le note di ripristino sono riservate ai manutentori

​
Checklist dell’operatore di rilascio

Questa checklist è la forma pubblica del flusso di rilascio. Credenziali private, firma, notarizzazione, ripristino dei dist-tag e dettagli di rollback di emergenza restano nel runbook di rilascio riservato ai manutentori.
  1. Parti dall’attuale main: esegui il pull dell’ultima versione, conferma che il commit di destinazione sia stato inviato e conferma che la CI dell’attuale main sia abbastanza verde da poter creare il branch da lì.
  2. Riscrivi la sezione superiore di CHANGELOG.md dalla cronologia reale dei commit con /changelog, mantieni le voci orientate agli utenti, esegui il commit, invialo e fai rebase/pull ancora una volta prima di creare il branch.
  3. Rivedi i record di compatibilità dei rilasci in src/plugins/compat/registry.ts e src/commands/doctor/shared/deprecation-compat.ts. Rimuovi la compatibilità scaduta solo quando il percorso di aggiornamento resta coperto, oppure registra perché viene intenzionalmente mantenuta.
  4. Crea release/YYYY.M.D dall’attuale main; non svolgere il normale lavoro di rilascio direttamente su main.
  5. Incrementa ogni posizione di versione richiesta per il tag previsto, quindi esegui pnpm release:prep. Aggiorna versioni dei Plugin, inventario dei Plugin, schema di configurazione, metadati della configurazione dei canali inclusi, baseline della documentazione di configurazione, export dell’SDK dei Plugin e baseline API dell’SDK dei Plugin nell’ordine corretto. Esegui il commit di qualunque deriva generata prima del tagging. Poi esegui il preflight locale deterministico: pnpm check:test-types, pnpm check:architecture, pnpm build && pnpm ui:build e pnpm release:check.
  6. Esegui OpenClaw NPM Release con preflight_only=true. Prima che esista un tag, uno SHA completo a 40 caratteri del branch di rilascio è consentito per il preflight solo di convalida. Salva il preflight_run_id riuscito.
  7. Avvia tutti i test pre-release con Full Release Validation per il branch di rilascio, il tag o lo SHA completo del commit. Questo è l’unico punto di ingresso manuale per le quattro grandi test box di rilascio: Vitest, Docker, QA Lab e Package.
  8. Se la convalida fallisce, correggi sul branch di rilascio ed esegui di nuovo il file, canale, job del workflow, profilo del pacchetto, provider o allowlist di modelli fallito più piccolo che dimostri la correzione. Riesegui l’ombrello completo solo quando la superficie modificata rende obsolete le prove precedenti.
  9. Per la beta, crea il tag vYYYY.M.D-beta.N, quindi esegui OpenClaw Release Publish dal branch release/YYYY.M.D corrispondente. Verifica pnpm plugins:sync:check, invia tutti i pacchetti Plugin pubblicabili su npm e lo stesso insieme a ClawHub in parallelo, quindi promuove l’artefatto di preflight npm di OpenClaw preparato con il dist-tag corrispondente non appena la pubblicazione npm dei Plugin riesce. Dopo che il child di pubblicazione npm di OpenClaw riesce, crea o aggiorna la pagina di rilascio/prerelease GitHub corrispondente dalla sezione completa corrispondente di CHANGELOG.md. I rilasci stabili pubblicati su npm latest diventano il rilascio latest di GitHub; i rilasci di manutenzione stabili mantenuti su npm beta sono creati con GitHub latest=false. La pubblicazione su ClawHub potrebbe essere ancora in esecuzione mentre OpenClaw npm pubblica, ma il workflow di pubblicazione del rilascio stampa immediatamente gli ID delle esecuzioni child. Per impostazione predefinita non attende ClawHub dopo averlo inviato, quindi la disponibilità npm di OpenClaw non è bloccata da approvazioni ClawHub o lavori di registro più lenti; imposta wait_for_clawhub=true quando ClawHub deve bloccare il completamento del workflow. Il percorso ClawHub ritenta i fallimenti transitori di installazione delle dipendenze CLI, pubblica i Plugin che superano la preview anche quando una cella di preview presenta un flake, e termina con la verifica del registro per ogni versione attesa dei Plugin, così le pubblicazioni parziali restano visibili e ripetibili. Dopo la pubblicazione, esegui pnpm release:verify-beta -- YYYY.M.D-beta.N --openclaw-npm-run <run-id> --plugin-npm-run <run-id> --plugin-clawhub-run <run-id> per verificare con un solo comando la prerelease GitHub, i dist-tag npm beta, l’integrità npm, il percorso di installazione pubblicato, le versioni esatte su ClawHub, gli artefatti ClawHub e le conclusioni dei workflow child. Aggiungi --rerun-failed-clawhub quando il sidecar ClawHub è fallito solo in job ritentabili e deve essere rieseguito sul posto. Quindi esegui l’accettazione del pacchetto post-pubblicazione contro il pacchetto pubblicato openclaw@YYYY.M.D-beta.N oppure openclaw@beta. Se una prerelease inviata o pubblicata necessita di una correzione, crea il numero di prerelease corrispondente successivo; non eliminare né riscrivere la vecchia prerelease.
  10. Per lo stabile, continua solo dopo che la beta verificata o il candidato di rilascio dispone delle prove di convalida richieste. Anche la pubblicazione npm stabile passa attraverso OpenClaw Release Publish, riutilizzando l’artefatto di preflight riuscito tramite preflight_run_id; la prontezza del rilascio macOS stabile richiede anche i pacchetti .zip, .dmg, .dSYM.zip e appcast.xml aggiornato su main. Il workflow privato di pubblicazione macOS pubblica automaticamente l’appcast firmato su main pubblico dopo la verifica degli asset di rilascio; se la protezione del branch blocca il push diretto, apre o aggiorna una PR appcast.
  11. Dopo la pubblicazione, esegui il verificatore npm post-pubblicazione, l’E2E Telegram npm pubblicato autonomo facoltativo quando hai bisogno di prova del canale post-pubblicazione, la promozione del dist-tag quando necessaria, verifica la pagina di rilascio GitHub generata ed esegui i passaggi di annuncio del rilascio.

​
Preflight del rilascio

  • Esegui pnpm check:test-types prima della preflight di release in modo che il TypeScript dei test resti coperto al di fuori del gate locale più veloce pnpm check
  • Esegui pnpm check:architecture prima della preflight di release in modo che i controlli più ampi sui cicli di importazione e sui confini architetturali siano verdi al di fuori del gate locale più veloce
  • Esegui pnpm build && pnpm ui:build prima di pnpm release:check in modo che gli artefatti di release dist/* attesi e il bundle Control UI esistano per il passaggio di validazione del pacchetto
  • Esegui pnpm release:prep dopo l’incremento della versione root e prima del tagging. Esegue ogni generatore di release deterministico che tende a divergere dopo una modifica di versione/configurazione/API: versioni dei plugin, inventario dei plugin, schema della configurazione base, metadati della configurazione dei canali inclusi, baseline della documentazione di configurazione, export dell’SDK dei plugin e baseline API dell’SDK dei plugin. pnpm release:check riesegue quei guard in modalità controllo e segnala in un solo passaggio ogni errore di deriva generata che trova prima di eseguire i controlli di release del pacchetto.
  • Esegui il workflow manuale Full Release Validation prima dell’approvazione della release per avviare tutte le test box pre-release da un unico punto di ingresso. Accetta un branch, tag o SHA completo di commit, avvia manualmente CI e avvia OpenClaw Release Checks per install smoke, accettazione pacchetto, controlli pacchetto cross-OS, parità QA Lab, Matrix e lane Telegram. Le esecuzioni stable/predefinite mantengono live/E2E esaustivi e soak Docker del percorso di release dietro run_release_soak=true; release_profile=full forza il soak. Con release_profile=full e rerun_group=all, esegue anche il pacchetto Telegram E2E contro l’artefatto release-package-under-test dei controlli di release. Fornisci release_package_spec dopo aver pubblicato una beta per riusare il pacchetto npm rilasciato nei controlli di release, Package Acceptance e pacchetto Telegram E2E senza ricostruire il tarball di release. Fornisci npm_telegram_package_spec solo quando Telegram deve usare un pacchetto pubblicato diverso dal resto della validazione di release. Fornisci package_acceptance_package_spec quando Package Acceptance deve usare un pacchetto pubblicato diverso dalla specifica del pacchetto di release. Fornisci evidence_package_spec quando il report privato delle prove deve dimostrare che la validazione corrisponde a un pacchetto npm pubblicato senza forzare Telegram E2E. Esempio: gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D
  • Esegui il workflow manuale Package Acceptance quando vuoi una prova side-channel per un candidato pacchetto mentre il lavoro di release continua. Usa source=npm per openclaw@beta, openclaw@latest o una versione di release esatta; source=ref per impacchettare un branch/tag/SHA package_ref affidabile con l’harness workflow_ref corrente; source=url per un tarball HTTPS con SHA-256 obbligatorio; oppure source=artifact per un tarball caricato da un’altra esecuzione di GitHub Actions. Il workflow risolve il candidato in package-under-test, riusa lo scheduler di release Docker E2E contro quel tarball e può eseguire la QA Telegram contro lo stesso tarball con telegram_mode=mock-openai o telegram_mode=live-frontier. Quando le lane Docker selezionate includono published-upgrade-survivor, l’artefatto del pacchetto è il candidato e published_upgrade_survivor_baseline seleziona la baseline pubblicata. update-restart-auth usa il pacchetto candidato sia come CLI installata sia come package-under-test, quindi esercita il percorso di restart gestito del comando di aggiornamento candidato. Esempio: gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai Profili comuni:
    • smoke: lane install/channel/agent, rete Gateway e reload configurazione
    • package: lane native dell’artefatto per pacchetto/aggiornamento/restart/plugin senza OpenWebUI o ClawHub live
    • product: profilo package più canali MCP, pulizia cron/subagent, ricerca web OpenAI e OpenWebUI
    • full: chunk Docker del percorso di release con OpenWebUI
    • custom: selezione esatta docker_lanes per una riesecuzione mirata
  • Esegui direttamente il workflow manuale CI quando ti serve solo la copertura CI normale completa per il candidato release. Gli avvii manuali di CI bypassano lo scoping delle modifiche e forzano gli shard Linux Node, gli shard dei plugin inclusi, i contratti dei canali, compatibilità Node 22, check, check-additional, build smoke, controlli docs, Skills Python, Windows, macOS, Android e lane i18n Control UI. Esempio: gh workflow run ci.yml --ref release/YYYY.M.D
  • Esegui pnpm qa:otel:smoke quando validi la telemetria di release. Esercita QA-lab tramite un ricevitore OTLP/HTTP locale e verifica i nomi degli span di trace esportati, gli attributi limitati e la redazione di contenuti/identificatori senza richiedere Opik, Langfuse o un altro collector esterno.
  • Esegui pnpm release:check prima di ogni release taggata
  • Esegui OpenClaw Release Publish per la sequenza di pubblicazione mutante dopo che il tag esiste. Avvialo da release/YYYY.M.D (o da main quando pubblichi un tag raggiungibile da main), passa il tag di release e il preflight_run_id npm OpenClaw riuscito, e mantieni lo scope predefinito di pubblicazione plugin all-publishable a meno che tu stia deliberatamente eseguendo una riparazione mirata. Il workflow serializza la pubblicazione npm dei plugin, la pubblicazione ClawHub dei plugin e la pubblicazione npm di OpenClaw, così il pacchetto core non viene pubblicato prima dei suoi plugin esternalizzati.
  • I controlli di release ora vengono eseguiti in un workflow manuale separato: OpenClaw Release Checks
  • OpenClaw Release Checks esegue anche la lane di parità mock QA Lab più il profilo Matrix live veloce e la lane QA Telegram prima dell’approvazione della release. Le lane live usano l’ambiente qa-live-shared; Telegram usa anche i lease delle credenziali CI Convex. Esegui il workflow manuale QA-Lab - All Lanes con matrix_profile=all e matrix_shards=true quando vuoi l’inventario completo Matrix di trasporto, media ed E2EE in parallelo.
  • La validazione runtime cross-OS di installazione e aggiornamento fa parte dei workflow pubblici OpenClaw Release Checks e Full Release Validation, che chiamano direttamente il workflow riusabile .github/workflows/openclaw-cross-os-release-checks-reusable.yml
  • Questa divisione è intenzionale: mantenere il percorso reale di release npm breve, deterministico e centrato sugli artefatti, mentre i controlli live più lenti restano nella propria lane così non rallentano né bloccano la pubblicazione
  • I controlli di release con segreti devono essere avviati tramite Full Release Validation o dal workflow ref main/release, così logica del workflow e segreti restano controllati
  • OpenClaw Release Checks accetta un branch, tag o SHA completo di commit purché il commit risolto sia raggiungibile da un branch OpenClaw o da un tag di release
  • Anche la preflight solo di validazione OpenClaw NPM Release accetta lo SHA completo di 40 caratteri del commit del branch del workflow corrente senza richiedere un tag inviato
  • Quel percorso SHA è solo per validazione e non può essere promosso a una pubblicazione reale
  • In modalità SHA il workflow sintetizza v<package.json version> solo per il controllo dei metadati del pacchetto; la pubblicazione reale richiede comunque un tag di release reale
  • Entrambi i workflow mantengono il percorso reale di pubblicazione e promozione su runner GitHub-hosted, mentre il percorso di validazione non mutante può usare i runner Linux Blacksmith più grandi
  • Quel workflow esegue OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache usando entrambi i segreti del workflow OPENAI_API_KEY e ANTHROPIC_API_KEY
  • La preflight di release npm non attende più la lane separata dei controlli di release
  • Prima di taggare localmente un candidato release, esegui RELEASE_TAG=vYYYY.M.D-beta.N pnpm release:fast-pretag-check. L’helper esegue i guardrail veloci di release, i controlli di release npm/ClawHub dei plugin, build, build UI e release:openclaw:npm:check nell’ordine che intercetta gli errori comuni bloccanti per l’approvazione prima che inizi il workflow di pubblicazione GitHub.
  • Esegui RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts (o il tag beta/correzione corrispondente) prima dell’approvazione
  • Dopo la pubblicazione npm, esegui node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D (o la versione beta/correzione corrispondente) per verificare il percorso di installazione dal registry pubblicato in un prefisso temporaneo pulito
  • Dopo una pubblicazione beta, esegui OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live per verificare onboarding del pacchetto installato, configurazione Telegram ed E2E Telegram reale contro il pacchetto npm pubblicato usando il pool condiviso di credenziali Telegram in lease. Le esecuzioni locali una tantum dei maintainer possono omettere le variabili Convex e passare direttamente le tre credenziali env OPENCLAW_QA_TELEGRAM_*.
  • Per eseguire lo smoke beta post-pubblicazione completo da una macchina maintainer, usa pnpm release:beta-smoke -- --beta betaN. L’helper esegue la validazione Parallels npm update/fresh-target, avvia NPM Telegram Beta E2E, interroga l’esecuzione esatta del workflow, scarica l’artefatto e stampa il report Telegram.
  • I maintainer possono eseguire lo stesso controllo post-pubblicazione da GitHub Actions tramite il workflow manuale NPM Telegram Beta E2E. È intenzionalmente solo manuale e non viene eseguito a ogni merge.
  • L’automazione di release dei maintainer ora usa preflight-then-promote:
    • la pubblicazione npm reale deve superare un preflight_run_id npm riuscito
    • la pubblicazione npm reale deve essere avviata dallo stesso branch main o release/YYYY.M.D dell’esecuzione preflight riuscita
    • le release npm stable usano beta come predefinito
    • la pubblicazione npm stable può puntare esplicitamente a latest tramite input del workflow
    • la mutazione dei dist-tag npm basata su token ora vive in openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml per sicurezza, perché npm dist-tag add richiede ancora NPM_TOKEN mentre il repository pubblico mantiene la pubblicazione solo OIDC
    • macOS Release pubblico è solo di validazione; quando un tag vive solo su un branch di release ma il workflow è avviato da main, imposta public_release_branch=release/YYYY.M.D
    • la pubblicazione mac privata reale deve superare preflight_run_id e validate_run_id mac privati riusciti
    • i percorsi di pubblicazione reali promuovono artefatti preparati invece di ricostruirli di nuovo
  • Per release correttive stable come YYYY.M.D-N, il verificatore post-pubblicazione controlla anche lo stesso percorso di upgrade con prefisso temporaneo da YYYY.M.D a YYYY.M.D-N, così le correzioni di release non possono lasciare silenziosamente installazioni globali più vecchie sul payload stable base
  • La preflight di release npm fallisce in modo chiuso a meno che il tarball includa sia dist/control-ui/index.html sia un payload non vuoto dist/control-ui/assets/, così non spediamo di nuovo una dashboard browser vuota
  • La verifica post-pubblicazione controlla anche che entrypoint dei plugin pubblicati e metadati del pacchetto siano presenti nel layout installato dal registry. Una release che spedisce payload runtime dei plugin mancanti fallisce il verificatore postpublish e non può essere promossa a latest.
  • pnpm test:install:smoke applica anche il budget npm pack unpackedSize sul tarball di aggiornamento candidato, così l’e2e dell’installer intercetta aumenti accidentali del pacchetto prima del percorso di pubblicazione release
  • Se il lavoro di release ha toccato la pianificazione CI, i manifest di timing delle estensioni o le matrici di test delle estensioni, rigenera e rivedi gli output della matrice plugin-prerelease-extension-shard di proprietà del planner da .github/workflows/plugin-prerelease.yml prima dell’approvazione, così le note di release non descrivono un layout CI obsoleto
  • La prontezza della release macOS stable include anche le superfici dell’updater:
    • la release GitHub deve finire con i pacchetti .zip, .dmg e .dSYM.zip
    • appcast.xml su main deve puntare al nuovo zip stable dopo la pubblicazione; il workflow privato di pubblicazione macOS lo committa automaticamente, oppure apre una PR appcast quando il push diretto è bloccato
    • l’app pacchettizzata deve mantenere un bundle id non di debug, un URL del feed Sparkle non vuoto e un CFBundleVersion pari o superiore al floor canonico di build Sparkle per quella versione di release

​
Macchine di test per il rilascio

Full Release Validation è il modo in cui gli operatori avviano tutti i test pre-rilascio da un unico punto di ingresso. Per una prova di commit fissato su un ramo in rapido movimento, usa l’helper in modo che ogni workflow figlio venga eseguito da un ramo temporaneo fissato allo SHA di destinazione: 
pnpm ci:full-release --sha <full-sha>
L’helper invia release-ci/<sha>-..., avvia Full Release Validation da quel ramo con ref=<sha>, verifica che ogni headSha del workflow figlio corrisponda alla destinazione, quindi elimina il ramo temporaneo. Questo evita di provare per errore un’esecuzione figlia di main più recente. Per la validazione di un ramo o tag di rilascio, eseguila dal ref del workflow main attendibile e passa il ramo o tag di rilascio come ref: 
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N
Il workflow risolve il ref di destinazione, avvia manualmente CI con target_ref=<release-ref>, avvia OpenClaw Release Checks, prepara un artefatto padre release-package-under-test per i controlli rivolti ai pacchetti e avvia l’E2E Telegram del pacchetto standalone quando release_profile=full con rerun_group=all o quando è impostato release_package_spec oppure npm_telegram_package_spec. OpenClaw Release Checks quindi distribuisce install smoke, controlli di rilascio cross-OS, copertura live/E2E Docker del percorso di rilascio quando il soak è abilitato, Package Acceptance con QA del pacchetto Telegram, parità QA Lab, Matrix live e Telegram live. Un’esecuzione completa è accettabile solo quando il riepilogo di Full Release Validation mostra normal_ci e release_checks come riusciti. In modalità full/all, anche il figlio npm_telegram deve riuscire; fuori da full/all viene saltato a meno che non sia stato fornito un release_package_spec o npm_telegram_package_spec pubblicato. Il riepilogo finale del verificatore include tabelle dei job più lenti per ogni esecuzione figlia, così il release manager può vedere il percorso critico corrente senza scaricare i log. Vedi Validazione completa del rilascio per la matrice completa delle fasi, i nomi esatti dei job del workflow, le differenze tra profilo stabile e completo, gli artefatti e gli handle per rerun mirati. I workflow figli vengono avviati dal ref attendibile che esegue Full Release Validation, normalmente --ref main, anche quando il ref di destinazione punta a un ramo o tag di rilascio più vecchio. Non esiste un input separato per il ref del workflow Full Release Validation; scegli l’harness attendibile scegliendo il ref dell’esecuzione del workflow. Non usare --ref main -f ref=<sha> per una prova esatta del commit su main in movimento; gli SHA di commit grezzi non possono essere ref di dispatch del workflow, quindi usa pnpm ci:full-release --sha <sha> per creare il ramo temporaneo fissato. Usa release_profile per selezionare l’ampiezza live/provider:
  • minimum: il percorso live e Docker OpenAI/core critico per il rilascio più veloce
  • stable: minimum più copertura stabile di provider/backend per l’approvazione del rilascio
  • full: stable più ampia copertura advisory di provider/media
Usa run_release_soak=true con stable quando le lane bloccanti per il rilascio sono verdi e vuoi l’esecuzione esaustiva live/E2E, il percorso di rilascio Docker e lo sweep limitato di sopravvivenza all’upgrade pubblicato prima della promozione. Questo sweep copre gli ultimi quattro pacchetti stabili più le baseline fissate 2026.4.23 e 2026.5.2 più la copertura precedente 2026.4.15, con baseline duplicate rimosse e ogni baseline suddivisa nel proprio job runner Docker. full implica run_release_soak=true. OpenClaw Release Checks usa il ref del workflow attendibile per risolvere il ref di destinazione una volta come release-package-under-test e riutilizza quell’artefatto nei controlli cross-OS, Package Acceptance e Docker del percorso di rilascio quando il soak viene eseguito. Questo mantiene tutte le macchine rivolte ai pacchetti sugli stessi byte ed evita build ripetute del pacchetto. Dopo che una beta è già su npm, imposta release_package_spec=openclaw@YYYY.M.D-beta.N in modo che i controlli di rilascio scarichino una volta il pacchetto rilasciato, estraggano il suo SHA sorgente di build da dist/build-info.json e riutilizzino quell’artefatto per le lane cross-OS, Package Acceptance, Docker del percorso di rilascio e Telegram del pacchetto. L’install smoke OpenAI cross-OS usa OPENCLAW_CROSS_OS_OPENAI_MODEL quando è impostata la variabile di repo/org, altrimenti openai/gpt-5.4, perché questa lane sta provando installazione del pacchetto, onboarding, avvio del Gateway e un turno live dell’agente anziché misurare il modello predefinito più lento. La matrice più ampia dei provider live rimane il posto per la copertura specifica per modello. Usa queste varianti in base alla fase del rilascio: 
# Validate an unpublished release candidate branch.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable

# Validate an exact pushed commit.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=<40-char-sha> \
  -f provider=openai \
  -f mode=both

# After publishing a beta, add published-package Telegram E2E.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=full \
  -f release_package_spec=openclaw@YYYY.M.D-beta.N \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N \
  -f npm_telegram_provider_mode=mock-openai
Non usare l’ombrello completo come primo rerun dopo una correzione mirata. Se una macchina fallisce, usa il workflow figlio, il job, la lane Docker, il profilo del pacchetto, il provider del modello o la lane QA non riusciti per la prova successiva. Esegui di nuovo l’ombrello completo solo quando la correzione ha cambiato l’orchestrazione condivisa del rilascio o ha reso obsolete le prove precedenti di tutte le macchine. Il verificatore finale dell’ombrello ricontrolla gli id registrati delle esecuzioni dei workflow figli, quindi dopo che un workflow figlio è stato rieseguito con successo, riesegui solo il job padre non riuscito Verify full validation. Per un recupero limitato, passa rerun_group all’ombrello. all è la vera esecuzione del candidato al rilascio, ci esegue solo il figlio CI normale, plugin-prerelease esegue solo il figlio Plugin solo per rilascio, release-checks esegue ogni macchina di rilascio, e i gruppi di rilascio più ristretti sono install-smoke, cross-os, live-e2e, package, qa, qa-parity, qa-live e npm-telegram. I rerun mirati npm-telegram richiedono release_package_spec o npm_telegram_package_spec; le esecuzioni full/all con release_profile=full usano l’artefatto del pacchetto dei release-checks. I rerun cross-OS mirati possono aggiungere cross_os_suite_filter=windows/packaged-upgrade o un altro filtro OS/suite. I fallimenti QA dei release-checks sono advisory; un fallimento solo QA non blocca la validazione del rilascio.

​
Vitest

La macchina Vitest è il workflow figlio manuale CI. La CI manuale bypassa intenzionalmente lo scoping delle modifiche e forza il grafo di test normale per il candidato al rilascio: shard Linux Node, shard dei Plugin bundled, contratti dei canali, compatibilità Node 22, check, check-additional, build smoke, controlli docs, Skills Python, Windows, macOS, Android e i18n della Control UI. Usa questa macchina per rispondere a “l’albero sorgente ha superato l’intera suite di test normale?” Non è la stessa cosa della validazione del prodotto sul percorso di rilascio. Prove da conservare:
  • riepilogo di Full Release Validation che mostra l’URL dell’esecuzione CI avviata
  • esecuzione CI verde sull’esatto SHA di destinazione
  • nomi degli shard falliti o lenti dai job CI quando si indagano regressioni
  • artefatti dei tempi Vitest come .artifacts/vitest-shard-timings.json quando un’esecuzione richiede analisi delle prestazioni
Esegui la CI manuale direttamente solo quando il rilascio richiede una CI normale deterministica ma non le macchine Docker, QA Lab, live, cross-OS o pacchetto: 
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D

​
Docker

La macchina Docker vive in OpenClaw Release Checks tramite openclaw-live-and-e2e-checks-reusable.yml, più il workflow install-smoke in modalità rilascio. Valida il candidato al rilascio tramite ambienti Docker pacchettizzati invece che solo con test a livello sorgente. La copertura Docker del rilascio include:
  • install smoke completo con lo smoke di installazione globale Bun lento abilitato
  • preparazione/riutilizzo dell’immagine smoke Dockerfile root per SHA di destinazione, con job QR, root/Gateway e installer/Bun smoke eseguiti come shard install-smoke separati
  • lane E2E del repository
  • chunk Docker del percorso di rilascio: core, package-update-openai, package-update-anthropic, package-update-core, plugins-runtime-plugins, plugins-runtime-services, plugins-runtime-install-a, plugins-runtime-install-b, plugins-runtime-install-c, plugins-runtime-install-d, plugins-runtime-install-e, plugins-runtime-install-f, plugins-runtime-install-g e plugins-runtime-install-h
  • copertura OpenWebUI dentro il chunk plugins-runtime-services quando richiesta
  • lane split di installazione/disinstallazione dei Plugin bundled da bundled-plugin-install-uninstall-0 a bundled-plugin-install-uninstall-23
  • suite provider live/E2E e copertura del modello live Docker quando i controlli di rilascio includono suite live
Usa gli artefatti Docker prima di rieseguire. Lo scheduler del percorso di rilascio carica .artifacts/docker-tests/ con log di lane, summary.json, failures.json, tempi di fase, JSON del piano dello scheduler e comandi di rerun. Per un recupero mirato, usa docker_lanes=<lane[,lane]> sul workflow riutilizzabile live/E2E invece di rieseguire tutti i chunk di rilascio. I comandi di rerun generati includono i precedenti package_artifact_run_id e gli input delle immagini Docker preparate quando disponibili, così una lane non riuscita può riutilizzare lo stesso tarball e le stesse immagini GHCR.

​
QA Lab

La macchina QA Lab fa anch’essa parte di OpenClaw Release Checks. È il gate di rilascio per il comportamento agentico e a livello di canale, separato da Vitest e dai meccanismi dei pacchetti Docker. La copertura QA Lab del rilascio include:
  • lane di parità mock che confronta la lane candidata OpenAI con la baseline Opus 4.6 usando il pack di parità agentica
  • profilo QA Matrix live veloce usando l’ambiente qa-live-shared
  • lane QA Telegram live usando lease di credenziali CI Convex
  • pnpm qa:otel:smoke quando la telemetria di rilascio richiede prova locale esplicita
Usa questa macchina per rispondere a “il rilascio si comporta correttamente negli scenari QA e nei flussi dei canali live?” Conserva gli URL degli artefatti per le lane parità, Matrix e Telegram quando approvi il rilascio. La copertura completa Matrix rimane disponibile come esecuzione QA-Lab manuale suddivisa in shard anziché come lane critica predefinita per il rilascio.

​
Pacchetto

La macchina Package è il gate del prodotto installabile. È supportata da Package Acceptance e dal resolver scripts/resolve-openclaw-package-candidate.mjs. Il resolver normalizza un candidato nel tarball package-under-test consumato da Docker E2E, valida l’inventario del pacchetto, registra la versione del pacchetto e SHA-256, e mantiene il ref dell’harness del workflow separato dal ref sorgente del pacchetto. Sorgenti candidate supportate:
  • source=npm: openclaw@beta, openclaw@latest o una versione esatta di rilascio OpenClaw
  • source=ref: pacchettizza un ramo package_ref, tag o SHA di commit completo attendibile con l’harness workflow_ref selezionato
  • source=url: scarica un .tgz HTTPS con package_sha256 richiesto
  • source=artifact: riutilizza un .tgz caricato da un’altra esecuzione GitHub Actions
OpenClaw Release Checks esegue Package Acceptance con source=artifact, l’artefatto del pacchetto di rilascio preparato, suite_profile=custom, docker_lanes=doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update, telegram_mode=mock-openai. Package Acceptance mantiene migrazione, aggiornamento, riavvio dell’aggiornamento con autenticazione configurata, installazione live di Skill ClawHub, pulizia delle dipendenze obsolete dei Plugin, fixture dei Plugin offline, aggiornamento dei Plugin e QA del pacchetto Telegram rispetto allo stesso tarball risolto. I controlli di rilascio bloccanti usano la baseline predefinita dell’ultimo pacchetto pubblicato; run_release_soak=true o release_profile=full si espande a ogni baseline stabile pubblicata su npm da 2026.4.23 fino a latest più le fixture dei problemi segnalati. Usa Package Acceptance con source=npm per un candidato già distribuito, oppure source=ref/source=artifact per un tarball npm locale basato su SHA prima della pubblicazione. È il sostituto nativo di GitHub per la maggior parte della copertura di pacchetto/aggiornamento che in precedenza richiedeva Parallels. I controlli di rilascio cross-OS restano importanti per onboarding, installer e comportamento di piattaforma specifici del sistema operativo, ma la convalida prodotto di pacchetto/aggiornamento dovrebbe preferire Package Acceptance. La checklist canonica per la convalida di aggiornamenti e Plugin è Test degli aggiornamenti e dei Plugin. Usala quando decidi quale lane locale, Docker, Package Acceptance o di controllo rilascio dimostra una modifica di installazione/aggiornamento di Plugin, pulizia doctor o migrazione di pacchetto pubblicato. La migrazione esaustiva degli aggiornamenti pubblicati da ogni pacchetto stabile 2026.4.23+ è un workflow manuale Update Migration separato, non parte della Full Release CI. La tolleranza legacy di package-acceptance è intenzionalmente limitata nel tempo. I pacchetti fino a 2026.4.25 possono usare il percorso di compatibilità per lacune nei metadati già pubblicate su npm: voci dell’inventario QA privato assenti dal tarball, gateway install --wrapper mancante, file di patch mancanti nella fixture git derivata dal tarball, update.channel persistito mancante, posizioni legacy dei record di installazione dei Plugin, persistenza mancante dei record di installazione del marketplace e migrazione dei metadati di configurazione durante plugins update. Il pacchetto 2026.4.26 pubblicato può avvisare per file di timbro dei metadati di build locali già distribuiti. I pacchetti successivi devono soddisfare i contratti moderni dei pacchetti; quelle stesse lacune fanno fallire la convalida del rilascio. Usa profili Package Acceptance più ampi quando la domanda sul rilascio riguarda un pacchetto effettivamente installabile: 
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f published_upgrade_survivor_baseline=openclaw@2026.4.26
Profili di pacchetto comuni:
  • smoke: lane rapide di installazione pacchetto/canale/agente, rete Gateway e ricaricamento della configurazione
  • package: contratti di pacchetto per installazione/aggiornamento/riavvio/Plugin più prova live di installazione Skill ClawHub; è il valore predefinito dei controlli di rilascio
  • product: package più canali MCP, pulizia cron/subagent, ricerca web OpenAI e OpenWebUI
  • full: chunk Docker del percorso di rilascio con OpenWebUI
  • custom: elenco esatto docker_lanes per riesecuzioni mirate
Per la prova Telegram di un candidato pacchetto, abilita telegram_mode=mock-openai o telegram_mode=live-frontier in Package Acceptance. Il workflow passa il tarball package-under-test risolto nella lane Telegram; il workflow Telegram autonomo accetta ancora una specifica npm pubblicata per controlli post-pubblicazione.

​
Automazione della pubblicazione del rilascio

OpenClaw Release Publish è il normale punto di ingresso mutante per la pubblicazione. Orchestri i workflow trusted-publisher nell’ordine richiesto dal rilascio:
  1. Esegue il checkout del tag di rilascio e ne risolve lo SHA del commit.
  2. Verifica che il tag sia raggiungibile da main o release/*.
  3. Esegue pnpm plugins:sync:check.
  4. Esegue il dispatch di Plugin NPM Release con publish_scope=all-publishable e ref=<release-sha>.
  5. Esegue il dispatch di Plugin ClawHub Release con lo stesso ambito e SHA.
  6. Esegue il dispatch di OpenClaw NPM Release con il tag di rilascio, il dist-tag npm e il preflight_run_id salvato.
Esempio di pubblicazione beta: 
gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D-beta.N \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=beta
Pubblicazione stabile sul dist-tag beta predefinito: 
gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=beta
La promozione stabile direttamente a latest è esplicita: 
gh workflow run openclaw-release-publish.yml \
  --ref release/YYYY.M.D \
  -f tag=vYYYY.M.D \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f npm_dist_tag=latest
Usa i workflow di livello inferiore Plugin NPM Release e Plugin ClawHub Release solo per lavori mirati di riparazione o ripubblicazione. Per una riparazione di Plugin selezionata, passa plugin_publish_scope=selected e plugins=@openclaw/name a OpenClaw Release Publish, oppure esegui direttamente il dispatch del workflow figlio quando il pacchetto OpenClaw non deve essere pubblicato.

​
Input del workflow NPM

OpenClaw NPM Release accetta questi input controllati dall’operatore:
  • tag: tag di rilascio obbligatorio come v2026.4.2, v2026.4.2-1 o v2026.4.2-beta.1; quando preflight_only=true, può essere anche lo SHA di commit completo a 40 caratteri del branch del workflow corrente per un preflight di sola convalida
  • preflight_only: true solo per convalida/build/pacchetto, false per il percorso di pubblicazione reale
  • preflight_run_id: obbligatorio nel percorso di pubblicazione reale affinché il workflow riutilizzi il tarball preparato dalla run di preflight riuscita
  • npm_dist_tag: tag npm di destinazione per il percorso di pubblicazione; il valore predefinito è beta
OpenClaw Release Publish accetta questi input controllati dall’operatore:
  • tag: tag di rilascio obbligatorio; deve già esistere
  • preflight_run_id: id della run di preflight OpenClaw NPM Release riuscita; obbligatorio quando publish_openclaw_npm=true
  • npm_dist_tag: tag npm di destinazione per il pacchetto OpenClaw
  • plugin_publish_scope: valore predefinito all-publishable; usa selected solo per lavori di riparazione mirati
  • plugins: nomi di pacchetti @openclaw/* separati da virgole quando plugin_publish_scope=selected
  • publish_openclaw_npm: valore predefinito true; imposta false solo quando usi il workflow come orchestratore di riparazione solo Plugin
  • wait_for_clawhub: valore predefinito false, così la disponibilità npm non è bloccata dal sidecar ClawHub; imposta true solo quando il completamento del workflow deve includere il completamento di ClawHub
OpenClaw Release Checks accetta questi input controllati dall’operatore:
  • ref: branch, tag o SHA di commit completo da convalidare. I controlli che richiedono segreti richiedono che il commit risolto sia raggiungibile da un branch OpenClaw o da un tag di rilascio.
  • run_release_soak: abilita soak esaustivo live/E2E, percorso di rilascio Docker e upgrade-survivor da tutte le versioni sui controlli di rilascio stabili/predefiniti. Viene forzato da release_profile=full.
Regole:
  • I tag stabili e di correzione possono essere pubblicati su beta o latest
  • I tag di prerelease beta possono essere pubblicati solo su beta
  • Per OpenClaw NPM Release, l’input SHA di commit completo è consentito solo quando preflight_only=true
  • OpenClaw Release Checks e Full Release Validation sono sempre solo di convalida
  • Il percorso di pubblicazione reale deve usare lo stesso npm_dist_tag usato durante il preflight; il workflow verifica quei metadati prima che la pubblicazione continui

​
Sequenza di rilascio npm stabile

Quando prepari un rilascio npm stabile:
  1. Esegui OpenClaw NPM Release con preflight_only=true
    • Prima che esista un tag, puoi usare lo SHA di commit completo del branch del workflow corrente per una prova generale di sola convalida del workflow di preflight
  2. Scegli npm_dist_tag=beta per il normale flusso beta-first, oppure latest solo quando vuoi intenzionalmente una pubblicazione stabile diretta
  3. Esegui Full Release Validation sul branch di rilascio, sul tag di rilascio o sullo SHA di commit completo quando vuoi CI normale più copertura live di prompt cache, Docker, QA Lab, Matrix e Telegram da un unico workflow manuale
  4. Se hai intenzionalmente bisogno solo del grafo di test normale deterministico, esegui invece il workflow manuale CI sul ref di rilascio
  5. Salva il preflight_run_id riuscito
  6. Esegui OpenClaw Release Publish con lo stesso tag, lo stesso npm_dist_tag e il preflight_run_id salvato; pubblica i Plugin esternalizzati su npm e ClawHub prima di promuovere il pacchetto npm OpenClaw
  7. Se il rilascio è arrivato su beta, usa il workflow privato openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml per promuovere quella versione stabile da beta a latest
  8. Se il rilascio è stato intenzionalmente pubblicato direttamente su latest e beta dovrebbe seguire immediatamente la stessa build stabile, usa lo stesso workflow privato per puntare entrambi i dist-tag alla versione stabile, oppure lascia che la sua sincronizzazione self-healing pianificata sposti beta più tardi
La mutazione del dist-tag vive nel repository privato per sicurezza perché richiede ancora NPM_TOKEN, mentre il repository pubblico mantiene la pubblicazione solo OIDC. Questo mantiene sia il percorso di pubblicazione diretta sia il percorso di promozione beta-first documentati e visibili all’operatore. Se un maintainer deve ripiegare sull’autenticazione npm locale, esegui qualsiasi comando 1Password CLI (op) solo dentro una sessione tmux dedicata. Non chiamare op direttamente dalla shell dell’agente principale; tenerlo dentro tmux rende prompt, avvisi e gestione OTP osservabili e previene avvisi host ripetuti.

​
Riferimenti pubblici

I maintainer usano la documentazione privata dei rilasci in openclaw/maintainers/release/README.md per il runbook effettivo.

​
Correlati