From b87702bef0c5cefdc68156c59ca415e7626e852b Mon Sep 17 00:00:00 2001 From: techartdev Date: Fri, 20 Feb 2026 14:08:17 +0200 Subject: [PATCH] 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 | 18 +++++++++++++++++ custom_components/openclaw/api.py | 20 ++++++++++--------- custom_components/openclaw/config_flow.py | 19 +++++++++++++++++- custom_components/openclaw/manifest.json | 2 +- custom_components/openclaw/strings.json | 1 + .../openclaw/translations/en.json | 1 + 6 files changed, 50 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4db9838..a9ee5c2 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/custom_components/openclaw/api.py b/custom_components/openclaw/api.py index 3f81936..fdcdcea 100644 --- a/custom_components/openclaw/api.py +++ b/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 + await self.async_get_models() + return True async def async_close(self) -> None: """Close the HTTP session.""" diff --git a/custom_components/openclaw/config_flow.py b/custom_components/openclaw/config_flow.py index c13af05..a57cdda 100644 --- a/custom_components/openclaw/config_flow.py +++ b/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( diff --git a/custom_components/openclaw/manifest.json b/custom_components/openclaw/manifest.json index cfa8327..6478a72 100644 --- a/custom_components/openclaw/manifest.json +++ b/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"] } diff --git a/custom_components/openclaw/strings.json b/custom_components/openclaw/strings.json index d68172d..424917c 100644 --- a/custom_components/openclaw/strings.json +++ b/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": { diff --git a/custom_components/openclaw/translations/en.json b/custom_components/openclaw/translations/en.json index d68172d..424917c 100644 --- a/custom_components/openclaw/translations/en.json +++ b/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": {