UNPKG

openclaw

Version:

Multi-channel AI gateway with extensible messaging integrations

github.com/openclaw/openclaw

openclaw/openclaw

321 lines (232 loc) • 17.5 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
--- doc-schema-version: 1 summary: "OpenClaw release channels, version numbers, validation, and published assets" title: "Release policy" read_when: - Choosing a release channel - Understanding version numbers and release checks - Checking which packages and apps have been published --- OpenClaw offers stable releases for everyday use, beta releases for testing, and extended-stable releases for users who prefer an older Gateway maintenance line. This page explains those choices and what a release has been checked for. For switching channels, see [Release channels](/install/development-channels). ## Release channels | Channel | What you get | | --------------- | --------------------------------------------------------------------------------------------------------- | | Stable | The regular release promoted to npm `latest`. | | Beta | A candidate on npm `beta`. This may be a prerelease or a final version awaiting promotion. | | Extended-stable | A Gateway maintenance release from either of the two trailing completed months, on npm `extended-stable`. | | Dev | The moving head of `main`, for development. | Extended-stable includes the Gateway, official npm plugins, and Docker images. It does not include native apps or ClawHub publication, and it does not change the regular stable channel. Its GitHub release is not marked Latest. A monthly line retires when it falls outside the two supported completed months. ## Version naming | Release | Version example | | ------------------ | --------------------------------------------------------------------- | | Regular final | `2026.9.6` | | Beta prerelease | `2026.9.6-beta.1` | | Regular correction | `2026.9.6-1` | | Extended-stable | `2026.8.33`, followed by `2026.8.34` for its next maintenance release | Versions use `year.month.patch`, without zero-padding. The patch is a release number within the month, not a day of the month. Regular releases use patches below `33`; extended-stable starts at `33`. Git tags add `v`, as in `v2026.9.6`. Release tags are annotated and signed. The shared publication workflow verifies the tag signature before checkout or evidence downloads and refuses lightweight, unsigned, or unverified tags. This also applies to recovery and republishing: historical unsigned tags are not eligible for the shared publication workflow, and recovery must use a new signed release version rather than replacing a tag. Published npm versions and release tags are never replaced. A fix receives a new version. Historical alpha-only versions do not advance the regular release number; alpha releases are retired. ## Release cadence Releases normally go to beta first and move to stable after validation. For core and every published official npm plugin, `beta` must be at least as new as `latest`; an already newer beta stays unchanged. A prerelease is older than the final version with the same base number. A final version published to the beta channel still has to meet the stable validation requirements below. The npm channel alone does not determine which checks apply. ## Release validation Stable publication requires stable or full validation, longer-running soak tests, and blocking performance checks. These requirements also apply to a final version first published on the beta channel. Beta-profile evidence cannot qualify stable. Every failed test needs an explicit release-lead decision: blocker or flake. Rerun a flake on the same Release SHA at most twice, file its fix-in-parallel issue or PR on `main`, and retain the original failure. Do not re-cut, change tooling, or start another Full Release Validation solely to clear a flake; a selected job that remains red blocks publication. Blocking jobs include the CI coverage gate, seal/evidence, Build Artifacts, install smoke, survivor lanes, `update-first-hop-compat*`, pack/npm qualification, package integrity, and all Linux/Windows/macOS Gateway checks, including Windows packaged install/upgrade checks in Release Checks. A cancelled run still blocks. The selected `openclaw/ci-gate` must succeed; failed, missing, skipped, or cancelled coverage blocks. Publication waivers cannot bypass failures or required coverage. Validation covers source CI, packages, plugins, Gateway installs and upgrades, and selected app, UI, Telegram, QA, and live-provider checks. All-group qualification includes all nine Gateway install/upgrade combinations across Linux, Windows, and macOS. Coverage otherwise varies by profile and selected operating systems. Check the release's recorded coverage: skipped or deferred checks are not passes. Dependency advisories never block or delay a release. Release dependency evidence records every advisory finding, at any severity, and CI dispatched by release validation or publication reports a failing dependency audit as a warning. The dependency fix ships through `main` after publication. Only a known-malware finding stops publication. The health of `main` CI does not gate a release. Validation and publication run from the release branch with pinned release tooling, so a red `main` is not a reason to wait, re-cut, or pause. See [Full release validation](/reference/full-release-validation) for coverage by profile and how to interpret the results. ### Frozen qualification identity New candidate qualification records three separate identities: - **C — candidate:** the exact commit whose source and publication bytes are checked. - **Q — qualification:** the full workflow closure at C, including reusable workflows, local actions, scripts, planners, contracts, and coverage data. By default **Q=C**. - **P — admission, verification, and publication tooling:** an independently trusted main revision or protected publication tag. P may differ from C/Q; C/Q does not need to be an ancestor of P. Trust in P does not replace qualification of C. The canonical SHA-pinned helper first asks P to record the reviewed operator attestation, complete normalized inputs, and data-only frozen Q coverage in an immutable admission artifact. Only then does that same helper dispatch Full Release Validation from an immutable `release-ci/*` ref at Q. A publication `release-publish/*` tag belongs to P, never to Q merely to make validation run. Admission is not a successful test result or publication approval. A candidate missing the required qualification contracts needs a deliberate backport. The helper does not silently use future-main checks or import main-only scenarios. A repair to the qualification harness changes C and Q and requires newly bound evidence; a P-only verifier/publisher repair can preserve C/Q and their original artifacts. Explicit trusted-main or protected-tag cross-revision validation is limited to diagnostic, main-qualification, and postpublish-confidence requests. It cannot supply new final candidate qualification. Existing historical publish requests keep their original meaning and remain recoverable. New publish qualification requires admitted Q=C. Evidence reuse preserves both the original producer identity and the current consumer identity, inputs, coverage, and artifact provenance. It cannot relabel an old run as candidate-owned. Reconciliation is read-only; explicit resume is limited to a candidate request before any qualification-ref mutation or FRV dispatch. An uncertain write never authorizes another dispatch. All publication gates, stable soak, blocking performance, environment approvals, and exact-byte checks remain unchanged. Local contract tests can prove input binding, refusal, and recovery behavior. They do not prove hosted workflow admission, environment access, OIDC, signing, or publication. Report hosted evidence and untested deployment prerequisites separately; a local green check is not a hosted release receipt. ## Packages and apps can become available at different times A published Gateway release does not mean every native app is ready. Signing and publishing the apps can finish separately from npm, Docker, and the GitHub release. Check the release's assets and announcements for each platform. A pending app build or an accepted publication request is not a completed app release. Extended-stable is a Gateway distribution and does not publish native apps. ## Release notes and verification The [release notes](/releases) describe user-facing changes. GitHub releases also carry validation results, dependency reports, and checks of the published packages. These records identify the tested version and the files that shipped. Later documentation updates may improve the release notes without rebuilding or replacing packages. For dependency review, see [Dependency locking](/gateway/security/dependency-locking). Release dependency archives include npm-format locks separately from the package tarballs. ### Downstream packaging To consume a release lock: 1. Download `openclaw-<version>-dependency-evidence.zip` from the GitHub release. Open `dependency-evidence/npm-package-locks.json` (`schemaVersion: 1`) and select the `packages` entry matching the exact package `name` and `version`. 2. Reject entries with a nonempty `omittedWorkspaceDependencies` array. These are partial locks: the generator omits sibling `workspace:` runtime dependencies that publish in the same release. The report counts these entries in `packagesWithOmittedWorkspaceDependencies`. 3. Verify that `dependency-evidence/dependency-evidence-manifest.json`'s `releaseSha`, the report's `sourceSha`, and the OpenClaw commit you pin all match. The report also records the source `pnpm-lock.yaml` SHA-256. 4. Serialize `entry.lock` as `package-lock.json` using two-space JSON indentation and a trailing newline, then verify its SHA-256 against `entry.lockSha256`. 5. Before `npm ci`, carry the source `pnpm-workspace.yaml` overrides into the consuming `package.json`, or rewrite nested `dependencies` and `optionalDependencies` specs to their locked versions. The generated locks encode workspace overrides, so unmodified specs can fail npm's lock-sync check. The companion `npm-package-locks.md` includes counts and a package table. Each entry records `bundleRuntimeDependencies` and direct dependency counts so packagers can identify lockless packages that need an external lock. Each entry also records a path-sorted `bundledDependencies` array with `path`, `name`, `version`, and `parent`. These dependencies carry `inBundle: true` in the npm lock; `parent` identifies the nearest enclosing non-bundled package whose `resolved` and `integrity` verify the tarball carrying their bytes. The report rejects missing or unverifiable carriers and preserves the lock payload. The Markdown table counts bundled dependencies per package and includes their total. ## Maintainer procedures Release preparation, publishing commands, approvals, and recovery live in the [release-maintainer skill](https://github.com/openclaw/openclaw/tree/main/.agents/skills/release-openclaw-maintainer). Credential handling and emergency procedures remain in the private maintainer runbook. Former section links below lead to their corresponding procedures. <a id="linux-companion-publication" /> [Linux publication](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/platform-publication.md#linux). <a id="release-changelog-artifacts" /> [Release changelogs](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/preparation.md#changelog-and-release-notes). <a id="changelog-only-evidence-reuse" /> [Changelog-only qualification](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#qualify-publication-bytes). <a id="monthly-gateway-extended-stable-publication" /> <a id="prepare-and-stabilize-the-candidate" /> <a id="publish-the-npm-packages" /> <a id="publish-the-release" /> [Extended-stable preparation and publication](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/extended-stable-publish.md). <a id="verify-and-recover" /> [Extended-stable recovery](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/extended-stable-publish.md#trusted-main-npm-recovery). <a id="regular-release-operator-checklist" /> <a id="fast-path-default" /> <a id="fast-path-(default)" /> <a id="stable-release-process" /> <a id="full-checklist" /> <a id="manual-fallback" /> [Regular release checklist](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#freeze-and-validate-code). <a id="orchestrated-stable-release" /> [Resumable release orchestration](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#orchestrated-stable-release). <a id="release-priority" /> [Deferred CI recovery](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-ci/SKILL.md#deferred-ci-recovery). <a id="continuous-release-readiness" /> [Nightly validation reuse](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-ci/SKILL.md#continuous-release-readiness). <a id="release-tooling-fast-lane" /> [Release tooling CI scope](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-ci/SKILL.md#release-tooling-fast-lane). <a id="stable-main-closeout" /> [Stable main closeout](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/stable-main-closeout.md). <a id="post-release-documentation-publication" /> [Post-release documentation publication](https://github.com/openclaw/openclaw/blob/main/.agents/skills/openclaw-changelog-update/SKILL.md#post-release-docs-mirrors). <a id="release-preflight" /> <a id="required-checks" /> [Source and package gates](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/validation.md#source-and-package-gates). <a id="previous-updater-compatibility" /> [Older updater verification](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/validation.md#older-updater-checks). <a id="design-proposal%3A-immutable-runtime-generations" /> <a id="design-proposal-immutable-runtime-generations" /> [Runtime generation design proposal (not shipped behavior)](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/validation.md#immutable-runtime-generation-proposal). <a id="release-test-boxes" /> <a id="vitest" /> <a id="docker" /> <a id="qa-lab" /> [Release validation lanes](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-ci/SKILL.md#dispatch). <a id="package" /> [Package Acceptance](/ci/release-validation/package-acceptance). <a id="regular-release-publish-automation" /> <a id="check-publication-gates" /> [Publication qualification](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#qualify-publication-bytes). <a id="probe-the-bootstrap-token" /> [Bootstrap-token verification](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/publication-recovery.md#check-the-bootstrap-token). <a id="prepare-once%2C-then-use-the-release-button" /> <a id="prepare-once-then-use-the-release-button" /> [Prepared publication](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#prepared-publication). <a id="recover-a-failed-download" /> [Interrupted preparation and publication](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/publication-recovery.md#interrupted-preparation-and-publication). <a id="direct-publication-and-owner-recovery" /> [Published-version recovery](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/publication-recovery.md#published-version-failed-parent). <a id="npm-workflow-inputs" /> <a id="regular-beta%2Flatest-stable-release-sequence" /> <a id="regular-beta/latest-stable-release-sequence" /> [Regular publication and verification](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-maintainer/references/regular-release.md#publish-and-verify). <a id="publication-modes%3A-strict-default-and-operator-fast-path" /> <a id="publication-modes-strict-default-and-operator-fast-path" /> <a id="publication-requirements" /> [Publication requirements](https://github.com/openclaw/openclaw/blob/main/.agents/skills/release-openclaw-ci/SKILL.md#publication-requirements). <a id="public-references" /> <a id="related" /> [Release workflow reference](/reference/full-release-validation).