feat(mcp): add auto-configuration for Home Assistant and enhance documentation

DOCS.md

@@ -313,8 +313,7 @@ To provide the SSH key: place the private key file in the add-on config director
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `clean_session_locks_on_start` | bool | `true` | Remove stale session lock files on startup (safe — only removes locks when gateway isn't running) |
-| `clean_session_locks_on_exit` | bool | `true` | Remove session lock files on clean shutdown |
+| `clean_session_locks_on_exit` | bool | `true` | Remove session lock files on clean shutdown || `auto_configure_mcp` | bool | `false` | Auto-register Home Assistant as an MCP server on startup (requires `homeassistant_token`) |
-
 ---
 
 ## 6. Use Case Guides
@@ -480,6 +479,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 will automatically register Home Assistant as an MCP server named `HA` using `mcporter`. It auto-detects the HA API URL (supervisor proxy when available, otherwise `localhost:8123`). Check the logs for:
+```
+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` | Run `openclaw onboard` first, then restart the add-on |
+| 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

openclaw_assistant/CHANGELOG.md

@@ -2,7 +2,27 @@
 
 All notable changes to the OpenClaw Assistant Home Assistant Add-on will be documented in this file.
 
-## [Unreleased]
+## [0.5.59] - 2026-03-10
+
+### Fixed
+- **Gateway restart loop** (issue #95): when the agent or user ran `openclaw gateway restart`, the supervisor loop detected the old PID exiting and immediately spawned a second gateway instance, which collided with the already-restarted one and looped with "another gateway instance is already listening". The supervisor now detects a self-restart (new PID already running on the same port) and re-tracks it instead of spawning a duplicate.
+- **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.
+
+### 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.
@@ -12,11 +32,16 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu
 - `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`.
 
-### Fixed
+## [0.5.55] - 2026-03-04
-- 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.
+
+### Changed
+- Bump OpenClaw to 2026.3.2.
 
 ## [0.5.54] - 2026-02-25
 

openclaw_assistant/Dockerfile

@@ -114,7 +114,7 @@ USER root
 
 # Install OpenClaw globally
 RUN npm config set fund false && npm config set audit false \
- && npm install -g openclaw@2026.3.7
+    && npm install -g openclaw@2026.3.8
 
 # Shell aliases and color options for interactive use
 RUN tee -a /etc/bash.bashrc <<'EOF'

openclaw_assistant/config.yaml

@@ -133,6 +133,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
@@ -163,4 +168,4 @@ schema:
     - name: "match(^[A-Z_][A-Z0-9_]*$)"
       value: str
   nginx_log_level: list(full|minimal)?
-
+  auto_configure_mcp: bool?

openclaw_assistant/landing.html.tpl

@@ -116,6 +116,31 @@
     </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">

openclaw_assistant/run.sh

@@ -58,6 +58,7 @@ CONTROLUI_DISABLE_DEVICE_AUTH=$(jq -r '.controlui_disable_device_auth // true' "
 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")
@@ -453,6 +454,7 @@ EOF
 # Graceful shutdown handling (PID 1 trap) to reduce stale locks
 # ------------------------------------------------------------------------------
 GW_PID=""
+GW_RELAY_PID=""
 NGINX_PID=""
 TTYD_PID=""
 SHUTTING_DOWN="false"
@@ -476,6 +478,11 @@ shutdown() {
     wait "${GW_PID}" || true
   fi
 
+  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}" || true
+  fi
+
   if [ "$CLEAN_LOCKS_ON_EXIT" = "true" ]; then
     cleanup_session_locks || true
   fi
@@ -700,15 +707,61 @@ if [ -f /usr/local/lib/openclaw-proxy-shim.cjs ]; then
   export OPENCLAW_GLOBAL_NODE_MODULES
 fi
 
+# ------------------------------------------------------------------------------
+# 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 "INFO: mcporter not available; skipping MCP auto-configuration (run 'openclaw onboard' first)"
+  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.
-    REMOTE_URL="$(timeout 2s openclaw config get gateway.remote.url 2>/dev/null | tr -d '\n' || true)"
+    # 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 empty in openclaw config"
+      echo "ERROR: gateway_mode=remote but gateway_remote_url is not set in add-on options"
-      echo "ERROR: Configure gateway.remote.url first, then restart the add-on"
+      echo "ERROR: Set gateway_remote_url in add-on Configuration (e.g. ws://192.168.1.10:18789), then restart"
       return 1
     fi
 
@@ -748,6 +801,37 @@ if ! start_openclaw_runtime; then
   exit 1
 fi
 
+# --- Loopback relay 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.
+# A lightweight Node.js relay (loopback-only) forwards those connections
+# to the Tailscale IP so terminal CLI commands work normally.
+# Token auth is still enforced end-to-end by the gateway.
+if [ "$GATEWAY_BIND_MODE" = "tailnet" ]; then
+  TAILSCALE_IP=$(ip -4 addr show tailscale0 2>/dev/null \
+    | awk '/inet /{gsub(/\/.*/,"",$2); print $2; exit}' || true)
+  if [[ "${TAILSCALE_IP:-}" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "INFO: Starting loopback relay for tailnet gateway (127.0.0.1:${GATEWAY_PORT} -> ${TAILSCALE_IP}:${GATEWAY_PORT})"
+    node -e "
+const net = require('net');
+const TARGET_HOST = '${TAILSCALE_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
+fi
+
 # Start web terminal (optional)
 TTYD_PID_FILE="/var/run/openclaw-ttyd.pid"
 
@@ -868,6 +952,19 @@ while true; do
     break
   fi
 
+  # Detect agent/user-initiated self-restart (e.g. 'openclaw gateway restart').
+  # When the gateway restarts itself, the old PID exits but a new process immediately
+  # binds the same port. Without this check the supervisor would spawn a second
+  # instance, which fails with "already listening" and loops forever.
+  # Give the new process a moment to start, then re-track it instead of spawning a duplicate.
+  sleep 1
+  RESTARTED_PID=$(pgrep -f "openclaw.*(gateway|node).*run" 2>/dev/null | head -1 || true)
+  if [ -n "$RESTARTED_PID" ] && [ "$RESTARTED_PID" != "$GW_PID" ]; then
+    echo "INFO: OpenClaw runtime restarted itself (new PID $RESTARTED_PID); re-tracking."
+    GW_PID="$RESTARTED_PID"
+    continue
+  fi
+
   echo "WARN: OpenClaw runtime exited with code ${GW_EXIT_CODE}. Restarting in 2s..."
   sleep 2
 

openclaw_assistant/translations/bg.yaml

@@ -110,3 +110,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 конфигурацията ръчно."

openclaw_assistant/translations/de.yaml

@@ -110,3 +110,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."

openclaw_assistant/translations/en.yaml

@@ -110,3 +110,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."

openclaw_assistant/translations/es.yaml

@@ -110,3 +110,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."

openclaw_assistant/translations/pl.yaml

@@ -110,3 +110,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."

openclaw_assistant/translations/pt-BR.yaml

@@ -110,3 +110,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."