fix: correct bundled OpenClaw version for 0.5.87

Co-authored-by: root <root@0bfc167e-openclaw-assistant.local.hass.io>

DOCS.md

@@ -43,10 +43,10 @@ When you open the add-on page in Home Assistant, nginx serves a landing page wit
 | `/config/` | Yes | All user data — survives add-on updates and rebuilds |
 | `/config/.openclaw/` | Yes | OpenClaw configuration (`openclaw.json`), skills, agent data |
 | `/config/clawd/` | Yes | Agent workspace (ClawHub-installed skills, files) |
-| `/config/.node_global/` | Yes | User-installed npm packages (skills installed via dashboard) |
+| `/config/.node_global/` | Optional | User-installed npm packages when `persist_node_global=true` |
 | `/config/secrets/` | Yes | Tokens (e.g., `homeassistant.token`) |
 | `/config/keys/` | Yes | SSH keys (e.g., router SSH key) |
-| `/config/.linuxbrew/` | Yes | Homebrew install and brew-installed CLI tools |
+| `/config/.linuxbrew/` | Optional | Homebrew install and brew-installed CLI tools when `persist_brew_tools=true` |
 | `/config/gogcli/` | Yes | gog OAuth credentials for Google APIs |
 | `/usr/lib/node_modules/openclaw/` | No | OpenClaw installation (rebuilt with each image update) |
 
@@ -314,7 +314,10 @@ To provide the SSH key: place the private key file in the add-on config director
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `clean_session_locks_on_start` | bool | `true` | Remove stale session lock files on startup (safe — only removes locks when gateway isn't running) |
-| `clean_session_locks_on_exit` | bool | `true` | Remove session lock files on clean shutdown || `auto_configure_mcp` | bool | `false` | Auto-register Home Assistant as an MCP server on startup (requires `homeassistant_token`) |
+| `clean_session_locks_on_exit` | bool | `true` | Remove session lock files on clean shutdown |
+| `persist_node_global` | bool | `false` | Persist user-installed npm global skills/packages in `/config/.node_global/`. Turn on only if you want those installs to survive add-on rebuilds. |
+| `persist_brew_tools` | bool | `false` | Persist Homebrew and brew-installed CLI tools in `/config/.linuxbrew/`. Turn on only if you want those installs to survive add-on rebuilds. |
+| `auto_configure_mcp` | bool | `false` | Auto-register Home Assistant as an MCP server on startup (requires `homeassistant_token`) |
 ---
 
 ## 6. Use Case Guides
@@ -494,7 +497,7 @@ The **Model Context Protocol (MCP)** lets OpenClaw communicate directly with Hom
 3. Set **Auto-Configure MCP for Home Assistant** (`auto_configure_mcp`) to **ON**
 4. Restart the add-on
 
-The add-on will automatically register Home Assistant as an MCP server named `HA` using `mcporter`. It auto-detects the HA API URL (supervisor proxy when available, otherwise `localhost:8123`). Check the logs for:
+The add-on bundles `mcporter` and automatically registers Home Assistant as an MCP server named `HA`. It auto-detects the HA API URL (supervisor proxy when available, otherwise `localhost:8123`). Check the logs for:
 ```
 INFO: MCP server 'HA' registered — OpenClaw can now control Home Assistant
 ```
@@ -540,7 +543,7 @@ MCP setup requires an AI model that understands tool/skill invocation. Budget mo
 
 | Symptom | Fix |
 |---|---|
-| `mcporter: command not found` | Run `openclaw onboard` first, then restart the add-on |
+| `mcporter: command not found` | Upgrade to add-on `0.5.84` or newer. Older builds did not bundle `mcporter`; as a temporary workaround, install it manually in the add-on terminal and restart. |
 | MCP add fails with auth error | Verify your long-lived token is valid and not expired |
 | OpenClaw doesn’t see HA entities | Run `mcporter call home-assistant.GetLiveContext` to refresh |
 | Model says “what’s MCP?” | Switch to a more capable model for the initial session (see above) |
@@ -648,10 +651,10 @@ You should see your account listed with the `sheets` service.
 | Built-in skills | `/config/.openclaw/skills/` | Yes |
 | Agent sessions & data | `/config/.openclaw/agents/` | Yes |
 | ClawHub workspace | `/config/clawd/` | Yes |
-| User-installed npm skills | `/config/.node_global/` | Yes |
+| User-installed npm skills | `/config/.node_global/` | Optional (`persist_node_global=true`) |
 | SSH keys | `/config/keys/` | Yes |
 | Tokens | `/config/secrets/` | Yes |
-| Homebrew & brew-installed tools | `/config/.linuxbrew/` | Yes (synced on startup) |
+| Homebrew & brew-installed tools | `/config/.linuxbrew/` | Optional (`persist_brew_tools=true`) |
 | gog OAuth credentials | `/config/gogcli/` | Yes |
 | TLS certificates (lan_https) | `/config/certs/` | Yes (CA persists; server cert regenerated if IP changes) |
 | OpenClaw binary | `/usr/lib/node_modules/openclaw/` | **No** — reinstalled from image |
@@ -668,19 +671,21 @@ This means built-in skills survive image rebuilds, and any customizations you ma
 
 ### How user-installed skills work
 
-When you install a skill via the OpenClaw dashboard or `npm install -g`, the add-on redirects global npm installs to `/config/.node_global/`. This directory persists across updates.
+By default, user-installed npm skills and global packages are **ephemeral** to keep Home Assistant backups small.
 
-The add-on also configures `pnpm` global directory to persistent storage at `/config/.node_global/pnpm/`.
+If you enable `persist_node_global`, the add-on redirects global npm installs to `/config/.node_global/` so dashboard-installed skills survive add-on rebuilds. The add-on also configures the pnpm global directory at `/config/.node_global/pnpm/` in that mode.
 
 ### Homebrew-installed tools
 
-Homebrew (Linuxbrew) and all brew-installed CLI tools (e.g., `gemini`, `aider`, `gh`, `bw`) are now **persisted** across add-on updates. On each startup, the add-on:
+By default, Homebrew (Linuxbrew) and brew-installed CLI tools are **ephemeral** to keep Home Assistant backups small.
+
+If you enable `persist_brew_tools`, the add-on:
 
 1. Syncs the image's Homebrew install to `/config/.linuxbrew/`
 2. Creates a symlink from `/home/linuxbrew/.linuxbrew/` to the persistent copy
 3. On subsequent boots, only newer files are synced (user-installed packages are preserved)
 
-This means `brew install` packages survive image rebuilds.
+This means `brew install` packages survive image rebuilds only when persistence is enabled.
 
 ---
 
@@ -742,7 +747,7 @@ Home Assistant checks for add-on updates automatically. When an update is availa
 **What happens during an update**:
 - The container is destroyed and recreated from the new image
 - Everything under `/config/` is preserved (config, skills, workspace, keys)
-- Homebrew and brew-installed packages are preserved (synced to `/config/.linuxbrew/`)
+- Homebrew and npm global packages are preserved only if you explicitly enable `persist_brew_tools` / `persist_node_global`
 - The OpenClaw binary is updated to the version in the new image
 
 ### Checking your version
@@ -755,7 +760,20 @@ openclaw --version
 
 ### Backup
 
-Home Assistant's built-in backup system automatically includes add-on configuration data (`/config/`). This covers all persistent data: OpenClaw config, skills, workspace, keys, and tokens.
+Home Assistant's built-in backup system automatically includes add-on configuration data (`/config/`). By default this covers the important user state: OpenClaw config, skills, workspace, keys, and tokens — without large optional toolchains.
+
+### Backup-friendly defaults (v0.5.75+)
+
+Starting with v0.5.75, the add-on keeps large optional toolchains out of backups by default:
+
+- `persist_node_global: false` → `/config/.node_global/` is not used unless you opt in
+- `persist_brew_tools: false` → `/config/.linuxbrew/` is not used unless you opt in
+
+Turn these on only if you specifically want user-installed npm global skills or brew-installed CLI tools to survive add-on rebuilds.
+
+### Migration note for older installs
+
+If you used an older add-on version, you may already have legacy directories such as `/config/.node_global/` or `/config/.linuxbrew/` from previous persistent behavior. Disabling persistence stops future growth, but those directories still count toward backup size until you remove or archive them manually.
 
 **To create a backup**: Go to **Settings → System → Backups → Create Backup**
 
@@ -764,7 +782,8 @@ Home Assistant's built-in backup system automatically includes add-on configurat
 # Key paths to back up:
 # /config/.openclaw/     - OpenClaw config, skills, agent data
 # /config/clawd/         - ClawHub workspace
-# /config/.node_global/  - User-installed npm skills
+# /config/.node_global/  - User-installed npm skills (only if persist_node_global=true)
+# /config/.linuxbrew/    - Homebrew tools (only if persist_brew_tools=true)
 # /config/keys/          - SSH keys
 # /config/secrets/       - Tokens
 ```
@@ -774,12 +793,12 @@ Home Assistant's built-in backup system automatically includes add-on configurat
 To reset the add-on to a clean state, remove the persistent data:
 
 ```sh
-rm -rf /config/.openclaw /config/clawd /config/.node_global
+rm -rf /config/.openclaw /config/clawd /config/.node_global /config/.linuxbrew
 ```
 
 Then restart the add-on. It will re-bootstrap a fresh configuration.
 
-> **Warning**: This deletes all your OpenClaw configuration, skills, and workspace data. Back up first if needed.
+> **Warning**: This deletes all your OpenClaw configuration, skills, workspace data, and any optionally persisted tool installations. Back up first if needed.
 
 ---
 
@@ -948,7 +967,7 @@ Built-in skills are synced to persistent storage on each startup. If skills are
 
 1. Check logs for `INFO: Synced built-in skills to persistent storage` — this confirms the sync ran
 2. If you see `WARN: Built-in skills directory not found`, the OpenClaw installation may be corrupted. Try reinstalling the add-on.
-3. User-installed skills (via dashboard) are stored in `/config/.node_global/` and should survive updates
+3. User-installed skills (via dashboard) survive updates only when `persist_node_global` is enabled. With the default backup-friendly setting (`false`), they are ephemeral and may need to be reinstalled after an add-on rebuild.
 
 ### Homebrew errors / CPU compatibility
 

openclaw_assistant/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to the OpenClaw Assistant Home Assistant Add-on will be documented in this file.
 
+## [0.5.87] - 2026-08-10
+
+### Fixed
+- Correct the bundled OpenClaw npm package version in the Docker image build for add-on `0.5.86`, fixing failed installs that requested the nonexistent `openclaw@2026.7.1-2-2`.
+
+## [0.5.85] - 2026-07-21
+
+### Changed
+- Bump OpenClaw to `2026.7.1-2`.
+
+## [0.5.84] - 2026-07-17
+
+### Changed
+- Bundle `mcporter@0.12.3` in the add-on image so `auto_configure_mcp` can register Home Assistant out of the box on fresh installs without a manual global install workaround.
+- Replace the misleading startup hint that told users to run `openclaw onboard` when `mcporter` was missing. The message now correctly points to a broken image state instead.
+
+## [0.5.82] - 2026-07-15
+
+### Fixed
+- Repair add-on startup automatically when the bundled OpenClaw CLI is older than the persisted `/config/.openclaw/openclaw.json` format version. On mismatch, the add-on now restores the newer runtime before launching the gateway instead of silently coming up broken after a Home Assistant OS update or add-on rebuild.
+- Regenerate malformed `lan_https` CA/server certificates with proper X.509 extensions (`basicConstraints`, `keyUsage`, `extendedKeyUsage`) so Python/OpenSSL strict verification accepts the built-in HTTPS proxy certificates.
+
+## [0.5.81] - 2026-07-14
+
+### Changed
+- Bump OpenClaw to `2026.7.1`.
+
+## [0.5.80] - 2026-06-26
+
+### Changed
+- Bump OpenClaw to `2026.6.10`.
+
+## [0.5.78] - 2026-06-16
+
+### Changed
+- Bump OpenClaw through the `2026.5.28` and `2026.6.6` upstream releases.
+
+## [0.5.76] - 2026-05-29
+
+### Changed
+- Bump OpenClaw to `2026.5.27`.
+
+## [0.5.75] - 2026-05-28
+
+### Changed
+- **Backup-friendly persistence defaults**: new add-on options `persist_node_global` and `persist_brew_tools`, both defaulting to `false` so large optional toolchains are no longer persisted into Home Assistant backups unless users explicitly opt in.
+- `run.sh` now keeps npm global installs and Homebrew ephemeral by default, while preserving the old rebuild-survival behavior when the new toggles are enabled.
+
+### Added
+- Migration notes and documentation for older installs that already have legacy `/config/.node_global/` or `/config/.linuxbrew/` directories contributing to backup size.
+
 ## [0.5.74] - 2026-05-27
 
 ### Fixed

openclaw_assistant/Dockerfile

@@ -4,7 +4,7 @@ FROM ${BUILD_FROM}
 # Base image is Debian Bookworm (glibc). This avoids musl-related native module issues
 # that occur on Alpine (e.g. clipboard, node-llama-cpp).
 
-# Install base packages (without nodejs/npm - we'll get Node 22 from NodeSource)
+# Install base packages (without nodejs/npm - we'll get Node 24 from NodeSource)
 # build-essential provides gcc/cc needed by Homebrew for OpenClaw's brew-managed dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
     bash \
@@ -34,19 +34,21 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Node.js 22 LTS from NodeSource (Debian Bookworm ships Node 18, but OpenClaw requires 20+)
-# Use explicit keyring + apt source instead of setup_22.x pipe script for deterministic builds.
+# Install Node.js 24 LTS from NodeSource.
+# OpenClaw supports Node >=24.15.0, and this keeps the image compatible with the
+# current mcporter releases without relying on an older pinned CLI line.
+# Use explicit keyring + apt source instead of setup_24.x pipe script for deterministic builds.
 RUN mkdir -p /etc/apt/keyrings \
     && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
     | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
     && chmod 644 /etc/apt/keyrings/nodesource.gpg \
-    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" \
+    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" \
     > /etc/apt/sources.list.d/nodesource.list \
     && apt-get update \
     && apt-get install -y --no-install-recommends nodejs \
     && NODE_VERSION="$(node -v)" \
     && echo "$NODE_VERSION" \
-    && echo "$NODE_VERSION" | grep -E '^v22\.' \
+    && echo "$NODE_VERSION" | grep -E '^v24\.' \
     && rm -f /etc/apt/sources.list.d/nodesource.list /etc/apt/keyrings/nodesource.gpg \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
@@ -113,11 +115,13 @@ RUN if [ -x /home/linuxbrew/.linuxbrew/bin/brew ]; then \
     fi
 USER root
 
-# Install OpenClaw globally
-# Bundle node-llama-cpp in the image so the default local memory/embeddings
-# provider works in HAOS without requiring manual npm installs in /usr/lib.
+# Install OpenClaw globally.
+# Bundle node-llama-cpp so the default local memory/embeddings provider works
+# in HAOS without requiring manual npm installs in /usr/lib.
+# Bundle mcporter so Home Assistant MCP auto-configuration works out of the box.
+# The image now ships Node 24, so use the current mcporter line.
 RUN npm config set fund false && npm config set audit false \
-    && npm install -g openclaw@2026.5.22 node-llama-cpp@3.18.1
+    && npm install -g openclaw@2026.7.1-2 node-llama-cpp@3.18.1 mcporter@0.12.3
 
 # Shell aliases and color options for interactive use
 RUN tee -a /etc/bash.bashrc <<'EOF'

openclaw_assistant/config.yaml

@@ -1,5 +1,5 @@
 name: OpenClaw Assistant
-version: "0.5.74"
+version: "0.5.87"
 slug: openclaw_assistant
 description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
 url: https://github.com/techartdev/OpenClawHomeAssistant
@@ -56,6 +56,11 @@ options:
   clean_session_locks_on_start: true
   clean_session_locks_on_exit: true
 
+  # Persist heavy optional tooling across add-on rebuilds.
+  # Disabled by default to keep Home Assistant backups small.
+  persist_node_global: false
+  persist_brew_tools: false
+
   # Gateway mode:
   # - local: Run gateway locally (recommended for most users)
   # - remote: Connect to a remote gateway
@@ -153,6 +158,8 @@ schema:
 
   clean_session_locks_on_start: bool?
   clean_session_locks_on_exit: bool?
+  persist_node_global: bool?
+  persist_brew_tools: bool?
   gateway_mode: list(local|remote)?
   gateway_remote_url: str?
   gateway_bind_mode: list(loopback|lan|tailnet)?

openclaw_assistant/run.sh

@@ -44,6 +44,8 @@ ROUTER_KEY=$(jq -r '.router_ssh_key_path // "/data/keys/router_ssh"' "$OPTIONS_F
 # Optional: allow disabling lock cleanup if you ever need to debug
 CLEAN_LOCKS_ON_START=$(jq -r '.clean_session_locks_on_start // true' "$OPTIONS_FILE")
 CLEAN_LOCKS_ON_EXIT=$(jq -r '.clean_session_locks_on_exit // true' "$OPTIONS_FILE")
+PERSIST_NODE_GLOBAL=$(jq -r '.persist_node_global // false' "$OPTIONS_FILE")
+PERSIST_BREW_TOOLS=$(jq -r '.persist_brew_tools // false' "$OPTIONS_FILE")
 
 # Gateway configuration
 GATEWAY_MODE=$(jq -r '.gateway_mode // "local"' "$OPTIONS_FILE")
@@ -149,6 +151,15 @@ export XDG_CONFIG_HOME=/config
 
 mkdir -p /config/.openclaw /config/.openclaw/identity /config/clawd /config/keys /config/secrets
 
+warn_legacy_persistent_dir() {
+  local path="$1"
+  local label="$2"
+  if [ -e "$path" ]; then
+    echo "WARN: Found legacy persistent ${label} at ${path}, but persistence is disabled."
+    echo "WARN: It will still inflate Home Assistant backups until you remove or archive it manually."
+  fi
+}
+
 # ------------------------------------------------------------------------------
 # Sync built-in OpenClaw skills from image to persistent storage
 # On each startup, copy new/updated built-in skills so they survive rebuilds.
@@ -180,21 +191,33 @@ else
 fi
 
 # ------------------------------------------------------------------------------
-# Persist user-installed node skills across Docker image rebuilds
-# Redirect npm/pnpm global installs to /config/.node_global (persistent storage)
-# so that skills installed via the dashboard survive container rebuilds.
+# Optional persistence for user-installed node skills across Docker image rebuilds.
+# When enabled, redirect npm/pnpm global installs to /config/.node_global so
+# dashboard-installed skills survive image updates. Disabled by default to keep
+# Home Assistant backups smaller.
 # NOTE: This MUST come after the skills sync above (which needs the original npm root -g).
 # ------------------------------------------------------------------------------
 PERSISTENT_NODE_GLOBAL="/config/.node_global"
-mkdir -p "$PERSISTENT_NODE_GLOBAL"
-npm config set prefix "$PERSISTENT_NODE_GLOBAL" 2>/dev/null || true
-export PATH="${PERSISTENT_NODE_GLOBAL}/bin:${PATH}"
-export NODE_PATH="${PERSISTENT_NODE_GLOBAL}/lib/node_modules:${NODE_PATH:-}"
+if [ "$PERSIST_NODE_GLOBAL" = "true" ] || [ "$PERSIST_NODE_GLOBAL" = "1" ]; then
+  mkdir -p "$PERSISTENT_NODE_GLOBAL"
+  npm config set prefix "$PERSISTENT_NODE_GLOBAL" 2>/dev/null || true
+  export PATH="${PERSISTENT_NODE_GLOBAL}/bin:${PATH}"
+  export NODE_PATH="${PERSISTENT_NODE_GLOBAL}/lib/node_modules:${NODE_PATH:-}"
 
-# Also configure pnpm global dir to persistent storage
-export PNPM_HOME="${PERSISTENT_NODE_GLOBAL}/pnpm"
-mkdir -p "$PNPM_HOME"
-export PATH="${PNPM_HOME}:${PATH}"
+  # Also configure pnpm global dir to persistent storage
+  export PNPM_HOME="${PERSISTENT_NODE_GLOBAL}/pnpm"
+  mkdir -p "$PNPM_HOME"
+  export PATH="${PNPM_HOME}:${PATH}"
+  echo "INFO: persist_node_global=true; user-installed npm skills will survive add-on rebuilds."
+else
+  npm config delete prefix 2>/dev/null || true
+  export npm_config_prefix="/usr/local"
+  export PNPM_HOME="/tmp/.pnpm-home"
+  mkdir -p "$PNPM_HOME"
+  export PATH="${PNPM_HOME}:${PATH}"
+  warn_legacy_persistent_dir "$PERSISTENT_NODE_GLOBAL" "node global tool/skill data"
+  echo "INFO: persist_node_global=false; npm/pnpm global installs are ephemeral and excluded from HA backups."
+fi
 
 # Protect critical runtime variables from accidental override via gateway_env_vars.
 is_reserved_gateway_env_var() {
@@ -331,42 +354,48 @@ elif [ "$GW_ENV_VARS_TYPE" != "null" ]; then
 fi
 
 # ------------------------------------------------------------------------------
-# Persist Linuxbrew/Homebrew across Docker image rebuilds
-# Homebrew installs to /home/linuxbrew/.linuxbrew/ which is ephemeral.
-# We sync it to /config/.linuxbrew and symlink back so brew-installed CLI
-# tools (gog, gh, bw, etc.) survive add-on updates.
+# Optional persistence for Linuxbrew/Homebrew across Docker image rebuilds.
+# When enabled, sync /home/linuxbrew/.linuxbrew to /config/.linuxbrew so
+# brew-installed CLI tools survive image updates. Disabled by default to keep
+# Home Assistant backups smaller.
 # ------------------------------------------------------------------------------
 IMAGE_BREW_DIR="/home/linuxbrew/.linuxbrew"
 PERSISTENT_BREW_DIR="/config/.linuxbrew"
 
-if [ -d "$IMAGE_BREW_DIR" ] && [ ! -L "$IMAGE_BREW_DIR" ]; then
-  # Image has a real Homebrew install — sync to persistent storage
-  if [ -d "$PERSISTENT_BREW_DIR" ]; then
-    # Persistent copy exists: sync new/updated files from image (upgrades),
-    # but preserve user-installed packages already in persistent storage.
-    if command -v rsync >/dev/null 2>&1; then
-      rsync -a --update "$IMAGE_BREW_DIR/" "$PERSISTENT_BREW_DIR/" 2>/dev/null || true
+if [ "$PERSIST_BREW_TOOLS" = "true" ] || [ "$PERSIST_BREW_TOOLS" = "1" ]; then
+  if [ -d "$IMAGE_BREW_DIR" ] && [ ! -L "$IMAGE_BREW_DIR" ]; then
+    # Image has a real Homebrew install — sync to persistent storage
+    if [ -d "$PERSISTENT_BREW_DIR" ]; then
+      # Persistent copy exists: sync new/updated files from image (upgrades),
+      # but preserve user-installed packages already in persistent storage.
+      if command -v rsync >/dev/null 2>&1; then
+        rsync -a --update "$IMAGE_BREW_DIR/" "$PERSISTENT_BREW_DIR/" 2>/dev/null || true
+      else
+        cp -ru "$IMAGE_BREW_DIR/"* "$PERSISTENT_BREW_DIR/" 2>/dev/null || true
+      fi
+      echo "INFO: Synced Homebrew updates to persistent storage"
     else
-      cp -ru "$IMAGE_BREW_DIR/"* "$PERSISTENT_BREW_DIR/" 2>/dev/null || true
+      # First time: copy entire Homebrew install to persistent storage
+      cp -a "$IMAGE_BREW_DIR" "$PERSISTENT_BREW_DIR" 2>/dev/null || true
+      echo "INFO: Copied Homebrew to persistent storage at $PERSISTENT_BREW_DIR"
     fi
-    echo "INFO: Synced Homebrew updates to persistent storage"
+    # Replace image dir with symlink to persistent copy
+    rm -rf "$IMAGE_BREW_DIR"
+    ln -sf "$PERSISTENT_BREW_DIR" "$IMAGE_BREW_DIR"
+  elif [ -L "$IMAGE_BREW_DIR" ]; then
+    echo "INFO: Homebrew already linked to persistent storage"
+  elif [ -d "$PERSISTENT_BREW_DIR" ]; then
+    # Image doesn't have Homebrew (failed install?) but persistent copy exists
+    mkdir -p "$(dirname "$IMAGE_BREW_DIR")"
+    ln -sf "$PERSISTENT_BREW_DIR" "$IMAGE_BREW_DIR"
+    echo "INFO: Restored Homebrew symlink from persistent storage"
   else
-    # First time: copy entire Homebrew install to persistent storage
-    cp -a "$IMAGE_BREW_DIR" "$PERSISTENT_BREW_DIR" 2>/dev/null || true
-    echo "INFO: Copied Homebrew to persistent storage at $PERSISTENT_BREW_DIR"
+    echo "INFO: Homebrew not available (install may have failed during image build)"
   fi
-  # Replace image dir with symlink to persistent copy
-  rm -rf "$IMAGE_BREW_DIR"
-  ln -sf "$PERSISTENT_BREW_DIR" "$IMAGE_BREW_DIR"
-elif [ -L "$IMAGE_BREW_DIR" ]; then
-  echo "INFO: Homebrew already linked to persistent storage"
-elif [ -d "$PERSISTENT_BREW_DIR" ]; then
-  # Image doesn't have Homebrew (failed install?) but persistent copy exists
-  mkdir -p "$(dirname "$IMAGE_BREW_DIR")"
-  ln -sf "$PERSISTENT_BREW_DIR" "$IMAGE_BREW_DIR"
-  echo "INFO: Restored Homebrew symlink from persistent storage"
+  echo "INFO: persist_brew_tools=true; brew-installed tools will survive add-on rebuilds."
 else
-  echo "INFO: Homebrew not available (install may have failed during image build)"
+  warn_legacy_persistent_dir "$PERSISTENT_BREW_DIR" "Homebrew data"
+  echo "INFO: persist_brew_tools=false; Homebrew installs stay ephemeral and excluded from HA backups."
 fi
 
 # Back-compat: some docs/scripts assume /data; point it at /config.
@@ -513,6 +542,69 @@ if ! command -v openclaw >/dev/null 2>&1; then
   exit 1
 fi
 
+get_openclaw_version() {
+  local raw
+  raw="$(openclaw --version 2>/dev/null | head -n 1 || true)"
+  printf '%s\n' "$raw" | grep -oE '[0-9]{4}\.[0-9]+\.[0-9]+' | head -n 1 || true
+}
+
+version_is_less_than() {
+  local left="$1"
+  local right="$2"
+  [ -n "$left" ] && [ -n "$right" ] && [ "$left" != "$right" ] && \
+    [ "$(printf '%s\n%s\n' "$left" "$right" | sort -V | head -n 1)" = "$left" ]
+}
+
+repair_runtime_version_mismatch() {
+  local config_path="/config/.openclaw/openclaw.json"
+  local runtime_version persisted_version refreshed_version
+
+  if [ ! -f "$config_path" ]; then
+    return 0
+  fi
+
+  runtime_version="$(get_openclaw_version)"
+  persisted_version="$(python3 - "$config_path" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+try:
+    data = json.loads(path.read_text(encoding="utf-8"))
+except Exception:
+    print("", end="")
+    raise SystemExit(0)
+
+value = data.get("meta", {}).get("lastTouchedVersion", "")
+print(value if isinstance(value, str) else "", end="")
+PY
+)"
+
+  if [ -z "$runtime_version" ] || [ -z "$persisted_version" ]; then
+    return 0
+  fi
+
+  if ! version_is_less_than "$runtime_version" "$persisted_version"; then
+    return 0
+  fi
+
+  echo "WARN: Persisted OpenClaw config was last written by newer version $persisted_version, but bundled runtime is $runtime_version."
+  echo "WARN: Attempting one-time runtime repair so the gateway can start after add-on rebuilds or Home Assistant OS updates."
+
+  if npm install -g "openclaw@${persisted_version}" >/tmp/openclaw-runtime-repair.log 2>&1; then
+    refreshed_version="$(get_openclaw_version)"
+    echo "INFO: OpenClaw runtime repair succeeded (${runtime_version} -> ${refreshed_version:-$persisted_version})."
+    return 0
+  fi
+
+  echo "ERROR: Automatic runtime repair failed; startup will continue with bundled OpenClaw $runtime_version."
+  echo "ERROR: Review /tmp/openclaw-runtime-repair.log and rerun 'openclaw update' or 'npm install -g openclaw@${persisted_version}' once connectivity is available."
+  return 0
+}
+
+repair_runtime_version_mismatch
+
 # Bootstrap minimal OpenClaw config ONLY if missing.
 # We do not overwrite or patch existing configs; onboarding owns everything else.
 OPENCLAW_CONFIG_PATH="/config/.openclaw/openclaw.json"
@@ -606,6 +698,71 @@ if [ "$ENABLE_HTTPS_PROXY" = "true" ]; then
   CERT_DIR="/config/certs"
   mkdir -p "$CERT_DIR"
 
+  cert_ext_contains() {
+    local cert_path="$1"
+    local extension_name="$2"
+    local expected="$3"
+    openssl x509 -in "$cert_path" -noout -ext "$extension_name" 2>/dev/null | grep -Fq "$expected"
+  }
+
+  local_ca_cert_is_valid() {
+    local cert_path="$1"
+    [ -f "$cert_path" ] && \
+      cert_ext_contains "$cert_path" basicConstraints "CA:TRUE" && \
+      cert_ext_contains "$cert_path" keyUsage "Certificate Sign, CRL Sign"
+  }
+
+  gateway_server_cert_is_valid() {
+    local cert_path="$1"
+    [ -f "$cert_path" ] && \
+      cert_ext_contains "$cert_path" extendedKeyUsage "TLS Web Server Authentication" && \
+      cert_ext_contains "$cert_path" subjectAltName "DNS:localhost"
+  }
+
+  generate_local_ca_cert() {
+    cat > "$CERT_DIR/_ca.ext" <<'CAEOF'
+[v3_ca]
+basicConstraints=critical,CA:TRUE
+keyUsage=critical,keyCertSign,cRLSign
+subjectKeyIdentifier=hash
+authorityKeyIdentifier=keyid:always,issuer
+CAEOF
+
+    openssl genrsa -out "$CERT_DIR/ca.key" 2048 2>/dev/null
+    openssl req -new -key "$CERT_DIR/ca.key" -out "$CERT_DIR/ca.csr" \
+      -subj "/CN=OpenClaw Local CA" 2>/dev/null
+    openssl x509 -req -in "$CERT_DIR/ca.csr" -signkey "$CERT_DIR/ca.key" \
+      -out "$CERT_DIR/ca.crt" -days 3650 \
+      -extfile "$CERT_DIR/_ca.ext" -extensions v3_ca 2>/dev/null
+
+    rm -f "$CERT_DIR/ca.csr" "$CERT_DIR/_ca.ext"
+    chmod 600 "$CERT_DIR/ca.key"
+  }
+
+  generate_gateway_server_cert() {
+    openssl genrsa -out "$CERT_DIR/gateway.key" 2048 2>/dev/null
+    openssl req -new -key "$CERT_DIR/gateway.key" -out "$CERT_DIR/gateway.csr" \
+      -subj "/CN=OpenClaw Gateway" 2>/dev/null
+
+    cat > "$CERT_DIR/_server.ext" <<SERVER_EOF
+[v3_server]
+basicConstraints=critical,CA:FALSE
+keyUsage=critical,digitalSignature,keyEncipherment
+extendedKeyUsage=serverAuth
+subjectAltName=IP:${LAN_IP:-127.0.0.1},IP:127.0.0.1,DNS:localhost,DNS:homeassistant,DNS:homeassistant.local${EXTRA_SANS:+,${EXTRA_SANS}}
+subjectKeyIdentifier=hash
+authorityKeyIdentifier=keyid,issuer
+SERVER_EOF
+
+    openssl x509 -req -in "$CERT_DIR/gateway.csr" \
+      -CA "$CERT_DIR/ca.crt" -CAkey "$CERT_DIR/ca.key" -CAcreateserial \
+      -out "$CERT_DIR/gateway.crt" -days 3650 \
+      -extfile "$CERT_DIR/_server.ext" -extensions v3_server 2>/dev/null
+
+    rm -f "$CERT_DIR/gateway.csr" "$CERT_DIR/_server.ext" "$CERT_DIR/ca.srl"
+    chmod 600 "$CERT_DIR/gateway.key"
+  }
+
   # Detect primary LAN IP
   LAN_IP=$(hostname -I 2>/dev/null | awk '{print $1}')
   STORED_IP=$(cat "$CERT_DIR/.cert_ip" 2>/dev/null || echo "")
@@ -613,12 +770,17 @@ if [ "$ENABLE_HTTPS_PROXY" = "true" ]; then
   # --- Local CA (generated once, persists across restarts) ---
   if [ ! -f "$CERT_DIR/ca.key" ] || [ ! -f "$CERT_DIR/ca.crt" ]; then
     echo "INFO: Generating local CA certificate (one-time)..."
-    openssl genrsa -out "$CERT_DIR/ca.key" 2048 2>/dev/null
-    openssl req -new -x509 -key "$CERT_DIR/ca.key" -out "$CERT_DIR/ca.crt" \
-      -days 3650 -nodes -subj "/CN=OpenClaw Local CA" 2>/dev/null
-    chmod 600 "$CERT_DIR/ca.key"
+    generate_local_ca_cert
     STORED_IP=""  # force server cert regeneration
     echo "INFO: Local CA created at $CERT_DIR/ca.crt"
+  elif ! local_ca_cert_is_valid "$CERT_DIR/ca.crt"; then
+    echo "WARN: Existing local CA certificate is missing required X.509 CA extensions."
+    echo "WARN: Regenerating CA/server certificates for OpenSSL and Python strict verification compatibility."
+    echo "WARN: Devices that trusted the old CA need the new /cert/ca.crt installed again."
+    rm -f "$CERT_DIR/ca.key" "$CERT_DIR/ca.crt" "$CERT_DIR/gateway.key" "$CERT_DIR/gateway.crt"
+    generate_local_ca_cert
+    STORED_IP=""
+    echo "INFO: Local CA rotated at $CERT_DIR/ca.crt"
   fi
 
   # --- Extra SANs from gateway_additional_allowed_origins + gateway_public_url ---
@@ -652,24 +814,9 @@ PY
   STORED_EXTRA_SANS=$(cat "$CERT_DIR/.cert_extra_sans" 2>/dev/null || echo "")
 
   # --- Server cert (regenerated when LAN IP or SANs change) ---
-  if [ ! -f "$CERT_DIR/gateway.crt" ] || [ ! -f "$CERT_DIR/gateway.key" ] || [ "$LAN_IP" != "$STORED_IP" ] || [ "$EXTRA_SANS" != "$STORED_EXTRA_SANS" ]; then
+  if [ ! -f "$CERT_DIR/gateway.crt" ] || [ ! -f "$CERT_DIR/gateway.key" ] || [ "$LAN_IP" != "$STORED_IP" ] || [ "$EXTRA_SANS" != "$STORED_EXTRA_SANS" ] || ! gateway_server_cert_is_valid "$CERT_DIR/gateway.crt"; then
     echo "INFO: Generating server TLS certificate for IP: ${LAN_IP:-unknown}..."
-    openssl genrsa -out "$CERT_DIR/gateway.key" 2048 2>/dev/null
-    openssl req -new -key "$CERT_DIR/gateway.key" -out "$CERT_DIR/gateway.csr" \
-      -subj "/CN=OpenClaw Gateway" 2>/dev/null
-
-    # SAN extension — include LAN IP, loopback, common mDNS names + user extras
-    cat > "$CERT_DIR/_san.ext" <<SANEOF
-subjectAltName=IP:${LAN_IP:-127.0.0.1},IP:127.0.0.1,DNS:localhost,DNS:homeassistant,DNS:homeassistant.local${EXTRA_SANS:+,${EXTRA_SANS}}
-SANEOF
-
-    openssl x509 -req -in "$CERT_DIR/gateway.csr" \
-      -CA "$CERT_DIR/ca.crt" -CAkey "$CERT_DIR/ca.key" -CAcreateserial \
-      -out "$CERT_DIR/gateway.crt" -days 3650 \
-      -extfile "$CERT_DIR/_san.ext" 2>/dev/null
-
-    rm -f "$CERT_DIR/gateway.csr" "$CERT_DIR/_san.ext" "$CERT_DIR/ca.srl"
-    chmod 600 "$CERT_DIR/gateway.key"
+    generate_gateway_server_cert
     printf '%s' "$LAN_IP" > "$CERT_DIR/.cert_ip"
     printf '%s' "$EXTRA_SANS" > "$CERT_DIR/.cert_extra_sans"
     echo "INFO: Server TLS certificate generated (SAN: IP:${LAN_IP:-127.0.0.1}${EXTRA_SANS:+,${EXTRA_SANS}})"
@@ -773,7 +920,7 @@ if [ "$AUTO_CONFIGURE_MCP" = "true" ] && [ -n "$HA_TOKEN" ]; then
       fi
     fi
   else
-    echo "INFO: mcporter not available; skipping MCP auto-configuration (run 'openclaw onboard' first)"
+    echo "WARN: mcporter is missing from the add-on image; skipping MCP auto-configuration"
   fi
 elif [ "$AUTO_CONFIGURE_MCP" = "true" ] && [ -z "$HA_TOKEN" ]; then
   echo "INFO: MCP auto-configure enabled but homeassistant_token not set — skipping"

openclaw_assistant/translations/bg.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Изчистване на заключвания при изход
     description: Изчистване на заключващи файлове на сесии при нормално спиране на добавката
+
+  persist_node_global:
+    name: Запазване на npm глобални умения
+    description: Когато е ВКЛ., съхранява инсталираните от потребителя npm умения и глобални пакети в /config/.node_global, за да оцелеят при преизграждане на добавката. По подразбиране е ИЗКЛ. за по-малки HA архиви.
+
+  persist_brew_tools:
+    name: Запазване на Homebrew инструменти
+    description: Когато е ВКЛ., съхранява Homebrew и инсталираните с brew CLI инструменти в /config/.linuxbrew, за да оцелеят при преизграждане на добавката. По подразбиране е ИЗКЛ. за по-малки HA архиви.
   
   gateway_mode:
     name: Режим на Gateway

openclaw_assistant/translations/de.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Sitzungssperren beim Beenden bereinigen
     description: Sitzungssperrdateien beim ordnungsgemäßen Stoppen des Add-ons bereinigen
+
+  persist_node_global:
+    name: npm-Globale Skills dauerhaft speichern
+    description: Wenn EIN, werden benutzerinstallierte npm-Skills und globale Pakete unter /config/.node_global gespeichert und über Add-on-Neubuilds hinweg behalten. Standard ist AUS, um Home-Assistant-Backups klein zu halten.
+
+  persist_brew_tools:
+    name: Homebrew-Tools dauerhaft speichern
+    description: Wenn EIN, werden Homebrew und per brew installierte CLI-Tools unter /config/.linuxbrew gespeichert und über Add-on-Neubuilds hinweg behalten. Standard ist AUS, um Home-Assistant-Backups klein zu halten.
   
   gateway_mode:
     name: Gateway-Modus

openclaw_assistant/translations/en.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Clean Session Locks on Exit
     description: Cleanup session lock files when add-on stops gracefully
+
+  persist_node_global:
+    name: Persist npm Global Skills
+    description: When ON, store user-installed npm skills and global packages under /config/.node_global so they survive add-on rebuilds. Default OFF to keep Home Assistant backups smaller.
+
+  persist_brew_tools:
+    name: Persist Homebrew Tools
+    description: When ON, store Homebrew and brew-installed CLI tools under /config/.linuxbrew so they survive add-on rebuilds. Default OFF to keep Home Assistant backups smaller.
   
   gateway_mode:
     name: Gateway Mode

openclaw_assistant/translations/es.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Limpiar bloqueos de sesión al salir
     description: Limpiar archivos de bloqueo de sesión cuando el complemento se detiene correctamente
+
+  persist_node_global:
+    name: Conservar habilidades globales de npm
+    description: Cuando está activado, guarda las habilidades npm instaladas por el usuario y los paquetes globales en /config/.node_global para que sobrevivan a reconstrucciones del complemento. Por defecto está desactivado para mantener pequeñas las copias de seguridad de Home Assistant.
+
+  persist_brew_tools:
+    name: Conservar herramientas de Homebrew
+    description: Cuando está activado, guarda Homebrew y las herramientas CLI instaladas con brew en /config/.linuxbrew para que sobrevivan a reconstrucciones del complemento. Por defecto está desactivado para mantener pequeñas las copias de seguridad de Home Assistant.
   
   gateway_mode:
     name: Modo del Gateway

openclaw_assistant/translations/pl.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Wyczyść blokady sesji przy wyjściu
     description: Usuń pliki blokad sesji gdy dodatek zatrzymuje się poprawnie
+
+  persist_node_global:
+    name: Zachowuj globalne umiejętności npm
+    description: Po włączeniu zapisuje umiejętności npm instalowane przez użytkownika i pakiety globalne w /config/.node_global, aby przetrwały przebudowę dodatku. Domyślnie wyłączone, aby kopie zapasowe Home Assistant były mniejsze.
+
+  persist_brew_tools:
+    name: Zachowuj narzędzia Homebrew
+    description: Po włączeniu zapisuje Homebrew i narzędzia CLI instalowane przez brew w /config/.linuxbrew, aby przetrwały przebudowę dodatku. Domyślnie wyłączone, aby kopie zapasowe Home Assistant były mniejsze.
   
   gateway_remote_url:
     name: URL zdalnego Gateway

openclaw_assistant/translations/pt-BR.yaml

@@ -42,6 +42,14 @@ configuration:
   clean_session_locks_on_exit:
     name: Limpar Bloqueios de Sessão ao Sair
     description: Limpar arquivos de bloqueio de sessão quando o add-on parar normalmente
+
+  persist_node_global:
+    name: Persistir skills globais do npm
+    description: Quando ativado, armazena skills npm instaladas pelo usuário e pacotes globais em /config/.node_global para sobreviverem a reconstruções do add-on. O padrão é desativado para manter menores os backups do Home Assistant.
+
+  persist_brew_tools:
+    name: Persistir ferramentas do Homebrew
+    description: Quando ativado, armazena o Homebrew e ferramentas CLI instaladas via brew em /config/.linuxbrew para sobreviverem a reconstruções do add-on. O padrão é desativado para manter menores os backups do Home Assistant.
   
   gateway_mode:
     name: Modo do Gateway