OpenClaw Release-Guide: Versionierung und Deployment

Als Entwickler kennst du das sicher: Das manuelle Veröffentlichen von Software kann schnell zu einem fehleranfälligen Prozess werden, bei dem man leicht den Überblick über Versionen oder Abhängigkeiten verliert. Ein klar definierter Release-Prozess hilft dabei, Frustration zu vermeiden und sicherzustellen, dass jede Version stabil bei den Nutzern ankommt.

Mit OpenClaw verwaltest du deine Releases effizient und stellst sicher, dass sowohl das npm-Paket als auch die macOS-App immer synchron und einsatzbereit sind.

Versionsbenennung

Die Versionsnummern folgen einem klaren Schema, um den Status jeder Veröffentlichung sofort erkennbar zu machen.

1. Stable Release Version: YYYY.M.D
   • Git tag: vYYYY.M.D
2. Stable Correction Release Version: YYYY.M.D-N
   • Git tag: vYYYY.M.D-N
3. Beta Prerelease Version: YYYY.M.D-beta.N
   • Git tag: vYYYY.M.D-beta.N
4. Monat und Tag werden nicht mit einer führenden Null aufgefüllt.
5. latest bezeichnet das aktuell geförderte, stabile npm-Release.
6. beta ist das aktuelle Installationsziel für Beta-Versionen.
7. Stable- und Korrektur-Releases werden standardmäßig auf npm als beta veröffentlicht; Release-Operatoren können explizit latest wählen oder einen geprüften Beta-Build später hochstufen.
8. Jedes OpenClaw-Release liefert das npm-Paket und die macOS-App gemeinsam aus.

Release-Zyklus

Der Prozess ist darauf ausgelegt, Stabilität durch eine klare Abfolge von Tests und Validierungen zu gewährleisten.

1. Releases werden zuerst als Beta veröffentlicht.
2. Ein Stable-Release folgt erst, nachdem die neueste Beta erfolgreich validiert wurde.
3. Detaillierte Release-Verfahren, Freigaben, Anmeldedaten und Wiederherstellungshinweise sind ausschließlich für Maintainer zugänglich.

Release-Preflight

Bevor ein Release veröffentlicht wird, müssen verschiedene Prüfungen durchlaufen werden, um die Qualität sicherzustellen.

1. Führe pnpm check:test-types vor dem Preflight aus, damit die TypeScript-Tests außerhalb des schnelleren lokalen pnpm check-Gates abgedeckt bleiben.
2. Führe pnpm check:architecture vor dem Preflight aus, damit die Architektur-Grenzen und Import-Zyklen außerhalb des lokalen Gates grün sind.
3. Führe pnpm build && pnpm ui:build vor pnpm release:check aus, damit die erwarteten dist/* Release-Artefakte und das Control UI Bundle für die Validierung existieren.
4. Führe pnpm release:check vor jedem getaggten Release aus.
5. Release-Prüfungen laufen jetzt in einem separaten manuellen Workflow: OpenClaw Release Checks.
6. Die plattformübergreifende Installations- und Upgrade-Validierung wird vom privaten Caller-Workflow openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml gestartet, welcher den wiederverwendbaren öffentlichen Workflow .github/workflows/openclaw-cross-os-release-checks-reusable.yml aufruft.
7. Diese Trennung ist beabsichtigt: Der eigentliche npm-Release-Pfad bleibt kurz und deterministisch, während langsamere Live-Prüfungen in ihrer eigenen Spur laufen, um den Publish-Prozess nicht zu blockieren.
8. Release-Prüfungen müssen vom GitHub-Workflow-Ref main gestartet werden, damit Logik und Secrets konsistent bleiben.
9. Der Workflow akzeptiert entweder ein existierendes Release-Tag oder den aktuellen 40-stelligen main-Commit-SHA.
10. Im Commit-SHA-Modus wird nur der aktuelle origin/main HEAD akzeptiert; verwende für ältere Commits ein Release-Tag.
11. Der OpenClaw NPM Release Validierungs-Preflight akzeptiert ebenfalls den aktuellen 40-stelligen main-Commit-SHA ohne ein gepushtes Tag.
12. Dieser SHA-Pfad dient nur der Validierung und kann nicht in ein echtes Release befördert werden.
13. Im SHA-Modus synthetisiert der Workflow v<package.json version> nur für die Paket-Metadatenprüfung; ein echtes Release erfordert ein echtes Tag.
14. Beide Workflows nutzen für den eigentlichen Publish GitHub-gehostete Runner, während der Validierungspfad die größeren Blacksmith Linux-Runner verwenden kann.
15. Der Workflow führt folgenden Befehl aus:

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

16. Hierbei werden die Workflow-Secrets OPENAI_API_KEY und ANTHROPIC_API_KEY verwendet.
17. Der npm-Release-Preflight wartet nicht mehr auf die separate Release-Prüfspur.
18. Führe vor der Freigabe folgenden Befehl aus:

RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts

19. Nach dem npm-Publish führe diesen Befehl aus, um den Installationspfad in einem frischen Temp-Präfix zu verifizieren:

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D

20. Die Release-Automatisierung nutzt nun das Prinzip “Preflight-then-Promote”.
21. Bei Stable-Korrektur-Releases wie YYYY.M.D-N prüft der Post-Publish-Verifier auch den Upgrade-Pfad von YYYY.M.D auf YYYY.M.D-N.
22. Der npm-Release-Preflight schlägt fehl, wenn das Tarball nicht sowohl dist/control-ui/index.html als auch ein nicht leeres dist/control-ui/assets/ enthält.
23. pnpm test:install:smoke erzwingt zudem das npm-Pack unpackedSize-Budget.
24. Wenn die Release-Arbeit CI-Planungen oder Test-Matrizen berührt hat, müssen die checks-node-extensions Workflow-Outputs aus .github/workflows/ci.yml vor der Freigabe regeneriert und geprüft werden.
25. Die Stabilität des macOS-Releases umfasst auch die Updater-Oberflächen: Das GitHub-Release muss das gepackte .zip, .dmg und .dSYM.zip enthalten, und appcast.xml auf main muss nach dem Publish auf das neue Stable-Zip zeigen.

NPM Workflow-Eingaben

Die Workflows für OpenClaw akzeptieren spezifische Eingaben, um den Release-Prozess zu steuern.

1. OpenClaw NPM Release akzeptiert:
   • tag: Erforderliches Release-Tag (z. B. v2026.4.2). Bei preflight_only=true auch der 40-stellige main-Commit-SHA.
   • preflight_only: true für reine Validierung/Build/Package, false für den echten Publish-Pfad.
   • preflight_run_id: Erforderlich auf dem Publish-Pfad zur Wiederverwendung des Tarballs.
   • npm_dist_tag: npm-Ziel-Tag; Standard ist beta.
2. OpenClaw Release Checks akzeptiert:
   • ref: Existierendes Release-Tag oder der 40-stellige main-Commit-SHA zur Validierung.
3. Regeln:
   • Stable- und Korrektur-Tags können auf beta oder latest veröffentlicht werden.
   • Beta-Prerelease-Tags dürfen nur auf beta veröffentlicht werden.
   • Der volle Commit-SHA ist nur bei preflight_only=true erlaubt.
   • Der Publish-Pfad muss dasselbe npm_dist_tag wie beim Preflight verwenden.

Stabiler NPM Release-Ablauf

Folge diesen Schritten, um ein stabiles npm-Release sicher durchzuführen.

1. Starte OpenClaw NPM Release mit preflight_only=true.
2. Wähle npm_dist_tag=beta für den Standard-Beta-First-Pfad oder latest für ein direktes Stable-Release.
3. Starte OpenClaw Release Checks separat mit demselben Tag oder dem aktuellen main-Commit-SHA.
4. Speichere die erfolgreiche preflight_run_id.
5. Starte OpenClaw NPM Release erneut mit preflight_only=false, demselben tag, dem npm_dist_tag und der gespeicherten preflight_run_id.
6. Falls das Release auf beta gelandet ist, nutze den privaten Workflow openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml, um die Version von beta auf latest zu befördern.
7. Wenn das Release direkt auf latest veröffentlicht wurde, nutze denselben privaten Workflow, um beide Dist-Tags auf die stabile Version zu setzen.

Öffentliche Referenzen

Hier findest du die relevanten Dateien und Skripte für den Release-Prozess.

• .github/workflows/openclaw-npm-release.yml
• .github/workflows/openclaw-release-checks.yml
• .github/workflows/openclaw-cross-os-release-checks-reusable.yml
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

Nächste Schritte

• Release-Check-Automatisierung verstehen
• CI/CD-Pipelines konfigurieren

AI Setup Assistant