Update changelog, enhance error handling, and improve user feedback for OpenClaw integration

- Documented changes in changelog for version 0.1.3.
- Improved error handling in async_check_connection to propagate OpenClawApiError.
- Added clear error messages for users regarding OpenAI API settings in config flow.
- Updated translations to include new error messages related to OpenAI API status.

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to the OpenClaw Home Assistant Integration will be documented in this file.
 
+## [0.1.3] - 2026-02-20
+
+### Fixed
+- `async_check_connection()` no longer silently swallows `OpenClawApiError`.
+  Previously any API-level error (e.g. gateway returning HTML) was caught and
+  converted to a generic "Cannot connect" message with no indication of the
+  real cause. The error is now propagated to the config flow.
+- Config flow now catches `OpenClawApiError` separately and shows a clear,
+  actionable error message: **"openai_api_disabled"** — pointing the user to
+  enable `enable_openai_api` in the addon settings and restart.
+- Auto-discovery now logs a `WARNING` when `enable_openai_api` is `false` in
+  the addon options, making the issue visible in the HA log before setup fails.
+
+### Changed
+- The `enable_openai_api` addon option (default `false`) must be `true` for the
+  integration to connect. The `/v1/models` probe endpoint requires the
+  OpenAI-compatible API layer to be active.
+
 ## [0.1.2] - 2026-02-20
 
 ### Fixed

custom_components/openclaw/api.py

@@ -292,20 +292,22 @@ class OpenClawApiClient:
         Uses the /v1/models endpoint as a lightweight probe — the only
         consistently available GET endpoint on the OpenClaw gateway.
 
+        The /v1/models endpoint requires 'enable_openai_api' to be enabled in
+        the addon configuration. If the gateway returns HTML instead of JSON,
+        the OpenAI-compatible API is likely disabled and an OpenClawApiError
+        is raised so the caller can surface a meaningful error.
+
         Returns:
             True if connected and authenticated.
 
         Raises:
-            OpenClawAuthError: If authentication fails (re-raised so callers
-                can distinguish bad tokens from unreachable gateways).
+            OpenClawAuthError: If authentication fails.
+            OpenClawApiError: If the gateway returns an unexpected response
+                (e.g. HTML when enable_openai_api is disabled).
+            OpenClawConnectionError: If the gateway is unreachable.
         """
-        try:
         await self.async_get_models()
         return True
-        except OpenClawAuthError:
-            raise
-        except OpenClawApiError:
-            return False
 
     async def async_close(self) -> None:
         """Close the HTTP session."""

custom_components/openclaw/config_flow.py

@@ -18,7 +18,7 @@ from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
 
-from .api import OpenClawApiClient, OpenClawAuthError, OpenClawConnectionError
+from .api import OpenClawApiClient, OpenClawApiError, OpenClawAuthError, OpenClawConnectionError
 from .const import (
     ADDON_CONFIGS_ROOT,
     ADDON_SLUG,
@@ -163,6 +163,15 @@ async def _async_try_discover_addon(hass: HomeAssistant) -> dict[str, Any] | Non
         )
         return None
 
+    # Warn early if the OpenAI-compatible API is disabled — /v1/models will return
+    # HTML and the connection probe will fail with a misleading error.
+    if not addon_options.get("enable_openai_api", False):
+        _LOGGER.warning(
+            "Addon option 'enable_openai_api' is false. "
+            "The integration requires this to be enabled. "
+            "Enable it in the addon configuration and restart the addon."
+        )
+
     # ── Step 2: Find the addon config directory on the filesystem ────
     config_dir = await hass.async_add_executor_job(_find_addon_config_dir)
     if not config_dir:
@@ -270,6 +279,10 @@ class OpenClawConfigFlow(ConfigFlow, domain=DOMAIN):
             except OpenClawConnectionError:
                 connected = False
                 errors["base"] = "cannot_connect"
+            except OpenClawApiError as err:
+                connected = False
+                errors["base"] = "openai_api_disabled"
+                _LOGGER.warning("Gateway API error during connection check: %s", err)
 
             if connected:
                 return self.async_create_entry(
@@ -313,6 +326,10 @@ class OpenClawConfigFlow(ConfigFlow, domain=DOMAIN):
             except OpenClawConnectionError:
                 errors["base"] = "cannot_connect"
                 connected = False
+            except OpenClawApiError as err:
+                errors["base"] = "openai_api_disabled"
+                connected = False
+                _LOGGER.warning("Gateway API error during connection check: %s", err)
 
             if connected:
                 return self.async_create_entry(

custom_components/openclaw/manifest.json

@@ -8,7 +8,7 @@
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/techartdev/OpenClawHomeAssistant/issues",
   "requirements": [],
-  "version": "0.1.2",
+  "version": "0.1.3",
   "dependencies": ["conversation"],
   "after_dependencies": ["hassio"]
 }

custom_components/openclaw/strings.json

@@ -24,6 +24,7 @@
     "error": {
       "cannot_connect": "Cannot connect to the OpenClaw gateway. Ensure the addon is running.",
       "invalid_auth": "Invalid gateway token. Check your OpenClaw configuration.",
+      "openai_api_disabled": "The gateway returned an unexpected response — the OpenAI-compatible API is likely disabled. In the OpenClaw addon settings enable 'enable_openai_api', restart the addon, and try again.",
       "unknown": "An unexpected error occurred."
     },
     "abort": {

custom_components/openclaw/translations/en.json

@@ -24,6 +24,7 @@
     "error": {
       "cannot_connect": "Cannot connect to the OpenClaw gateway. Ensure the addon is running.",
       "invalid_auth": "Invalid gateway token. Check your OpenClaw configuration.",
+      "openai_api_disabled": "The gateway returned an unexpected response — the OpenAI-compatible API is likely disabled. In the OpenClaw addon settings enable 'enable_openai_api', restart the addon, and try again.",
       "unknown": "An unexpected error occurred."
     },
     "abort": {