Three defects proven by running the shipped configs:
Kubernetes probes checked only the status code against /startupz, but the
pinned image predates that route and the Control UI answers unknown paths
with a catch-all 200. A wedged pod was therefore marked Ready forever.
Probes now assert the JSON probe contract and target routes the pinned
image actually serves; verified in a kind cluster where the old command
exits 0 on the missing route and the new one exits 1.
render.yaml set no dockerCommand, so the image CMD ran without
--allow-unconfigured and a fresh Render disk exited 78 with 'Missing
config' before binding. Reproduced locally with Render's exact env.
The Cloudflare Container readiness poll had the same route mismatch
against operator-supplied official image digests; it now polls /healthz,
which every published image serves.
Also replaces an R2 verification step that could never fail: wrangler
cannot list object keys, so the documented command 404'd into || true.
The template shipped without the operator-facing half: no way to prove the
restore path works before depending on it, no cost signal for the always-on
versus webhook-only choice, no log surfaces, and no failure-mode index.
Adds an architecture diagram, a restore rehearsal, measured recovery numbers
from the real-R2 proof, provisioned-resource cost guidance, wrangler tail
observability, and a troubleshooting index covering image architecture,
Litestream S3 credentials, the startupz/readyz split, and ephemeral-disk
config loss.
* feat(deploy): add experimental Cloudflare template
* fix(deploy): keep container SSH debug access opt-in
* fix(deploy): satisfy scripts tsgo lane and model wrangler entrypoint in knip
* fix(deploy): model wrangler-consumed exports and isolated dependency in knip
The Worker default export and Durable Object class are instantiated by
wrangler from wrangler.jsonc, and @cloudflare/containers lives in the
template's isolated package.json — modeled per the deadcode checks' own
guidance rather than root-manifest changes.
* docs(deploy): align SSH bootstrap flow with the disabled-by-default policy
* fix(channels): validate headless channel setup
* docs(channels): document headless provisioning
* fix(channels): repair setup metadata typing
* chore(channels): regenerate official channel catalog for env metadata
* fix(slack): keep mode-conditional env contract plugin-owned
Static --use-env declaration keeps only the unconditional SLACK_BOT_TOKEN;
socket-vs-HTTP conditional requirements (app token, signing secret) stay in
Slack's own setup validation so HTTP mode no longer demands an irrelevant
SLACK_APP_TOKEN.
* chore(sdk): regenerate api baselines and catalog after rebase
* fix(slack): align manifest env declaration with runtime contract
* chore(sdk): regenerate api baselines after rebase
* chore(sdk): regenerate api baselines after rebase
* chore(sdk): regenerate api baselines after rebase
* refactor(infra): extract shared git exec and verified snapshot-copy helpers
Moves the worktrees git wrapper to src/infra/git-exec.ts (with optional
maxOutputBytes for large buffered reads) and the online-backup/sanitize/
VACUUM/verify snapshot step into src/snapshot/openclaw-snapshot-copy.ts so
snapshot backends share one hardened copy path. Behavior-identical moves;
all importers updated.
* feat(snapshot): git-backed versioned SQLite snapshot engine
Deterministic per-table JSONL dumps (PK-ordered, lossless bigint/blob
encoding), verbatim DDL preservation, virtual/shadow-table skipping with
FTS rebuild on restore, secret-table redaction policy, manifest with
per-table row counts and content hashes, and restore verification by
re-serialization. Unchanged data produces no commit.
* feat(backup): recorded runs, freshness surfacing, and scheduled git backups
Every backup attempt is recorded in the previously writer-less backup_runs
table (bounded to 200 rows). openclaw status gains a Backups overview row
and JSON payload; doctor prints an informational hint when no successful
backup is recorded or the newest is stale. New commands: backup git
init/create/log/verify/restore and backup enable/disable, which provision
one idempotent gateway cron job running scheduled git backups.
* fix(state): stop bumping schema_meta.updated_at on unchanged opens
updated_at now records when schema metadata actually changed instead of
when the database was last opened; unconditional bumps dirtied the row on
every open and defeated no-change backup detection.
* docs: document versioned git backups, scheduling, and backup freshness
* fix(backup): satisfy CI ownership checks
* fix(backup): complete CI contract coverage
* fix(backup): complete credential table redaction
* fix(backup): isolate git repository ownership
* fix(backup): persist push degradation
* fix(backup): atomically converge schedules
* fix(status): isolate backup freshness environment
* fix(status): carry scan environment to freshness reads
* fix(backup): harden Git repository ownership
* docs(backup): document Git repository safety
* fix(backup): non-creating outcome log and origin preflight for pushed schedules
Recording a backup outcome never bootstraps an absent state database (a
failed backup on a fresh host would otherwise create a blank DB that a
retry treats as real input), and backup enable --push now requires the
repository to have an origin remote, pointing at backup git init --remote
instead of scheduling permanently degraded pushes.
* refactor(worktrees): use shared git exec helpers
* refactor(worktrees): remove unused git buffer wrapper
* refactor(worktrees): consume buffered git helper
* feat(backup): redact pushed schedules by default
Unattended recurring pushes retain credential-bearing tables durably in
remote Git history, so backup enable --push now defaults to
--exclude-secrets; --include-secrets is the explicit full-fidelity
override (still warned). Local non-push schedules keep full fidelity for
complete restores.
* fix(backup): redact audit HMAC and OAuth pending state; tolerate absent backup_runs
Adds audit_identity_keys (audit HMAC key) and mcp_oauth_pending_authorizations
(live OAuth callback state) to the redaction inventory, and makes read-only
backup freshness treat a same-version database without the additive
backup_runs table as no recorded backups instead of failing before a
writable open converges the schema.
* fix(backup): restrict schedules to local gateways
* fix(snapshot): harden Git restore and redaction
* fix(backup): block pushes of adopted history
* fix(backup): contain commits and pairing secrets
* docs(backup): describe manual restore flow
* docs(backup): make restore copy-back fail closed
* docs(backup): make inspect-and-stage block fail closed
Add set -euo pipefail to the first restore staging snippet so a failed
openclaw backup verify stops before mktemp/tar extraction, matching the
fail-closed copy-back block. Addresses ClawSweeper P1 on docs/cli/backup.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(backup): reconcile restore guidance with exclusions
Punchcard-Session: brisk-harbor-harbor-6w
* docs(backup): centralize archive restore guidance
Punchcard-Session: calm-cedar-workshop-by
---------
Co-authored-by: clawSean <260045960+clawSean@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
* feat(gateway): add /startupz startup probe with auth-gated version detail
Startup/traffic-admission probe that excludes downstream channel health:
200 started once startup work completes and the gateway is not draining,
503 starting/draining otherwise. Version and uptime are only included for
local-direct or authenticated callers, reusing the /readyz detail gate.
* fix(deploy): use /startupz for traffic admission in bundled templates
fly.toml gains its missing HTTP check; render.yaml stops using pure
liveness as admission; k8s pins an immutable image tag, seeds config
only when missing, and adds a startupProbe; stale Fly healthcheck-port
doc corrected (healthcheck follows the active gateway lock port since
bc4221a07e).
* docs(k8s): make persistent-file config ownership explicit with reseed path
* fix(ui): confirm disruptive Control UI updates before dispatch
Every Control UI update affordance dispatched `update.run` (or the macOS
bridge `start-update` message) on the first click, so a misclick could
install new code, restart the Gateway, and interrupt active work.
Add one canonical confirmation gate in the Control UI owner boundary and
route the sidebar/settings-sidebar/floating update card and the
Settings -> Updates row through it. The gate owns the copy, the versions,
the restart consequence, the action-specific confirm label, and the
choice between the macOS bridge and `update.run`, so the bridge fork no
longer lives in the card and no surface can drift.
CLI, API, automation, agent-driven paths, automatic update campaigns, and
the `update.run` contract are unchanged.
Addresses the Control UI portion of #117178.
* style(ui): apply oxfmt to update confirmation sources
* perf(ui): load the update confirmation lazily and share its impact copy
Keeps the Control UI startup bundle under its 317 KiB gzip ceiling: the
confirmation dialog only loads when an operator opens it.
* test(ui): drive the update confirmation in sidebar and shell wiring tests
* fix(ui): report dev checkout update status
Show tracked-upstream commit lag and verified install/commit timestamps in Settings > Updates. Verify the post-restart Git revision before reporting success, and surface same-revision updates as an explicit no-op unless plugin convergence changed the install.
* test(ui): expect authoritative update reconciliation
* feat(update): scheduled update campaigns with countdown, dev-channel auto-update, and Updates settings page
* fix(ui): satisfy update campaign deadcode checks
* feat(update): extend scheduled update campaigns
* test(ui): include Updates page in settings sidebar search expectations
* fix(update): end campaigns when apply fails
* fix(update): pin dev campaign applies to the announced commit
* test(ui): align update e2e fixtures
* fix(update): pin adopted dev updates to the announced commit
* docs(update): document automatic dev update campaigns
* fix(ui): gate automatic dev updates on git installs
* fix(gateway): scope detailed update metadata to read-capable clients
* fix(gateway): break post-attach madge cycle with a leaf client-lookup type
* chore(protocol): regenerate clients after rebase
* test(gateway): update method tail after rebase
* fix(update): preserve campaign target and hold state
* test(update): align adoption mocks and split handoff suite
* test(update): route split handoff suites on Windows
Reject symlinked generated-output roots before build and postbuild mutation paths can recurse into unrelated targets. Cover aggregate, UI, export-template, bundled-plugin, Docker-prune, and plugin-runtime entry points with regression tests and migration guidance.
Closes#116498
Co-authored-by: WangYan <wang.yan29@xydigit.com>
The documented `npm install -g openclaw@latest` does not run OpenClaw's
preinstall/postinstall steps on npm 12, which blocks package lifecycle
scripts by default. Nothing in the install docs mentioned this.
Adds a note to the npm tab with the working command. The pnpm tab
already documents its equivalent (`pnpm approve-builds -g`), so npm was
the only tab without one.
Scoped to npm 12 rather than 11.16: `strict-allow-scripts` is undefined
on npm 11.12.1 and false on both 11.16.0 and 12.0.1, and only npm 12
reports the scripts as "blocked because they are not covered by
allowScripts". npm 11.16.x warns that they are "not yet covered" and
still runs them, so the note describes it as warning-only and keeps the
ENOMATCH caveat about the approve-scripts remedy it suggests.
Closes#114665
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* docs: recommend Node 26 in quickstart, landing, and platform install docs
- Problem: the user-facing quickstart (docs/start/getting-started.md), landing
page (docs/index.md), and Linux/macOS platform install docs still mark
Node 24 as the recommended default, contradicting maintainer PR #114399
('recommend Node 26 as the OpenClaw runtime') and the installer default
(scripts/install.sh NODE_DEFAULT_MAJOR=26, openclaw.mjs
RECOMMENDED_NODE_MAJOR=26). Users following the quickstart pick a slower,
heavier runtime against the project's stated recommendation.
- Fix: align the 4 missed user-facing install surfaces to 'Node 26
recommended', matching the phrasing already in docs/install/node.md,
docs/install/index.md, docs/install/ansible.md, docs/install/bun.md, and
docs/help/faq-first-run.md. Leave docs/start/setup.md (the source/dev
workflow where CI pins Node 24) unchanged on purpose.
- Verification: docs-only diff reviewed; supported-version floors
(22.22.3+/24.15+/25.9+) unchanged; consistent across all install surfaces.
* docs: complete Node 26 installation guidance
Co-authored-by: Santhi Prakash <b.santhiprakash@gmail.com>
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* feat(runtime): allow Bun runtimes that provide node:sqlite
* fix(process): drop execa buffer encoding under Bun spawn (Bun rejects non-spawn options)
* chore(process): cite oven-sh/bun#36049 in bun spawn workaround
* docs(install): bun with node:sqlite can run openclaw; bun install workspace caveat
* fix(process): clear execa buffer encoding under Bun without mutating read-only options
* feat(scripts): reference update script for source-checkout gateway servers
Teams running a gateway from a git checkout kept re-deriving the same
update ritual by hand: restore the tracked bundle pnpm build rewrites,
fail closed on real local changes, fast-forward main or rebase a local
server branch, install deps, build clean (incremental builds have
shipped stale hashed chunks), restart the service. update-gateway.sh
encodes that as the documented reference; simple installs keep using
openclaw update --channel dev.
* fix(scripts): harden update-gateway guards and refresh docs map
Review findings: never run over a pre-existing rebase/merge/cherry-pick
(the abort path could discard operator progress), and treat untracked
files honestly — fail closed only where the clean build would delete
them, warn-list elsewhere. Regenerate docs_map for the new updating.md
section.
* fix(scripts): pipefail-safe warnings and honest disposable-dir policy
Review findings: head-truncating a long warning list through a pipe
dies under pipefail (SIGPIPE) in the warning path, so truncate via
here-strings; the untracked-under-build-dirs guard was theater since
ignored files bypassed it — declare dist/dist-runtime/.artifacts as
wholly disposable instead and say so; note the rm targets are
symlink-safe (no trailing slashes).
* fix(scripts): order guards before mutations and refuse symlinked build dirs
Review round: the in-progress-operation guard now precedes the bundle
restore (the script's first mutation), symlinked build dirs are refused
before the recursive clean (intermediate symlink resolution would
redirect the delete outside the checkout), and the untracked-files note
no longer overpromises — kept files can affect the build and the
message says so.
* fix(scripts): preserve merge commits when rebasing the server branch
Plain git rebase flattens merges, silently dropping merge-only conflict
resolutions from a local server branch; --rebase-merges keeps them.
* feat(migrate): add Hermes memory-only import and a shared memory-import core
* feat(onboarding): offer detected memory imports during CLI setup and guided onboarding
* feat(ui): show a first-run memory-import offer in Control UI onboarding mode
* feat(linux-app): open the first-run dashboard in onboarding mode
* feat(macos): add the onboarding memory-import page
* docs: document the onboarding memory-import page across surfaces
* chore(i18n): translate onboarding memory-import strings for control-ui and native locales
* refactor: keep memory-import internals unexported for deadcode gates
* fix(ci): resolve lint findings in onboarding memory import
* chore(i18n): refresh native inventory after lint refactor
* fix(ci): skip updater artifacts in the unsigned Linux companion PR lane
* chore(i18n): reconcile locale artifacts after rebase
Peter Steinberger