From 10bd4737f22ae99597b001e52ea9756a332776ae Mon Sep 17 00:00:00 2001
From: techartdev <admin@techart.bg>
Date: Wed, 25 Feb 2026 16:30:19 +0200
Subject: [PATCH] docs update

---
 DOCS.md | 1243 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 903 insertions(+), 340 deletions(-)

diff --git a/DOCS.md b/DOCS.md
index e850cf0..885c46d 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -1,400 +1,963 @@
-# OpenClaw Home Assistant Integration — Full Documentation
+# OpenClaw Assistant — Home Assistant Add-on Documentation
 
-This guide is a complete setup and usage manual for OpenClaw in Home Assistant.
+This add-on runs [OpenClaw](https://github.com/openclaw/openclaw) inside Home Assistant OS (HAOS). It provides a fully self-contained environment with a web terminal, gateway server, and all the tools OpenClaw needs — no manual Docker setup required.
 
+**Table of Contents**
 
-## 1) What this integration does
+1. [Architecture Overview](#1-architecture-overview)
+2. [Installation](#2-installation)
+3. [First-Time Setup](#3-first-time-setup)
+4. [Accessing the Gateway Web UI](#4-accessing-the-gateway-web-ui)
+5. [Configuration Reference](#5-configuration-reference)
+6. [Use Case Guides](#6-use-case-guides)
+7. [Data Persistence & Skills](#7-data-persistence--skills)
+8. [Bundled Tools](#8-bundled-tools)
+9. [Updating & Backup](#9-updating--backup)
+10. [Troubleshooting](#10-troubleshooting)
+11. [FAQ](#11-faq)
 
-OpenClaw connects Home Assistant to your OpenClaw Gateway and gives you:
-- A native **Assist conversation agent** (`openclaw`)
-- A built-in **chat card** for dashboards
-- **Voice input modes** (browser voice and Home Assistant STT)
-- **Automation services and events**
-- **Status and telemetry sensors**
+> **Important**: Before using this add-on, please read the [Security Risks & Disclaimer](SECURITY.md).
 
 ---
 
-## 2) Before you begin
+## 1. Architecture Overview
 
-## Required
-- Home Assistant Core **2025.1.0+**
-- OpenClaw Assistant addon installed and running, or standalone OpenClaw instance running and available over network
-- A valid gateway auth token/password configured in the OpenClaw addon
+### What runs inside the add-on
 
-## Recommended
-- HACS installed (for easiest updates)
-- Modern browser (Chrome/Edge/Firefox/Safari)
-- Microphone permission allowed in browser for your Home Assistant URL, if you want to use voice features
+The add-on container runs three services:
 
-## Important gateway setting
-OpenClaw’s OpenAI-compatible endpoint is required by this integration.
-In addon settings, confirm chat completions endpoint support is enabled (for your gateway version/settings model).
-If you run OpenClaw standalone set `gateway.http.endpoints.chatCompletions.enabled` to `true`
+| Service | Port | Purpose |
+|---|---|---|
+| **OpenClaw Gateway** | 18789 (configurable) | The AI agent server — handles skills, chat, automations |
+| **nginx** (Ingress proxy) | 48099 (fixed) | Serves the landing page inside Home Assistant |
+| **ttyd** (Web terminal) | 7681 (configurable) | Provides a browser-based terminal for setup and management |
 
-If this endpoint is disabled, chat and connection checks can fail even when the addon is running.
+When you open the add-on page in Home Assistant, nginx serves a landing page with:
+- An **Open Gateway Web UI** button (opens in a new tab to avoid WebSocket issues with Ingress)
+- An embedded **terminal** for running commands
+
+### Key directories
+
+| Path | Persistent? | Contents |
+|---|---|---|
+| `/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/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/gogcli/` | Yes | gog OAuth credentials for Google APIs |
+| `/usr/lib/node_modules/openclaw/` | No | OpenClaw installation (rebuilt with each image update) |
+
+> **Important**: Everything under `/config/` persists across add-on updates. The container filesystem (`/usr/`, `/opt/`, etc.) is rebuilt each time the image changes.
 
 ---
 
-## 3) Installation
+## 2. Installation
 
-## Option A — HACS (recommended)
-1. Open **HACS → Integrations**.
-2. Use the **⋮ menu** (top-right) → **Custom repositories**.
-3. Add repository URL: `https://github.com/techartdev/OpenClawHomeAssistantIntegration`
-4. Category: **Integration**.
-5. Install **OpenClaw**.
-6. Restart Home Assistant.
-7. Go to **Settings → Devices & Services → Add Integration**.
-8. Add **OpenClaw**.
+1. In Home Assistant, go to **Settings → Add-ons → Add-on store**
+2. Click ⋮ (top-right) → **Repositories** → paste one of:
+   - **Stable**: `https://github.com/techartdev/OpenClawHomeAssistant`
+   - **Dev/Experimental**: `https://github.com/techartdev/OpenClawHomeAssistant-dev`
+3. Find and install **OpenClaw Assistant**
+4. Click **Start**
 
-## Option B — Manual installation
-1. Copy `custom_components/openclaw` into your Home Assistant config folder.
-2. Restart Home Assistant.
-3. Add integration from **Settings → Devices & Services**.
+**Supported architectures**: amd64, aarch64 (Raspberry Pi 4/5), armv7
 
 ---
 
-## 4) Initial setup flow
+## 3. First-Time Setup
 
-When adding the integration, it attempts:
-1. **Auto-discovery** (if Supervisor/addon metadata is available)
-2. **Manual setup** fallback (host/port/token)
+### What happens on first boot
 
-If auto-discovery succeeds:
-- Confirm discovered host/port
-- Submit
+When the add-on starts for the first time, it automatically:
+1. Creates persistent directories under `/config/`
+2. Generates a minimal `openclaw.json` with a random gateway auth token
+3. Syncs built-in skills to persistent storage
+4. Starts the gateway, terminal, and nginx
 
-If manual setup is needed:
-- Enter gateway host
-- Enter gateway port
-- Enter auth token/password value expected by gateway
-- Enable SSL only if your gateway endpoint is HTTPS
+### Step 1 — Run onboarding
 
-After setup, Home Assistant creates OpenClaw entities and services automatically.
+Open the add-on page in Home Assistant. You'll see a landing page with an embedded terminal.
 
----
+In the terminal, run:
 
-## 5) Dashboard chat card
-
-The chat card is auto-registered by the integration. You can add it from dashboard card picker.
-
-### Card behavior
-- Restores chat history for active session
-- Shows typing/thinking indicator
-- Supports text and voice interactions
-- Shows gateway connection badge in header (`Online`, `Offline`, or `Unknown`)
-
-### Session behavior in the card
-- Card uses a session id (default session if not overridden)
-- Keep the same session id to continue conversations
-- Different session ids isolate conversations
-- You can add different chat cards on different dashboards and set different session id, this way you keep them as separate conversations
-
----
-
-## 6) Voice features (important)
-
-OpenClaw supports two voice input providers:
-
-## A) Browser voice provider
-- Uses browser speech recognition APIs, free and doesn't need voice integrations installed in HA
-- Supports:
-  - Manual mic capture
-  - Continuous voice mode
-  - Optional wake-word gating
-
-Best for users who want continuous conversational voice mode.
-
-## B) Home Assistant STT provider (`assist_stt`)
-- Uses Home Assistant STT pipeline endpoint
-- Designed for **manual** voice capture (press mic, speak, transcribe)
-- Requires an STT engine configured in Home Assistant Voice settings
-
-### Continuous mode + assist_stt
-If continuous voice mode is enabled while provider is `assist_stt`, the card uses browser speech for continuous listening.
-This is expected behavior in current architecture. Assist STT does not support continuous audio.
-
-### Wake word setting
-- `Wake word enabled` controls whether continuous mode requires wake phrase before sending recognized speech.
-- If disabled, continuous mode can send finalized recognized phrases directly.
-- Wake-word logic applies to continuous mode behavior, not manual one-shot mic usage.
-
-### Browser notes
-- Brave may produce speech backend errors depending on environment/policies.
-- Chrome/Edge are often more consistent for browser speech APIs.
-
----
-
-## 7) Integration options (Configure screen)
-
-Path: **Settings → Devices & Services → OpenClaw → Configure**
-
-### Context options
-- **Include exposed entities context**
-  - Adds context from entities exposed to voice assistant.
-- **Max context characters**
-  - Safety limit for injected context size.
-- **Context strategy**
-  - `truncate`: keep beginning up to max
-  - `clear`: drop context when too large
-
-### Tool-call option
-- **Enable tool calls (execute services)**
-  - Allows supported tool-call responses to execute Home Assistant services.
-  - Keep disabled if you prefer read-only assistant behavior.
-
-### Voice options
-- **Wake word enabled**
-- **Wake word**
-- **Allow Web Speech in Brave (experimental)** (currently may not work, but voice support in Brave is expected in future)
-- **Voice input provider** (`browser` or `assist_stt`)
-
-Note: Legacy always-on voice option is removed.
-
----
-
-## 8) Home Assistant Assist integration
-
-OpenClaw registers as a native Assist conversation agent. This means that you can select OpenClaw as agent in the HA Assist feature and the Assist dialog.
-
-To use:
-1. Open Voice Assistants settings.
-2. Select OpenClaw as the conversation agent where desired.
-3. Ensure exposed entities and pipeline language settings are configured as expected.
-
-If responses are unexpected:
-- Check selected conversation agent
-- Check exposed entities list
-- Confirm pipeline STT/TTS language settings
-
----
-
-## 9) Services you can use in automations
-
-## `openclaw.send_message`
-Use this to send text to OpenClaw from scripts/automations.
-
-Use cases:
-- Trigger assistant checks on schedule
-- Ask model to summarize state
-- Start guided routines
-
-Automation example (scheduled morning summary):
-
-```yaml
-alias: OpenClaw Morning Summary
-trigger:
-  - platform: time
-    at: "08:00:00"
-action:
-  - service: openclaw.send_message
-    data:
-      message: "Give me a short morning summary for home status and weather."
-      session_id: "daily-briefing"
-mode: single
+```sh
+openclaw onboard
 ```
 
-## `openclaw.clear_history`
-Clears stored integration-side history for a specific session (or default/all depending call).
+This interactive wizard walks you through connecting your AI providers (OpenAI, Google, Anthropic, etc.) and basic configuration.
 
-Use cases:
-- Reset context for new workflow
-- Recover from stale context
+> **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.
 
-Automation example (clear context every night):
+Alternatively, for more granular control:
 
-```yaml
-alias: OpenClaw Clear Night Session
-trigger:
-  - platform: time
-    at: "23:59:00"
-action:
-  - service: openclaw.clear_history
-    data:
-      session_id: "daily-briefing"
-mode: single
+```sh
+openclaw configure
 ```
 
-## `openclaw.invoke_tool`
-Directly invokes one OpenClaw gateway tool through `/tools/invoke`.
+### Step 2 — Get your Gateway token
 
-Typical fields in UI:
-- Tool name
-- Action
-- Args object
-- Session key
-- Optional channel/account routing hints
+The gateway requires a token for authentication. To retrieve it:
 
-Use cases:
-- Admin/diagnostic tool calls
-- Session list retrieval
-- Controlled operations exposed by gateway policy
-
-Automation example (diagnostic sessions list on startup):
-
-```yaml
-alias: OpenClaw Sessions Diagnostic On Start
-trigger:
-  - platform: homeassistant
-    event: start
-action:
-  - service: openclaw.invoke_tool
-    data:
-      tool: sessions_list
-      action: json
-      args: {}
-      session_key: main
-mode: single
+```sh
+jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json
 ```
 
-Security note:
-Tool availability is still controlled by gateway policy and deny-lists.
+> **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
+   ```
+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.
 
 ---
 
-## 10) Events for automations
+## 4. Accessing the Gateway Web UI
 
-## `openclaw_message_received`
-Fires when OpenClaw sends a response.
+The Gateway Web UI (Control UI) is OpenClaw's main web interface. It opens in a **separate browser tab** because Home Assistant's Ingress proxy has WebSocket limitations.
 
-Useful for:
-- Notifications
-- Logging
-- Chained automations
+> **Important (v2026.2.21+):** OpenClaw now requires a **secure context** (HTTPS or localhost) for the Control UI. Plain HTTP over LAN is no longer accepted. The add-on's `access_mode` option makes this easy — see below.
+>
+> **v2026.2.22 note:** The gateway now emits a startup security warning when `dangerouslyDisableDeviceAuth` is active (used by `lan_https` mode). This warning is **expected and safe to ignore** — token authentication is still enforced.
 
-Automation example (notify on every assistant reply):
+### Choosing an access mode
 
-```yaml
-alias: OpenClaw Reply Notification
-trigger:
-  - platform: event
-    event_type: openclaw_message_received
-action:
-  - service: notify.mobile_app_my_phone
-    data:
-      message: "OpenClaw: {{ trigger.event.data.message }}"
-mode: queued
+Set `access_mode` in **Settings → Add-ons → OpenClaw Assistant → Configuration**:
+
+| Mode | Best for | What it does |
+|---|---|---|
+| **`lan_https`** | Phones, tablets, LAN browsers | Adds a built-in HTTPS proxy inside the add-on. No external setup needed. |
+| **`lan_reverse_proxy`** | Users with NPM / Caddy / Traefik | Binds gateway to LAN; your proxy terminates TLS. |
+| **`tailnet_https`** | Tailscale users | Binds to Tailscale interface; use Tailscale HTTPS certs. |
+| **`local_only`** | Terminal/Ingress only | Loopback — gateway not reachable from other devices. |
+| **`custom`** | Advanced / backward compat | Uses the individual `gateway_bind_mode` / `gateway_auth_mode` settings. |
+
+### Method A — Built-in HTTPS proxy (`lan_https` — recommended)
+
+This is the simplest way to get secure LAN access, especially for phones and tablets.
+
+1. Go to **Settings → Add-ons → OpenClaw Assistant → Configuration**
+2. Set `access_mode`: **lan_https**
+3. Restart the add-on
+
+**What happens automatically:**
+- The add-on generates a local CA certificate and a TLS server certificate
+- nginx listens on the gateway port (default 18789) with HTTPS on all interfaces
+- The gateway process itself binds to loopback on an internal port (gateway_port + 1)
+- The landing page shows a **Download CA Certificate** button
+
+**Phone/tablet setup (one-time):**
+1. Open the add-on page in HA and click **Download CA Certificate**
+2. Install the certificate on your device:
+   - **Android**: Settings → Security → Install certificate → CA certificate → select file
+   - **iOS**: Open the `.crt` file → Install Profile → Settings → General → About → Certificate Trust Settings → enable the OpenClaw CA
+3. After installing the CA, your browser will trust the gateway without warnings
+
+> **Note**: If you skip CA installation, you can still access the gateway — just accept the browser's certificate warning once.
+
+### Method B — HTTPS via external reverse proxy (tested recipe: NPM)
+
+Use this when you already run Nginx Proxy Manager (or Caddy/Traefik).
+
+**OpenClaw add-on settings**
+1. Set `access_mode`: **lan_reverse_proxy**
+2. Set `gateway_trusted_proxies` to your proxy source CIDR/IP.
+   - Example for NPM add-on network: `172.30.0.0/16`
+   - Or strict single IP: `172.30.x.y/32`
+3. Set `gateway_public_url` to your final HTTPS URL (example: `https://openclaw.example.com`)
+4. Restart OpenClaw add-on
+
+**NPM host config (known-good pattern)**
+1. Create Proxy Host: `openclaw.example.com`
+2. Forward to: `http://<HA-LAN-IP>:18789`
+3. Enable **Websockets Support**
+4. SSL tab: request/attach certificate, enable **Force SSL**
+5. Add custom header for trusted-proxy auth:
+   - `X-Forwarded-User: openclaw`
+
+Then open `https://openclaw.example.com`.
+
+> **Important**: Nabu Casa remote access only proxies port 8123. It does not expose custom add-on ports directly.
+
+### Method C — SSH port forwarding (secure, no config changes)
+
+Forward the gateway port from your HA host to your local machine:
+
+```sh
+ssh -L 18789:127.0.0.1:18789 your-user@your-ha-ip
 ```
 
-## `openclaw_tool_invoked`
-Fires after `openclaw.invoke_tool` completes.
+Then open `http://localhost:18789` in your browser. `localhost` counts as a secure context.
 
-Includes success/failure metadata and timing info, useful for:
-- Alerting on failed tool runs
-- Telemetry dashboards
-- Automation branching based on `ok/error`
+> **Limitation**: SSH forwarding doesn't work on phones/tablets. Use `lan_https` for mobile access.
 
-Automation example (alert on tool failure):
+### Method D — Tailnet flow (tested with HA Tailscale add-on + NPM)
 
+This is the practical flow users report as stable in HAOS.
+
+1. In **Tailscale add-on**:
+   - Disable `userspace_networking` (must be `false` so other add-ons can reach tailnet interface)
+2. In **OpenClaw add-on**:
+   - Preferred: set `access_mode` to **tailnet_https**
+   - Alternative (equivalent): `gateway_bind_mode: tailnet`, token auth
+3. In **NPM**:
+   - Forward target to `http://<HA-TAILNET-IP>:18789`
+   - Enable websockets
+   - Configure TLS cert on the public host
+4. Set `gateway_public_url` to the final HTTPS URL and restart OpenClaw
+
+> **Why this flow**: `tailnet_https` in this add-on is a bind/auth preset. It does not automatically run `tailscale serve` inside OpenClaw.
+
+### Setting up the "Open Gateway Web UI" button
+
+Set `gateway_public_url` in the add-on configuration to the URL where the gateway is reachable from your browser.
+
+**Examples**:
+- LAN HTTPS (built-in): `https://192.168.1.119:18789`
+- External HTTPS: `https://openclaw.example.com`
+- Tailscale: `https://ha-machine.ts.net:18789`
+
+> **Tip**: In `lan_https` mode, if you leave `gateway_public_url` empty, the add-on auto-constructs it from the detected LAN IP.
+
+### Browser security: "requires HTTPS or localhost"
+
+If you see:
+
+> control ui requires HTTPS or localhost (secure context)
+> disconnected (1008): control ui requires device identity
+
+This means the browser is connecting over plain HTTP. **Solutions**:
+- Set `access_mode` to **lan_https** (easiest — no external setup)
+- Set `access_mode` to **lan_reverse_proxy** and use an HTTPS reverse proxy
+- Use SSH port forwarding to `localhost` (desktop only)
+
+### Unauthorized error
+
+If the Gateway UI shows **Unauthorized**, re-check your token:
+
+```sh
+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
+
+All options are set via **Settings → Apps/Add-ons → OpenClaw Assistant → Configuration** in Home Assistant. They are applied automatically on each add-on restart.
+
+### General
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timezone` | string | `Europe/Sofia` | Timezone for the add-on (e.g., `America/New_York`, `Europe/London`) |
+
+### Gateway
+
+| 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`. 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`. |
+| `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`). |
+| `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 |
+|---|---|---|---|
+| `enable_terminal` | bool | `true` | Show the web terminal on the add-on page |
+| `terminal_port` | int | `7681` | Port for the terminal (ttyd). Change if 7681 conflicts. Range: 1024-65535 |
+
+### Security & Tokens
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `homeassistant_token` | string | _(empty)_ | Optional HA long-lived access token (use at own risk, can be very unsecure but very powerful). Saved to `/config/secrets/homeassistant.token` for use by scripts/skills |
+| `http_proxy` | string | _(empty)_ | Optional outbound proxy URL for HTTP/HTTPS requests from OpenClaw and Node tools. Example: `http://192.168.2.1:3128` |
+
+### Router SSH
+
+For skills or scripts that need SSH access to a router, firewall, or other network device:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `router_ssh_host` | string | _(empty)_ | Hostname or IP of the SSH target |
+| `router_ssh_user` | string | _(empty)_ | SSH username |
+| `router_ssh_key_path` | string | `/data/keys/router_ssh` | Path to the private key inside the container |
+
+To provide the SSH key: place the private key file in the add-on config directory so it appears at the configured path inside the container. Set permissions: `chmod 600`. (use at own risk, can be very unsecure but very powerful)
+
+### Maintenance
+
+| 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 |
+
+---
+
+## 6. Use Case Guides
+
+### 6a. LAN Access Setup
+
+This is the most common setup — accessing the Gateway Web UI from a browser on your local network (including phones and tablets).
+
+> **Since OpenClaw v2026.2.21**, the Control UI requires a secure context (HTTPS or localhost). Use the `access_mode` option for easy setup.
+
+#### Option 1 — Built-in HTTPS proxy (recommended)
+
+1. Go to **Settings → Add-ons → OpenClaw Assistant → Configuration**
+2. Set `access_mode`: **lan_https**
+3. Restart the add-on
+4. Click the **Open Gateway Web UI** button — it uses HTTPS automatically
+
+**Phone/tablet (one-time):** Click **Download CA Certificate** on the landing page, then install it on your device for trusted access without browser warnings.
+
+#### Option 2 — External reverse proxy
+
+1. Go to **Settings → Add-ons → OpenClaw Assistant → Configuration**
+2. Set these options:
+
+| Option | Value |
+|---|---|
+| `access_mode` | **lan_reverse_proxy** |
+| `gateway_trusted_proxies` | **127.0.0.1,192.168.88.0/24** |
+| `gateway_public_url` | `https://<your-domain>` |
+
+3. Configure your reverse proxy to forward HTTPS to `<HA-IP>:18789`
+4. Restart the add-on
+
+**Security note**: Always use HTTPS for Control UI access. The `lan_https` mode handles this automatically; for reverse proxy setups, ensure your proxy terminates TLS.
+
+### 6b. Remote Gateway Mode
+
+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. 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
+
+### 6c. Assist Pipeline Integration (OpenAI API)
+
+OpenClaw's Gateway exposes an **OpenAI-compatible Chat Completions endpoint** (`POST /v1/chat/completions`). This lets you use OpenClaw as a **conversation agent** in Home Assistant's Assist pipeline — enabling voice control, automations, and smart home commands.
+
+There are two ways to connect it to Home Assistant:
+
+---
+
+#### Option 1 — OpenClaw Integration (recommended)
+
+The **native OpenClaw integration** provides auto-discovery, a Lovelace chat card, voice mode, tool invocation services, and status sensors — all in one package.
+
+**Step 1 — Enable the endpoint**
+
+In the add-on configuration, set `enable_openai_api`: **true**, then restart.
+
+Or via terminal:
+```sh
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+```
+
+**Step 2 — Install the OpenClaw integration**
+
+Via HACS:
+1. In HACS, add as a custom repository:
+   - Repository: `https://github.com/techartdev/OpenClawHomeAssistantIntegration`
+   - Category: **Integration**
+2. Install and restart Home Assistant
+
+Or manually: copy `custom_components/openclaw` from the repo into your HA config directory.
+
+**Step 3 — Add the integration**
+
+1. Go to **Settings → Devices & Services → Add Integration**
+2. Search for **OpenClaw**
+3. If the addon is running locally, it will be **auto-discovered** — just click Submit
+4. If connecting to a remote instance, fill in host, port, token, and SSL settings manually
+
+> **`lan_https` mode**: The integration auto-detects this and connects to the internal gateway port on loopback — no certificate setup needed for local addons.
+
+**Step 4 — Set as conversation agent**
+
+1. Go to **Settings → Voice Assistants**
+2. Edit your assistant (or create a new one)
+3. Under **Conversation agent**, select **OpenClaw**
+
+**Step 5 — Expose entities**
+
+Go to **Settings → Voice Assistants → Expose** and toggle on the entities you want OpenClaw to control.
+
+**Step 6 — Add the chat card (optional)**
+
+The integration auto-registers a Lovelace card. Add it to any dashboard:
 ```yaml
-alias: OpenClaw Tool Failure Alert
-trigger:
-  - platform: event
-    event_type: openclaw_tool_invoked
-condition:
-  - condition: template
-    value_template: "{{ trigger.event.data.ok == false }}"
-action:
-  - service: persistent_notification.create
-    data:
-      title: "OpenClaw Tool Failed"
-      message: >-
-        Tool: {{ trigger.event.data.tool }}
-        Error: {{ trigger.event.data.error }}
-        Duration: {{ trigger.event.data.duration_ms }} ms
-mode: queued
+type: custom:openclaw-chat-card
+```
+
+The card includes message history, typing indicator, voice input, wake-word support, and TTS responses.
+
+> **Works with standalone OpenClaw too.** The integration doesn't require the HA addon — it connects to any reachable OpenClaw gateway over HTTP/HTTPS. See the [integration README](https://github.com/techartdev/OpenClawHomeAssistantIntegration) for remote connection details.
+
+---
+
+#### Option 2 — Extended OpenAI Conversation (alternative)
+
+If you prefer to use the [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation) integration instead:
+
+**Prerequisites:**
+- [HACS](https://hacs.xyz/) installed on your Home Assistant
+
+**Step 1 — Enable the endpoint**
+
+In the add-on configuration, set `enable_openai_api`: **true**, then restart.
+
+Or via terminal:
+```sh
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+```
+
+**Step 2 — Install Extended OpenAI Conversation**
+
+1. In HACS, add as a custom repository:
+   - Repository: `https://github.com/jekalmin/extended_openai_conversation`
+   - Category: **Integration**
+2. Install and restart Home Assistant
+
+**Step 3 — Configure the integration**
+
+1. Go to **Settings → Devices & Services → Add Integration**
+2. Search for **Extended OpenAI Conversation**
+3. Configure:
+   - **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
+   - **Skip Authentication**: **true**
+
+> If using `gateway_bind_mode: lan`, you can also use `http://<your-ha-ip>:18789/v1` — this allows other HA instances on your network to connect too.
+
+**Step 4 — Set as conversation agent**
+
+1. Go to **Settings → Voice Assistants**
+2. Edit your assistant (or create a new one)
+3. Under **Conversation agent**, select **Extended OpenAI Conversation**
+
+**Step 5 — Expose entities**
+
+Go to **Settings → Voice Assistants → Expose** and toggle on the entities you want OpenClaw to control.
+
+You can now use Assist (voice or text) and OpenClaw will handle conversations, control devices, answer questions, and create automations.
+
+### 6d. Browser Automation (Chromium)
+
+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.
+
+To enable it, add to `/config/.openclaw/openclaw.json`:
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+> **Note**: `noSandbox` is required inside Docker containers due to security namespace restrictions.
+
+### 6e. Router / Network Device SSH
+
+If you have skills or scripts that need SSH access to a router, firewall, or other network device:
+
+1. Generate an SSH key pair (if you don't have one):
+   ```sh
+   ssh-keygen -t ed25519 -f /config/keys/router_ssh -N ""
+   ```
+2. Copy the public key to your router:
+   ```sh
+   cat /config/keys/router_ssh.pub
+   ```
+   Add it to the router's authorized keys.
+3. Configure the add-on options:
+   - `router_ssh_host`: your router's IP (e.g., `192.168.1.1`)
+   - `router_ssh_user`: SSH username (e.g., `admin`)
+   - `router_ssh_key_path`: `/config/keys/router_ssh` (or wherever you saved it)
+4. Test from the terminal:
+   ```sh
+   ssh -i /config/keys/router_ssh admin@192.168.1.1
+   ```
+
+The connection details are also saved to `/config/CONNECTION_NOTES.txt` for reference by scripts.
+
+### 6f. Google Sheets / Google APIs (gog OAuth)
+
+Some OpenClaw skills use [gog](https://github.com/deftdawg/gog) to interact with Google APIs (Sheets, Drive, etc.). Because the add-on runs inside a container, the standard browser-based OAuth flow won't work — the localhost redirect can't reach your PC. Use the **manual** flow instead.
+
+#### Step 1 — Prepare OAuth credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) → **APIs & Services → Credentials**
+2. Create an **OAuth 2.0 Client ID** (type: **Web application**) or use an existing one
+3. In the client's **Authorized redirect URIs**, add: `http://localhost:1`
+4. Download the client JSON file and copy it into the add-on:
+   ```sh
+   # From your PC, copy the file to the HA config directory
+   # Then in the add-on terminal:
+   mkdir -p /config/secrets
+   # Place the downloaded JSON as:
+   /config/secrets/gmail_oauth_client.json
+   ```
+
+#### Step 2 — Register credentials with gog
+
+```sh
+gog auth credentials /config/secrets/gmail_oauth_client.json
+```
+
+This tells gog where to find your OAuth client configuration.
+
+#### Step 3 — Authorize with `--manual`
+
+```sh
+gog auth add your-email@gmail.com --services sheets --manual
+```
+
+The `--manual` flag avoids the localhost redirect problem. gog will:
+
+1. Print an authorization URL — **open it in your PC's browser**
+2. Sign in with your Google account and grant access
+3. You'll be redirected to a URL starting with `http://localhost:1?...` — the page will fail to load, **that's expected**
+4. **Copy the full URL** from your browser's address bar
+5. Paste it back into the add-on terminal when prompted
+6. If prompted for a **passphrase**, enter one to encrypt the stored token (remember it — you'll need it if gog asks again)
+
+#### Step 4 — Verify
+
+```sh
+gog auth list
+```
+
+You should see your account listed with the `sheets` service.
+
+> **Why `--manual`?** The default OAuth flow starts a temporary HTTP server on localhost to receive the callback. Since the add-on runs on your HA device (not your PC), the browser redirect to `localhost` can't reach the add-on's server. The `--manual` flag skips the local server and lets you paste the redirect URL directly.
+
+> **Persistence**: gog stores credentials under `/config/gogcli/` which is persistent storage — your auth survives add-on updates.
+
+---
+
+## 7. Data Persistence & Skills
+
+### What persists across add-on updates
+
+| Data | Location | Persists? |
+|---|---|---|
+| OpenClaw config | `/config/.openclaw/openclaw.json` | Yes |
+| 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 |
+| SSH keys | `/config/keys/` | Yes |
+| Tokens | `/config/secrets/` | Yes |
+| Homebrew & brew-installed tools | `/config/.linuxbrew/` | Yes (synced on startup) |
+| 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 |
+
+### How built-in skills work
+
+OpenClaw ships with premade skills (e.g., web search, file management). On each startup, the add-on:
+
+1. Copies built-in skills from the image to `/config/.openclaw/skills/`
+2. Creates a symlink from the image path back to persistent storage
+3. On subsequent boots, only newer files are synced (existing files are preserved)
+
+This means built-in skills survive image rebuilds, and any customizations you make to skill files are preserved.
+
+### 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.
+
+The add-on also configures `pnpm` global directory to persistent storage at `/config/.node_global/pnpm/`.
+
+### 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:
+
+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.
+
+---
+
+## 8. Bundled Tools
+
+The add-on image includes these tools, available in the terminal:
+
+| Tool | Command | Notes |
+|---|---|---|
+| Git | `git` | Version control |
+| Vim | `vim` | Text editor |
+| Nano | `nano` | Text editor (beginner-friendly) |
+| bat | `bat` (alias for `batcat`) | Syntax-highlighted `cat` |
+| fd | `fd` (alias for `fdfind`) | Fast file finder |
+| ripgrep | `rg` | Fast text search |
+| curl | `curl` | HTTP client |
+| jq | `jq` | JSON processor |
+| Python 3 | `python3` | Scripting |
+| Node.js 22 | `node` | JavaScript runtime |
+| npm | `npm` | Node package manager |
+| pnpm | `pnpm` | Fast Node package manager |
+| Homebrew | `brew` | Package manager (optional — may not be available on all CPUs) |
+| Chromium | `chromium` | Headless browser for automation |
+| SSH | `ssh` | Remote access |
+| oc-cleanup | `oc-cleanup` | Interactive disk space monitor & cache cleanup helper |
+
+### oc-cleanup
+
+Run `oc-cleanup` from the add-on terminal to see an overview of disk usage and
+selectively clear caches that accumulate over time:
+
+```
+$ oc-cleanup
+```
+
+The tool displays:
+
+- **Disk usage** — total, used, available, and percentage for the overlay filesystem.
+- **Cache sizes** — npm global cache, pnpm content store, OpenClaw data, Homebrew cellar, workspace, Python `__pycache__`, and `/tmp`.
+- **Cleanup menu** — choose which caches to purge (npm, pnpm, pycache, tmp, all at once).
+
+> **Note:** The add-on cannot prune Docker images directly. If disk space is
+> critically low due to old Docker layers, SSH into the host and run
+> `docker image prune -a` or `docker system prune`.
+
+---
+
+## 9. Updating & Backup
+
+### Updating the add-on
+
+Home Assistant checks for add-on updates automatically. When an update is available:
+
+1. Go to **Settings → Add-ons → OpenClaw Assistant**
+2. Click **Update**
+3. The add-on will rebuild with the new image
+
+**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/`)
+- The OpenClaw binary is updated to the version in the new image
+
+### Checking your version
+
+The add-on version is shown on the add-on page in Home Assistant. To check the OpenClaw version:
+
+```sh
+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.
+
+**To create a backup**: Go to **Settings → System → Backups → Create Backup**
+
+**Manual backup** (from the terminal):
+```sh
+# Key paths to back up:
+# /config/.openclaw/     - OpenClaw config, skills, agent data
+# /config/clawd/         - ClawHub workspace
+# /config/.node_global/  - User-installed npm skills
+# /config/keys/          - SSH keys
+# /config/secrets/       - Tokens
+```
+
+### Factory reset
+
+To reset the add-on to a clean state, remove the persistent data:
+
+```sh
+rm -rf /config/.openclaw /config/clawd /config/.node_global
+```
+
+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.
+
+---
+
+## 10. Troubleshooting
+
+### How to read add-on logs
+
+Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show startup messages, errors, and service status.
+
+### Port 48099 conflict (add-on page won't load)
+
+**Symptom**: `bind() to 0.0.0.0:48099 failed (98: Address already in use)` in logs.
+
+**Cause**: A stale nginx process from a previous run is still holding the port. This can happen after a crash or unclean restart.
+
+**Fix**: Restart the add-on. The startup script automatically cleans up stale processes. If the problem persists, stop the add-on, wait 10 seconds, then start it again.
+
+### Port 7681 conflict (terminal won't load)
+
+**Symptom**: `lws_socket_bind: ERROR on binding fd to port 7681` in logs.
+
+**Fix**: Either restart the add-on (stale process cleanup), or change `terminal_port` to a different value (e.g., `7682`).
+
+### ERR_CONNECTION_REFUSED
+
+**Symptom**: Browser shows connection refused when opening the Gateway Web UI.
+
+**Checks**:
+1. Is the gateway running? In the terminal: `openclaw 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
+
+### "disconnected (1008): control ui requires device identity" / "requires HTTPS or localhost"
+
+**Symptom**: Gateway UI shows error 1008 or "requires secure context / device identity".
+
+**Cause**: OpenClaw v2026.2.21+ requires HTTPS or localhost. Plain HTTP over LAN is blocked. (v2026.2.22 further hardens this by defaulting remote onboarding to `wss://` and rejecting insecure non-loopback targets.)
+
+**Fix** (pick one):
+1. **Easiest**: Set `access_mode` to **lan_https** in add-on Configuration → restart. This adds a built-in HTTPS proxy with zero external setup.
+2. **External proxy**: Set `access_mode` to **lan_reverse_proxy** and configure NPM/Caddy/Traefik with TLS.
+3. **SSH tunnel** (desktop only): `ssh -L 18789:127.0.0.1:18789 user@ha-ip` then open `http://localhost:18789`.
+
+### "disconnected (1008): origin not allowed"
+
+**Symptom**: Gateway UI shows `origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)`.
+
+**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.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"]'
+   ```
+   Then restart the add-on to re-merge defaults + extras.
+
+### "disconnected (1008): pairing required"
+
+**Symptom**: Gateway UI loads over HTTPS but shows `pairing required` and the status is Offline.
+
+**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.50+** 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.
+
+> **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.
+
+1. **Restart the add-on** — the startup script writes the config before launching the gateway.
+2. If the error persists, set it manually:
+   ```sh
+   nano /config/.openclaw/openclaw.json
+   ```
+   Ensure `gateway.controlUi` contains:
+   ```json
+   "controlUi": {
+     "dangerouslyDisableDeviceAuth": true,
+     "allowedOrigins": ["https://YOUR_IP:18789"]
+   }
+   ```
+   Then restart the gateway: `openclaw gateway restart`
+3. Alternatively, approve devices individually without disabling auth:
+   ```sh
+   openclaw devices list       # show pending pairing requests
+   openclaw devices approve <requestId>
+   ```
+
+### Gateway UI shows "Unauthorized"
+
+**Fix**: Get the correct token and use it:
+
+```sh
+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
+2. Check logs for `Starting web terminal (ttyd)` — if missing, the terminal is disabled
+3. If you see a port conflict error, change `terminal_port` to a different value
+
+### `web_fetch failed: fetch failed` / HTTP tool calls time out
+
+**Symptom**: OpenClaw's `web_fetch` tool (or any outbound HTTP call from a skill) fails with `fetch failed`.
+
+**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.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)
+
+If Telegram is configured but polling fails with network fetch errors:
+
+1. In add-on terminal, test IPv4 vs IPv6 explicitly:
+   ```sh
+   curl -4 https://api.telegram.org/bot<token>/getMe
+   curl -6 https://api.telegram.org/bot<token>/getMe
+   ```
+2. If IPv4 works but default/IPv6 fails, ensure add-on option `force_ipv4_dns` is `true` (default) and restart.
+3. Keep `channels.telegram.network.autoSelectFamily: false` (default on Node 22).
+4. If still failing, check host/VM IPv6 routing and DNS configuration.
+
+### Outbound proxy not applied
+
+**Symptom**: External API/network calls still fail in restricted networks even after setting proxy.
+
+**Checks**:
+1. Set add-on option `http_proxy` with full URL format: `http://host:port` (example: `http://192.168.2.1:3128`).
+2. Restart the add-on after changing configuration.
+3. Check logs for `INFO: Outbound HTTP/HTTPS proxy enabled from add-on configuration.`
+4. If you see `WARN: Invalid http_proxy value`, fix the URL format and restart.
+
+When proxy is enabled, add-on startup also applies default bypass ranges via `NO_PROXY`/`no_proxy` for localhost and private network ranges.
+
+### Skills disappearing after update
+
+Built-in skills are synced to persistent storage on each startup. If skills are missing:
+
+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
+
+### Homebrew errors / CPU compatibility
+
+**Symptom**: `Homebrew's x86_64 support on Linux requires a CPU with SSSE3 support!`
+
+**Cause**: Your CPU doesn't support SSSE3 instructions (required by Homebrew). Affects older Intel Atom, Celeron, or pre-2006 processors.
+
+**Impact**: Skills that depend on Homebrew-installed CLI tools (e.g., `gemini`, `aider`) won't work. Core OpenClaw functionality is unaffected.
+
+**Workarounds**:
+- Use a machine with a newer CPU (Intel Core 2 or newer, ~2006+)
+- Install the required CLI tools manually if possible
+- Use alternative skills that don't require Homebrew dependencies
+
+### "openclaw: command not found"
+
+The OpenClaw binary should be installed at `/usr/lib/node_modules/openclaw/`. If this error appears:
+
+1. Check the add-on logs for npm installation errors during build
+2. Try restarting the add-on
+3. If the problem persists, uninstall and reinstall the add-on
+
+### Gateway won't start / config errors
+
+**Symptom**: `ERROR: Failed to apply gateway settings` in logs.
+
+**Fix**: The `openclaw.json` config file may be corrupted. To reset it:
+
+```sh
+rm /config/.openclaw/openclaw.json
+```
+
+Restart the add-on — it will generate a fresh config. You'll need to run `openclaw onboard` again.
+
+### Disk space running low / "no space left on device"
+
+**Symptom**: Build or startup fails, or the landing page shows a red disk-usage indicator.
+
+**Cause**: Old Docker images and container layers accumulate on the host. Each add-on rebuild (~1–2 GB) keeps the previous image until pruned.
+
+**Fix (from inside the add-on)**:
+1. Open the terminal and run `oc-cleanup` to clear npm/pnpm caches, pycache, and temp files.
+
+**Fix (from the host)** — you need a **root shell on the HAOS host**, not the `ha` CLI
+(the `ha docker` command does **not** support `prune`):
+
+*Option A — Advanced SSH & Web Terminal add-on (easiest):*
+1. Install the **Advanced SSH & Web Terminal** add-on from the HA store.
+2. In its Configuration, **disable Protection Mode** (required for host-level access).
+3. Open the terminal and run:
+   ```sh
+   docker image prune -a       # remove all unused images
+   docker builder prune -a      # remove build cache
+   ```
+
+*Option B — HAOS debug console (VirtualBox / physical):*
+1. On the HAOS console (keyboard/VirtualBox window), type `login` to get a root shell.
+2. Run the same `docker image prune -a` and `docker builder prune -a` commands.
+
+> **Note:** The `ha docker` CLI (shown by `ha docker --help`) only exposes `info`,
+> `options`, and `registries` — it cannot prune images. You must use the raw `docker`
+> command from a host root shell.
+
+**Prevention**: If running HAOS in VirtualBox, resize the VDI to at least 64 GB:
+```
+VBoxManage modifymedium disk haos.vdi --resize 64000
 ```
 
 ---
 
-## 11) Entities and sensors
+## 11. FAQ
 
-## Core status entities
-- **Connected** (binary sensor)
-- **Status** (`online`/`offline`)
-- **Last Activity**
-- **Model**
-- **Session Count**
+**Does this work on Raspberry Pi?**
+Yes. The add-on supports aarch64 (Raspberry Pi 4/5) and armv7 (Raspberry Pi 3). Note that Homebrew may not work on all ARM devices, but core functionality is unaffected.
 
-## Tool telemetry sensors
-- **Last Tool**
-- **Last Tool Status**
-- **Last Tool Duration**
-- **Last Tool Invoked**
+**Can I run multiple agents?**
+OpenClaw supports multiple agent profiles. Configure them via `openclaw configure` or by editing `/config/.openclaw/openclaw.json`. The gateway serves all configured agents.
 
-### Why some sensors may show `Unknown`
-- `Last Tool*` sensors remain `Unknown` until at least one tool invocation completes.
-- `Session Count` can remain `0` if tool policy blocks `sessions_list` over HTTP invoke endpoint.
+**Can I use a remote gateway?**
+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.
 
-## 12) Troubleshooting
+**Can other devices on my network use the OpenClaw API?**
+Yes. Set `access_mode` to `lan_https` (recommended) or `lan_reverse_proxy`. Any device on your network can connect to `https://<ha-ip>:18789`. Use the gateway token for authentication. This also enables the [Assist pipeline integration](#6c-assist-pipeline-integration-openai-api) from other HA instances or standalone OpenClaw integrations.
 
-## Integration cannot connect
-Check:
-- Addon is running
-- Host/port/token are correct
-- Gateway auth mode matches what you entered
-- Chat completions endpoint is enabled in gateway settings
+**Where is my data stored on the host?**
+The add-on's `/config/` directory maps to `/addon_configs/<slug>/` on the Home Assistant host. This is included in HA backups automatically.
 
-## Chat responses missing on card
-Check:
-- Dashboard loaded latest card resource (hard refresh)
-- `openclaw_message_received` event firing
-- Session id consistency between message source and card
-
-## Voice issues
-Check:
-- Browser mic permission for Home Assistant URL
-- Correct provider selected (`browser` vs `assist_stt`)
-- STT engine configured in HA voice settings (for `assist_stt`)
-- Browser compatibility (try Chrome/Edge if Brave is unstable)
-
-## Conversation context seems reset
-Check:
-- Same session id is used across turns
-- Gateway session routing is active
-- Gateway policy/routing not forcing isolated sessions
-
----
-
-## 13) Best practices
-
-- Keep one session id per topic/workflow.
-- Use separate sessions for unrelated automations.
-- Keep tool calls permissioned and minimal.
-- Prefer explicit automations for critical actions.
-- Review logs after upgrades and hard-refresh dashboard resources.
-
----
-
-## 14) Operational checklist (quick)
-
-After install/update:
-1. Restart Home Assistant
-2. Hard refresh dashboard browser tab
-3. Verify OpenClaw entities are available
-4. Send one text chat test
-5. Test voice provider you plan to use
-6. If using tools, run one `invoke_tool` test and verify telemetry sensors/events
-
----
-
-## 15) Audience-specific quick paths
-
-## Non-technical path
-- Install via HACS
-- Add integration
-- Add card
-- Use text first
-- Enable voice after basic chat works
-
-## Technical path
-- Validate gateway endpoint behavior and auth mode
-- Validate session routing behavior
-- Build automations with service calls/events
-- Use telemetry sensors for health and troubleshooting
-
----
-
-If you want this guide split into separate files later (Install, Voice, Automation, Troubleshooting), you can keep this `DOCS.md` as the master index and link each specialized document from it.
\ No newline at end of file
+The add-on also mounts Home Assistant `/share` and `/media` as writable paths inside the container (`/share`, `/media`) for file access workflows. These are separate from OpenClaw's default persistent workspace under `/config`.