fix: correct bundled OpenClaw version for 0.5.87

Co-authored-by: root <root@0bfc167e-openclaw-assistant.local.hass.io>
Merge pull request #167 from techartdev/bot/openclaw-bump-2026.7.1-2
2026-08-14 08:52:15 +00:00 · 2026-08-11 15:32:12 +03:00 · 2026-08-10 14:38:47 +03:00 · 2026-08-10 09:00:46 +03:00 · 2026-07-21 15:07:59 +03:00 · 2026-07-21 15:07:33 +03:00
24 changed files with 1801 additions and 295 deletions
@@ -1,68 +0,0 @@
-name: Announce release to Discord
-
-on:
-release:
-types: [published]
-
-permissions:
-contents: read
-
-jobs:
-notify-discord:
-runs-on: ubuntu-latest
-steps:
- name: Post release announcement to Discord
-env:
-DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-RELEASE_NAME: ${{ github.event.release.name }}
-RELEASE_TAG: ${{ github.event.release.tag_name }}
-RELEASE_URL: ${{ github.event.release.html_url }}
-RELEASE_BODY: ${{ github.event.release.body }}
-REPO: ${{ github.repository }}
-run: |
-if [ -z "$DISCORD_WEBHOOK_URL" ]; then
-echo "DISCORD_WEBHOOK_URL is not configured; skipping."
-exit 0
-fi
-
-if [ -n "$RELEASE_NAME" ]; then
-TITLE="$RELEASE_NAME"
-else
-TITLE="$RELEASE_TAG"
-fi
-
-BODY_CLEAN=$(printf '%s' "$RELEASE_BODY" | sed 's/\r//g')
-BODY_TRIM=$(printf '%s' "$BODY_CLEAN" | sed '/^[[:space:]]*$/d')
-
-if [ -n "$BODY_TRIM" ]; then
-SUMMARY=$(printf '%s' "$BODY_TRIM" | head -c 1400)
-else
-SUMMARY="No release notes provided."
-fi
-
-PAYLOAD=$(jq -n \
--arg title "🚀 New release published: $TITLE" \
--arg repo "$REPO" \
--arg tag "$RELEASE_TAG" \
--arg url "$RELEASE_URL" \
--arg summary "$SUMMARY" \
-'{
-content: "",
-embeds: [
-{
-title: $title,
-url: $url,
-color: 5814783,
-fields: [
-{name: "Repository", value: $repo, inline: true},
-{name: "Tag", value: $tag, inline: true},
-{name: "Release URL", value: $url, inline: false},
-{name: "Release notes", value: $summary, inline: false}
-]
-}
-]
-}')
-
-curl -sS -X POST "$DISCORD_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d "$PAYLOAD"
@@ -0,0 +1,56 @@
+# OpenClaw Home Assistant Add-on Patterns
+
+Always reuse existing logic in `run.sh`, `oc_config_helper.py`, and `render_nginx.py`.
+Avoid duplicate implementations for config parsing, gateway patching, or template rendering.
+Respect guidelines in AGENTS.md
+
+## Stack
+
+- Home Assistant add-on (Debian Bookworm base)
+- Bash runtime orchestrator (`run.sh`)
+- Python helper scripts for config/template work
+- nginx template rendering
+- YAML config schema + 6 locale translation files
+
+## Source of Truth
+
+- Add-on options/schema: `openclaw_assistant_dev/config.yaml`
+- Runtime boot logic: `openclaw_assistant_dev/run.sh`
+- Safe OpenClaw config edits: `openclaw_assistant_dev/oc_config_helper.py`
+- nginx + landing rendering: `openclaw_assistant_dev/render_nginx.py`
+- UI text in Home Assistant: `openclaw_assistant_dev/translations/*.yaml`
+- User-facing docs: `DOCS.md`
+
+## Required Sync Rules
+
+When changing add-on options, update in the same PR:
+
+1. `config.yaml` option default + schema
+2. All translation files (`en`, `bg`, `de`, `es`, `pl`, `pt-BR`)
+3. `DOCS.md` config/troubleshooting sections
+4. `CHANGELOG.md`
+
+When changing landing/nginx placeholders:
+- Keep template keys and `render_nginx.py` replacements in sync.
+
+## Security Rules
+
+- Do not log secrets/tokens.
+- For gateway token docs/UI guidance, do not use `openclaw config get gateway.auth.token` (redacted in v2026.2.22+).
+- Prefer `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`.
+
+## Editing Rules
+
+- Keep fixes minimal and root-cause focused.
+- Preserve backward compatibility for existing add-on options unless migration is explicit.
+- Do not change unrelated behavior while fixing one issue.
+
+## Validation Commands
+
+```sh
+bash -n openclaw_assistant_dev/run.sh
+python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py
+python3 -m py_compile openclaw_assistant_dev/render_nginx.py
+```
+
+If behavior changes are user-visible, update `openclaw_assistant_dev/CHANGELOG.md`.
@@ -0,0 +1,68 @@
+name: Announce release to Discord
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  notify-discord:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post release announcement to Discord
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          RELEASE_NAME: ${{ github.event.release.name }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_URL: ${{ github.event.release.html_url }}
+          RELEASE_BODY: ${{ github.event.release.body }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -z "$DISCORD_WEBHOOK_URL" ]; then
+            echo "DISCORD_WEBHOOK_URL is not configured; skipping."
+            exit 0
+          fi
+
+          if [ -n "$RELEASE_NAME" ]; then
+            TITLE="$RELEASE_NAME"
+          else
+            TITLE="$RELEASE_TAG"
+          fi
+
+          BODY_CLEAN=$(printf '%s' "$RELEASE_BODY" | sed 's/\r//g')
+          BODY_TRIM=$(printf '%s' "$BODY_CLEAN" | sed '/^[[:space:]]*$/d')
+
+          if [ -n "$BODY_TRIM" ]; then
+            SUMMARY=$(printf '%s' "$BODY_TRIM" | head -c 1400)
+          else
+            SUMMARY="No release notes provided."
+          fi
+
+          PAYLOAD=$(jq -n \
+            --arg title "🚀 New App/Add-on release published: $TITLE" \
+            --arg repo "$REPO" \
+            --arg tag "$RELEASE_TAG" \
+            --arg url "$RELEASE_URL" \
+            --arg summary "$SUMMARY" \
+            '{
+              content: "",
+              embeds: [
+                {
+                  title: $title,
+                  url: $url,
+                  color: 5814783,
+                  fields: [
+                    {name: "Repository", value: $repo, inline: true},
+                    {name: "Tag", value: $tag, inline: true},
+                    {name: "Release URL", value: $url, inline: false},
+                    {name: "Release notes", value: $summary, inline: false}
+                  ]
+                }
+              ]
+            }')
+
+          curl -sS -X POST "$DISCORD_WEBHOOK_URL" \
+            -H "Content-Type: application/json" \
+            -d "$PAYLOAD"
@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "timonwong.shellcheck",
+    "redhat.vscode-yaml",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "esbenp.prettier-vscode"
+  ]
+}
@@ -0,0 +1,44 @@
+{
+  "editor.formatOnSave": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.eol": "\n",
+
+  "[shellscript]": {
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true
+  },
+  "[yaml]": {
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true
+  },
+  "[python]": {
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true
+  },
+  "[markdown]": {
+    "editor.wordWrap": "on",
+    "editor.quickSuggestions": {
+      "comments": "off",
+      "strings": "off",
+      "other": "off"
+    }
+  },
+
+  "files.associations": {
+    "*.tpl": "nginx"
+  },
+
+  "yaml.validate": true,
+  "yaml.format.enable": true,
+
+  "shellcheck.enable": true,
+  "shellcheck.run": "onType",
+
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.autoImportCompletions": true,
+
+  "search.exclude": {
+    "**/__pycache__": true
+  }
+}
@@ -0,0 +1,108 @@
+# Repository Guidelines
+
+## Project Scope
+
+This repository builds the **OpenClaw Assistant (DEV)** Home Assistant add-on.
+The add-on packages OpenClaw + nginx + ttyd and manages startup/configuration glue.
+
+## Architecture at a Glance
+
+- Add-on root metadata/docs:
+  - `README.md`
+  - `DOCS.md`
+  - `SECURITY.md`
+  - `repository.yaml`
+- Runtime implementation (all add-on behavior lives here):
+  - `openclaw_assistant_dev/run.sh` (PID 1 orchestrator)
+  - `openclaw_assistant_dev/oc_config_helper.py` (safe JSON config edits)
+  - `openclaw_assistant_dev/render_nginx.py` (template rendering)
+  - `openclaw_assistant_dev/nginx.conf.tpl`
+  - `openclaw_assistant_dev/landing.html.tpl`
+  - `openclaw_assistant_dev/config.yaml` (HA options + schema)
+  - `openclaw_assistant_dev/translations/*.yaml` (all locale UI strings)
+  - `openclaw_assistant_dev/Dockerfile`
+  - `openclaw_assistant_dev/CHANGELOG.md`
+
+## Core Rules
+
+- Fix root causes, not symptoms.
+- Keep edits surgical; do not refactor unrelated code.
+- Never introduce insecure defaults.
+- Never log secrets or auth tokens.
+- Keep behavior backward-compatible unless the change explicitly requires a migration.
+
+## Add-on Config Coupling Rules (Critical)
+
+When adding/changing any add-on option, update **all** of the following in one change:
+
+1. `openclaw_assistant_dev/config.yaml`
+   - `options:` default
+   - `schema:` validation entry
+   - comments/help text
+2. `openclaw_assistant_dev/translations/en.yaml`
+3. `openclaw_assistant_dev/translations/bg.yaml`
+4. `openclaw_assistant_dev/translations/de.yaml`
+5. `openclaw_assistant_dev/translations/es.yaml`
+6. `openclaw_assistant_dev/translations/pl.yaml`
+7. `openclaw_assistant_dev/translations/pt-BR.yaml`
+8. `DOCS.md` configuration reference / troubleshooting if user-facing
+9. `openclaw_assistant_dev/CHANGELOG.md`
+
+If any of these are skipped, the UX becomes inconsistent in HA.
+
+## Runtime Safety Rules
+
+- `run.sh` runs with `set -euo pipefail`; avoid constructs that fail unexpectedly under `set -e`.
+- Validate all user-provided values from `/data/options.json` before injecting into shell/nginx/openclaw config.
+- Keep `run.sh` idempotent on restart (multiple starts must not corrupt state).
+- Treat `/config/` as persistent state; never wipe user data unless explicitly requested.
+
+## Gateway/Auth/Security Rules
+
+- OpenClaw v2026.2.22+ redacts sensitive values in `openclaw config get`.
+  - For token retrieval guidance, prefer: `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`.
+- `trusted-proxy` mode may reject direct local CLI WS calls (`trusted_proxy_user_missing`); document this clearly instead of hiding it.
+- For `lan_https` certificate logic, keep SAN generation deterministic and regeneration-triggered on SAN/IP changes.
+
+## Template Coupling Rules
+
+- If adding placeholders in `landing.html.tpl` or `nginx.conf.tpl`, update `render_nginx.py` in the same change.
+- If landing-page guidance changes (commands/errors), sync corresponding troubleshooting text in `DOCS.md`.
+
+## Versioning and Changelog
+
+- User-visible changes should update:
+  - `openclaw_assistant_dev/CHANGELOG.md`
+  - `openclaw_assistant_dev/config.yaml` version
+- Keep changelog entries user-facing and action-oriented.
+
+## Coding Style
+
+- Shell: POSIX-friendly Bash, explicit quoting, descriptive variable names.
+- Python: small focused helpers, explicit error handling, no hidden side effects.
+- YAML/Markdown: preserve existing style and structure.
+- Avoid adding dependencies unless necessary.
+
+## Validation Checklist (Run After Relevant Changes)
+
+From repo root:
+
+```sh
+bash -n openclaw_assistant_dev/run.sh
+python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py
+python3 -m py_compile openclaw_assistant_dev/render_nginx.py
+```
+
+For option changes:
+- verify `config.yaml` option + schema + all translations exist
+- verify `DOCS.md` matches current behavior
+
+For startup/auth/proxy/cert changes:
+- verify log messages remain clear and actionable
+- verify `landing.html.tpl` instructions match actual commands
+
+## Commit Scope
+
+- Group related changes only.
+- Do not include unrelated formatting churn.
+- Do not edit generated/cache folders (`__pycache__`, temporary outputs).
@@ -0,0 +1 @@
+AGENTS.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) |

@@ -89,6 +89,8 @@ openclaw onboard

 This interactive wizard walks you through connecting your AI providers (OpenAI, Google, Anthropic, etc.) and basic configuration.

+> **Note (v0.5.54+)**: If onboarding triggers a gateway runtime restart, the add-on now keeps nginx/terminal alive and auto-recovers the runtime instead of restarting the whole container.
+
 Alternatively, for more granular control:

 ```sh
@@ -100,17 +102,20 @@ openclaw configure
 The gateway requires a token for authentication. To retrieve it:

 ```sh
-openclaw config get gateway.auth.token
+jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json
 ```

+> **Note**: Since OpenClaw v2026.2.22+ `openclaw config get` redacts sensitive values (returns `openclaw_redacted`). Read the token directly from the config file with `jq` as shown above.
+
 Save this token — you'll need it to access the Gateway Web UI and for API integrations.

 ### Step 3 — Verify everything works

 1. In the terminal, confirm the gateway is running:
   ```sh
-   openclaw gateway status
+   oc-gateway status
   ```
+   > In this add-on, the gateway is supervised by `run.sh` (not systemd), so `openclaw gateway status` can show misleading service-manager warnings.
 2. Click the **Open Gateway Web UI** button on the landing page
 3. If prompted for a token, paste the one from Step 2 or go to the Overview tab, paste the token in the 'Gateway Token' field and press Connect.

@@ -240,9 +245,11 @@ This means the browser is connecting over plain HTTP. **Solutions**:
 If the Gateway UI shows **Unauthorized**, re-check your token:

 ```sh
-openclaw config get gateway.auth.token
+jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json
 ```

+> **Note**: Since OpenClaw v2026.2.22+ `openclaw config get` redacts sensitive values — use `jq` to read directly from the config file.
+
 ---

 ## 5. Configuration Reference
@@ -260,19 +267,22 @@ All options are set via **Settings → Apps/Add-ons → OpenClaw Assistant → C
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `gateway_mode` | `local` / `remote` | `local` | **local**: run gateway in this add-on. **remote**: connect to an external gateway |
+| `gateway_remote_url` | string | _(empty)_ | Remote gateway WebSocket URL used when `gateway_mode: remote` (example: `ws://192.168.1.20:18789` or `wss://gateway.example.com:443`) |
 | `gateway_bind_mode` | `loopback` / `lan` / `tailnet` | `loopback` | **loopback**: 127.0.0.1 only (secure). **lan**: all interfaces (LAN-accessible). **tailnet**: Tailscale interface only. Only applies when `gateway_mode` is `local` |
 | `gateway_port` | int | `18789` | Port for the gateway. Only applies when `gateway_mode` is `local` |
 | `access_mode` | `custom` / `local_only` / `lan_https` / `lan_reverse_proxy` / `tailnet_https` | `custom` | **Simplifies secure access setup.** `custom`: use individual settings (backward-compatible). `lan_https`: built-in HTTPS proxy for LAN (recommended for phones). `lan_reverse_proxy`: external reverse proxy. `tailnet_https`: Tailscale. `local_only`: Ingress only. See [Accessing the Gateway Web UI](#4-accessing-the-gateway-web-ui) |
-| `gateway_public_url` | string | _(empty)_ | Public URL for the "Open Gateway Web UI" button. Auto-constructed in `lan_https` mode if empty. Example: `https://192.168.1.119:18789` |
+| `gateway_public_url` | string | _(empty)_ | Public URL for the "Open Gateway Web UI" button. Auto-constructed in `lan_https` mode if empty. Example: `https://192.168.1.119:18789`. In newer versions this origin is also merged into `gateway.controlUi.allowedOrigins` to reduce reverse-proxy origin errors. |
 | `enable_openai_api` | bool | `false` | Enable the OpenAI-compatible `/v1/chat/completions` endpoint. Required for [Assist pipeline integration](#6c-assist-pipeline-integration-openai-api) |
 | `gateway_auth_mode` | `token` / `trusted-proxy` | `token` | Gateway auth mode. Use `trusted-proxy` when terminating HTTPS in a reverse proxy and forwarding trusted auth headers. |
 | `gateway_trusted_proxies` | string | _(empty)_ | Comma-separated trusted proxy IP/CIDR list used with `gateway_auth_mode: trusted-proxy`. |
-
-When `gateway_auth_mode: trusted-proxy` is used, the add-on sets `gateway.auth.trustedProxy.userHeader` to `x-forwarded-user` by default.
+| `gateway_additional_allowed_origins` | string | _(empty)_ | Comma-separated additional origins merged into `gateway.controlUi.allowedOrigins` in `lan_https` mode (example: `https://ha.example.com:8443,capacitor://localhost`). |
+| `controlui_disable_device_auth` | bool | `true` | Controls `gateway.controlUi.dangerouslyDisableDeviceAuth` in `lan_https` mode. **ON (recommended):** skip per-device pairing approval, avoid error 1008 on LAN HTTPS, token auth still required. **OFF:** enforce per-device pairing prompts (stricter, but more friction). |
 | `force_ipv4_dns` | bool | `true` | Force IPv4-first DNS ordering for Node network calls. **Recommended ON** — most HAOS VMs lack IPv6 egress, causing `web_fetch` and Telegram timeouts. Set to `false` only if your network has working IPv6. |
 | `gateway_env_vars` | list of `{name, value}` | `[]` | Environment variables exported to the gateway process at startup. UI format: list entries with `name` and `value` (example: `name=OPENAI_API_KEY`, `value=sk-...`). Limits: max 50 vars, key length 255, value length 10000. Reserved runtime keys are blocked (for example `PATH`, `HOME`, `NODE_OPTIONS`, `NODE_PATH`, `OPENCLAW_*`, proxy vars). Legacy string/object formats are still accepted for backward compatibility. |
 | `nginx_log_level` | `full` / `minimal` | `minimal` | Nginx access log verbosity. `minimal` suppresses repetitive Home Assistant health-check and polling requests (`GET /`, `GET /v1/models`). `full` logs everything. |

+When `gateway_auth_mode: trusted-proxy` is used, the add-on sets `gateway.auth.trustedProxy.userHeader` to `x-forwarded-user` by default.
+
 ### Terminal

 | Option | Type | Default | Description |
@@ -305,7 +315,9 @@ To provide the SSH key: place the private key file in the add-on config director
 |---|---|---|---|
 | `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 |
-
+| `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
@@ -346,14 +358,12 @@ This is the most common setup — accessing the Gateway Web UI from a browser on
 If you have an OpenClaw gateway running on a different machine (e.g., a more powerful server), you can configure this add-on to connect to it instead of running its own.

 1. Set `gateway_mode`: **remote**
-2. In the add-on terminal, configure the remote gateway URL:
-   ```sh
-   openclaw config set gateway.url <remote-gateway-url>
-   ```
+2. Set `gateway_remote_url` in add-on configuration (example: `wss://gateway.example.com:443`)
 3. Restart the add-on

 When `gateway_mode` is `remote`:
 - The add-on does **not** start a local gateway process
+- The add-on writes `gateway.remote.url` from `gateway_remote_url` on startup
 - `gateway_bind_mode` and `gateway_port` are ignored
 - The terminal and landing page still work normally
 - You still need the remote gateway's auth token
@@ -449,7 +459,7 @@ openclaw config set gateway.http.endpoints.chatCompletions.enabled true
 1. Go to **Settings → Devices & Services → Add Integration**
 2. Search for **Extended OpenAI Conversation**
 3. Configure:
-   - **API Key**: your gateway token (`openclaw config get gateway.auth.token`)
+   - **API Key**: your gateway token — run `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json` in the terminal
   - **Base URL**: `http://127.0.0.1:18789/v1`
   - **API Version**: leave empty
   - **Organization**: leave empty
@@ -473,6 +483,71 @@ You can now use Assist (voice or text) and OpenClaw will handle conversations, c

 The add-on includes **Chromium** for browser-based automation tasks. OpenClaw can use it for web scraping, form filling, website testing, and other browser automation skills.

+### 6d-mcp. MCP Integration (Home Assistant Control)
+
+The **Model Context Protocol (MCP)** lets OpenClaw communicate directly with Home Assistant — reading entity states, calling services, creating automations, and more. This is the recommended way to give OpenClaw full control over your smart home.
+
+#### Automatic setup (recommended)
+
+1. Create a **long-lived access token** in Home Assistant:
+   - Go to your HA profile page (click your user avatar at the bottom of the sidebar)
+   - Scroll to **Long-Lived Access Tokens** → **Create Token**
+   - Give it a name (e.g. "OpenClaw") and copy the token
+2. Paste the token into the add-on option **Home Assistant Token** (`homeassistant_token`) in **Settings → Add-ons → OpenClaw Assistant → Configuration**
+3. Set **Auto-Configure MCP for Home Assistant** (`auto_configure_mcp`) to **ON**
+4. Restart the add-on
+
+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
+```
+
+On subsequent restarts, the configuration is skipped if the token hasn’t changed.
+
+#### Manual setup
+
+If you prefer to configure MCP manually (or `auto_configure_mcp` is off), run this in the add-on terminal:
+
+```sh
+mcporter config add HA "http://localhost:8123/api/mcp" \
+  --header "Authorization=Bearer YOUR_LONG_LIVED_TOKEN" \
+  --scope home
+```
+
+Replace `YOUR_LONG_LIVED_TOKEN` with your HA long-lived access token.
+
+#### Verifying MCP works
+
+After setup, ask OpenClaw something like:
+- _"Turn off the living room lights"_
+- _"What’s the temperature of the bedroom sensor?"_
+- _"List all entities in the kitchen"_
+
+If OpenClaw can execute HA actions, MCP is working.
+
+#### Refreshing HA context after upgrades
+
+If OpenClaw has stale or missing Home Assistant data after an upgrade, run:
+
+```sh
+mcporter call home-assistant.GetLiveContext
+```
+
+This refreshes the entity/service metadata that OpenClaw uses.
+
+#### Model requirements
+
+MCP setup requires an AI model that understands tool/skill invocation. Budget models (e.g. Gemini 2.5 Flash) may struggle with the initial MCP discovery. For the **first-time setup**, use a capable model (e.g. Gemini 3.1 Pro, Claude Sonnet 4, GPT-4.1). After MCP is configured, you can switch back to a cheaper model for daily use.
+
+#### Troubleshooting MCP
+
+| Symptom | Fix |
+|---|---|
+| `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) |
+
 To enable it, add to `/config/.openclaw/openclaw.json`:

 ```json
@@ -576,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 |
@@ -596,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.

 ---

@@ -634,6 +711,7 @@ The add-on image includes these tools, available in the terminal:
 | Chromium | `chromium` | Headless browser for automation |
 | SSH | `ssh` | Remote access |
 | oc-cleanup | `oc-cleanup` | Interactive disk space monitor & cache cleanup helper |
+| oc-gateway | `oc-gateway status` / `oc-gateway restart` | Add-on-native gateway status/restart helper (`run.sh` supervised, no systemd) |

 ### oc-cleanup

@@ -669,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
@@ -682,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**

@@ -691,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
 ```
@@ -701,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.

 ---

@@ -735,11 +827,23 @@ Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show sta
 **Symptom**: Browser shows connection refused when opening the Gateway Web UI.

 **Checks**:
-1. Is the gateway running? In the terminal: `openclaw gateway status`
+1. Is the gateway running? In the terminal: `oc-gateway status`
 2. Is the bind mode correct? `openclaw config get gateway.bind` — must be `lan` for direct LAN access, or `loopback` if using `lan_https` mode
 3. Is the port correct? `openclaw config get gateway.port`
 4. Is the firewall blocking the port? Check your HA host firewall rules

+### Gateway restart loop: `web_search provider is not available: brave`
+
+**Symptom**: Logs repeat `Invalid config at /config/.openclaw/openclaw.json` and `tools.web.search.provider: web_search provider is not available: brave`.
+
+**Cause**: The persisted OpenClaw config selects the Brave web search provider, but that provider plugin is not currently installed or enabled in the add-on runtime.
+
+**Fix**: In v0.5.72+ the add-on clears that unavailable provider automatically during startup. On older versions, run this in the add-on terminal, then restart:
+
+```sh
+jq 'del(.tools.web.search.provider)' /config/.openclaw/openclaw.json > /tmp/openclaw.json && mv /tmp/openclaw.json /config/.openclaw/openclaw.json
+```
+
 ### "disconnected (1008): control ui requires device identity" / "requires HTTPS or localhost"

 **Symptom**: Gateway UI shows error 1008 or "requires secure context / device identity".
@@ -757,17 +861,15 @@ Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show sta

 **Cause**: OpenClaw v2026.2.21+ checks the browser's `Origin` header against an allow-list. When using the built-in HTTPS proxy (`lan_https`), the origin (`https://<ip>:<port>`) must be registered in `gateway.controlUi.allowedOrigins`.

-**Fix**: In **v0.5.78+** this is configured automatically on startup. If you still see the error:
-1. Restart the add-on (the startup script detects the LAN IP and sets the origins).
-2. If the IP has changed since you last started, restart again — the cert and origins are regenerated.
-3. **Manual override** (from the add-on terminal):
+**Fix**: In **v0.5.50+** defaults are configured automatically on startup. In **v0.5.54+**, the add-on now merges defaults with existing values and user extras.
+1. Restart the add-on (the startup script detects LAN IP and updates origins).
+2. If needed, set `gateway_additional_allowed_origins` in add-on configuration (comma-separated), then restart.
+3. If the IP has changed since you last started, restart again — the cert and defaults are refreshed.
+4. **Manual override** (advanced, from the add-on terminal):
   ```sh
   openclaw config set gateway.controlUi.allowedOrigins '["https://192.168.1.10:18789"]'
   ```
-   Replace the IP and port with your actual values, then restart the gateway:
-   ```sh
-   openclaw gateway restart
-   ```
+   Then restart the add-on to re-merge defaults + extras.

 ### "disconnected (1008): pairing required"

@@ -775,7 +877,7 @@ Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show sta

 **Cause**: OpenClaw v2026.2.21+ requires new devices to complete a pairing handshake before the Control UI WebSocket is accepted. Loopback connections are auto-approved (v2026.2.22 further improves this with loopback scope-upgrade auto-approval), but LAN connections (including those through the HTTPS proxy) require explicit approval.

-**Fix**: In **v0.5.80+** the add-on automatically sets `gateway.controlUi.dangerouslyDisableDeviceAuth: true` on startup when using `lan_https` mode. This bypasses per-device pairing — token authentication is still enforced.
+**Fix**: In **v0.5.50+** the add-on configures `gateway.controlUi.dangerouslyDisableDeviceAuth` in `lan_https` mode. By default it is enabled (`controlui_disable_device_auth: true`) to bypass per-device pairing while still enforcing token auth. If you prefer stricter behavior, set `controlui_disable_device_auth: false` and approve new devices manually.

 > **v2026.2.22 note:** The gateway now logs a security warning on startup when this flag is active. The warning is expected and harmless — run `openclaw security audit` for details.

@@ -791,7 +893,7 @@ Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show sta
     "allowedOrigins": ["https://YOUR_IP:18789"]
   }
   ```
-   Then restart the gateway: `openclaw gateway restart`
+   Then restart only the gateway process: `oc-gateway restart`
 3. Alternatively, approve devices individually without disabling auth:
   ```sh
   openclaw devices list       # show pending pairing requests
@@ -803,11 +905,23 @@ Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show sta
 **Fix**: Get the correct token and use it:

 ```sh
-openclaw config get gateway.auth.token
+jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json
 ```

+> **Note**: Since OpenClaw v2026.2.22+ `openclaw config get` redacts sensitive values (returns `openclaw_redacted`). Use `jq` to read the token directly from the config file.
+
 Paste this token when the UI prompts for authentication, or append it to the URL: `http://<ip>:18789/?token=<your-token>`

+### CLI shows unauthorized with `trusted_proxy_user_missing`
+
+**Symptom**: In add-on terminal, commands that open direct gateway WebSocket (for example some `openclaw status`/gateway probes) fail with unauthorized and logs mention `trusted_proxy_user_missing`.
+
+**Cause**: `gateway_auth_mode: trusted-proxy` expects identity headers from your reverse proxy. Direct local CLI connections are not proxied, so they may be rejected.
+
+**What to do**:
+- Keep `trusted-proxy` for browser traffic via your reverse proxy.
+- For local terminal workflows that require direct gateway auth, temporarily switch to `gateway_auth_mode: token` (or run via proxy path that injects trusted headers), then switch back if needed.
+
 ### Terminal not visible

 1. Check that `enable_terminal` is **true** in the add-on configuration
@@ -820,7 +934,7 @@ Paste this token when the UI prompts for authentication, or append it to the URL

 **Cause**: Node 22 uses `autoSelectFamily` which tries IPv6 first. Most HAOS VMs have IPv6 DNS resolution but no IPv6 egress, so connections time out before falling back to IPv4.

-**Fix**: Ensure `force_ipv4_dns` is **true** (default since v0.5.81). If you upgraded from an older version, the option may still be set to `false` — change it to `true` in **Settings → Add-ons → OpenClaw Assistant → Configuration** and restart.
+**Fix**: Ensure `force_ipv4_dns` is **true** (default since v0.5.51). If you upgraded from an older version, the option may still be set to `false` — change it to `true` in **Settings → Add-ons → OpenClaw Assistant → Configuration** and restart.

 ### Telegram network errors (`TypeError: fetch failed` / `getUpdates` fails)

@@ -853,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

@@ -933,7 +1047,7 @@ Yes. The add-on supports aarch64 (Raspberry Pi 4/5) and armv7 (Raspberry Pi 3).
 OpenClaw supports multiple agent profiles. Configure them via `openclaw configure` or by editing `/config/.openclaw/openclaw.json`. The gateway serves all configured agents.

 **Can I use a remote gateway?**
-Yes. Set `gateway_mode` to `remote` and configure the remote gateway URL via `openclaw config set gateway.url <url>`. See [Remote Gateway Mode](#6b-remote-gateway-mode).
+Yes. Set `gateway_mode` to `remote` and set `gateway_remote_url` in add-on configuration. The add-on syncs it into OpenClaw config automatically. See [Remote Gateway Mode](#6b-remote-gateway-mode).

 **How do I change the AI model or provider?**
 Run `openclaw configure` in the terminal to reconfigure your AI providers, or edit `/config/.openclaw/openclaw.json` directly. You can use OpenAI, Google (Gemini), Anthropic (Claude), local models, and more.
@@ -1,7 +1,9 @@
 # OpenClaw Assistant – Home Assistant App/Add-on

 ## [Join our Discord Server!](https://discord.gg/xeHeKu9jYp)
-![OpenClaw Assistant](https://github.com/techartdev/OpenClawHomeAssistant/blob/main/oca_addon.png?raw=true)
+<img width="1038" height="597" alt="image" src="https://github.com/user-attachments/assets/6dae3918-7bad-4e89-9695-c7f549e8abda" />
+<img width="1536" height="542" alt="ChatGPT Image Feb 25, 2026, 11_37_02 PM" src="https://github.com/user-attachments/assets/ea662d87-5414-4c01-ac48-cb8f731a4988" />
+

 ### OpenClaw Home Assistant integration is available now!  https://github.com/techartdev/OpenClawHomeAssistantIntegration

@@ -2,6 +2,193 @@

 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
+- Bundle `node-llama-cpp` inside the add-on image so the default local memory/embeddings provider works in HAOS without manual package installs.
+- Add `cmake` to the image so `node-llama-cpp` can fall back to a source build when a prebuilt binary is unavailable for the target architecture.
+
+## [0.5.73] - 2026-05-26
+
+### Added
+- New add-on-native `oc-gateway` helper for container-supervised runtime management:
+  - `oc-gateway status` shows gateway state in the HA add-on model (`run.sh` supervisor, not systemd)
+  - `oc-gateway restart` requests gateway self-restart via `SIGUSR1` without full add-on restart
+
+### Changed
+- Troubleshooting and setup docs now use `oc-gateway status` / `oc-gateway restart` in add-on contexts to avoid confusing systemd-related CLI output.
+
+## [0.5.72] - 2026-05-04
+
+### Fixed
+- Repair startup when a persisted OpenClaw config still selects the unavailable `tools.web.search.provider=brave` provider. The add-on now clears that provider before launching the gateway so OpenClaw can start; users can reinstall/enable the Brave provider later if they want web search through Brave.
+
+## [0.5.71] - 2026-05-03
+
+### Changed
+- Bump OpenClaw through the 2026.4.29 and 2026.5.2 upstream releases.
+
+## [0.5.70] - 2026-04-30
+
+### Changed
+- Bump OpenClaw to 2026.4.27.
+
+## [0.5.69] - 2026-04-27
+
+### Changed
+- Bump OpenClaw through the 2026.4.23 and 2026.4.24 upstream releases.
+
+## [0.5.68] - 2026-04-25
+
+### Changed
+- Bump OpenClaw through the 2026.4.14, 2026.4.15, 2026.4.21, and 2026.4.22 upstream releases.
+
+## [0.5.67] - 2026-04-25
+
+### Changed
+- Bump OpenClaw through the 2026.4.5, 2026.4.8, 2026.4.9, 2026.4.10, 2026.4.11, and 2026.4.12 upstream releases.
+
+## [0.5.66] - 2026-04-04
+
+### Fixed
+- **"Open Gateway Web UI" button missing token on first boot / post-onboard** (issue #102): the gateway token was read once at startup, before `openclaw onboard` had a chance to write `openclaw.json`. The landing page now re-renders automatically in the background (up to ~2 min after startup) once the token appears in `openclaw.json`, and nginx is reloaded with SIGHUP — no add-on restart required. Existing installs with a token already present are unaffected.
+
+## [0.5.65] - 2026-04-04
+
+### Changed
+- Bump OpenClaw to 2026.4.2.
+
+## [0.5.63] - 2026-03-14
+
+### Changed
+- Bump OpenClaw to 2026.3.13.
+
+## [0.5.62] - 2026-03-10
+
+### Fixed
+- **Gateway restart loop** (issue #95): `openclaw gateway run` is a thin wrapper that spawns `openclaw-gateway` as a long-running daemon then exits immediately. On self-restart (SIGUSR1 / `openclaw gateway restart`), the old daemon forks a new one and exits — the new PID is not a child of run.sh. The supervisor now uses a 3-tier daemon detection function (`find_gateway_daemon_pid`): (1) port ownership via `ss -tlnp`, (2) process title via `pgrep -f "openclaw-gateway"`, (3) `/proc/*/cmdline` scan for "openclaw" (catches the daemon immediately after fork, even before process.title or port bind — critical on Pi/eMMC where initialization takes 20-30 s). Detection retries up to 10 times with a final port-occupancy guard before any supervisor-initiated restart. Non-child PIDs are monitored with `kill -0` polling instead of `wait`. The loopback relay (tailnet mode) is stopped/restarted around gateway restarts to prevent port conflicts.
+
+## [0.5.61] - 2026-03-10
+
+### Fixed
+- **Gateway restart loop** (issue #95): stop the tailnet loopback relay before supervisor-initiated gateway restarts and start it again after the new daemon is launched, preventing the relay from holding the local port and trapping the add-on in an `already listening` restart loop.
+
+## [0.5.60] - 2026-03-10
+
+### Fixed
+- **Session lock cleanup ignored non-default agents**: `cleanup_session_locks` was hardcoded to `agents/main/sessions`, skipping stale locks for any agent with a custom `forcedAgentId`. Stale locks could block the gateway from opening sessions for those agents, causing silent fallback to `main`. Cleanup now scans all `agents/*/sessions/` directories.
+
+## [0.5.59] - 2026-03-10
+
+- **Remote mode URL not propagated** (issue #93): `start_openclaw_runtime` was reading `gateway.remote.url` back via `openclaw config get`, which can time out (2 s limit at startup) or return an empty/redacted result. The function now uses `$GATEWAY_REMOTE_URL` directly from the already-parsed add-on options, which is the same value the config helper writes to `openclaw.json`.
+- **Terminal CLI unreachable in tailnet mode** (issue #90): when `gateway_bind_mode=tailnet` (or `access_mode=tailnet_https`), the gateway binds only to the Tailscale IP. The local CLI always connects via `ws://127.0.0.1:PORT`, causing "Gateway not running" inside the add-on terminal. A lightweight loopback relay (Node.js) is now started automatically to forward `127.0.0.1:PORT → TAILSCALE_IP:PORT`, making all terminal CLI commands work normally. Token auth is still enforced end-to-end by the gateway.
+- **Session lock cleanup ignored non-default agents**: `cleanup_session_locks` was hardcoded to `agents/main/sessions`, skipping stale locks for any agent with a custom `forcedAgentId`. Stale locks could block the gateway from opening sessions for those agents, causing silent fallback to `main`. Cleanup now scans all `agents/*/sessions/` directories.
+
+### Added
+- **MCP auto-configuration for Home Assistant**: new option `auto_configure_mcp` (default: `false`). When enabled and `homeassistant_token` is set, the add-on automatically registers Home Assistant as an MCP server (`mcporter config add HA ...`) on startup. Auto-detects the HA API URL (supervisor proxy or localhost:8123). Re-configures only when the token changes.
+- Landing page: new collapsible **MCP setup** section with automatic and manual setup instructions, post-upgrade refresh command, and model tips.
+- DOCS: new **MCP Integration** guide covering automatic/manual setup, verification, model requirements, and troubleshooting.
+
+### Changed
+- Bump OpenClaw to 2026.3.9.
+
+## [0.5.58] - 2026-03-08
+
+### Changed
+- Bump OpenClaw to 2026.3.7.
+
+## [0.5.57] - 2026-03-07
+
+### Added
+- New add-on option `controlui_disable_device_auth` (default: `true`) to control whether `gateway.controlUi.dangerouslyDisableDeviceAuth` is enabled in `lan_https` mode.
+
+### Changed
+- `set-control-ui-origins` helper now accepts an explicit device-auth toggle and applies `dangerouslyDisableDeviceAuth` accordingly instead of forcing it on.
+- `run.sh` now forwards the add-on option to the config helper.
+- Control UI guidance text and docs were updated to explain when device-pairing bypass should be ON vs OFF.
+
+### Fixed
+- Docker build stability: replaced NodeSource `setup_22.x | bash` installer with explicit keyring + apt source configuration for Node.js 22, avoiding intermittent `apt-get install nodejs` exit code 100 failures.
+
+### Translations
+- Added `controlui_disable_device_auth` labels/descriptions to: `en`, `bg`, `de`, `es`, `pl`, `pt-BR`.
+
+## [0.5.55] - 2026-03-04
+
+### Changed
+- Bump OpenClaw to 2026.3.2.
+
+## [0.5.54] - 2026-02-25
+
+### Changed
+- Added startup guidance when `gateway_auth_mode=trusted-proxy` is enabled to clarify why direct local CLI gateway calls can show `trusted_proxy_user_missing`/unauthorized.
+- Bump OpenClaw to 2026.2.24.
+
+### Added
+- New add-on option `gateway_additional_allowed_origins` for extra Control UI origins in `lan_https` mode.
+- **Custom SANs in TLS certificate** (`lan_https` mode): hostnames and IPs from `gateway_additional_allowed_origins` and `gateway_public_url` are now included in the server certificate's Subject Alternative Name. The certificate auto-regenerates when SANs change.
+
+### Fixed
+- **Gateway token on landing page**: read token directly from `openclaw.json` instead of via `openclaw config get` which redacts secrets since OpenClaw v2026.2.22+ (fixes "Open Gateway Web UI" button sending `openclaw_redacted` as the token).
+- **Token retrieval instructions**: all "get your token" references in the landing page and DOCS now use `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json` with a note explaining why the old `openclaw config get` command no longer works.
+- `lan_https` startup no longer overwrites `gateway.controlUi.allowedOrigins` with defaults only.
+- Control UI origins are now merged as: built-in defaults + existing config values + `gateway_additional_allowed_origins` (deduplicated).
+- In `lan_reverse_proxy` and other non-`lan_https` setups, Control UI origins now also include the origin derived from `gateway_public_url`.
+- `gateway.controlUi.allowedOrigins` configuration is now consistently applied via merge logic (defaults + existing values + user extras), reducing manual `openclaw.json` edits after upgrades.
+- Add-on no longer exits/restarts when OpenClaw runtime process is restarted during onboarding or config changes.
+- `run.sh` now supervises the OpenClaw runtime (`openclaw gateway run` / `openclaw node run`) and auto-restarts it while keeping nginx + terminal alive.
+
 ## [0.5.53] - 2026-02-24
 - Bump OpenClaw to 2026.2.23.

@@ -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 \
@@ -18,6 +18,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    xz-utils \
    file \
    python3 \
+    cmake \
    nginx \
    gnupg \
    build-essential \
@@ -30,22 +31,35 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    bat \
    less \
    openssl \
- && apt-get clean \
- && rm -rf /var/lib/apt/lists/*
+    && 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+)
-RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
- && apt-get install -y nodejs \
- && apt-get clean \
- && rm -rf /var/lib/apt/lists/*
+# 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_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 '^v24\.' \
+    && rm -f /etc/apt/sources.list.d/nodesource.list /etc/apt/keyrings/nodesource.gpg \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*

 # Install ttyd (web terminal) - not in Debian repos, download binary
 # Docker TARGETARCH: amd64, arm64, arm/v7 → ttyd filenames: x86_64, aarch64, armhf
 ARG TARGETARCH
 RUN ARCH=$(echo ${TARGETARCH:-$(dpkg --print-architecture)} | sed 's|arm64|aarch64|;s|arm/v7|armhf|;s|armv7|armhf|;s|amd64|x86_64|') \
- && echo "Downloading ttyd for arch: ${ARCH}" \
- && curl -fsSL "https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd.${ARCH}" -o /usr/local/bin/ttyd \
- && chmod +x /usr/local/bin/ttyd
+    && echo "Downloading ttyd for arch: ${ARCH}" \
+    && curl -fsSL "https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd.${ARCH}" -o /usr/local/bin/ttyd \
+    && chmod +x /usr/local/bin/ttyd

 RUN node -v && npm -v

@@ -57,8 +71,8 @@ RUN npm install -g pnpm && pnpm -v
 RUN apt-get update && apt-get install -y --no-install-recommends \
    chromium \
    chromium-driver \
- && apt-get clean \
- && rm -rf /var/lib/apt/lists/*
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*

 # Install Homebrew (Linuxbrew) for OpenClaw skill dependencies
 # Homebrew is optional - some skills need CLI tools like gemini, aider, etc.
@@ -69,16 +83,16 @@ ENV HOMEBREW_NO_AUTO_UPDATE=1 \
    HOMEBREW_NO_ANALYTICS=1

 RUN useradd -m -s /bin/bash linuxbrew \
- && mkdir -p /home/linuxbrew/.linuxbrew \
- && chown -R linuxbrew:linuxbrew /home/linuxbrew
+    && mkdir -p /home/linuxbrew/.linuxbrew \
+    && chown -R linuxbrew:linuxbrew /home/linuxbrew

 USER linuxbrew
 RUN /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || \
    (echo "WARNING: Homebrew installation failed (likely unsupported CPU - requires SSSE3). Some skills may not work." && exit 0)
 RUN if [ -d /home/linuxbrew/.linuxbrew/Homebrew ]; then \
-        cd /home/linuxbrew/.linuxbrew/Homebrew && \
-        git config --global --add safe.directory /home/linuxbrew/.linuxbrew/Homebrew && \
-        /home/linuxbrew/.linuxbrew/bin/brew update --force || true; \
+    cd /home/linuxbrew/.linuxbrew/Homebrew && \
+    git config --global --add safe.directory /home/linuxbrew/.linuxbrew/Homebrew && \
+    /home/linuxbrew/.linuxbrew/bin/brew update --force || true; \
    fi
 USER root

@@ -94,16 +108,20 @@ RUN chmod +x /usr/local/bin/brew
 # Skip if brew installation failed
 USER linuxbrew
 RUN if [ -x /home/linuxbrew/.linuxbrew/bin/brew ]; then \
-        /home/linuxbrew/.linuxbrew/bin/brew --version && \
-        /home/linuxbrew/.linuxbrew/bin/brew install gcc || true; \
+    /home/linuxbrew/.linuxbrew/bin/brew --version && \
+    /home/linuxbrew/.linuxbrew/bin/brew install gcc || true; \
    else \
-        echo "Skipping gcc installation - Homebrew not available"; \
+    echo "Skipping gcc installation - Homebrew not available"; \
    fi
 USER root

-# Install OpenClaw globally
+# 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.2.23
+    && 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'
@@ -127,10 +145,11 @@ COPY run.sh /run.sh
 COPY oc_config_helper.py /oc_config_helper.py
 COPY render_nginx.py /render_nginx.py
 COPY oc-cleanup.sh /usr/local/bin/oc-cleanup
+COPY oc-gateway /usr/local/bin/oc-gateway
 COPY openclaw-proxy-shim.cjs /usr/local/lib/openclaw-proxy-shim.cjs
 COPY nginx.conf.tpl /etc/nginx/nginx.conf.tpl
 COPY landing.html.tpl /etc/nginx/landing.html.tpl
-RUN chmod +x /run.sh /oc_config_helper.py /render_nginx.py /usr/local/bin/oc-cleanup \
- && mkdir -p /run/nginx
+RUN chmod +x /run.sh /oc_config_helper.py /render_nginx.py /usr/local/bin/oc-cleanup /usr/local/bin/oc-gateway \
+    && mkdir -p /run/nginx

 CMD [ "/run.sh" ]
@@ -1,5 +1,5 @@
 name: OpenClaw Assistant
-version: "0.5.53"
+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,12 +56,21 @@ 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
  # Default is local.
  gateway_mode: local

+  # Remote gateway URL (used when gateway_mode=remote)
+  # Example: "ws://192.168.1.20:18789" or "wss://gateway.example.com:443"
+  gateway_remote_url: ""
+
  # Gateway network bind mode:
  # - loopback: bind to 127.0.0.1 only (local access only, most secure)
  # - lan: bind to all interfaces (accessible from local network)
@@ -89,6 +98,18 @@ options:
  # Example: "127.0.0.1,192.168.88.0/24"
  gateway_trusted_proxies: ""

+  # Additional allowed origins for gateway.controlUi.allowedOrigins.
+  # Merged with built-in defaults and existing configured origins.
+  # In lan_https mode, hostnames/IPs from these origins are also added to the
+  # TLS certificate SAN so the cert is valid for custom domains.
+  # Example: "https://ha.example.com:8443,capacitor://localhost"
+  gateway_additional_allowed_origins: ""
+
+  # In lan_https mode, disable per-device Control UI auth ceremony.
+  # Default true (recommended) to avoid interactive pairing error 1008 on LAN.
+  # Set false only if you explicitly want strict per-device approvals.
+  controlui_disable_device_auth: true
+
  # Enable OpenAI-compatible Chat Completions API endpoint
  # When enabled, OpenClaw can be used as a conversation agent in HA Assist pipeline
  # via Extended OpenAI Conversation (HACS) or any OpenAI-compatible client
@@ -117,6 +138,11 @@ options:
  # Limits: max 50 variables, max key length 255 chars, max value length 10000 chars
  gateway_env_vars: []

+  # Auto-configure MCP (Model Context Protocol) for Home Assistant.
+  # When enabled and homeassistant_token is set, automatically registers HA as an
+  # MCP server in OpenClaw so the AI can control Home Assistant entities/services.
+  auto_configure_mcp: false
+

 schema:
  timezone: str
@@ -132,16 +158,21 @@ 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)?
  gateway_port: int(1,65535)?
  access_mode: list(custom|local_only|lan_https|lan_reverse_proxy|tailnet_https)?
  gateway_auth_mode: list(token|trusted-proxy)?
  gateway_trusted_proxies: str?
+  gateway_additional_allowed_origins: str?
+  controlui_disable_device_auth: bool?
  enable_openai_api: bool?
  force_ipv4_dns: bool?
  gateway_env_vars:
    - name: "match(^[A-Z_][A-Z0-9_]*$)"
      value: str
  nginx_log_level: list(full|minimal)?
-
+  auto_configure_mcp: bool?
@@ -109,12 +109,38 @@
        Set <code>gateway_public_url</code> in add-on options if the button URL is wrong.
      </div>
      <div class="muted" style="margin-top:6px">
-        If the Gateway UI says <b>Unauthorized</b>, get your token in the terminal:
-        <code>openclaw config get gateway.auth.token</code>
+        If the Gateway UI says <b>Unauthorized</b>, get your token from the terminal:<br>
+        <code>jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json</code><br>
+        <small style="color:#6b7280">(Since OpenClaw v2026.2.22+, <code>openclaw config get</code> redacts secrets — read the file directly instead.)</small>
      </div>
    </details>

    <!-- ==================== PROXY RECIPES ==================== -->
+    <details>
+      <summary>MCP setup (Home Assistant control)</summary>
+      <div style="margin-top:8px;font-size:13px;color:#9ca3af;line-height:1.7">
+        <p><b>MCP (Model Context Protocol)</b> lets OpenClaw control Home Assistant entities, services, and automations directly.</p>
+
+        <b>Automatic (recommended)</b>
+        <ol style="margin:4px 0;padding-left:22px;line-height:1.8">
+          <li>Create a <b>Long-Lived Access Token</b> in HA: click your profile avatar → scroll to <b>Long-Lived Access Tokens</b> → <b>Create Token</b></li>
+          <li>Paste it into add-on option <code>homeassistant_token</code> in <b>Settings → Add-ons → Configuration</b></li>
+          <li>Set <code>auto_configure_mcp</code> to <b>ON</b> in add-on Configuration</li>
+          <li>Restart the add-on — MCP is configured automatically</li>
+        </ol>
+
+        <b>Manual (terminal)</b>
+        <pre style="background:#0b1220;padding:8px;border-radius:6px;overflow-x:auto;font-size:12px">mcporter config add HA "http://localhost:8123/api/mcp" \
+  --header "Authorization=Bearer YOUR_LONG_LIVED_TOKEN" \
+  --scope home</pre>
+
+        <b>After upgrades</b> — if OpenClaw has stale HA data:
+        <pre style="background:#0b1220;padding:8px;border-radius:6px;overflow-x:auto;font-size:12px">mcporter call home-assistant.GetLiveContext</pre>
+
+        <p><b>Tip:</b> The first MCP session needs a capable model (Gemini 3.1 Pro, Claude Sonnet 4, GPT-4.1). After setup, cheaper models work fine.</p>
+      </div>
+    </details>
+
    <details>
      <summary>Reverse-proxy recipes (NPM / Caddy / Traefik / Tailscale)</summary>
      <div style="margin-top:8px;font-size:13px;color:#9ca3af;line-height:1.7">
@@ -210,7 +236,7 @@ SSL tab:  Request a new SSL certificate (Let's Encrypt or custom)</pre>
      'pairing required': {
        friendly: 'The Gateway requires device pairing before the Control UI can connect.',
        fix: ACCESS_MODE === 'lan_https'
-          ? 'Restart the add-on — it auto-sets <code>controlUi.dangerouslyDisableDeviceAuth: true</code> to skip pairing (token auth is still enforced). <br><small>Note: v2026.2.22+ shows an <em>expected</em> security warning for this flag in the gateway logs — it is safe to ignore.</small>'
+          ? 'Restart the add-on — by default it sets <code>controlUi.dangerouslyDisableDeviceAuth: true</code> to skip pairing (token auth is still enforced). You can change this via <code>controlui_disable_device_auth</code> in add-on options. <br><small>Note: v2026.2.22+ shows an <em>expected</em> security warning for this flag in the gateway logs — it is safe to ignore.</small>'
          : 'Set <code>access_mode</code> to <b>lan_https</b> and restart. Or from the terminal: edit <code>/config/.openclaw/openclaw.json</code> and set <code>gateway.controlUi.dangerouslyDisableDeviceAuth: true</code>, then restart the gateway.'
      },
      'origin not allowed': {
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cmd="${1:-status}"
+shift || true
+
+find_gateway_pid() {
+  local port="${1:-18789}"
+  local pid=""
+
+  # 1) Port owner (most accurate)
+  if command -v ss >/dev/null 2>&1; then
+    pid=$(ss -tlnp 2>/dev/null \
+      | grep ":${port} " \
+      | sed -n 's/.*pid=\([0-9]*\).*/\1/p' \
+      | head -1 || true)
+    if [ -n "$pid" ] && [ -r "/proc/$pid/cmdline" ]; then
+      local cmdline
+      cmdline=$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null || true)
+      if echo "$cmdline" | grep -qi "openclaw\|node"; then
+        echo "$pid"
+        return 0
+      fi
+    fi
+  fi
+
+  # 2) Process title
+  pid=$(pgrep -f "openclaw-gateway" 2>/dev/null | head -1 || true)
+  if [ -n "$pid" ]; then
+    echo "$pid"
+    return 0
+  fi
+
+  # 3) /proc cmdline fallback
+  for f in /proc/[0-9]*/cmdline; do
+    [ -r "$f" ] || continue
+    if tr '\0' ' ' < "$f" 2>/dev/null | grep -qi "openclaw"; then
+      echo "${f#/proc/}" | cut -d/ -f1
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+get_gateway_port() {
+  python3 - <<'PY'
+import json, os
+p = os.environ.get('OPENCLAW_CONFIG_PATH', '/config/.openclaw/openclaw.json')
+try:
+    with open(p, 'r', encoding='utf-8') as f:
+        cfg = json.load(f)
+    print(int(cfg.get('gateway', {}).get('port', 18789)))
+except Exception:
+    print(18789)
+PY
+}
+
+status_cmd() {
+  local port pid
+  port="$(get_gateway_port)"
+  pid="$(find_gateway_pid "$port" || true)"
+
+  echo "OpenClaw add-on gateway status"
+  echo "Supervisor: run.sh (not systemd)"
+  echo "Configured port: ${port}"
+
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+    echo "Gateway process: running (PID ${pid})"
+    if command -v ss >/dev/null 2>&1 && ss -tlnp 2>/dev/null | grep -q ":${port} "; then
+      echo "Listener: active on :${port}"
+    else
+      echo "Listener: process found, port bind not detected yet"
+    fi
+    exit 0
+  fi
+
+  echo "Gateway process: not detected"
+  echo "Tip: Check add-on logs in Home Assistant for startup errors."
+  exit 1
+}
+
+restart_cmd() {
+  local port pid
+  port="$(get_gateway_port)"
+  pid="$(find_gateway_pid "$port" || true)"
+
+  if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
+    echo "No running gateway process found to restart."
+    echo "Tip: If startup failed, inspect add-on logs."
+    exit 1
+  fi
+
+  echo "Requesting gateway self-restart via SIGUSR1 (PID ${pid})..."
+  kill -USR1 "$pid"
+
+  for _ in $(seq 1 20); do
+    sleep 1
+    local new_pid
+    new_pid="$(find_gateway_pid "$port" || true)"
+    if [ -n "$new_pid" ] && kill -0 "$new_pid" 2>/dev/null; then
+      echo "Gateway active (PID ${new_pid})"
+      exit 0
+    fi
+  done
+
+  echo "Restart signal sent; gateway may still be reinitializing."
+  echo "Run 'oc-gateway status' again in a few seconds."
+  exit 0
+}
+
+case "$cmd" in
+  status)
+    status_cmd
+    ;;
+  restart|reload)
+    restart_cmd
+    ;;
+  help|-h|--help)
+    cat <<'EOF'
+Usage: oc-gateway <status|restart|reload>
+
+status   Show add-on-native gateway status (run.sh-supervised)
+restart  Request gateway self-restart via SIGUSR1
+reload   Alias of restart
+EOF
+    ;;
+  *)
+    echo "Unknown command: $cmd" >&2
+    echo "Run: oc-gateway help" >&2
+    exit 2
+    ;;
+esac
@@ -57,12 +57,13 @@ def set_gateway_setting(key, value):
    return write_config(cfg)


-def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_api: bool, auth_mode: str, trusted_proxies_csv: str):
+def apply_gateway_settings(mode: str, remote_url: str, bind_mode: str, port: int, enable_openai_api: bool, auth_mode: str, trusted_proxies_csv: str):
    """
    Apply gateway settings to OpenClaw config.
    
    Args:
        mode: "local" or "remote"
+        remote_url: remote Gateway websocket URL (used when mode=remote)
        bind_mode: "loopback", "lan", or "tailnet"
        port: Port number to listen on (must be 1-65535)
        enable_openai_api: Enable OpenAI-compatible Chat Completions endpoint
@@ -97,7 +98,12 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
        cfg["gateway"] = {}
    
    gateway = cfg["gateway"]
-    
+
+    # gateway.remote settings
+    if "remote" not in gateway or not isinstance(gateway.get("remote"), dict):
+        gateway["remote"] = {}
+    remote_cfg = gateway["remote"]
+
    # auth should be nested inside gateway
    if "auth" not in gateway:
        gateway["auth"] = {}
@@ -120,6 +126,7 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
    trusted_proxy_cfg_default = {"userHeader": "x-forwarded-user"}

    current_mode = gateway.get("mode", "")
+    current_remote_url = remote_cfg.get("url", "")
    current_bind = gateway.get("bind", "")
    current_port = gateway.get("port", 18789)
    current_openai_api = chat_completions.get("enabled", False)
@@ -132,6 +139,10 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
    if current_mode != mode:
        gateway["mode"] = mode
        changes.append(f"mode: {current_mode} -> {mode}")
+
+    if current_remote_url != remote_url:
+        remote_cfg["url"] = remote_url
+        changes.append(f"remote.url: {current_remote_url} -> {remote_url}")
    
    if current_bind != bind_mode:
        gateway["bind"] = bind_mode
@@ -166,28 +177,27 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
            print("ERROR: Failed to write config")
            return False
    else:
-        print(f"INFO: Gateway settings already correct (mode={mode}, bind={bind_mode}, port={port}, chatCompletions={enable_openai_api}, authMode={auth_mode}, trustedProxies={trusted_proxies})")
+        print(f"INFO: Gateway settings already correct (mode={mode}, remoteUrl={remote_url}, bind={bind_mode}, port={port}, chatCompletions={enable_openai_api}, authMode={auth_mode}, trustedProxies={trusted_proxies})")
        return True


-def set_control_ui_origins(origins_csv: str):
+def set_control_ui_origins(origins_csv: str, additional_origins_csv: str = "", disable_device_auth: bool = True): 
    """
    Configure gateway.controlUi for the built-in HTTPS proxy.

    Sets:
      - allowedOrigins: the HTTPS proxy origins so the browser WebSocket
        is accepted (required since v2026.2.21).
-      - dangerouslyDisableDeviceAuth: true — skips the interactive device
-        pairing ceremony.  In a self-hosted HA add-on the user already
-        controls the gateway token, so the pairing step adds friction
-        without meaningful security benefit.
+      - dangerouslyDisableDeviceAuth: controlled by add-on option
+        `controlui_disable_device_auth` (default true). When true, skips
+        interactive device pairing; token auth remains enforced.

    Also removes any stale/invalid keys (e.g. pairingMode) that may have
    been written by earlier add-on versions.

    Args:
-        origins_csv: Comma-separated list of allowed origins.
-                     Pass an empty string to clear / leave unset.
+        origins_csv: Comma-separated list of default origins provided by the add-on.
+        additional_origins_csv: Comma-separated list of user-provided extra origins.
    """
    cfg = read_config()
    if cfg is None:
@@ -201,21 +211,32 @@ def set_control_ui_origins(origins_csv: str):
        gateway["controlUi"] = {}

    control_ui = gateway["controlUi"]
-    origins = [o.strip() for o in origins_csv.split(",") if o.strip()]
+    default_origins = [o.strip() for o in origins_csv.split(",") if o.strip()]
+    additional_origins = [o.strip() for o in (additional_origins_csv or "").split(",") if o.strip()]
    changes = []

    # --- allowedOrigins ---
    current_origins = control_ui.get("allowedOrigins", [])
-    if current_origins != origins:
-        control_ui["allowedOrigins"] = origins
-        changes.append(f"allowedOrigins: {current_origins} -> {origins}")
+    if not isinstance(current_origins, list):
+        current_origins = []
+
+    merged_origins = []
+    for origin in [*default_origins, *current_origins, *additional_origins]:
+        if isinstance(origin, str) and origin and origin not in merged_origins:
+            merged_origins.append(origin)
+
+    if current_origins != merged_origins:
+        control_ui["allowedOrigins"] = merged_origins
+        changes.append(f"allowedOrigins: {current_origins} -> {merged_origins}")

    # --- dangerouslyDisableDeviceAuth ---
-    # Skips the interactive pairing handshake (error 1008: pairing required).
-    # Token auth is still enforced; this only disables the per-device approval.
-    if control_ui.get("dangerouslyDisableDeviceAuth") is not True:
-        control_ui["dangerouslyDisableDeviceAuth"] = True
-        changes.append("dangerouslyDisableDeviceAuth: True")
+    # Optional bypass of interactive per-device pairing (error 1008: pairing required).
+    # Token auth is still enforced; this only controls the approval ceremony.
+    desired_device_auth_flag = True if disable_device_auth else False
+    if control_ui.get("dangerouslyDisableDeviceAuth") is not desired_device_auth_flag:
+        prev = control_ui.get("dangerouslyDisableDeviceAuth")
+        control_ui["dangerouslyDisableDeviceAuth"] = desired_device_auth_flag
+        changes.append(f"dangerouslyDisableDeviceAuth: {prev} -> {desired_device_auth_flag}")

    # --- Remove invalid keys from earlier add-on versions ---
    for stale_key in ("pairingMode",):
@@ -224,7 +245,8 @@ def set_control_ui_origins(origins_csv: str):
            changes.append(f"removed invalid key: {stale_key}")

    if not changes:
-        print(f"INFO: controlUi already correct: origins={origins}, deviceAuth=disabled")
+        status = "disabled" if desired_device_auth_flag else "enabled"
+        print(f"INFO: controlUi already correct: origins={merged_origins}, deviceAuth={status}")
        return True

    if write_config(cfg):
@@ -234,6 +256,43 @@ def set_control_ui_origins(origins_csv: str):
    return False


+def repair_known_invalid_settings():
+    """Repair known config values that prevent OpenClaw from starting."""
+    cfg = read_config()
+    if cfg is None:
+        return True
+
+    tools = cfg.get("tools")
+    if not isinstance(tools, dict):
+        return True
+
+    web = tools.get("web")
+    if not isinstance(web, dict):
+        return True
+
+    search = web.get("search")
+    if not isinstance(search, dict):
+        return True
+
+    provider = search.get("provider")
+    changes = []
+
+    if provider == "brave":
+        del search["provider"]
+        changes.append("removed unavailable tools.web.search.provider=brave")
+
+    if not changes:
+        print("INFO: No known invalid OpenClaw config settings found")
+        return True
+
+    if write_config(cfg):
+        print(f"INFO: Repaired OpenClaw config: {', '.join(changes)}")
+        return True
+
+    print("ERROR: Failed to write config")
+    return False
+
+
 def main():
    """CLI entry point for use by run.sh"""
    if len(sys.argv) < 2:
@@ -243,16 +302,17 @@ def main():
    cmd = sys.argv[1]
    
    if cmd == "apply-gateway-settings":
-        if len(sys.argv) != 8:
-            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <loopback|lan|tailnet> <port> <enable_openai_api:true|false> <auth_mode:token|trusted-proxy> <trusted_proxies_csv>")
+        if len(sys.argv) != 9:
+            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <remote_url> <loopback|lan|tailnet> <port> <enable_openai_api:true|false> <auth_mode:token|trusted-proxy> <trusted_proxies_csv>")
            sys.exit(1)
        mode = sys.argv[2]
-        bind_mode = sys.argv[3]
-        port = int(sys.argv[4])
-        enable_openai_api = sys.argv[5].lower() == "true"
-        auth_mode = sys.argv[6]
-        trusted_proxies_csv = sys.argv[7]
-        success = apply_gateway_settings(mode, bind_mode, port, enable_openai_api, auth_mode, trusted_proxies_csv)
+        remote_url = sys.argv[3]
+        bind_mode = sys.argv[4]
+        port = int(sys.argv[5])
+        enable_openai_api = sys.argv[6].lower() == "true"
+        auth_mode = sys.argv[7]
+        trusted_proxies_csv = sys.argv[8]
+        success = apply_gateway_settings(mode, remote_url, bind_mode, port, enable_openai_api, auth_mode, trusted_proxies_csv)
        sys.exit(0 if success else 1)
    
    elif cmd == "get":
@@ -266,11 +326,22 @@ def main():
        sys.exit(0)
    
    elif cmd == "set-control-ui-origins":
-        if len(sys.argv) != 3:
-            print("Usage: oc_config_helper.py set-control-ui-origins <origins_csv>")
+        if len(sys.argv) not in (3, 4, 5):
+            print("Usage: oc_config_helper.py set-control-ui-origins <origins_csv> [additional_origins_csv] [disable_device_auth:true|false]")
            sys.exit(1)
        origins_csv = sys.argv[2]
-        success = set_control_ui_origins(origins_csv)
+        additional_origins_csv = sys.argv[3] if len(sys.argv) >= 4 else ""
+        disable_device_auth = True
+        if len(sys.argv) == 5:
+            disable_device_auth = sys.argv[4].strip().lower() == "true"
+        success = set_control_ui_origins(origins_csv, additional_origins_csv, disable_device_auth)
+        sys.exit(0 if success else 1)
+
+    elif cmd == "repair-known-invalid-settings":
+        if len(sys.argv) != 2:
+            print("Usage: oc_config_helper.py repair-known-invalid-settings")
+            sys.exit(1)
+        success = repair_known_invalid_settings()
        sys.exit(0 if success else 1)

    elif cmd == "set":
@@ -44,17 +44,23 @@ 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")
+GATEWAY_REMOTE_URL=$(jq -r '.gateway_remote_url // empty' "$OPTIONS_FILE")
 GATEWAY_BIND_MODE=$(jq -r '.gateway_bind_mode // "loopback"' "$OPTIONS_FILE")
 GATEWAY_PORT=$(jq -r '.gateway_port // 18789' "$OPTIONS_FILE")
 ENABLE_OPENAI_API=$(jq -r '.enable_openai_api // false' "$OPTIONS_FILE")
 GATEWAY_AUTH_MODE=$(jq -r '.gateway_auth_mode // "token"' "$OPTIONS_FILE")
 GATEWAY_TRUSTED_PROXIES=$(jq -r '.gateway_trusted_proxies // empty' "$OPTIONS_FILE")
+GATEWAY_ADDITIONAL_ALLOWED_ORIGINS=$(jq -r '.gateway_additional_allowed_origins // empty' "$OPTIONS_FILE")
+CONTROLUI_DISABLE_DEVICE_AUTH=$(jq -r '.controlui_disable_device_auth // true' "$OPTIONS_FILE")
 FORCE_IPV4_DNS=$(jq -r '.force_ipv4_dns // true' "$OPTIONS_FILE")
 ACCESS_MODE=$(jq -r '.access_mode // "custom"' "$OPTIONS_FILE")
 NGINX_LOG_LEVEL=$(jq -r '.nginx_log_level // "minimal"' "$OPTIONS_FILE")
+AUTO_CONFIGURE_MCP=$(jq -r '.auto_configure_mcp // false' "$OPTIONS_FILE")
 GW_ENV_VARS_TYPE=$(jq -r 'if .gateway_env_vars == null then "null" else (.gateway_env_vars | type) end' "$OPTIONS_FILE")
 GW_ENV_VARS_RAW=$(jq -r '.gateway_env_vars // empty' "$OPTIONS_FILE")
 GW_ENV_VARS_JSON=$(jq -c '.gateway_env_vars // []' "$OPTIONS_FILE")
@@ -145,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.
@@ -176,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() {
@@ -327,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.
@@ -370,8 +403,9 @@ if [ ! -e /data ]; then
  ln -s /config /data || true
 fi

-# Ensure these exist so cleanup doesn't fail
-mkdir -p /config/.openclaw/agents/main/sessions || true
+# Ensure the agents base directory exists so cleanup scans work even before first run.
+# Do NOT pre-create agent-specific directories; OpenClaw creates them as needed.
+mkdir -p /config/.openclaw/agents || true

 # ------------------------------------------------------------------------------
 # SINGLE-INSTANCE GUARD (prevents multiple gateway runs racing each other)
@@ -389,30 +423,43 @@ fi
 # ------------------------------------------------------------------------------

 gateway_running() {
-  pgrep -f "openclaw.*gateway.*run" >/dev/null 2>&1
+  pgrep -f "openclaw-gateway" >/dev/null 2>&1
 }

 cleanup_session_locks() {
-  local sessions_dir="/config/.openclaw/agents/main/sessions"
-  local glob1="${sessions_dir}"/*.jsonl.lock
+  local agents_dir="/config/.openclaw/agents"
+  local total_locks=0
+  local cleaned_dirs=()

+  # Scan all agent session directories, not just 'main'.
+  # This is needed for users who have gateway.forcedAgentId set to a non-default agent.
  shopt -s nullglob
-  local locks=( $glob1 )
+  local all_locks=()
+  for agent_sessions_dir in "${agents_dir}"/*/sessions; do
+    local agent_locks=( "${agent_sessions_dir}"/*.jsonl.lock )
+    if [ ${#agent_locks[@]} -gt 0 ]; then
+      all_locks+=( "${agent_locks[@]}" )
+      cleaned_dirs+=( "$agent_sessions_dir" )
+      total_locks=$(( total_locks + ${#agent_locks[@]} ))
+    fi
+  done
  shopt -u nullglob

-  if [ ${#locks[@]} -eq 0 ]; then
+  if [ "$total_locks" -eq 0 ]; then
    return 0
  fi

  # If gateway is running, do NOT remove locks automatically (could be real).
  if gateway_running; then
    echo "INFO: Gateway appears to be running; leaving session lock files untouched."
-    echo "INFO: Locks present: ${#locks[@]}"
+    echo "INFO: Locks present: $total_locks"
    return 0
  fi

-  echo "INFO: Removing stale session lock files (${#locks[@]}) from ${sessions_dir}"
-  rm -f "${sessions_dir}"/*.jsonl.lock || true
+  echo "INFO: Removing stale session lock files ($total_locks) across agents: ${cleaned_dirs[*]}"
+  for agent_sessions_dir in "${cleaned_dirs[@]}"; do
+    rm -f "${agent_sessions_dir}"/*.jsonl.lock || true
+  done
 }

 if [ "$CLEAN_LOCKS_ON_START" = "true" ]; then
@@ -450,10 +497,13 @@ EOF
 # Graceful shutdown handling (PID 1 trap) to reduce stale locks
 # ------------------------------------------------------------------------------
 GW_PID=""
+GW_RELAY_PID=""
 NGINX_PID=""
 TTYD_PID=""
+SHUTTING_DOWN="false"

 shutdown() {
+  SHUTTING_DOWN="true"
  echo "Shutdown requested; stopping services..."

  if [ -n "${NGINX_PID}" ] && kill -0 "${NGINX_PID}" >/dev/null 2>&1; then
@@ -468,9 +518,18 @@ shutdown() {

  if [ -n "${GW_PID}" ] && kill -0 "${GW_PID}" >/dev/null 2>&1; then
    kill -TERM "${GW_PID}" >/dev/null 2>&1 || true
-    wait "${GW_PID}" || true
+    # wait reaps child PIDs; for non-child (re-tracked) PIDs it fails instantly,
+    # so fall back to a timed kill -0 poll to let the gateway finish cleanly.
+    if ! wait "${GW_PID}" 2>/dev/null; then
+      for _i in 1 2 3 4 5; do
+        kill -0 "${GW_PID}" 2>/dev/null || break
+        sleep 1
+      done
+    fi
  fi

+  stop_gw_relay
+
  if [ "$CLEAN_LOCKS_ON_EXIT" = "true" ]; then
    cleanup_session_locks || true
  fi
@@ -483,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"
@@ -532,9 +654,20 @@ fi

 if [ -f "$OPENCLAW_CONFIG_PATH" ]; then
  if [ -f "$HELPER_PATH" ]; then
+    if python3 "$HELPER_PATH" repair-known-invalid-settings; then
+      :
+    else
+      rc=$?
+      echo "ERROR: Failed to repair known invalid OpenClaw config settings via oc_config_helper.py (exit code ${rc})."
+      echo "ERROR: Gateway configuration may be invalid; aborting startup."
+      exit "${rc}"
+    fi
+
    # In lan_https mode the gateway uses an internal port; nginx owns the external one.
    EFFECTIVE_GW_PORT="$GATEWAY_INTERNAL_PORT"
-    if ! python3 "$HELPER_PATH" apply-gateway-settings "$GATEWAY_MODE" "$GATEWAY_BIND_MODE" "$EFFECTIVE_GW_PORT" "$ENABLE_OPENAI_API" "$GATEWAY_AUTH_MODE" "$GATEWAY_TRUSTED_PROXIES"; then
+    if python3 "$HELPER_PATH" apply-gateway-settings "$GATEWAY_MODE" "$GATEWAY_REMOTE_URL" "$GATEWAY_BIND_MODE" "$EFFECTIVE_GW_PORT" "$ENABLE_OPENAI_API" "$GATEWAY_AUTH_MODE" "$GATEWAY_TRUSTED_PROXIES"; then
+      :
+    else
      rc=$?
      echo "ERROR: Failed to apply gateway settings via oc_config_helper.py (exit code ${rc})."
      echo "ERROR: Gateway configuration may be incorrect; aborting startup."
@@ -549,15 +682,87 @@ else
  echo "INFO: Run 'openclaw onboard' first, then restart the add-on"
 fi

+if [ "$GATEWAY_AUTH_MODE" = "trusted-proxy" ]; then
+  echo "NOTICE: gateway_auth_mode=trusted-proxy is enabled."
+  echo "NOTICE: Direct local CLI calls to the gateway may return unauthorized (trusted_proxy_user_missing) unless identity headers are injected by your reverse proxy."
+  echo "NOTICE: For local terminal CLI workflows, temporarily switch to token auth or use commands that don't require direct gateway WS auth."
+fi
+
 # ------------------------------------------------------------------------------
 # TLS certificate generation for built-in HTTPS proxy (lan_https mode)
 # Generates a local CA + server cert so phones/tablets get proper HTTPS.
 # The CA cert can be installed once on a device for trusted access.
 # ------------------------------------------------------------------------------
+LAN_IP=""
 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 "")
@@ -565,35 +770,56 @@ 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

-  # --- Server cert (regenerated when LAN IP changes) ---
-  if [ ! -f "$CERT_DIR/gateway.crt" ] || [ ! -f "$CERT_DIR/gateway.key" ] || [ "$LAN_IP" != "$STORED_IP" ]; then
+  # --- Extra SANs from gateway_additional_allowed_origins + gateway_public_url ---
+  EXTRA_SANS=""
+  EXTRA_SAN_SOURCES="${GATEWAY_ADDITIONAL_ALLOWED_ORIGINS},${GW_PUBLIC_URL}"
+  if [ "$EXTRA_SAN_SOURCES" != "," ]; then
+    EXTRA_SANS="$(python3 - "$EXTRA_SAN_SOURCES" "${LAN_IP:-}" <<'PY'
+import sys, re
+from urllib.parse import urlparse
+raw = sys.argv[1] if len(sys.argv) > 1 else ""
+lan_ip = sys.argv[2] if len(sys.argv) > 2 else ""
+entries = [e.strip() for e in raw.split(",") if e.strip()]
+sans = []
+seen = {"127.0.0.1", "localhost", "homeassistant", "homeassistant.local"}
+if lan_ip:
+    seen.add(lan_ip)
+for entry in entries:
+    if "://" not in entry:
+        entry = "https://" + entry
+    host = urlparse(entry).hostname or ""
+    if host and host not in seen:
+        seen.add(host)
+        if re.match(r"^\d{1,3}(\.\d{1,3}){3}$", host):
+            sans.append(f"IP:{host}")
+        else:
+            sans.append(f"DNS:{host}")
+print(",".join(sans), end="")
+PY
+)"
+  fi
+  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" ] || ! 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, and common mDNS names
-    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
-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"
-    echo "INFO: Server TLS certificate generated (SAN includes IP:${LAN_IP:-127.0.0.1})"
+    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}})"
  else
    echo "INFO: Reusing existing TLS certificate (IP: $STORED_IP)"
  fi
@@ -603,32 +829,44 @@ SANEOF
  cp "$CERT_DIR/ca.crt" /etc/nginx/html/openclaw-ca.crt 2>/dev/null || true
  echo "INFO: CA certificate available for download at /cert/ca.crt on the HTTPS port"

-  # ------------------------------------------------------------------
-  # Configure gateway.controlUi for the HTTPS proxy:
-  #
-  # 1. allowedOrigins — the browser's HTTPS origin must be listed,
-  #    otherwise v2026.2.21+ rejects with 1008 "origin not allowed".
-  #
-  # 2. dangerouslyDisableDeviceAuth — skips the interactive device
-  #    pairing ceremony (1008 "pairing required").  In a self-hosted
-  #    add-on the user already controls the token, so per-device
-  #    approval adds friction without real security benefit.
-  #
-  #    NOTE: v2026.2.22+ emits a startup security warning when this
-  #    flag is active. The warning is expected and harmless for this
-  #    use case — run `openclaw security audit` for details.
-  #
-  # Also cleans up any stale keys (e.g. pairingMode) from older
-  # add-on versions that would cause "Unrecognized key" errors.
-  # ------------------------------------------------------------------
-  if [ -n "$LAN_IP" ] && [ -f "$HELPER_PATH" ] && [ -f "$OPENCLAW_CONFIG_PATH" ]; then
+fi
+
+# ------------------------------------------------------------------
+# Configure gateway.controlUi.allowedOrigins:
+# - In lan_https: include HTTPS proxy defaults (LAN IP + common hostnames)
+# - In all modes: also include origin from gateway_public_url when present
+# - Helper merges with existing origins + user extras and deduplicates
+# ------------------------------------------------------------------
+if [ -f "$HELPER_PATH" ] && [ -f "$OPENCLAW_CONFIG_PATH" ]; then
+  ALLOWED_ORIGINS=""
+
+  if [ "$ENABLE_HTTPS_PROXY" = "true" ] && [ -n "$LAN_IP" ]; then
    ALLOWED_ORIGINS="https://${LAN_IP}:${GATEWAY_PORT}"
-    # Also permit common mDNS/hostname variants so the cert SAN names work too
    ALLOWED_ORIGINS="${ALLOWED_ORIGINS},https://homeassistant.local:${GATEWAY_PORT}"
    ALLOWED_ORIGINS="${ALLOWED_ORIGINS},https://homeassistant:${GATEWAY_PORT}"
-    python3 "$HELPER_PATH" set-control-ui-origins "$ALLOWED_ORIGINS" || \
-      echo "WARN: Could not set controlUi settings — gateway may reject the Control UI"
  fi
+
+  if [ -n "$GW_PUBLIC_URL" ]; then
+    GW_PUBLIC_ORIGIN="$(python3 - "$GW_PUBLIC_URL" <<'PY'
+import sys
+from urllib.parse import urlparse
+u = (sys.argv[1] or '').strip()
+p = urlparse(u)
+if p.scheme in ('http', 'https') and p.netloc:
+    print(f"{p.scheme}://{p.netloc}", end='')
+PY
+)"
+    if [ -n "$GW_PUBLIC_ORIGIN" ]; then
+      if [ -n "$ALLOWED_ORIGINS" ]; then
+        ALLOWED_ORIGINS="${ALLOWED_ORIGINS},${GW_PUBLIC_ORIGIN}"
+      else
+        ALLOWED_ORIGINS="$GW_PUBLIC_ORIGIN"
+      fi
+    fi
+  fi
+
+  python3 "$HELPER_PATH" set-control-ui-origins "$ALLOWED_ORIGINS" "$GATEWAY_ADDITIONAL_ALLOWED_ORIGINS" "$CONTROLUI_DISABLE_DEVICE_AUTH" || \
+    echo "WARN: Could not set controlUi settings — gateway may reject the Control UI"
 fi

 # ------------------------------------------------------------------------------
@@ -645,9 +883,193 @@ if [ -f /usr/local/lib/openclaw-proxy-shim.cjs ]; then
  export OPENCLAW_GLOBAL_NODE_MODULES
 fi

-echo "Starting OpenClaw Assistant gateway (openclaw)..."
-openclaw gateway run &
-GW_PID=$!
+# ------------------------------------------------------------------------------
+# Auto-configure MCP (Model Context Protocol) for Home Assistant
+# Registers HA as an MCP server so OpenClaw can control HA entities/services.
+# Requires: homeassistant_token set in add-on options + mcporter CLI available.
+# Runs once; re-runs when the token changes.
+# Auto-detects HA API URL: supervisor proxy if available, else localhost:8123.
+# ------------------------------------------------------------------------------
+if [ "$AUTO_CONFIGURE_MCP" = "true" ] && [ -n "$HA_TOKEN" ]; then
+  if command -v mcporter >/dev/null 2>&1; then
+    # Detect HA API URL: prefer supervisor proxy (works in all add-on network modes),
+    # fall back to localhost:8123 (works with host_network: true).
+    if [ -n "${SUPERVISOR_TOKEN:-}" ]; then
+      MCP_HA_URL="http://supervisor/core/api/mcp"
+    else
+      MCP_HA_URL="http://localhost:8123/api/mcp"
+    fi
+    MCP_FLAG="/config/.openclaw/.mcp_ha_configured"
+    MCP_TOKEN_HASH=$(printf '%s' "$HA_TOKEN" | sha256sum | cut -d' ' -f1)
+
+    if [ -f "$MCP_FLAG" ] && [ "$(cat "$MCP_FLAG" 2>/dev/null)" = "$MCP_TOKEN_HASH" ]; then
+      echo "INFO: MCP Home Assistant server already configured (token unchanged)"
+    else
+      echo "INFO: Configuring MCP for Home Assistant at $MCP_HA_URL ..."
+      # Remove stale entry if present (token may have changed)
+      mcporter config remove HA 2>/dev/null || true
+
+      if mcporter config add HA "$MCP_HA_URL" \
+          --header "Authorization=Bearer $HA_TOKEN" \
+          --scope home 2>&1; then
+        printf '%s' "$MCP_TOKEN_HASH" > "$MCP_FLAG"
+        echo "INFO: MCP server 'HA' registered — OpenClaw can now control Home Assistant"
+      else
+        echo "WARN: MCP auto-configuration failed. Configure manually in the terminal:"
+        echo "WARN:   mcporter config add HA \"$MCP_HA_URL\" --header \"Authorization=Bearer YOUR_TOKEN\" --scope home"
+      fi
+    fi
+  else
+    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"
+  echo "INFO: To auto-configure, set homeassistant_token in add-on Configuration, then restart"
+fi
+
+start_openclaw_runtime() {
+  echo "Starting OpenClaw Assistant runtime (openclaw)..."
+  if [ "$GATEWAY_MODE" = "remote" ]; then
+    # Remote mode: do NOT start a local gateway service.
+    # Start a node/client host that connects to the configured remote gateway URL.
+    # Use $GATEWAY_REMOTE_URL directly from add-on options — do NOT read back via
+    # 'openclaw config get' which can time out at startup or return redacted values.
+    REMOTE_URL="$GATEWAY_REMOTE_URL"
+    if [ -z "$REMOTE_URL" ]; then
+      echo "ERROR: gateway_mode=remote but gateway_remote_url is not set in add-on options"
+      echo "ERROR: Set gateway_remote_url in add-on Configuration (e.g. ws://192.168.1.10:18789), then restart"
+      return 1
+    fi
+
+    NODE_HOST=""
+    NODE_PORT=""
+    NODE_TLS_FLAG=""
+    if ! eval "$(python3 - "$REMOTE_URL" <<'PY'
+import sys
+from urllib.parse import urlparse
+url = (sys.argv[1] or '').strip()
+p = urlparse(url)
+if p.scheme not in ('ws', 'wss') or not p.hostname:
+    print('echo "ERROR: Invalid gateway.remote.url (expected ws:// or wss://): %s"' % url.replace('"', '\\"'))
+    print('exit 1')
+    raise SystemExit(0)
+port = p.port or (443 if p.scheme == 'wss' else 80)
+print(f'NODE_HOST={p.hostname}')
+print(f'NODE_PORT={port}')
+print(f'NODE_TLS_FLAG={"--tls" if p.scheme == "wss" else ""}')
+PY
+)"; then
+      echo "ERROR: Failed to parse gateway.remote.url: $REMOTE_URL"
+      return 1
+    fi
+
+    echo "INFO: gateway_mode=remote detected; starting node host to $NODE_HOST:$NODE_PORT ${NODE_TLS_FLAG}"
+    # shellcheck disable=SC2086
+    openclaw node run --host "$NODE_HOST" --port "$NODE_PORT" $NODE_TLS_FLAG &
+  else
+    openclaw gateway run &
+  fi
+  GW_PID=$!
+  return 0
+}
+
+# --- Loopback relay helpers for tailnet bind mode (issue #90) ---
+# When gateway.bind=tailnet the gateway only listens on the Tailscale IP.
+# The local CLI always tries ws://127.0.0.1:PORT and fails with
+# "Gateway not running" even though the gateway is healthy.
+# These functions start/stop a lightweight Node.js TCP relay on
+# 127.0.0.1:PORT -> TAILSCALE_IP:PORT so terminal CLI commands work.
+# IMPORTANT: stop_gw_relay must be called before restarting the gateway;
+# otherwise the relay holds the loopback port and the new gateway instance
+# detects it as "already listening" and exits with code 1.
+start_gw_relay() {
+  if [ "$GATEWAY_BIND_MODE" != "tailnet" ]; then
+    return 0
+  fi
+  local ts_ip
+  ts_ip=$(ip -4 addr show tailscale0 2>/dev/null \
+    | awk '/inet /{gsub(/\/.*/,"",$2); print $2; exit}' || true)
+  if [[ "${ts_ip:-}" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "INFO: Starting loopback relay for tailnet gateway (127.0.0.1:${GATEWAY_PORT} -> ${ts_ip}:${GATEWAY_PORT})"
+    node -e "
+const net = require('net');
+const TARGET_HOST = '${ts_ip}';
+const TARGET_PORT = ${GATEWAY_PORT};
+const server = net.createServer(function(c) {
+  const t = net.createConnection(TARGET_PORT, TARGET_HOST);
+  c.pipe(t); t.pipe(c);
+  c.on('error', function() { t.destroy(); });
+  t.on('error', function() { c.destroy(); });
+});
+server.listen(TARGET_PORT, '127.0.0.1');" &
+    GW_RELAY_PID=$!
+    echo "INFO: Loopback relay started (PID ${GW_RELAY_PID})"
+  else
+    echo "WARN: tailnet bind mode active but Tailscale IP not found on tailscale0 interface."
+    echo "WARN: Terminal CLI may show gateway as unreachable. Ensure Tailscale is running and restart."
+  fi
+}
+
+stop_gw_relay() {
+  if [ -n "${GW_RELAY_PID}" ] && kill -0 "${GW_RELAY_PID}" >/dev/null 2>&1; then
+    kill -TERM "${GW_RELAY_PID}" >/dev/null 2>&1 || true
+    wait "${GW_RELAY_PID}" 2>/dev/null || true
+    GW_RELAY_PID=""
+  fi
+}
+
+# Find a running gateway daemon's PID using multiple detection methods.
+# Used by the supervisor loop to detect self-restarts (SIGUSR1) without
+# spawning duplicate gateway instances that collide on the port.
+#
+# Three tiers, tried in order of reliability:
+#   1. Port ownership via `ss -tlnp` — authoritative, but only works once
+#      the daemon has bound the port (can take 20+ s on Pi hardware).
+#   2. Process title via `pgrep -f openclaw-gateway` — works after Node.js
+#      sets process.title, which also happens late during init.
+#   3. /proc cmdline scan — catches the daemon IMMEDIATELY after fork,
+#      before title or port bind, by matching "openclaw" in the cmdline.
+#      Excludes known PIDs (nginx, ttyd, relay, our shell, old GW_PID).
+#
+# Returns the PID on stdout and exit 0, or exits with code 1 if nothing found.
+find_gateway_daemon_pid() {
+  local pid=""
+
+  # Tier 1: port ownership (authoritative once port is bound)
+  pid=$(ss -tlnp 2>/dev/null \
+    | grep ":${GATEWAY_INTERNAL_PORT} " \
+    | sed -n 's/.*pid=\([0-9]*\).*/\1/p' \
+    | head -1)
+  [ -n "$pid" ] && { echo "$pid"; return 0; }
+
+  # Tier 2: process title (after Node sets process.title)
+  pid=$(pgrep -f "openclaw-gateway" 2>/dev/null | head -1)
+  [ -n "$pid" ] && { echo "$pid"; return 0; }
+
+  # Tier 3: scan /proc for any openclaw process we don't already know about.
+  # The daemon's cmdline (e.g. node /usr/.../openclaw/...) contains "openclaw"
+  # from the moment it is forked, even before process.title is set.
+  local known=" ${NGINX_PID:-0} ${TTYD_PID:-0} ${GW_RELAY_PID:-0} ${GW_PID:-0} $$ "
+  local f cand
+  for f in /proc/[0-9]*/cmdline; do
+    [ -r "$f" ] || continue
+    if tr '\0' ' ' < "$f" 2>/dev/null | grep -q "openclaw"; then
+      cand="${f#/proc/}"
+      cand="${cand%%/*}"
+      case "$known" in *" $cand "*) continue ;; esac
+      echo "$cand"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+if ! start_openclaw_runtime; then
+  exit 1
+fi
+
+start_gw_relay

 # Start web terminal (optional)
 TTYD_PID_FILE="/var/run/openclaw-ttyd.pid"
@@ -715,34 +1137,61 @@ if command -v ss >/dev/null 2>&1 && ss -tlnp 2>/dev/null | grep -q ':48099 '; th
  echo "WARN: Port 48099 still in use after cleanup; nginx may fail to start"
 fi

-# Render nginx config from template.
-# The gateway token is NOT managed by the add-on; OpenClaw will generate/store it.
-# Best-effort: query it via CLI (works even if openclaw.json is JSON5). If unknown, we hide the button.
-GW_TOKEN="$(timeout 2s openclaw config get gateway.auth.token 2>/dev/null | tr -d '\n' || true)"
+# ------------------------------------------------------------------------------
+# render_landing: (re-)render the nginx config + landing page HTML.
+#
+# Called once before nginx starts (token may be empty on first boot/pre-onboard)
+# and again in the background after the gateway comes up so a freshly-generated
+# token is immediately reflected in the "Open Gateway Web UI" button.
+# nginx is sent SIGHUP to reload the updated config without restarting.
+# ------------------------------------------------------------------------------
+render_landing() {
+  local label="${1:-startup}"
+  # Read gateway token directly from openclaw.json (CLI redacts secrets v2026.2.22+)
+  local token
+  token="$(python3 -c "
+import json, os
+p = os.environ.get('OPENCLAW_CONFIG_PATH', '/config/.openclaw/openclaw.json')
+print(json.load(open(p)).get('gateway',{}).get('auth',{}).get('token',''), end='')
+" 2>/dev/null || true)"

-# Collect disk usage for landing page status card
-DISK_TOTAL="" DISK_USED="" DISK_AVAIL="" DISK_PCT=""
-if df -h /config >/dev/null 2>&1; then
-  DISK_TOTAL=$(df -h /config | awk 'NR==2{print $2}')
-  DISK_USED=$(df -h /config | awk 'NR==2{print $3}')
-  DISK_AVAIL=$(df -h /config | awk 'NR==2{print $4}')
-  DISK_PCT=$(df -h /config | awk 'NR==2{print $5}')
-  echo "INFO: Disk usage: ${DISK_USED}/${DISK_TOTAL} (${DISK_PCT} used, ${DISK_AVAIL} free)"
-  # Warn early if disk is getting full
-  DISK_PCT_NUM=${DISK_PCT//%/}
-  if [ "$DISK_PCT_NUM" -ge 90 ] 2>/dev/null; then
-    echo "WARNING: Disk is ${DISK_PCT} full! Add-on updates may fail. Run 'oc-cleanup' in the terminal."
-  elif [ "$DISK_PCT_NUM" -ge 75 ] 2>/dev/null; then
-    echo "NOTICE: Disk is ${DISK_PCT} full. Consider running 'oc-cleanup' in the terminal."
+  local disk_total="" disk_used="" disk_avail="" disk_pct=""
+  if df -h /config >/dev/null 2>&1; then
+    disk_total=$(df -h /config | awk 'NR==2{print $2}')
+    disk_used=$(df -h /config  | awk 'NR==2{print $3}')
+    disk_avail=$(df -h /config | awk 'NR==2{print $4}')
+    disk_pct=$(df -h /config   | awk 'NR==2{print $5}')
+    if [ "$label" = "startup" ]; then
+      echo "INFO: Disk usage: ${disk_used}/${disk_total} (${disk_pct} used, ${disk_avail} free)"
+      local pct_num=${disk_pct//%/}
+      if [ "$pct_num" -ge 90 ] 2>/dev/null; then
+        echo "WARNING: Disk is ${disk_pct} full! Add-on updates may fail. Run 'oc-cleanup' in the terminal."
+      elif [ "$pct_num" -ge 75 ] 2>/dev/null; then
+        echo "NOTICE: Disk is ${disk_pct} full. Consider running 'oc-cleanup' in the terminal."
+      fi
+    fi
  fi
-fi

-GW_PUBLIC_URL="$GW_PUBLIC_URL" GW_TOKEN="$GW_TOKEN" TERMINAL_PORT="$TERMINAL_PORT" \
-  ENABLE_HTTPS_PROXY="$ENABLE_HTTPS_PROXY" HTTPS_PROXY_PORT="$GATEWAY_PORT" \
-  GATEWAY_INTERNAL_PORT="$GATEWAY_INTERNAL_PORT" ACCESS_MODE="$ACCESS_MODE" \
-  DISK_TOTAL="$DISK_TOTAL" DISK_USED="$DISK_USED" DISK_AVAIL="$DISK_AVAIL" DISK_PCT="$DISK_PCT" \
-  NGINX_LOG_LEVEL="$NGINX_LOG_LEVEL" \
-  python3 /render_nginx.py
+  GW_PUBLIC_URL="$GW_PUBLIC_URL" GW_TOKEN="$token" TERMINAL_PORT="$TERMINAL_PORT" \
+    ENABLE_HTTPS_PROXY="$ENABLE_HTTPS_PROXY" HTTPS_PROXY_PORT="$GATEWAY_PORT" \
+    GATEWAY_INTERNAL_PORT="$GATEWAY_INTERNAL_PORT" ACCESS_MODE="$ACCESS_MODE" \
+    DISK_TOTAL="$disk_total" DISK_USED="$disk_used" DISK_AVAIL="$disk_avail" DISK_PCT="$disk_pct" \
+    NGINX_LOG_LEVEL="$NGINX_LOG_LEVEL" \
+    python3 /render_nginx.py
+
+  if [ "$label" != "startup" ]; then
+    # Signal nginx to reload config/landing HTML without dropping connections.
+    local nginx_pid
+    nginx_pid=$(cat "${NGINX_PID_FILE:-/var/run/openclaw-nginx.pid}" 2>/dev/null || true)
+    if [ -n "$nginx_pid" ] && kill -0 "$nginx_pid" 2>/dev/null; then
+      kill -HUP "$nginx_pid" 2>/dev/null || true
+      echo "INFO: Landing page re-rendered with gateway token (nginx reloaded)."
+    fi
+  fi
+}
+
+# Initial render (token may be absent if openclaw.json does not exist yet)
+render_landing startup

 echo "Starting ingress proxy (nginx) on :48099 ..."
 nginx -g 'daemon off;' &
@@ -755,5 +1204,123 @@ else
  echo "WARN: nginx failed to start (PID $NGINX_PID exited); ingress UI may be unavailable"
 fi

-# Wait for gateway; if it exits, shut down others.
-wait "${GW_PID}"
+# If the token was not available at startup (first boot / pre-onboard), schedule
+# a background re-render so the "Open Gateway Web UI" button gets the real token
+# once openclaw onboard writes openclaw.json (typically within 30-90 s).
+(
+  CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-/config/.openclaw/openclaw.json}"
+  for _i in $(seq 1 24); do
+    sleep 5
+    token=$(python3 -c "
+import json, os
+p='$CONFIG_PATH'
+try:
+    print(json.load(open(p)).get('gateway',{}).get('auth',{}).get('token',''), end='')
+except Exception:
+    pass
+" 2>/dev/null || true)
+    if [ -n "$token" ]; then
+      render_landing post-onboard
+      break
+    fi
+  done
+) &
+
+# Keep add-on alive even if gateway/node runtime restarts itself (e.g. during onboarding).
+# If runtime exits unexpectedly, restart it while nginx/ttyd stay up.
+#
+# Design notes (issue #95):
+#   `openclaw gateway run` is a thin wrapper that spawns `openclaw-gateway` as a
+#   long-running daemon and then exits. When the gateway self-restarts (SIGUSR1 /
+#   `openclaw gateway restart`), the old daemon exits and a NEW daemon is forked —
+#   the new PID is NOT a child of this shell so `wait` cannot block on it.
+#
+#   The new daemon can take 20-30 seconds to initialise on low-power hardware
+#   (Pi / eMMC). During that time its process.title and port binding are not yet
+#   visible, but the process itself exists in /proc with "openclaw" in its cmdline.
+#
+#   Strategy:
+#     1. `wait` for our child (the wrapper). After it exits, use
+#        `find_gateway_daemon_pid` (port → pgrep → /proc scan) with retries
+#        to find the daemon. If found → re-track and poll with `kill -0`.
+#     2. When the re-tracked daemon eventually exits (crash or another restart),
+#        `kill -0` fails, we check again for a live daemon to re-track.
+#     3. Before any supervisor-initiated restart, do a final port-occupancy
+#        guard to prevent launching a duplicate.
+GW_IS_CHILD=true   # true only when GW_PID was started by us (can use `wait`)
+
+while true; do
+  if [ "$GW_IS_CHILD" = "true" ]; then
+    # Efficient blocking wait on our child process.
+    GW_EXIT_CODE=0
+    wait "${GW_PID}" 2>/dev/null || GW_EXIT_CODE=$?
+  else
+    # GW_PID is NOT our child (re-tracked after a self-restart).
+    # Poll with kill -0 until it exits.
+    while kill -0 "$GW_PID" 2>/dev/null; do
+      if [ "$SHUTTING_DOWN" = "true" ]; then break 2; fi
+      sleep 5
+    done
+    GW_EXIT_CODE=0
+  fi
+
+  if [ "$SHUTTING_DOWN" = "true" ]; then
+    break
+  fi
+
+  # --- Detect self-restart ---------------------------------------------------
+  # Try up to 10 times (≈ 20 s) using all 3 tiers of find_gateway_daemon_pid.
+  # Tier 3 (/proc scan) usually finds the daemon on the very first attempt
+  # because the process exists immediately after fork, even before port bind
+  # or process.title. The retries cover edge cases on extremely slow I/O.
+  RESTARTED_PID=""
+  if [ "$GATEWAY_MODE" != "remote" ]; then
+    for _attempt in 1 2 3 4 5 6 7 8 9 10; do
+      RESTARTED_PID=$(find_gateway_daemon_pid 2>/dev/null || true)
+      [ -n "$RESTARTED_PID" ] && break
+      sleep 2
+    done
+  else
+    sleep 2
+    RESTARTED_PID=$(pgrep -f "openclaw.*node.*run" 2>/dev/null | head -1 || true)
+  fi
+
+  if [ -n "$RESTARTED_PID" ]; then
+    echo "INFO: OpenClaw runtime active (PID $RESTARTED_PID); monitoring."
+    GW_PID="$RESTARTED_PID"
+    GW_IS_CHILD=false
+    continue
+  fi
+
+  # --- Final port guard ------------------------------------------------------
+  # Even if all detection methods missed the daemon during the loop above,
+  # the port may now be bound (the daemon finished initialising while we slept).
+  # Never launch a duplicate if the port is occupied.
+  if [ "$GATEWAY_MODE" != "remote" ] && \
+     ss -tlnp 2>/dev/null | grep -q ":${GATEWAY_INTERNAL_PORT} "; then
+    PORT_PID=$(ss -tlnp 2>/dev/null \
+      | grep ":${GATEWAY_INTERNAL_PORT} " \
+      | sed -n 's/.*pid=\([0-9]*\).*/\1/p' \
+      | head -1 || true)
+    echo "INFO: Gateway port ${GATEWAY_INTERNAL_PORT} occupied by PID ${PORT_PID:-unknown}; monitoring."
+    GW_PID="${PORT_PID:-$GW_PID}"
+    GW_IS_CHILD=false
+    continue
+  fi
+
+  echo "WARN: OpenClaw runtime exited with code ${GW_EXIT_CODE}. Restarting in 2s..."
+  sleep 2
+
+  # Stop the loopback relay BEFORE restarting the gateway (tailnet mode only).
+  # The relay holds 127.0.0.1:GATEWAY_PORT — leaving it up causes the new gateway
+  # to detect the port as occupied and exit with code 1, re-entering the loop.
+  stop_gw_relay
+
+  if ! start_openclaw_runtime; then
+    echo "ERROR: Failed to restart OpenClaw runtime; retrying in 5s..."
+    sleep 5
+  else
+    GW_IS_CHILD=true
+    start_gw_relay
+  fi
+done
@@ -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
@@ -50,6 +58,18 @@ configuration:
      local: "Локален (препоръчително)"
      remote: "Отдалечен"

+  gateway_remote_url:
+    name: URL на отдалечен Gateway
+    description: WebSocket URL на отдалечения gateway, използван когато Gateway Mode е remote (пример - ws://192.168.1.20:18789 или wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Допълнителни разрешени origins
+    description: Допълнителни origins за Control UI, разделени със запетая; сливат се в gateway.controlUi.allowedOrigins при lan_https (пример - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Изключи device pairing за Control UI (lan_https)
+    description: "Когато е ВКЛ. (препоръчително), задава gateway.controlUi.dangerouslyDisableDeviceAuth=true и пропуска одобрението по устройство, за да избегне error 1008 в LAN HTTPS режим. Остави ВКЛ. за домашна/доверена мрежа. Изключи само ако искаш стриктно pairing потвърждение за всеки нов браузър/устройство."
+
  gateway_bind_mode:
    name: Режим на свързване на Gateway
    description: Режим на мрежово свързване - loopback (само 127.0.0.1, най-сигурен), lan (всички интерфейси) или tailnet (само Tailscale интерфейс). Пренебрегва се от предварителните режими на достъп.
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Променливи на средата за Gateway
    description: Променливи на средата, предавани на OpenClaw gateway процеса при стартиране (списък от записи name/value в Home Assistant UI; макс. 50 променливи, ключове до 255 знака, стойности до 10000 знака).
+  auto_configure_mcp:
+    name: Автоматично конфигуриране на MCP за Home Assistant
+    description: "Когато е ВКЛ. и Home Assistant Token е зададен, автоматично регистрира Home Assistant като MCP сървър при всяко стартиране. Това позволява на OpenClaw да контролира HA устройства, услуги и автоматизации чрез Model Context Protocol. Изключете само ако управлявате mcporter конфигурацията ръчно."
@@ -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
@@ -50,6 +58,18 @@ configuration:
      local: "Lokal (empfohlen)"
      remote: "Remote"

+  gateway_remote_url:
+    name: Remote Gateway-URL
+    description: Remote-Gateway-WebSocket-URL, verwendet wenn Gateway-Modus auf Remote steht (Beispiel - ws://192.168.1.20:18789 oder wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Zusätzliche erlaubte Origins
+    description: Kommagetrennte zusätzliche Control-UI-Origins, die bei lan_https in gateway.controlUi.allowedOrigins zusammengeführt werden (Beispiel - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Control-UI-Geräte-Pairing deaktivieren (lan_https)
+    description: "Wenn EIN (empfohlen), setzt dies gateway.controlUi.dangerouslyDisableDeviceAuth=true, überspringt die Gerätefreigabe und vermeidet Fehler 1008 im LAN-HTTPS-Modus. Für Heim-/vertrauenswürdiges LAN eingeschaltet lassen. Nur AUS schalten, wenn du striktes Geräte-Pairing für jeden neuen Browser/jedes neue Gerät willst."
+
  gateway_bind_mode:
    name: Gateway-Bindungsmodus
    description: Netzwerk-Bindungsmodus - loopback (nur 127.0.0.1, am sichersten), lan (alle Schnittstellen) oder tailnet (nur Tailscale-Schnittstelle). Wird durch Zugriffsmodus-Voreinstellungen überschrieben.
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Gateway-Umgebungsvariablen
    description: Umgebungsvariablen, die beim Start an den OpenClaw-Gateway-Prozess übergeben werden (Liste mit name/value-Einträgen in der Home Assistant UI; max. 50 Variablen, Schlüssel bis 255 Zeichen, Werte bis 10.000 Zeichen).
+  auto_configure_mcp:
+    name: MCP für Home Assistant automatisch konfigurieren
+    description: "Wenn AN und Home Assistant Token gesetzt ist, wird Home Assistant bei jedem Start automatisch als MCP-Server registriert. Das erlaubt OpenClaw, HA-Geräte, -Dienste und -Automatisierungen über das Model Context Protocol zu steuern. Nur deaktivieren, wenn Sie die mcporter-Konfiguration manuell verwalten."
@@ -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
@@ -50,6 +58,18 @@ configuration:
      local: "Local (recommended)"
      remote: "Remote"

+  gateway_remote_url:
+    name: Remote Gateway URL
+    description: Remote gateway WebSocket URL used when Gateway Mode is Remote (example - ws://192.168.1.20:18789 or wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Additional Allowed Origins
+    description: Comma-separated extra Control UI origins to merge into gateway.controlUi.allowedOrigins in lan_https mode (example - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Disable Control UI Device Pairing (lan_https)
+    description: "When ON (recommended), sets gateway.controlUi.dangerouslyDisableDeviceAuth=true to skip per-device approval and avoid error 1008 in LAN HTTPS mode. Keep ON for home/trusted LAN. Turn OFF only when you want strict per-device pairing prompts on every new browser/device."
+
  gateway_bind_mode:
    name: Gateway Bind Mode
    description: Network bind mode - loopback (127.0.0.1 only, most secure), lan (all interfaces), or tailnet (Tailscale interface only). Overridden by access_mode presets.
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Gateway Environment Variables
    description: Environment variables passed to the OpenClaw gateway process at startup (list entries with name/value in Home Assistant UI; max 50 variables, keys up to 255 characters, values up to 10,000 characters).
+  auto_configure_mcp:
+    name: Auto-Configure MCP for Home Assistant
+    description: "When ON and Home Assistant Token is set, automatically registers Home Assistant as an MCP server on each startup. This lets OpenClaw control HA entities, services, and automations via the Model Context Protocol. Disable only if you manage mcporter configuration manually."
@@ -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
@@ -50,6 +58,18 @@ configuration:
      local: "Local (recomendado)"
      remote: "Remoto"

+  gateway_remote_url:
+    name: URL del Gateway Remoto
+    description: URL WebSocket del gateway remoto utilizada cuando Gateway Mode es Remote (ejemplo - ws://192.168.1.20:18789 o wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Orígenes permitidos adicionales
+    description: Orígenes extra de Control UI separados por comas que se combinan en gateway.controlUi.allowedOrigins en modo lan_https (ejemplo - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Desactivar emparejamiento por dispositivo en Control UI (lan_https)
+    description: "Cuando está ACTIVADO (recomendado), establece gateway.controlUi.dangerouslyDisableDeviceAuth=true para omitir la aprobación por dispositivo y evitar el error 1008 en modo LAN HTTPS. Déjalo ACTIVADO en redes domésticas/de confianza. Desactívalo solo si quieres emparejamiento estricto para cada navegador/dispositivo nuevo."
+
  gateway_bind_mode:
    name: Modo de enlace del Gateway
    description: "Modo de enlace de red: loopback (solo 127.0.0.1, más seguro), lan (todas las interfaces) o tailnet (solo interfaz Tailscale). Se anula con las preselecciones del modo de acceso."
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Variables de entorno del Gateway
    description: Variables de entorno que se pasan al proceso del gateway OpenClaw al iniciarse (lista de entradas name/value en la UI de Home Assistant; maximo 50 variables, claves de hasta 255 caracteres, valores de hasta 10 000 caracteres).
+  auto_configure_mcp:
+    name: Configurar MCP automáticamente para Home Assistant
+    description: "Cuando está ACTIVADO y el token de Home Assistant está configurado, registra automáticamente Home Assistant como servidor MCP en cada inicio. Esto permite a OpenClaw controlar entidades, servicios y automatizaciones de HA mediante el Model Context Protocol. Desactive solo si administra la configuración de mcporter manualmente."
@@ -42,7 +42,27 @@ 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
+    description: Adres WebSocket zdalnego gateway używany gdy Gateway Mode = Remote (przykład - ws://192.168.1.20:18789 lub wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Dodatkowe dozwolone origins
+    description: Dodatkowe origins Control UI rozdzielone przecinkami; łączone z gateway.controlUi.allowedOrigins w trybie lan_https (przykład - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Wyłącz parowanie urządzeń Control UI (lan_https)
+    description: "Gdy WŁĄCZONE (zalecane), ustawia gateway.controlUi.dangerouslyDisableDeviceAuth=true, pomija akceptację per-urządzenie i zapobiega błędowi 1008 w trybie LAN HTTPS. Zostaw WŁĄCZONE w domowej/zaufanej sieci. Wyłącz tylko jeśli chcesz ścisłe parowanie dla każdej nowej przeglądarki/urządzenia."
+
  gateway_bind_mode:
    name: Tryb bindowania Gateway
    description: Tryb bindowania sieci - loopback (tylko 127.0.0.1, najbezpieczniejszy), lan (wszystkie interfejsy) lub tailnet (tylko interfejs Tailscale). Nadpisywane przez ustawienia trybu dostępu.
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Zmienne środowiskowe gateway
    description: Zmienne środowiskowe przekazywane do procesu gateway OpenClaw podczas uruchamiania (lista wpisow name/value w UI Home Assistant; maks. 50 zmiennych, klucze do 255 znakow, wartosci do 10000 znakow).
+  auto_configure_mcp:
+    name: Automatyczna konfiguracja MCP dla Home Assistant
+    description: "Gdy WŁĄCZONE i token Home Assistant jest ustawiony, automatycznie rejestruje Home Assistant jako serwer MCP przy każdym starcie. Pozwala to OpenClaw kontrolować urządzenia HA, usługi i automatyzacje przez Model Context Protocol. Wyłącz tylko jeśli zarządzasz konfiguracją mcporter ręcznie."
@@ -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
@@ -50,6 +58,18 @@ configuration:
      local: "Local (recomendado)"
      remote: "Remoto"

+  gateway_remote_url:
+    name: URL do Gateway Remoto
+    description: URL WebSocket do gateway remoto usada quando Gateway Mode está em Remote (exemplo - ws://192.168.1.20:18789 ou wss://gateway.example.com:443)
+
+  gateway_additional_allowed_origins:
+    name: Origens permitidas adicionais
+    description: Origens extras da Control UI separadas por vírgula, mescladas em gateway.controlUi.allowedOrigins no modo lan_https (exemplo - https://ha.example.com:8443,capacitor://localhost)
+
+  controlui_disable_device_auth:
+    name: Desativar pareamento por dispositivo no Control UI (lan_https)
+    description: "Quando LIGADO (recomendado), define gateway.controlUi.dangerouslyDisableDeviceAuth=true para pular aprovação por dispositivo e evitar erro 1008 no modo LAN HTTPS. Mantenha LIGADO em rede doméstica/confiável. Desligue apenas se quiser pareamento estrito para cada novo navegador/dispositivo."
+
  gateway_bind_mode:
    name: Modo de Vinculação do Gateway
    description: Modo de vinculação de rede - loopback (somente 127.0.0.1, mais seguro), lan (todas as interfaces) ou tailnet (somente interface Tailscale). Substituído pelas predefinições do modo de acesso.
@@ -98,3 +118,6 @@ configuration:
  gateway_env_vars:
    name: Variáveis de Ambiente do Gateway
    description: Variaveis de ambiente passadas para o processo do gateway OpenClaw na inicializacao (lista de entradas name/value na UI do Home Assistant; maximo de 50 variaveis, chaves com ate 255 caracteres, valores com ate 10.000 caracteres).
+  auto_configure_mcp:
+    name: Configurar MCP automaticamente para o Home Assistant
+    description: "Quando LIGADO e o token do Home Assistant estiver definido, registra automaticamente o Home Assistant como servidor MCP a cada inicialização. Isso permite que o OpenClaw controle entidades, serviços e automações do HA via Model Context Protocol. Desative apenas se você gerencia a configuração do mcporter manualmente."
Author	SHA1	Message	Date
TechArtDevandroot	b0a0cc3f23	fix: correct bundled OpenClaw version for 0.5.87 Co-authored-by: root <root@0bfc167e-openclaw-assistant.local.hass.io>	2026-08-11 15:32:12 +03:00
TechArtDev	00df877305	Merge pull request #167 from techartdev/bot/openclaw-bump-2026.7.1-2 Bump OpenClaw to 2026.7.1-2	2026-08-10 14:38:47 +03:00
root	a037d8311b	Bump OpenClaw to 2026.7.1-2 (add-on 0.5.86)	2026-08-10 09:00:46 +03:00
PapurHa	beb59e8eb6	Merge pull request #166 from techartdev/bot/openclaw-bump-2026.7.1-2	2026-07-21 15:07:59 +03:00
PapurHa	a6af4b78ac	docs(changelog): add 0.5.85 release note	2026-07-21 15:07:33 +03:00
root	f658885c59	Bump OpenClaw to 2026.7.1-2 (add-on 0.5.85)	2026-07-21 09:00:43 +03:00
TechArtDev	ceb9522648	Merge pull request #164 from techartdev/fix/issue-163-mcporter-auto-config fix(addon): bundle mcporter for HA MCP auto-config	2026-07-17 16:52:47 +03:00
TechArtDev	ca2c7cab82	Merge origin/main into fix/issue-163-mcporter-auto-config	2026-07-17 16:51:51 +03:00
TechArtDev	99be0ed6e6	chore(release): 0.5.83	2026-07-17 16:45:27 +03:00
TechArtDev	ec825fa8c5	Merge pull request #165 from techartdev/chore/node24-addon-runtime chore(build): bump add-on runtime to Node 24	2026-07-17 16:43:36 +03:00
root	971e4bc8e0	chore(build): bump add-on runtime to Node 24	2026-07-17 00:34:09 +03:00
root	c3a926299f	fix(addon): bundle mcporter for HA MCP auto-config	2026-07-17 00:19:13 +03:00
root	883f5b8778	Merge pull request #162 from techartdev/fix/issues-159-150-release	2026-07-17 00:12:08 +03:00
root	7608357297	fix(addon): repair runtime downgrade and lan certs	2026-07-15 13:08:13 +03:00
TechArtDev	9235903ef2	Merge pull request #161 from techartdev/bot/openclaw-bump-2026.7.1 Bump OpenClaw to 2026.7.1	2026-07-14 18:14:19 +03:00
root	d5f3831131	Bump OpenClaw to 2026.7.1 (add-on 0.5.81)	2026-07-14 09:00:42 +03:00
TechArtDev	b45e665bca	Merge pull request #157 from techartdev/bot/openclaw-bump-2026.6.10 Bump OpenClaw to 2026.6.10	2026-06-26 17:51:42 +03:00
root	0b799f5fb1	Bump OpenClaw to 2026.6.10 (add-on 0.5.80)	2026-06-26 09:00:44 +03:00
TechArtDev	6129b62512	Merge pull request #156 from techartdev/bot/openclaw-bump-2026.6.9 Bump OpenClaw to 2026.6.9	2026-06-24 00:48:22 +03:00
root	fe082864ec	Bump OpenClaw to 2026.6.9 (add-on 0.5.79)	2026-06-23 09:00:40 +03:00
TechArtDev	4d8fa8996a	Merge pull request #153 from techartdev/bot/openclaw-bump-2026.6.6 Bump OpenClaw to 2026.6.6	2026-06-16 23:54:44 +03:00
root	45d4066d2a	Bump OpenClaw to 2026.6.6 (add-on 0.5.78)	2026-06-16 09:00:32 +03:00
TechArtDev	28574b28ef	Merge pull request #149 from techartdev/bot/openclaw-bump-2026.5.28 Bump OpenClaw to 2026.5.28	2026-05-31 10:50:08 +03:00
root	089594a95b	Bump OpenClaw to 2026.5.28 (add-on 0.5.77)	2026-05-31 09:00:39 +03:00
TechArtDev	08bc68b9e7	Merge pull request #148 from techartdev/bot/openclaw-bump-2026.5.27 Bump OpenClaw to 2026.5.27	2026-05-29 13:22:21 +03:00
TechArtDev	3a06c4604f	Merge branch 'main' into bot/openclaw-bump-2026.5.27	2026-05-29 13:22:09 +03:00
TechArtDev	661085afc3	Bump version to 0.5.76 in config.yaml	2026-05-29 13:21:32 +03:00
TechArtDev	ccde8598d7	Merge pull request #146 from techartdev/fix/backup-friendly-persistence-defaults fix(addon): make heavy tool persistence opt-in	2026-05-29 13:15:28 +03:00
root	80f86ae030	Bump OpenClaw to 2026.5.27 (add-on 0.5.75)	2026-05-29 09:01:20 +03:00
root	082c2c74b2	fix(addon): keep backups lean by default	2026-05-28 01:47:06 +03:00
TechArtDev	d070dbe1e1	Merge pull request #145 from techartdev/fix/issue-136-local-embeddings-addon fix(addon): bundle node-llama-cpp for local embeddings	2026-05-27 23:43:19 +03:00
root	9824f7c138	fix: bundle local embeddings runtime in addon	2026-05-27 23:28:33 +03:00
TechArtDev	71e3fbe410	Merge pull request #144 from techartdev/bot/openclaw-bump-2026.5.22 Bump OpenClaw to 2026.5.22	2026-05-26 14:11:23 +03:00
root	c2398c84a4	Bump OpenClaw to 2026.5.22 (add-on 0.5.73)	2026-05-26 09:00:38 +03:00
techartdev	3e5e0877b1	Bump OpenClaw to version 0.5.72 and add repair for known invalid config settings	2026-05-04 10:19:53 +03:00
TechArtDev	c769cb88e1	Merge pull request #127 from techartdev/bot/openclaw-bump-2026.5.2 Bump OpenClaw to 2026.5.2	2026-05-03 12:01:49 +03:00
root	865ca08873	Bump OpenClaw to 2026.5.2 (add-on 0.5.71)	2026-05-03 09:01:16 +03:00
TechArtDev	f0a465bf7c	Update OpenClaw to version 2026.4.27 Bump OpenClaw version to 2026.4.27.	2026-04-30 04:22:52 +03:00
TechArtDev	80ef635315	Merge pull request #124 from techartdev/bot/openclaw-bump-2026.4.26 Bump OpenClaw to 2026.4.26	2026-04-30 04:19:20 +03:00
TechArtDev	2acfc77a3f	Update OpenClaw version to 2026.4.27	2026-04-30 04:19:09 +03:00
root	91a2ddd01f	Bump OpenClaw to 2026.4.26 (add-on 0.5.70)	2026-04-29 09:01:24 +03:00
TechArtDev	f66c574611	Merge pull request #122 from techartdev/bot/openclaw-bump-2026.4.24 Bump OpenClaw to 2026.4.24	2026-04-27 14:33:27 +03:00
root	57a8bf3868	Bump OpenClaw to 2026.4.24 (add-on 0.5.69)	2026-04-27 09:01:16 +03:00
TechArtDev	2b6c875b0e	Merge pull request #121 from techartdev/bot/openclaw-bump-2026.4.22 Bump OpenClaw to 2026.4.22	2026-04-25 00:38:13 +03:00
root	ff5e1eba1e	Bump OpenClaw to 2026.4.22 (add-on 0.5.68)	2026-04-24 09:01:21 +03:00
TechArtDev	9a65e66b75	Merge pull request #116 from techartdev/bot/openclaw-bump-2026.4.12 Bump OpenClaw to 2026.4.12	2026-04-14 12:09:42 +03:00
root	9b7b701d5b	Bump OpenClaw to 2026.4.12 (add-on 0.5.67)	2026-04-14 09:00:41 +03:00
TechArtDev	505115e06f	Merge pull request #107 from techartdev/fix/landing-token-post-onboard fix: re-render landing page with gateway token after onboard (issue #102)	2026-04-04 16:17:54 +03:00
root	72495984ad	fix: re-render landing page with token after onboard (issue #102 ) On first boot the gateway token doesn't exist yet when nginx/landing are first rendered, so the 'Open Gateway Web UI' button opens the Control UI without a token and the user sees Unauthorized. Fix: extract render logic into render_landing(), call it once at startup (as before) and spawn a background poller that re-renders and HUPs nginx as soon as the token appears in openclaw.json — no add-on restart needed. Bumps add-on to 0.5.66.	2026-04-04 15:03:26 +03:00
TechArtDev	ba8fd59571	Merge pull request #106 from techartdev/bot/openclaw-bump-2026.4.2 chore: bump OpenClaw to 2026.4.2	2026-04-04 03:09:45 +03:00
root	dab02d2e22	chore: bump OpenClaw to 2026.4.2	2026-04-04 03:09:20 +03:00
techartdev	38e104d663	Merge branch 'main' of https://github.com/techartdev/OpenClawHomeAssistant	2026-03-18 14:21:27 +02:00
techartdev	991cc3bcfc	feat: enhance gateway daemon detection and restart handling	2026-03-18 14:21:19 +02:00
techartdev	1a4e23e8c3	feat: update version to 0.5.63 and bump OpenClaw to 2026.3.13	2026-03-14 20:14:44 +02:00
techartdev	4f56a16b91	feat: update version to 0.5.62 and fix gateway restart loop issues	2026-03-10 23:31:04 +02:00
techartdev	6a08c66128	feat: update version to 0.5.61 and fix gateway restart loop in tailnet mode	2026-03-10 23:05:32 +02:00
techartdev	02814db080	feat: update version to 0.5.60 and enhance session lock cleanup for non-default agents	2026-03-10 22:44:51 +02:00
techartdev	dd6b7eca6c	bump version	2026-03-10 21:13:24 +02:00
techartdev	c6232b6f5d	feat(mcp): add auto-configuration for Home Assistant and enhance documentation	2026-03-10 21:12:21 +02:00
TechArtDev	e6cad868ab	Merge pull request #92 from techartdev/bot/openclaw-bump-2026.3.7 Bump OpenClaw to 2026.3.7	2026-03-08 13:12:00 +02:00
root	8f91cdc23e	Bump OpenClaw to 2026.3.7 (add-on 0.5.58)	2026-03-08 09:00:08 +02:00
TechArtDev	04ffef8f9f	Merge pull request #91 from techartdev/fix/issue-89-nodesource-install-stability fix(build): stabilize NodeSource Node 22 install in Docker image	2026-03-07 15:39:09 +02:00
root	60fb692e7d	fix(build): address follow-up Copilot review on NodeSource step - remove NodeSource repo/key after Node install - avoid duplicate node -v call via NODE_VERSION variable	2026-03-07 15:38:45 +02:00
root	7d8f7d524d	fix(build): address Copilot review for NodeSource repo setup - ensure nodesource keyring is world-readable for _apt - assert installed Node major is v22 to avoid Debian Node 18 fallback	2026-03-07 14:48:50 +02:00
root	6707c4ed28	fix(build): make Node 22 install deterministic in Dockerfile - replace NodeSource setup_22.x pipe script with keyring + apt source - prevent intermittent apt exit 100 during nodejs install - bump add-on version to 0.5.57 Fixes #89	2026-03-07 12:44:46 +02:00
TechArtDev	2c5fa46572	Merge pull request #88 from techartdev/fix/issue-87-controlui-device-auth-toggle feat(addon): make lan_https device-auth toggle configurable	2026-03-07 12:32:21 +02:00
root	31656139c0	chore(release): bump add-on version to 0.5.56	2026-03-06 09:17:20 +02:00
root	3aaed98ac0	feat(addon): make lan_https device auth toggle configurable Fixes #87	2026-03-06 08:16:43 +02:00
TechArtDev	9259ce16a6	Merge pull request #85 from techartdev/bot/openclaw-bump-2026.3.2 Bump OpenClaw to 2026.3.2	2026-03-03 13:00:03 +02:00
root	206cf75889	Bump OpenClaw to 2026.3.2 (add-on 0.5.55)	2026-03-03 09:00:09 +02:00
TechArtDev	c0e83c3aac	Add image to README and update integration link	2026-02-25 23:38:54 +02:00
techartdev	45bad5f76b	Merge branch 'main' of https://github.com/techartdev/OpenClawHomeAssistant	2026-02-25 18:13:58 +02:00
techartdev	615ea2f1a4	agentic instructions and guidelines	2026-02-25 18:13:45 +02:00
TechArtDev	9181b4d22a	Add image and integration link to README Updated the README to include a new image and integration link.	2026-02-25 17:15:28 +02:00
techartdev	ab07454051	docs update	2026-02-25 16:34:07 +02:00
techartdev	a82df8c851	Update OpenClaw to 2026.2.24 and enhance gateway configuration options - Added `gateway_remote_url` and `gateway_additional_allowed_origins` options for improved remote gateway support. - Updated startup guidance for `gateway_auth_mode=trusted-proxy`. - Adjusted token retrieval instructions in the landing page. - Updated translations for new configuration options. - Fixed various issues related to gateway settings and TLS certificate generation.	2026-02-25 16:24:21 +02:00
techartdev	90607c867d	relocate release workflow	2026-02-24 17:44:36 +02:00