From 33017605678be69b5caec159e7522939143ab6ff Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 3 May 2026 21:39:49 +0100 Subject: [PATCH] docs: record upgrade recovery fixes --- CHANGELOG.md | 1 + docs/cli/update.md | 10 ++++++---- docs/plugins/dependency-resolution.md | 7 +++++-- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca3dd86dac9..927276fd8e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,7 @@ Docs: https://docs.openclaw.ai - Agents/network: allow trusted web-search providers and configured model-provider hosts to work behind Surge/Clash/sing-box fake-IP DNS by accepting RFC 2544 and IPv6 ULA synthetic answers only for the request's scoped hostname, without broad private-network access. Refs #76530 and #76549. Thanks @zqchris. - Providers: honor env-proxy settings for guarded provider model fetches when no explicit dispatcher policy is configured, preserving explicit transport overrides. Fixes #70453. (#72480) Thanks @mjamiv. - Feishu: accept and honor `channels.feishu.blockStreaming` at the top level and per account, while keeping the legacy default off so Feishu cards no longer reject documented config or silently drop block replies. Fixes #75555. Thanks @vincentkoc. +- Gateway/update: avoid `launchctl kickstart -k` immediately after fresh macOS update bootstraps, and remove dangling global plugin-runtime symlinks during packaged postinstall and `doctor --fix` so upgrades no longer SIGTERM the newly booted Gateway or leave bundled plugin imports pointed at pruned `plugin-runtime-deps` trees. Completes #76261 and fixes #76466. (#76929) - Google Chat: normalize custom Google auth transport headers before google-auth/gaxios interceptors run, restoring webhook token verification when certificate retrieval expects Fetch `Headers`. Fixes #76742. Thanks @donbowman. - Doctor/plugins: reset stale `plugins.slots.memory` and `plugins.slots.contextEngine` references during `doctor --fix`, so cleanup of missing plugin config does not leave unrecoverable slot owners behind. Fixes #76550 and #76551. Thanks @vincentkoc. - Docs/WhatsApp: merge the duplicate top-level `web` objects in the gateway channel config example so copy-pasted WhatsApp config keeps both `web.whatsapp` and reconnect settings. Fixes #76619. Thanks @WadydX. diff --git a/docs/cli/update.md b/docs/cli/update.md index 17fb8513bea..60a1269b1fb 100644 --- a/docs/cli/update.md +++ b/docs/cli/update.md @@ -116,10 +116,12 @@ service, and verify the restarted Gateway reports the expected version before reporting success. On macOS, the post-update check also verifies the LaunchAgent is loaded/running for the active profile and the configured loopback port is healthy. If the plist is installed but launchd is not supervising it, OpenClaw -re-bootstraps and kickstarts the LaunchAgent automatically, then reruns the -health/version/channel readiness checks. If the Gateway still does not become -healthy, the command exits non-zero and prints the restart log path plus explicit -restart, reinstall, and package rollback instructions. With `--no-restart`, +re-bootstraps the LaunchAgent automatically, then reruns the +health/version/channel readiness checks. A fresh bootstrap loads the RunAtLoad +job directly, so update recovery does not immediately `kickstart -k` the newly +spawned Gateway. If the Gateway still does not become healthy, the command exits +non-zero and prints the restart log path plus explicit restart, reinstall, and +package rollback instructions. With `--no-restart`, package replacement still runs but the managed service is not stopped or restarted, so the running Gateway may keep old code until you restart it manually. diff --git a/docs/plugins/dependency-resolution.md b/docs/plugins/dependency-resolution.md index 7324706d038..45838efcc0c 100644 --- a/docs/plugins/dependency-resolution.md +++ b/docs/plugins/dependency-resolution.md @@ -118,8 +118,11 @@ not a supported way to prepare bundled plugin dependencies. Older OpenClaw versions generated bundled-plugin dependency roots at startup or during doctor repair. Current doctor cleanup removes those stale directories and -symlinks when `--fix` is used, including old `plugin-runtime-deps` roots, +symlinks when `--fix` is used, including old `plugin-runtime-deps` roots, global +Node-prefix package symlinks that point at pruned `plugin-runtime-deps` targets, `.openclaw-runtime-deps*` manifests, generated plugin `node_modules`, install -stage directories, and package-local pnpm stores. +stage directories, and package-local pnpm stores. Packaged postinstall also +removes those global symlinks before pruning the legacy target roots so upgrades +do not leave dangling ESM package imports. These paths are legacy debris only. New installs should not create them.