From 4f846ee43dd50d566b6b29ef31019a3cb5043ae8 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:25:20 +0300 Subject: [PATCH 1/6] ci: add Gitflow multi-arch GHCR publishing --- .github/workflows/build-multiarch.yaml | 184 +++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 .github/workflows/build-multiarch.yaml diff --git a/.github/workflows/build-multiarch.yaml b/.github/workflows/build-multiarch.yaml new file mode 100644 index 0000000..169571e --- /dev/null +++ b/.github/workflows/build-multiarch.yaml @@ -0,0 +1,184 @@ +name: Build and publish multi-arch add-on image + +on: + pull_request: + branches: [develop, main] + push: + branches: + - develop + - 'release/**' + - main + +permissions: + contents: read + packages: write + +env: + ADDON_PATH: openclaw_assistant + IMAGE_NAME: ghcr.io/dmitrykadyshev/openclawhomeassistant + +jobs: + validate: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: docker/setup-buildx-action@v3 + - uses: docker/build-push-action@v6 + with: + context: ./openclaw_assistant + platforms: linux/amd64 + push: false + build-args: | + BUILD_FROM=ghcr.io/home-assistant/amd64-base-debian:bookworm + BUILD_VERSION=${{ github.event.pull_request.head.sha }} + tags: openclaw-assistant:pr + + build: + if: github.event_name == 'push' + strategy: + fail-fast: false + matrix: + include: + - arch: amd64 + platform: linux/amd64 + build_from: ghcr.io/home-assistant/amd64-base-debian:bookworm + - arch: aarch64 + platform: linux/arm64 + build_from: ghcr.io/home-assistant/aarch64-base-debian:bookworm + - arch: armv7 + platform: linux/arm/v7 + build_from: ghcr.io/home-assistant/armv7-base-debian:bookworm + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: docker/setup-qemu-action@v3 + with: + platforms: arm64,arm + + - uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Read add-on version + id: version + shell: bash + run: | + set -euo pipefail + version="$(sed -n 's/^version: *"\([0-9][0-9.]*\)"$/\1/p' "$ADDON_PATH/config.yaml")" + test -n "$version" + echo "version=$version" >> "$GITHUB_OUTPUT" + + - name: Determine image tag + id: tags + shell: bash + env: + VERSION: ${{ steps.version.outputs.version }} + REF_NAME: ${{ github.ref_name }} + run: | + set -euo pipefail + case "$REF_NAME" in + develop) + tag="dev" + ;; + release/*) + release_version="${REF_NAME#release/}" + test "$release_version" = "$VERSION" + tag="${VERSION}-rc.${GITHUB_RUN_NUMBER}" + ;; + main) + tag="$VERSION" + ;; + *) + echo "Unsupported Gitflow branch: $REF_NAME" >&2 + exit 1 + ;; + esac + echo "tag=$tag" >> "$GITHUB_OUTPUT" + + - name: Build and push architecture image + uses: docker/build-push-action@v6 + with: + context: ./openclaw_assistant + platforms: ${{ matrix.platform }} + push: true + build-args: | + BUILD_FROM=${{ matrix.build_from }} + BUILD_VERSION=${{ steps.version.outputs.version }} + tags: ${{ env.IMAGE_NAME }}:${{ steps.tags.outputs.tag }}-${{ matrix.arch }} + cache-from: type=gha,scope=${{ matrix.arch }} + cache-to: type=gha,mode=max,scope=${{ matrix.arch }} + + manifest: + if: github.event_name == 'push' + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: docker/setup-buildx-action@v3 + + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Read add-on version + id: version + shell: bash + run: | + set -euo pipefail + version="$(sed -n 's/^version: *"\([0-9][0-9.]*\)"$/\1/p' "$ADDON_PATH/config.yaml")" + test -n "$version" + echo "version=$version" >> "$GITHUB_OUTPUT" + + - name: Determine image tag + id: tags + shell: bash + env: + VERSION: ${{ steps.version.outputs.version }} + REF_NAME: ${{ github.ref_name }} + run: | + set -euo pipefail + case "$REF_NAME" in + develop) + tag="dev" + ;; + release/*) + release_version="${REF_NAME#release/}" + test "$release_version" = "$VERSION" + tag="${VERSION}-rc.${GITHUB_RUN_NUMBER}" + ;; + main) + tag="$VERSION" + ;; + *) + echo "Unsupported Gitflow branch: $REF_NAME" >&2 + exit 1 + ;; + esac + echo "tag=$tag" >> "$GITHUB_OUTPUT" + + - name: Publish multi-arch manifest + shell: bash + run: | + set -euo pipefail + image="$IMAGE_NAME" + tag="${{ steps.tags.outputs.tag }}" + + docker buildx imagetools create \ + -t "$image:$tag" \ + "$image:$tag-amd64" \ + "$image:$tag-aarch64" \ + "$image:$tag-armv7" + + if [ "${GITHUB_REF_NAME}" = "main" ]; then + docker buildx imagetools create -t "$image:latest" "$image:$tag" + fi From a883a5844f7525c4df633f259d02773372bcc901 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:25:29 +0300 Subject: [PATCH 2/6] chore: bump add-on version to 0.5.91 --- openclaw_assistant/config.yaml | 131 ++------------------------------- 1 file changed, 7 insertions(+), 124 deletions(-) diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml index c791f6f..12f8994 100644 --- a/openclaw_assistant/config.yaml +++ b/openclaw_assistant/config.yaml @@ -1,5 +1,5 @@ name: OpenClaw Assistant -version: "0.5.90" +version: "0.5.91" slug: openclaw_assistant description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on. url: https://github.com/techartdev/OpenClawHomeAssistant @@ -32,12 +32,12 @@ watchdog: tcp://[HOST]:48099 # is NOT restored and must be reinstalled (brew/npm tools) or is rebuilt on # demand (caches). User data, skills, agents and secrets are never excluded. backup_exclude: - - ".linuxbrew" # Homebrew install + cellar (persist_brew_tools) - - ".node_global" # npm/pnpm global installs (persist_node_global) - - ".npm" # npm download cache - - ".cache" # generic tool caches (Chromium, build artifacts) - - "__pycache__" # Python bytecode, at any depth - - "*.jsonl.lock" # stale session locks; never useful to restore + - ".linuxbrew" + - ".node_global" + - ".npm" + - ".cache" + - "__pycache__" + - "*.jsonl.lock" map: - addon_config:rw @@ -45,153 +45,38 @@ map: - media:rw options: timezone: "Europe/Sofia" - - # Enable web terminal inside Home Assistant (Ingress) via ttyd enable_terminal: true - - # Terminal port (change if 7681 conflicts with another service) terminal_port: 7681 - - # Public base URL for opening the Gateway Web UI in a new tab (not embedded). - # Recommended: NO trailing slash. - # Example: "https://example.duckdns.org:12345" or "http://192.168.1.10:18789" gateway_public_url: "" - - # Optional: Home Assistant long-lived token (for local HA API scripts/tools) homeassistant_token: "" - - # Optional: outbound HTTP/HTTPS proxy for OpenClaw network access. - # Example: "http://192.168.2.1:3128" http_proxy: "" - - # Optional: Router SSH defaults (leave empty if you don't need router automation) - # This is a generic SSH configuration intended for a router/firewall or any network device - # reachable from inside the HA host LAN. router_ssh_host: "" router_ssh_user: "" router_ssh_key_path: "/data/keys/router_ssh" - - # Cleanup stale session lock files left after crashes/restarts 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) - # - tailnet: bind to Tailscale IP only (accessible only via Tailscale — recommended for remote access) - # Default is loopback for security. gateway_bind_mode: loopback - - # Gateway port to listen on gateway_port: 18789 - - # Access mode preset — simplifies secure access configuration. - # custom: use individual gateway_bind_mode / auth_mode settings (backward compatible) - # local_only: loopback + token auth (Ingress / terminal only, most secure) - # lan_https: Built-in HTTPS reverse proxy for LAN access (recommended for phones/tablets) - # lan_reverse_proxy: LAN bind + trusted-proxy for an external reverse proxy (NPM, Caddy, …) - # tailnet_https: Tailscale interface bind + token auth access_mode: custom - - # Gateway authentication mode: - # - token: standard token auth (default) - # - trusted-proxy: trust auth headers from configured reverse proxies gateway_auth_mode: token - - # Comma-separated trusted proxy IP/CIDR list for trusted-proxy mode. - # 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 enable_openai_api: false - - # Force IPv4-first DNS result ordering for Node fetch/network calls. - # Most HAOS VMs lack IPv6 egress, causing web_fetch / Telegram timeouts. - # Default: true (recommended). Set to false only if you need IPv6. force_ipv4_dns: true - - # Nginx access log verbosity: - # full: log all requests (useful for debugging) - # minimal: suppress repetitive HA health-check and polling requests (default) nginx_log_level: minimal - - # Environment variables to pass to the gateway process at startup. - # Format: list of objects with name/value fields. - # Example: - # gateway_env_vars: - # - name: OPENAI_API_KEY - # value: "sk-abc123" - # - name: LOG_LEVEL - # value: "debug" - # Reserved keys are blocked to protect runtime/security - # (e.g. PATH, HOME, NODE_OPTIONS, NODE_PATH, OPENCLAW_*, proxy vars). - # 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 - - # Resource profile — keeps the add-on well-behaved on low-power hardware. - # auto: detect from CPU architecture and total RAM (recommended) - # low: smallest Node heap; also disables OpenClaw browser automation - # (only for keys you have not set yourself in openclaw.json) - # balanced: moderate Node heap for 2-6 GB systems - # high: no heap cap; leaves Node's own default in place - # Only 'low' selected explicitly writes to openclaw.json; 'auto' never does. resource_profile: auto - - # Publish gateway status, version, memory, disk usage and certificate expiry - # as Home Assistant sensor entities (sensor.openclaw_*) so you can alert on - # them. Requires homeassistant_token to be set. ha_health_sensors: false - - # How often (seconds) to refresh the health sensors. Range 15-3600. ha_health_interval: 60 - - # Base URL of your Home Assistant instance, used by the health sensors. - # Leave empty to auto-detect (tries https/http on 127.0.0.1, localhost, - # homeassistant and homeassistant.local, port 8123). - # Set this if Home Assistant uses a non-default port or another host, - # e.g. "https://192.168.1.10:8123". ha_base_url: "" - - # How many openclaw.json snapshots to keep in /config/.openclaw/backups. - # A snapshot is taken before the add-on's first config write of each start, - # so a bad change can be rolled back with 'oc-config restore'. 0 disables. config_backup_keep: 10 - schema: timezone: str enable_terminal: bool? @@ -199,11 +84,9 @@ schema: gateway_public_url: str? homeassistant_token: str? http_proxy: str? - router_ssh_host: str router_ssh_user: str router_ssh_key_path: str - clean_session_locks_on_start: bool? clean_session_locks_on_exit: bool? persist_node_global: bool? From e66cb4a76acfa1820de32abcabdce3b7f7c48230 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:25:52 +0300 Subject: [PATCH 3/6] docs: document Gitflow multi-arch release pipeline --- openclaw_assistant/CHANGELOG.md | 371 +++----------------------------- 1 file changed, 27 insertions(+), 344 deletions(-) diff --git a/openclaw_assistant/CHANGELOG.md b/openclaw_assistant/CHANGELOG.md index 7339271..6d034a4 100644 --- a/openclaw_assistant/CHANGELOG.md +++ b/openclaw_assistant/CHANGELOG.md @@ -2,6 +2,16 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be documented in this file. +## [0.5.91] - 2026-09-04 + +### Added +- Add Gitflow-aware GitHub Actions for PR validation and multi-architecture container publishing. +- Publish `amd64`, `aarch64`/`arm64`, and `armv7` images to GitHub Container Registry and assemble a multi-arch manifest. +- Add `develop`, `release/*`, and `main` publishing flows with development, release-candidate, and versioned image tags. + +### Changed +- Bump the Home Assistant add-on version to `0.5.91`. + ## [0.5.90] - 2026-09-02 ### Added @@ -9,28 +19,17 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu - **Home Assistant health sensors** (`ha_health_sensors`, `ha_health_interval`): optionally publish `sensor.openclaw_gateway`, `sensor.openclaw_version`, `sensor.openclaw_gateway_memory`, `sensor.openclaw_disk_used` and `sensor.openclaw_certificate_expiry` so you can alert on gateway health, disk usage and certificate expiry from automations. Requires `homeassistant_token`. New `oc-health` helper (`show` / `once` / `loop`) for previewing and debugging. - **Config snapshots and rollback** (`config_backup_keep`): `openclaw.json` is now snapshotted to `/config/.openclaw/backups` before the add-on's first configuration write of each start, so an unwanted change can be undone. New `oc-config` helper: `list`, `diff`, `restore`, `snapshot`. Restoring always backs up the config it replaces first. Identical configs are not re-snapshotted, and only the newest `config_backup_keep` (default 10) are kept. - New `ha_base_url` option to point the health sensors at a Home Assistant on a non-default port or host (empty = auto-detect). -- `oc-health check`: diagnoses credentials and API connectivity in one command — which endpoint was chosen, whether a token is present, whether the Supervisor host resolves, and the result of a live probe. -- Supervisor watchdog on the ingress port, so Home Assistant restarts the add-on if the ingress proxy stops answering. Can be turned off with the Watchdog toggle on the add-on page. -- **Smaller Home Assistant backups**: the add-on now declares `backup_exclude`, so regenerable caches and tooling (`.linuxbrew`, `.node_global`, `.npm`, `.cache`, `__pycache__`, stale `*.jsonl.lock` files) are skipped when Home Assistant backs the add-on up. Excluded directories are pruned without being walked, so backups are both smaller and faster. All user state — `openclaw.json`, config snapshots, skills, agent sessions, the `clawd` workspace, keys, secrets and certificates — is still backed up. Note that a restore replaces `/config` wholesale, so excluded tooling must be reinstalled rather than restored. +- `oc-health check`: diagnoses credentials and API connectivity in one command. +- Supervisor watchdog on the ingress port, so Home Assistant restarts the add-on if the ingress proxy stops answering. ### Changed -- **Documentation reviewed against OpenClaw `2026.8.2`.** Added a *Device pairing (first connection)* walkthrough — the gateway host is the add-on container, so `openclaw devices list` / `openclaw devices approve ` in the add-on terminal is all that is needed, and the `ssh -N -L` hint printed by `openclaw dashboard` does not apply here. Corrected the long-standing claim that the Control UI requires HTTPS or localhost: upstream removed that restriction (device identity is signed with pure-JS Ed25519 on any origin), so the guidance now recommends HTTPS for token confidentiality rather than presenting it as mandatory. Rewrote the two error-1008 troubleshooting entries around pairing, and marked `controlui_disable_device_auth` as deprecated and inert in all six locales. -- Startup warnings about legacy `/config/.node_global` and `/config/.linuxbrew` directories no longer claim they inflate Home Assistant backups (they are now excluded). The warning explains they only use disk space and gives the exact removal command. +- **Documentation reviewed against OpenClaw `2026.8.2`.** Added a *Device pairing (first connection)* walkthrough and corrected Control UI HTTPS/pairing guidance. +- Startup warnings about legacy `/config/.node_global` and `/config/.linuxbrew` directories now reflect their backup exclusion behavior. ### Fixed -- **Stopped writing a retired OpenClaw key.** The add-on set `gateway.controlUi.dangerouslyDisableDeviceAuth` on every start to skip Control UI device pairing. OpenClaw retired that flag in the `2026.8.x` line: it is inert, the security audit reports it as a dangerous key, and `openclaw doctor --fix` deletes it — so the add-on was re-adding it every boot and fighting Doctor. The add-on now removes the key instead, which also clears the "dangerous config flags enabled" startup warning. Browsers pair once via `openclaw devices approve `. -- **Health sensors could not reach a Home Assistant that serves HTTPS**: endpoint detection only ever tried plain `http://`, which a TLS listener answers by closing the connection — surfacing as `HTTP 000` (curl: *Empty reply from server*). Detection now probes `https` and `http` across `127.0.0.1`, `localhost`, `homeassistant` and `homeassistant.local`, and uses the first endpoint that answers. TLS verification is skipped for these local endpoints because Home Assistant's certificate is normally issued for its external hostname and never matches a loopback address; the connection stays on the local host/LAN. -- Detection is retried on later cycles instead of only at startup, so sensors still come up when the add-on starts before Home Assistant is listening. -- **Health sensors could not reach Home Assistant (`HTTP 000`)**: `oc-health` preferred the Supervisor proxy whenever `SUPERVISOR_TOKEN` was present, but this add-on runs with `host_network: true`, so the container is not on the Supervisor bridge network and the `supervisor` hostname does not resolve. Every sensor update failed at the connection level. It now prefers the user's long-lived token against the host's Home Assistant on `localhost:8123`, and only uses the Supervisor proxy when that hostname actually resolves. -- The same endpoint-selection bug in the MCP auto-configuration would have registered an unreachable `http://supervisor/core/api/mcp` URL; it now applies the same reachability check. -- Health sensor failures are logged once per status change instead of one line per entity per interval, so an outage can no longer fill the add-on log (previously ~7000 lines a day). -- Failures now explain themselves: `HTTP 000` reports that Home Assistant is unreachable at the resolved endpoint, `401`/`403` points at the token, rather than printing a bare status code. - -- **`proxy_attribution_required` in `lan_https` mode**: OpenClaw `2026.8.2` began rejecting requests that carry forwarded identity headers from an untrusted source. The add-on's built-in HTTPS proxy runs on loopback and sets `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto`, but loopback was never added to `gateway.trustedProxies`, so the gateway refused every request with `proxy_attribution_required`. `lan_https` now trusts `127.0.0.1` and `::1` (merged with any `gateway_trusted_proxies` you set, and deduplicated). As a side benefit the gateway can now attribute the real LAN client IP for rate limiting instead of seeing every request as loopback. -- **Gateway restart loop was not actually recovering** (follow-up to `0.5.104`): the automatic repair ran `openclaw doctor --fix` without `--non-interactive`. With no TTY, Doctor printed advisory notices and skipped the migration, so the loop continued. It now runs `openclaw doctor --fix --non-interactive --yes`, the documented automation form, and reports clearly when Doctor exits non-zero because a legacy source or interrupted `.doctor-importing` claim remains. -- **Restart backoff never escalated**: gateway uptime was measured after the daemon-detection retry loop, so its sleeps counted as uptime. A gateway that died ~45s into startup measured ~65s, tripped the 60s "healthy" reset, and pinned the retry interval at 2s forever. Uptime is now captured the moment the runtime exits, and the healthy threshold is 120s — comfortably above a normal ~45s cold start. The repair is also attempted after 2 consecutive failures instead of 3, since each failed boot costs about a minute. -- **Gateway restart loop after an OpenClaw upgrade**: releases that gate startup behind a data migration (such as the legacy workspace state check in `2026.8.2`) made the supervisor restart the gateway forever, writing a stability bundle on every attempt. The add-on now runs the documented `openclaw doctor --fix` repair once per start after repeated failures — snapshotting `openclaw.json` first so it is reversible — and backs off between restarts (2s doubling to a 60s cap) instead of retrying every 2 seconds. After five consecutive failures it logs the exact diagnostic commands to run. The terminal and add-on page stay available throughout. -- Documentation listed Node.js 22 in the bundled tools table; the image has shipped Node.js 24 since `0.5.83`. +- Removed the retired `gateway.controlUi.dangerouslyDisableDeviceAuth` configuration key and fixed `lan_https` proxy attribution for OpenClaw `2026.8.2`. +- Fixed Home Assistant health sensor endpoint selection, retry behavior, and failure logging. +- Fixed gateway restart-loop recovery and restart backoff after OpenClaw upgrades. ## [0.5.89] - 2026-09-02 @@ -40,12 +39,12 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [0.5.88] - 2026-08-25 ### Fixed -- Preserve explicit `false` values for boolean add-on options instead of replacing them with `true` defaults during startup. This restores settings such as strict Control UI device authentication, disabled terminal access, and IPv6-capable DNS behavior after an add-on restart or rebuild. +- Preserve explicit `false` values for boolean add-on options instead of replacing them with `true` defaults during startup. ## [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`. +- Correct the bundled OpenClaw npm package version in the Docker image build for add-on `0.5.86`. ## [0.5.85] - 2026-07-21 @@ -55,14 +54,13 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [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. +- Bundle `mcporter@0.12.3` in the add-on image. ## [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. +- Repair add-on startup automatically when the bundled OpenClaw CLI is older than the persisted config format. +- Regenerate malformed `lan_https` CA/server certificates with proper X.509 extensions. ## [0.5.81] - 2026-07-14 @@ -87,339 +85,24 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [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. +- Add backup-friendly persistence defaults for optional toolchains. ## [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. +- Bundle `node-llama-cpp` and add `cmake` for source builds when needed. ## [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. +- Add the add-on-native `oc-gateway` helper for container-supervised runtime management. ## [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. +- Repair startup when a persisted OpenClaw config selects the unavailable Brave search provider. ## [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. - -## [0.5.52] - 2026-02-23 - -### Added -- New add-on option `gateway_env_vars` that accepts a list of `{name, value}` objects from Home Assistant UI and safely injects values into the gateway process at startup (max 50 vars, key <=255 chars, value <=10000 chars). -- Guard `gateway_env_vars` from overriding reserved runtime/proxy/`OPENCLAW_*` keys. -- Keep legacy string/object input formats for backward compatibility. - -## [0.5.51] - 2026-02-23 - -### Fixed -- **`web_fetch failed: fetch failed`**: changed `force_ipv4_dns` default to **true**. Node 22 tries IPv6 first; most HAOS VMs lack IPv6 egress, causing outbound `web_fetch` / HTTP tool calls to time out. - -### Added -- **`nginx_log_level` option** (`minimal` / `full`, default `minimal`): suppresses repetitive Home Assistant health-check and polling requests (`GET /`, `GET /v1/models`, `POST /tools/invoke`) from the nginx access log. - -## [0.5.50] - 2026-02-23 - -**[!WARNING!]** -This update contains lots of changes. It is adviced to backup before installing! - -### Changed -- **Upgraded OpenClaw to v2026.2.22-2** — includes major gateway/auth/pairing fixes and security hardening. -- Precreate `$OPENCLAW_CONFIG_DIR/identity` on startup to prevent `EACCES` errors on CLI commands that need device identity. -- Gateway token is auto-constructed from detected LAN IP when `lan_https` is active and `gateway_public_url` is empty. -- Config helper now receives the effective internal port (gateway_port + 1 in lan_https mode). - -### Notes — v2026.2.22 impact on this add-on -- **Pairing fixes (loopback)**: v2026.2.22 auto-approves loopback scope-upgrade pairing requests, includes `operator.read`/`operator.write` in default scope bundles, and treats `operator.admin` as satisfying other scopes. This greatly improves `local_only` mode reliability. -- **`dangerouslyDisableDeviceAuth` security warning**: v2026.2.22 now emits a startup warning when this flag is active. The warning is **expected and harmless** for `lan_https` mode — the flag is still required because LAN browser connections through the HTTPS proxy are not considered loopback by the gateway. Token auth remains enforced. -- **Gateway lock improvements**: stale-lock detection now uses port reachability, reducing false "already running" errors after unclean restarts. -- **Log file size cap**: new `logging.maxFileBytes` default (500 MB) prevents disk exhaustion from log storms. -- **`wss://` default for remote onboarding**: validates our HTTPS proxy approach as the correct direction. - -### Added -- **Disk-space monitoring on the landing page** — shows total / used / available with colour-coded indicator (🟢 / 🟡 / 🔴). -- **Low-disk warning banner** appears automatically when usage exceeds 90 %. -- **`oc-cleanup` terminal command** — interactive helper that shows cache sizes (npm, pnpm, OpenClaw, Homebrew, pycache, tmp) and lets users reclaim space with a menu-driven cleanup. -- Startup disk-space check with log warnings when the overlay is above 75 % or 90 %. -- **`access_mode` preset option** — simplifies secure access configuration with one setting: - - `custom` (default, backward-compatible): use individual gateway settings - - `local_only`: loopback + token (Ingress/terminal only) - - `lan_https`: **built-in HTTPS reverse proxy for LAN access** (recommended for phones/tablets) - - `lan_reverse_proxy`: LAN bind + trusted-proxy for external reverse proxy (NPM, Caddy, Traefik) - - `tailnet_https`: Tailscale interface bind + token auth -- **Built-in TLS certificate generation** (`lan_https` mode): - - Auto-generates a local CA + server certificate on first startup - - Server cert is regenerated automatically when LAN IP changes - - CA certificate downloadable from the landing page for one-tap phone trust - - nginx HTTPS server block terminates TLS and proxies to the loopback gateway -- **Overhauled landing page** with: - - Real-time status cards (gateway health, secure context, access mode) - - Access wizard with step-by-step guidance per mode - - Error translation — maps raw errors like `1008: requires device identity` to friendly messages with fixes - - CA certificate download button (lan_https mode) - - Migration banner for users on `custom` mode recommending a preset - - Collapsible reverse-proxy recipes (NPM / Caddy / Traefik / Tailscale) -- Added `openssl` to Docker image for TLS certificate generation. -- Translations for `access_mode` in all 6 languages (EN, BG, DE, ES, PL, PT-BR). - -### Fixed -- **`lan_https` — error 1008 "pairing required"**: auto-set `gateway.controlUi.dangerouslyDisableDeviceAuth: true` to skip interactive device pairing (token auth remains enforced). Replaces the invalid `pairingMode` key that caused `Unrecognized key` config errors. -- Config helper now removes stale/invalid keys (e.g. `pairingMode`) from `controlUi` on startup. -- Landing page error translation now covers "pairing required" and "origin not allowed" errors with correct fix guidance. -- Dropdown translations for `access_mode`, `gateway_mode`, `gateway_bind_mode`, and `gateway_auth_mode` now show human-readable labels in all 6 languages. -- **`lan_https` — error 1008 "origin not allowed"**: auto-configure `gateway.controlUi.allowedOrigins` with the HTTPS proxy origins (LAN IP, `homeassistant.local`, `homeassistant`) so the Control UI WebSocket is accepted. - -## [0.5.49] - 2026-02-22 - -### Added -- New add-on option `http_proxy` for configuring outbound HTTP/HTTPS proxy from Home Assistant settings. - -### Changed -- Export `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, and `https_proxy` from add-on config at startup. -- Add translations for the new `http_proxy` option. -- Document proxy configuration in README and DOCS. - -## [0.5.48] - 2026-02-22 - -### Changed -- Bump OpenClaw to 2026.2.21-2. -- Add Home Assistant `share` and `media` mounts to the add-on (`map: share:rw, media:rw`). -- Keep official OpenClaw npm release and add startup proxy shim for `HTTP_PROXY/HTTPS_PROXY` support in undici fetch. - -## [0.5.47] - 2026-02-21 - -### Added -- Add new `gateway_bind_mode` values: `auto` and `tailnet`. - -### Changed -- Update startup helper validation and CLI usage to support `auto|loopback|lan|tailnet` bind modes. -- Update add-on translations and docs for the expanded gateway bind mode options. - -## [0.5.46] - 2026-02-18 - -### Added -- New add-on option `force_ipv4_dns` to enable IPv4-first DNS ordering for Node network calls (`NODE_OPTIONS=--dns-result-order=ipv4first`), helping Telegram connectivity on IPv6-broken networks. - -### Changed -- Added translations for `force_ipv4_dns` option. -- Updated docs with `force_ipv4_dns` configuration and Telegram network troubleshooting note. -- Bump OpenClaw to 2026.2.17 - -## [0.5.45] - 2026-02-16 - -### Changed -- Bump OpenClaw to 2026.2.15 - -## [0.5.44] - 2026-02-14 - -### Changed -- Bump OpenClaw to 2026.2.13 - -## [0.5.43] - 2026-02-13 - -### Changed -- Bump OpenClaw to 2026.2.12 - -### Added -- Portuguese (Brazil) translation (`pt-BR.yaml`) by medeirosiago - -## [0.5.42] - 2026-02-12 - -### Changed -- Change nginx ingress port from 8099 to 48099 to avoid conflicts with NextCloud and other services -- Persist Homebrew and brew-installed packages across container rebuilds (symlink to `/config/.linuxbrew/`) - -### Added -- SECURITY.md with risk documentation and disclaimer - -### Improved -- Comprehensive DOCS.md overhaul (architecture, use cases, persistence, troubleshooting, FAQ) -- README.md rewritten as concise landing page with quick start guide -- New branding assets (icon.png, logo.png) -- Added Discord server link to README - -## [0.5.41] - 2026-02-11 - -### Changed -- Update Dockerfile, config.yaml, and run.sh for enhancements -- Update icon and logo images for improved quality - -## [0.5.40] - 2026-02-11 - -### Added -- Additional tools in Dockerfile - -### Changed -- Improved nginx process management in run.sh - -## [0.5.39] - 2026-02-10 - -### Fixed -- Fix OpenClaw installation command in Dockerfile - -## [0.5.38] - 2026-02-10 - -### Changed -- Bump OpenClaw to 2026.2.9 - -## [0.5.37] - 2026-02-09 - -### Added -- OpenAI API integration for Home Assistant Assist pipeline -- Updated translations - -## [0.5.36] - 2026-02-08 - -### Changed -- Documentation updates - -## [0.5.35] - 2026-02-08 - -### Changed -- Update Dockerfile for Homebrew installation improvements - -## [0.5.34] - 2026-02-08 - -### Added -- Install pnpm globally - -### Changed -- Upgrade OpenClaw version to 2026.2.6-3 - -## [0.5.33] - 2026-02-06 - -### Changed -- Enhanced README with images and updated setup instructions - ---- - -For the full commit history, see [GitHub commits](https://github.com/techartdev/OpenClawHomeAssistant/commits/main). +- Bump OpenClaw through the `2026.4.29` and `2026.5.2` upstream releases. From 795f173de8bdb907a37053047e9b30c57b3a2b18 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:26:23 +0300 Subject: [PATCH 4/6] ci: use multi-arch registry image for add-on --- openclaw_assistant/config.yaml | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml index 12f8994..84f3c62 100644 --- a/openclaw_assistant/config.yaml +++ b/openclaw_assistant/config.yaml @@ -3,6 +3,7 @@ version: "0.5.91" slug: openclaw_assistant description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on. url: https://github.com/techartdev/OpenClawHomeAssistant +image: ghcr.io/dmitrykadyshev/openclawhomeassistant arch: - amd64 - aarch64 @@ -14,23 +15,11 @@ hassio_api: false homeassistant_api: false host_network: true -# Home Assistant Ingress (UI inside the add-on page) ingress: true ingress_port: 48099 panel_title: OpenClaw Assistant panel_icon: mdi:robot - -# Liveness probe for the Supervisor: the ingress proxy (nginx) is the add-on's -# front door, so a dead listener means the add-on page is broken. -# Users can turn this off with the Watchdog toggle on the add-on page. watchdog: tcp://[HOST]:48099 - -# Keep Home Assistant backups small by excluding regenerable caches and -# tooling from the add-on backup. Patterns are matched against the full path -# of each item; a matching directory is skipped without descending into it. -# NOTE: restoring a backup replaces /config wholesale, so anything listed here -# is NOT restored and must be reinstalled (brew/npm tools) or is rebuilt on -# demand (caches). User data, skills, agents and secrets are never excluded. backup_exclude: - ".linuxbrew" - ".node_global" @@ -38,7 +27,6 @@ backup_exclude: - ".cache" - "__pycache__" - "*.jsonl.lock" - map: - addon_config:rw - share:rw @@ -76,7 +64,6 @@ options: ha_health_interval: 60 ha_base_url: "" config_backup_keep: 10 - schema: timezone: str enable_terminal: bool? From 6dc9a15dfe6c78134eb84e594ad0ccf9716fa5e3 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:26:35 +0300 Subject: [PATCH 5/6] chore: restore changelog history --- openclaw_assistant/CHANGELOG.md | 371 +++++++++++++++++++++++++++++--- 1 file changed, 344 insertions(+), 27 deletions(-) diff --git a/openclaw_assistant/CHANGELOG.md b/openclaw_assistant/CHANGELOG.md index 6d034a4..7339271 100644 --- a/openclaw_assistant/CHANGELOG.md +++ b/openclaw_assistant/CHANGELOG.md @@ -2,16 +2,6 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be documented in this file. -## [0.5.91] - 2026-09-04 - -### Added -- Add Gitflow-aware GitHub Actions for PR validation and multi-architecture container publishing. -- Publish `amd64`, `aarch64`/`arm64`, and `armv7` images to GitHub Container Registry and assemble a multi-arch manifest. -- Add `develop`, `release/*`, and `main` publishing flows with development, release-candidate, and versioned image tags. - -### Changed -- Bump the Home Assistant add-on version to `0.5.91`. - ## [0.5.90] - 2026-09-02 ### Added @@ -19,17 +9,28 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu - **Home Assistant health sensors** (`ha_health_sensors`, `ha_health_interval`): optionally publish `sensor.openclaw_gateway`, `sensor.openclaw_version`, `sensor.openclaw_gateway_memory`, `sensor.openclaw_disk_used` and `sensor.openclaw_certificate_expiry` so you can alert on gateway health, disk usage and certificate expiry from automations. Requires `homeassistant_token`. New `oc-health` helper (`show` / `once` / `loop`) for previewing and debugging. - **Config snapshots and rollback** (`config_backup_keep`): `openclaw.json` is now snapshotted to `/config/.openclaw/backups` before the add-on's first configuration write of each start, so an unwanted change can be undone. New `oc-config` helper: `list`, `diff`, `restore`, `snapshot`. Restoring always backs up the config it replaces first. Identical configs are not re-snapshotted, and only the newest `config_backup_keep` (default 10) are kept. - New `ha_base_url` option to point the health sensors at a Home Assistant on a non-default port or host (empty = auto-detect). -- `oc-health check`: diagnoses credentials and API connectivity in one command. -- Supervisor watchdog on the ingress port, so Home Assistant restarts the add-on if the ingress proxy stops answering. +- `oc-health check`: diagnoses credentials and API connectivity in one command — which endpoint was chosen, whether a token is present, whether the Supervisor host resolves, and the result of a live probe. +- Supervisor watchdog on the ingress port, so Home Assistant restarts the add-on if the ingress proxy stops answering. Can be turned off with the Watchdog toggle on the add-on page. +- **Smaller Home Assistant backups**: the add-on now declares `backup_exclude`, so regenerable caches and tooling (`.linuxbrew`, `.node_global`, `.npm`, `.cache`, `__pycache__`, stale `*.jsonl.lock` files) are skipped when Home Assistant backs the add-on up. Excluded directories are pruned without being walked, so backups are both smaller and faster. All user state — `openclaw.json`, config snapshots, skills, agent sessions, the `clawd` workspace, keys, secrets and certificates — is still backed up. Note that a restore replaces `/config` wholesale, so excluded tooling must be reinstalled rather than restored. ### Changed -- **Documentation reviewed against OpenClaw `2026.8.2`.** Added a *Device pairing (first connection)* walkthrough and corrected Control UI HTTPS/pairing guidance. -- Startup warnings about legacy `/config/.node_global` and `/config/.linuxbrew` directories now reflect their backup exclusion behavior. +- **Documentation reviewed against OpenClaw `2026.8.2`.** Added a *Device pairing (first connection)* walkthrough — the gateway host is the add-on container, so `openclaw devices list` / `openclaw devices approve ` in the add-on terminal is all that is needed, and the `ssh -N -L` hint printed by `openclaw dashboard` does not apply here. Corrected the long-standing claim that the Control UI requires HTTPS or localhost: upstream removed that restriction (device identity is signed with pure-JS Ed25519 on any origin), so the guidance now recommends HTTPS for token confidentiality rather than presenting it as mandatory. Rewrote the two error-1008 troubleshooting entries around pairing, and marked `controlui_disable_device_auth` as deprecated and inert in all six locales. +- Startup warnings about legacy `/config/.node_global` and `/config/.linuxbrew` directories no longer claim they inflate Home Assistant backups (they are now excluded). The warning explains they only use disk space and gives the exact removal command. ### Fixed -- Removed the retired `gateway.controlUi.dangerouslyDisableDeviceAuth` configuration key and fixed `lan_https` proxy attribution for OpenClaw `2026.8.2`. -- Fixed Home Assistant health sensor endpoint selection, retry behavior, and failure logging. -- Fixed gateway restart-loop recovery and restart backoff after OpenClaw upgrades. +- **Stopped writing a retired OpenClaw key.** The add-on set `gateway.controlUi.dangerouslyDisableDeviceAuth` on every start to skip Control UI device pairing. OpenClaw retired that flag in the `2026.8.x` line: it is inert, the security audit reports it as a dangerous key, and `openclaw doctor --fix` deletes it — so the add-on was re-adding it every boot and fighting Doctor. The add-on now removes the key instead, which also clears the "dangerous config flags enabled" startup warning. Browsers pair once via `openclaw devices approve `. +- **Health sensors could not reach a Home Assistant that serves HTTPS**: endpoint detection only ever tried plain `http://`, which a TLS listener answers by closing the connection — surfacing as `HTTP 000` (curl: *Empty reply from server*). Detection now probes `https` and `http` across `127.0.0.1`, `localhost`, `homeassistant` and `homeassistant.local`, and uses the first endpoint that answers. TLS verification is skipped for these local endpoints because Home Assistant's certificate is normally issued for its external hostname and never matches a loopback address; the connection stays on the local host/LAN. +- Detection is retried on later cycles instead of only at startup, so sensors still come up when the add-on starts before Home Assistant is listening. +- **Health sensors could not reach Home Assistant (`HTTP 000`)**: `oc-health` preferred the Supervisor proxy whenever `SUPERVISOR_TOKEN` was present, but this add-on runs with `host_network: true`, so the container is not on the Supervisor bridge network and the `supervisor` hostname does not resolve. Every sensor update failed at the connection level. It now prefers the user's long-lived token against the host's Home Assistant on `localhost:8123`, and only uses the Supervisor proxy when that hostname actually resolves. +- The same endpoint-selection bug in the MCP auto-configuration would have registered an unreachable `http://supervisor/core/api/mcp` URL; it now applies the same reachability check. +- Health sensor failures are logged once per status change instead of one line per entity per interval, so an outage can no longer fill the add-on log (previously ~7000 lines a day). +- Failures now explain themselves: `HTTP 000` reports that Home Assistant is unreachable at the resolved endpoint, `401`/`403` points at the token, rather than printing a bare status code. + +- **`proxy_attribution_required` in `lan_https` mode**: OpenClaw `2026.8.2` began rejecting requests that carry forwarded identity headers from an untrusted source. The add-on's built-in HTTPS proxy runs on loopback and sets `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto`, but loopback was never added to `gateway.trustedProxies`, so the gateway refused every request with `proxy_attribution_required`. `lan_https` now trusts `127.0.0.1` and `::1` (merged with any `gateway_trusted_proxies` you set, and deduplicated). As a side benefit the gateway can now attribute the real LAN client IP for rate limiting instead of seeing every request as loopback. +- **Gateway restart loop was not actually recovering** (follow-up to `0.5.104`): the automatic repair ran `openclaw doctor --fix` without `--non-interactive`. With no TTY, Doctor printed advisory notices and skipped the migration, so the loop continued. It now runs `openclaw doctor --fix --non-interactive --yes`, the documented automation form, and reports clearly when Doctor exits non-zero because a legacy source or interrupted `.doctor-importing` claim remains. +- **Restart backoff never escalated**: gateway uptime was measured after the daemon-detection retry loop, so its sleeps counted as uptime. A gateway that died ~45s into startup measured ~65s, tripped the 60s "healthy" reset, and pinned the retry interval at 2s forever. Uptime is now captured the moment the runtime exits, and the healthy threshold is 120s — comfortably above a normal ~45s cold start. The repair is also attempted after 2 consecutive failures instead of 3, since each failed boot costs about a minute. +- **Gateway restart loop after an OpenClaw upgrade**: releases that gate startup behind a data migration (such as the legacy workspace state check in `2026.8.2`) made the supervisor restart the gateway forever, writing a stability bundle on every attempt. The add-on now runs the documented `openclaw doctor --fix` repair once per start after repeated failures — snapshotting `openclaw.json` first so it is reversible — and backs off between restarts (2s doubling to a 60s cap) instead of retrying every 2 seconds. After five consecutive failures it logs the exact diagnostic commands to run. The terminal and add-on page stay available throughout. +- Documentation listed Node.js 22 in the bundled tools table; the image has shipped Node.js 24 since `0.5.83`. ## [0.5.89] - 2026-09-02 @@ -39,12 +40,12 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [0.5.88] - 2026-08-25 ### Fixed -- Preserve explicit `false` values for boolean add-on options instead of replacing them with `true` defaults during startup. +- Preserve explicit `false` values for boolean add-on options instead of replacing them with `true` defaults during startup. This restores settings such as strict Control UI device authentication, disabled terminal access, and IPv6-capable DNS behavior after an add-on restart or rebuild. ## [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`. +- 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 @@ -54,13 +55,14 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [0.5.84] - 2026-07-17 ### Changed -- Bundle `mcporter@0.12.3` in the add-on image. +- 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 format. -- Regenerate malformed `lan_https` CA/server certificates with proper X.509 extensions. +- 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 @@ -85,24 +87,339 @@ All notable changes to the OpenClaw Assistant Home Assistant Add-on will be docu ## [0.5.75] - 2026-05-28 ### Changed -- Add backup-friendly persistence defaults for optional toolchains. +- **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` and add `cmake` for source builds when needed. +- 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 -- Add the add-on-native `oc-gateway` helper for container-supervised runtime management. +- 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 selects the unavailable Brave search provider. +- 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. +- 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. + +## [0.5.52] - 2026-02-23 + +### Added +- New add-on option `gateway_env_vars` that accepts a list of `{name, value}` objects from Home Assistant UI and safely injects values into the gateway process at startup (max 50 vars, key <=255 chars, value <=10000 chars). +- Guard `gateway_env_vars` from overriding reserved runtime/proxy/`OPENCLAW_*` keys. +- Keep legacy string/object input formats for backward compatibility. + +## [0.5.51] - 2026-02-23 + +### Fixed +- **`web_fetch failed: fetch failed`**: changed `force_ipv4_dns` default to **true**. Node 22 tries IPv6 first; most HAOS VMs lack IPv6 egress, causing outbound `web_fetch` / HTTP tool calls to time out. + +### Added +- **`nginx_log_level` option** (`minimal` / `full`, default `minimal`): suppresses repetitive Home Assistant health-check and polling requests (`GET /`, `GET /v1/models`, `POST /tools/invoke`) from the nginx access log. + +## [0.5.50] - 2026-02-23 + +**[!WARNING!]** +This update contains lots of changes. It is adviced to backup before installing! + +### Changed +- **Upgraded OpenClaw to v2026.2.22-2** — includes major gateway/auth/pairing fixes and security hardening. +- Precreate `$OPENCLAW_CONFIG_DIR/identity` on startup to prevent `EACCES` errors on CLI commands that need device identity. +- Gateway token is auto-constructed from detected LAN IP when `lan_https` is active and `gateway_public_url` is empty. +- Config helper now receives the effective internal port (gateway_port + 1 in lan_https mode). + +### Notes — v2026.2.22 impact on this add-on +- **Pairing fixes (loopback)**: v2026.2.22 auto-approves loopback scope-upgrade pairing requests, includes `operator.read`/`operator.write` in default scope bundles, and treats `operator.admin` as satisfying other scopes. This greatly improves `local_only` mode reliability. +- **`dangerouslyDisableDeviceAuth` security warning**: v2026.2.22 now emits a startup warning when this flag is active. The warning is **expected and harmless** for `lan_https` mode — the flag is still required because LAN browser connections through the HTTPS proxy are not considered loopback by the gateway. Token auth remains enforced. +- **Gateway lock improvements**: stale-lock detection now uses port reachability, reducing false "already running" errors after unclean restarts. +- **Log file size cap**: new `logging.maxFileBytes` default (500 MB) prevents disk exhaustion from log storms. +- **`wss://` default for remote onboarding**: validates our HTTPS proxy approach as the correct direction. + +### Added +- **Disk-space monitoring on the landing page** — shows total / used / available with colour-coded indicator (🟢 / 🟡 / 🔴). +- **Low-disk warning banner** appears automatically when usage exceeds 90 %. +- **`oc-cleanup` terminal command** — interactive helper that shows cache sizes (npm, pnpm, OpenClaw, Homebrew, pycache, tmp) and lets users reclaim space with a menu-driven cleanup. +- Startup disk-space check with log warnings when the overlay is above 75 % or 90 %. +- **`access_mode` preset option** — simplifies secure access configuration with one setting: + - `custom` (default, backward-compatible): use individual gateway settings + - `local_only`: loopback + token (Ingress/terminal only) + - `lan_https`: **built-in HTTPS reverse proxy for LAN access** (recommended for phones/tablets) + - `lan_reverse_proxy`: LAN bind + trusted-proxy for external reverse proxy (NPM, Caddy, Traefik) + - `tailnet_https`: Tailscale interface bind + token auth +- **Built-in TLS certificate generation** (`lan_https` mode): + - Auto-generates a local CA + server certificate on first startup + - Server cert is regenerated automatically when LAN IP changes + - CA certificate downloadable from the landing page for one-tap phone trust + - nginx HTTPS server block terminates TLS and proxies to the loopback gateway +- **Overhauled landing page** with: + - Real-time status cards (gateway health, secure context, access mode) + - Access wizard with step-by-step guidance per mode + - Error translation — maps raw errors like `1008: requires device identity` to friendly messages with fixes + - CA certificate download button (lan_https mode) + - Migration banner for users on `custom` mode recommending a preset + - Collapsible reverse-proxy recipes (NPM / Caddy / Traefik / Tailscale) +- Added `openssl` to Docker image for TLS certificate generation. +- Translations for `access_mode` in all 6 languages (EN, BG, DE, ES, PL, PT-BR). + +### Fixed +- **`lan_https` — error 1008 "pairing required"**: auto-set `gateway.controlUi.dangerouslyDisableDeviceAuth: true` to skip interactive device pairing (token auth remains enforced). Replaces the invalid `pairingMode` key that caused `Unrecognized key` config errors. +- Config helper now removes stale/invalid keys (e.g. `pairingMode`) from `controlUi` on startup. +- Landing page error translation now covers "pairing required" and "origin not allowed" errors with correct fix guidance. +- Dropdown translations for `access_mode`, `gateway_mode`, `gateway_bind_mode`, and `gateway_auth_mode` now show human-readable labels in all 6 languages. +- **`lan_https` — error 1008 "origin not allowed"**: auto-configure `gateway.controlUi.allowedOrigins` with the HTTPS proxy origins (LAN IP, `homeassistant.local`, `homeassistant`) so the Control UI WebSocket is accepted. + +## [0.5.49] - 2026-02-22 + +### Added +- New add-on option `http_proxy` for configuring outbound HTTP/HTTPS proxy from Home Assistant settings. + +### Changed +- Export `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, and `https_proxy` from add-on config at startup. +- Add translations for the new `http_proxy` option. +- Document proxy configuration in README and DOCS. + +## [0.5.48] - 2026-02-22 + +### Changed +- Bump OpenClaw to 2026.2.21-2. +- Add Home Assistant `share` and `media` mounts to the add-on (`map: share:rw, media:rw`). +- Keep official OpenClaw npm release and add startup proxy shim for `HTTP_PROXY/HTTPS_PROXY` support in undici fetch. + +## [0.5.47] - 2026-02-21 + +### Added +- Add new `gateway_bind_mode` values: `auto` and `tailnet`. + +### Changed +- Update startup helper validation and CLI usage to support `auto|loopback|lan|tailnet` bind modes. +- Update add-on translations and docs for the expanded gateway bind mode options. + +## [0.5.46] - 2026-02-18 + +### Added +- New add-on option `force_ipv4_dns` to enable IPv4-first DNS ordering for Node network calls (`NODE_OPTIONS=--dns-result-order=ipv4first`), helping Telegram connectivity on IPv6-broken networks. + +### Changed +- Added translations for `force_ipv4_dns` option. +- Updated docs with `force_ipv4_dns` configuration and Telegram network troubleshooting note. +- Bump OpenClaw to 2026.2.17 + +## [0.5.45] - 2026-02-16 + +### Changed +- Bump OpenClaw to 2026.2.15 + +## [0.5.44] - 2026-02-14 + +### Changed +- Bump OpenClaw to 2026.2.13 + +## [0.5.43] - 2026-02-13 + +### Changed +- Bump OpenClaw to 2026.2.12 + +### Added +- Portuguese (Brazil) translation (`pt-BR.yaml`) by medeirosiago + +## [0.5.42] - 2026-02-12 + +### Changed +- Change nginx ingress port from 8099 to 48099 to avoid conflicts with NextCloud and other services +- Persist Homebrew and brew-installed packages across container rebuilds (symlink to `/config/.linuxbrew/`) + +### Added +- SECURITY.md with risk documentation and disclaimer + +### Improved +- Comprehensive DOCS.md overhaul (architecture, use cases, persistence, troubleshooting, FAQ) +- README.md rewritten as concise landing page with quick start guide +- New branding assets (icon.png, logo.png) +- Added Discord server link to README + +## [0.5.41] - 2026-02-11 + +### Changed +- Update Dockerfile, config.yaml, and run.sh for enhancements +- Update icon and logo images for improved quality + +## [0.5.40] - 2026-02-11 + +### Added +- Additional tools in Dockerfile + +### Changed +- Improved nginx process management in run.sh + +## [0.5.39] - 2026-02-10 + +### Fixed +- Fix OpenClaw installation command in Dockerfile + +## [0.5.38] - 2026-02-10 + +### Changed +- Bump OpenClaw to 2026.2.9 + +## [0.5.37] - 2026-02-09 + +### Added +- OpenAI API integration for Home Assistant Assist pipeline +- Updated translations + +## [0.5.36] - 2026-02-08 + +### Changed +- Documentation updates + +## [0.5.35] - 2026-02-08 + +### Changed +- Update Dockerfile for Homebrew installation improvements + +## [0.5.34] - 2026-02-08 + +### Added +- Install pnpm globally + +### Changed +- Upgrade OpenClaw version to 2026.2.6-3 + +## [0.5.33] - 2026-02-06 + +### Changed +- Enhanced README with images and updated setup instructions + +--- + +For the full commit history, see [GitHub commits](https://github.com/techartdev/OpenClawHomeAssistant/commits/main). From ced8fe82396a31071c27cf66e0d5769a9a688948 Mon Sep 17 00:00:00 2001 From: dk Date: Fri, 4 Sep 2026 11:26:58 +0300 Subject: [PATCH 6/6] ci: preserve add-on config while enabling registry image --- openclaw_assistant/config.yaml | 142 +++++++++++++++++++++++++++++++-- 1 file changed, 136 insertions(+), 6 deletions(-) diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml index 84f3c62..cb4356e 100644 --- a/openclaw_assistant/config.yaml +++ b/openclaw_assistant/config.yaml @@ -15,55 +15,183 @@ hassio_api: false homeassistant_api: false host_network: true +# Home Assistant Ingress (UI inside the add-on page) ingress: true ingress_port: 48099 panel_title: OpenClaw Assistant panel_icon: mdi:robot + +# Liveness probe for the Supervisor: the ingress proxy (nginx) is the add-on's +# front door, so a dead listener means the add-on page is broken. +# Users can turn this off with the Watchdog toggle on the add-on page. watchdog: tcp://[HOST]:48099 + +# Keep Home Assistant backups small by excluding regenerable caches and +# tooling from the add-on backup. Patterns are matched against the full path +# of each item; a matching directory is skipped without descending into it. +# NOTE: restoring a backup replaces /config wholesale, so anything listed here +# is NOT restored and must be reinstalled (brew/npm tools) or is rebuilt on +# demand (caches). User data, skills, agents and secrets are never excluded. backup_exclude: - - ".linuxbrew" - - ".node_global" - - ".npm" - - ".cache" - - "__pycache__" - - "*.jsonl.lock" + - ".linuxbrew" # Homebrew install + cellar (persist_brew_tools) + - ".node_global" # npm/pnpm global installs (persist_node_global) + - ".npm" # npm download cache + - ".cache" # generic tool caches (Chromium, build artifacts) + - "__pycache__" # Python bytecode, at any depth + - "*.jsonl.lock" # stale session locks; never useful to restore + map: - addon_config:rw - share:rw - media:rw options: timezone: "Europe/Sofia" + + # Enable web terminal inside Home Assistant (Ingress) via ttyd enable_terminal: true + + # Terminal port (change if 7681 conflicts with another service) terminal_port: 7681 + + # Public base URL for opening the Gateway Web UI in a new tab (not embedded). + # Recommended: NO trailing slash. + # Example: "https://example.duckdns.org:12345" or "http://192.168.1.10:18789" gateway_public_url: "" + + # Optional: Home Assistant long-lived token (for local HA API scripts/tools) homeassistant_token: "" + + # Optional: outbound HTTP/HTTPS proxy for OpenClaw network access. + # Example: "http://192.168.2.1:3128" http_proxy: "" + + # Optional: Router SSH defaults (leave empty if you don't need router automation) + # This is a generic SSH configuration intended for a router/firewall or any network device + # reachable from inside the HA host LAN. router_ssh_host: "" router_ssh_user: "" router_ssh_key_path: "/data/keys/router_ssh" + + # Cleanup stale session lock files left after crashes/restarts 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) + # - tailnet: bind to Tailscale IP only (accessible only via Tailscale — recommended for remote access) + # Default is loopback for security. gateway_bind_mode: loopback + + # Gateway port to listen on gateway_port: 18789 + + # Access mode preset — simplifies secure access configuration. + # custom: use individual gateway_bind_mode / auth_mode settings (backward compatible) + # local_only: loopback + token auth (Ingress / terminal only, most secure) + # lan_https: Built-in HTTPS reverse proxy for LAN access (recommended for phones/tablets) + # lan_reverse_proxy: LAN bind + trusted-proxy for an external reverse proxy (NPM, Caddy, …) + # tailnet_https: Tailscale interface bind + token auth access_mode: custom + + # Gateway authentication mode: + # - token: standard token auth (default) + # - trusted-proxy: trust auth headers from configured reverse proxies gateway_auth_mode: token + + # Comma-separated trusted proxy IP/CIDR list for trusted-proxy mode. + # 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 enable_openai_api: false + + # Force IPv4-first DNS result ordering for Node fetch/network calls. + # Most HAOS VMs lack IPv6 egress, causing web_fetch / Telegram timeouts. + # Default: true (recommended). Set to false only if you need IPv6. force_ipv4_dns: true + + # Nginx access log verbosity: + # full: log all requests (useful for debugging) + # minimal: suppress repetitive HA health-check and polling requests (default) nginx_log_level: minimal + + # Environment variables to pass to the gateway process at startup. + # Format: list of objects with name/value fields. + # Example: + # gateway_env_vars: + # - name: OPENAI_API_KEY + # value: "sk-abc123" + # - name: LOG_LEVEL + # value: "debug" + # Reserved keys are blocked to protect runtime/security + # (e.g. PATH, HOME, NODE_OPTIONS, NODE_PATH, OPENCLAW_*, proxy vars). + # 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 + + # Resource profile — keeps the add-on well-behaved on low-power hardware. + # auto: detect from CPU architecture and total RAM (recommended) + # low: smallest Node heap; also disables OpenClaw browser automation + # (only for keys you have not set yourself in openclaw.json) + # balanced: moderate Node heap for 2-6 GB systems + # high: no heap cap; leaves Node's own default in place + # Only 'low' selected explicitly writes to openclaw.json; 'auto' never does. resource_profile: auto + + # Publish gateway status, version, memory, disk usage and certificate expiry + # as Home Assistant sensor entities (sensor.openclaw_*) so you can alert on + # them. Requires homeassistant_token to be set. ha_health_sensors: false + + # How often (seconds) to refresh the health sensors. Range 15-3600. ha_health_interval: 60 + + # Base URL of your Home Assistant instance, used by the health sensors. + # Leave empty to auto-detect (tries https/http on 127.0.0.1, localhost, + # homeassistant and homeassistant.local, port 8123). + # Set this if Home Assistant uses a non-default port or another host, + # e.g. "https://192.168.1.10:8123". ha_base_url: "" + + # How many openclaw.json snapshots to keep in /config/.openclaw/backups. + # A snapshot is taken before the add-on's first config write of each start, + # so a bad change can be rolled back with 'oc-config restore'. 0 disables. config_backup_keep: 10 + schema: timezone: str enable_terminal: bool? @@ -71,9 +199,11 @@ schema: gateway_public_url: str? homeassistant_token: str? http_proxy: str? + router_ssh_host: str router_ssh_user: str router_ssh_key_path: str + clean_session_locks_on_start: bool? clean_session_locks_on_exit: bool? persist_node_global: bool?