Skip to main content
Users could sometimes experience instability after updating OpenClaw. Supported update paths now inspect the installation before replacing it and stop unsafe candidates while leaving the previous CLI runnable. In the Control UI, updates identify the target, ask for confirmation, and keep progress and the final outcome visible. Maintenance tools now provide clearer recovery paths. Configuration errors point to the setting that needs attention, Doctor focuses on problems and the next action, new backups are checked against the guarded restore path, destructive cleanup stops when ownership is unclear, and supported restarts give tracked work time to finish before handoff.
Gateway updates started in the Control UI now identify the target, require confirmation, show progress through the update and restart, and report the final outcome. On eligible signed Mac apps, that flow updates the app first and then only the app-managed local Gateway; browser and user-managed installs keep their Gateway-only path.Supported CLI updates check Node compatibility, package-manager lifecycle rules, and whether npm, pnpm, or Bun owns the installation before replacement. An unsafe candidate stops while leaving the previous CLI runnable, and an exact openclaw update --dry-run previews the path without changing configuration, handoff, cleanup, or restart state.On Linux, code updates can preserve an administrator-owned service definition instead of trying to rewrite it, while an unsafe or uninspectable service handoff still fails visibly. If a plugin replacement asks for new capabilities, OpenClaw keeps the known-good plugin available while the replacement waits for review; openclaw update --accept-capabilities or openclaw update repair --accept-capabilities approves only the staged artifact for that invocation, and --yes does not.One upgrade path still needs a manual repair. If you are on OpenClaw 2026.7.1 with pnpm 11, run pnpm add -g openclaw@latest once. OpenClaw does not upgrade Node for you.
Bad configuration now stops with a useful answer instead of quietly starting OpenClaw with something else. Packaged builds, CLI checks, service preflight, and Gateway startup show the file, line, full setting path, allowed values when available, and a safe version of what was received; malformed top-level scalar files fail closed instead of loading defaults.If you are upgrading a configuration that still contains retired keys, run openclaw doctor --fix before September 18, 2026. Doctor keeps canonical values when old and new keys conflict and removes settings that no longer do anything, although explicitly retired tuning values return to the built-in defaults.Supported Gateway service repairs preserve the installed state directory, config path, port, managed environment, and eligible file-backed credentials instead of silently retargeting the service. Changing those targets intentionally requires openclaw gateway install --force; on Linux, service commands also refuse conflicting user and system units and show which unit owns the Gateway.
Before a supported snapshot or targeted restart, Gateway suspend and resume can pause new ordinary work, report blockers, and drain the agent runs, deliveries, scheduled jobs, queues, sessions, and background commands OpenClaw already tracks. Failed configuration reloads keep the prior coherent state, and rapid configuration writes retain pending restart intent instead of dropping it.After restart, health checks, the agent list, and core controls become usable before optional catalog, plugin, and migration work finishes. That work is deferred rather than removed, so the first explicit catalog request can still take longer.The wait covers work OpenClaw tracks. New channel or external ingress, existing plugin connections, unregistered background work, and durable receipt of incoming messages remain outside it, and externally supervised installations must consume the handoff and complete their own restart.
Doctor now spends less time reciting healthy inventory and more time showing what broke and what to do next. A recoverable interactive startup failure can offer one confirmed doctor --fix attempt, while an unrecoverable configuration stays unchanged with exact instructions to inspect, edit, or move it aside. Bare openclaw doctor --json is a read-only advisory check; use openclaw doctor --lint --all when you need the advisory checks omitted from the default run.Logs now fill their bounded tail window across short reads, preserve Unicode at file boundaries, distinguish line and byte truncation from rollover, and report unavailable storage instead of an empty success. Status keeps its base report when optional health details fail, so missing information remains unknown rather than being shown as healthy.In the admin Control UI, Ask OpenClaw can turn consequential health state into a diagnostic question and keep the system-care conversation docked as you move around, while the System overlay shows a short history of scheduler pressure, CPU, memory, event-loop delay, and optional disk activity. These controls require admin or operator access and do not appear during onboarding or to read-scoped clients.
Commands used by scripts now have a more predictable machine interface. The named JSON and JSONL commands keep terminal-reset bytes out of stdout and return a consistent structured error when an invocation fails, so automation no longer has to special-case them.Shell completion installation and refresh preserve unrelated profile content and permissions while publishing profiles and caches atomically across Bash, Zsh, Fish, and PowerShell. Remote Gateway turns and common read-only commands also skip startup work they do not need, while local probes and human output keep fuller validation; mistyped commands now point to the command tree that rejected them, nearby commands, and the correct help.The predictable machine-output contract covers the named command paths. Human diagnostics can still appear on stderr, successful degraded results remain command-specific, and raw lifecycle-error redaction is not yet universal.
Reset and uninstall now refuse to remove data until the Gateway service is torn down and OpenClaw can establish that no other process owns the state. If teardown or ownership checks fail, the state stays put, and a state-only uninstall leaves configured workspaces alone.New full backups preserve configured agent state roots and safe relative links, avoid mistaking active archive work for a stall, and restore default or custom layouts through the same guarded flow. Managed dev/ checkouts and local source edits still need a separate backup, while older archives containing absolute generated plugin-skills/ links remain rejected.Known-vulnerable Node and SQLite combinations now stop before state opens, with guidance for whether the embedded Node runtime or shared system SQLite library needs upgrading.