merge: incorporate PR techartdev#9 debug logging

Adds opt-in CONF_DEBUG_LOGGING toggle for API request tracing.
Enhanced debug log to include resolved area name alongside
agent ID and session ID.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DarrenBenson

custom_components/openclaw/__init__.py

@@ -66,6 +66,7 @@
     CONF_BROWSER_VOICE_LANGUAGE,
     CONF_VOICE_PROVIDER,
     CONF_THINKING_TIMEOUT,
+    CONF_DEBUG_LOGGING,
     CONTEXT_STRATEGY_TRUNCATE,
     DEFAULT_AGENT_ID,
     DEFAULT_VOICE_AGENT_ID,
@@ -79,6 +80,7 @@
     DEFAULT_BROWSER_VOICE_LANGUAGE,
     DEFAULT_VOICE_PROVIDER,
     DEFAULT_THINKING_TIMEOUT,
+    DEFAULT_DEBUG_LOGGING,
     DOMAIN,
     EVENT_MESSAGE_RECEIVED,
     EVENT_TOOL_INVOKED,
@@ -162,6 +164,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: OpenClawConfigEntry) ->
         verify_ssl=verify_ssl,
         session=session,
         agent_id=agent_id,
+        debug_logging=entry.options.get(CONF_DEBUG_LOGGING, DEFAULT_DEBUG_LOGGING),
     )
 
     coordinator = OpenClawCoordinator(hass, client)
@@ -880,6 +883,10 @@ def websocket_get_settings(
                     CONF_THINKING_TIMEOUT,
                     DEFAULT_THINKING_TIMEOUT,
                 ),
+                CONF_DEBUG_LOGGING: options.get(
+                    CONF_DEBUG_LOGGING,
+                    DEFAULT_DEBUG_LOGGING,
+                ),
                 "language": hass.config.language,
             },
         )

custom_components/openclaw/api.py

@@ -52,6 +52,7 @@ def __init__(
         verify_ssl: bool = True,
         session: aiohttp.ClientSession | None = None,
         agent_id: str = "main",
+        debug_logging: bool = False,
     ) -> None:
         """Initialize the API client.
 
@@ -71,6 +72,7 @@ def __init__(
         self._verify_ssl = verify_ssl
         self._session = session
         self._agent_id = agent_id
+        self._debug_logging = debug_logging
         self._base_url = f"{'https' if use_ssl else 'http'}://{host}:{port}"
         # ssl=False disables cert verification for self-signed certs;
         # ssl=None uses default verification.
@@ -85,6 +87,20 @@ def update_token(self, token: str) -> None:
         """Update the authentication token (e.g., after addon restart)."""
         self._token = token
 
+
+    def _log_request(self, label: str, agent_id: str | None, model: str | None, session_id: str | None, headers: dict[str, str]) -> None:
+        if not self._debug_logging:
+            return
+        safe_headers = {k: ("<redacted>" if k.lower() == "authorization" else v) for k, v in headers.items()}
+        _LOGGER.warning(
+            "OpenClaw API %s: agent=%s model=%s session=%s headers=%s",
+            label,
+            agent_id or self._agent_id or "main",
+            model,
+            session_id,
+            safe_headers,
+        )
+
     def _headers(
         self,
         agent_id: str | None = None,
@@ -239,6 +255,8 @@ async def async_send_message(
         session = await self._get_session()
         url = f"{self._base_url}{API_CHAT_COMPLETIONS}"
 
+        self._log_request("chat", agent_id, payload.get("model"), session_id, headers)
+
         try:
             async with session.post(
                 url,
@@ -307,6 +325,8 @@ async def async_stream_message(
         session = await self._get_session()
         url = f"{self._base_url}{API_CHAT_COMPLETIONS}"
 
+        self._log_request("chat", agent_id, payload.get("model"), session_id, headers)
+
         try:
             async with session.post(
                 url,
@@ -372,6 +392,8 @@ async def async_check_connection(self) -> bool:
         session = await self._get_session()
         url = f"{self._base_url}{API_CHAT_COMPLETIONS}"
 
+        self._log_request("chat", agent_id, payload.get("model"), session_id, headers)
+
         try:
             async with session.post(
                 url,

custom_components/openclaw/config_flow.py

@@ -54,6 +54,7 @@
     CONF_BROWSER_VOICE_LANGUAGE,
     CONF_VOICE_PROVIDER,
     CONF_THINKING_TIMEOUT,
+    CONF_DEBUG_LOGGING,
     BROWSER_VOICE_LANGUAGES,
     CONTEXT_STRATEGY_CLEAR,
     CONTEXT_STRATEGY_TRUNCATE,
@@ -71,6 +72,7 @@
     DEFAULT_BROWSER_VOICE_LANGUAGE,
     DEFAULT_VOICE_PROVIDER,
     DEFAULT_THINKING_TIMEOUT,
+    DEFAULT_DEBUG_LOGGING,
     DEFAULT_VOICE_AGENT_ID,
     DOMAIN,
     OPENCLAW_CONFIG_REL_PATH,
@@ -537,6 +539,13 @@ async def async_step_init(
                 CONF_VOICE_PROVIDER,
                 default=selected_provider,
             ): vol.In(["browser", "assist_stt"]),
+            vol.Optional(
+                CONF_DEBUG_LOGGING,
+                default=options.get(
+                    CONF_DEBUG_LOGGING,
+                    DEFAULT_DEBUG_LOGGING,
+                ),
+            ): bool,
             vol.Optional(
                 CONF_THINKING_TIMEOUT,
                 default=options.get(

custom_components/openclaw/const.py

@@ -39,6 +39,7 @@
 CONF_VOICE_PROVIDER = "voice_provider"
 CONF_BROWSER_VOICE_LANGUAGE = "browser_voice_language"
 CONF_THINKING_TIMEOUT = "thinking_timeout"
+CONF_DEBUG_LOGGING = "debug_logging"
 
 DEFAULT_AGENT_ID = "main"
 DEFAULT_VOICE_AGENT_ID = ""
@@ -53,6 +54,7 @@
 DEFAULT_VOICE_PROVIDER = "browser"
 DEFAULT_BROWSER_VOICE_LANGUAGE = "auto"
 DEFAULT_THINKING_TIMEOUT = 120
+DEFAULT_DEBUG_LOGGING = False
 
 BROWSER_VOICE_LANGUAGES: tuple[str, ...] = (
 	"auto",

custom_components/openclaw/conversation.py

@@ -29,12 +29,14 @@
     CONF_AGENT_ID,
     CONF_CONTEXT_MAX_CHARS,
     CONF_CONTEXT_STRATEGY,
+    CONF_DEBUG_LOGGING,
     CONF_INCLUDE_EXPOSED_CONTEXT,
     CONF_VOICE_AGENT_ID,
     DEFAULT_ASSIST_SESSION_ID,
     DEFAULT_AGENT_ID,
     DEFAULT_CONTEXT_MAX_CHARS,
     DEFAULT_CONTEXT_STRATEGY,
+    DEFAULT_DEBUG_LOGGING,
     DEFAULT_INCLUDE_EXPOSED_CONTEXT,
     DATA_MODEL,
     DOMAIN,
@@ -182,6 +184,14 @@ async def async_process(
         else:
             voice_headers = None
 
+        if options.get(CONF_DEBUG_LOGGING, DEFAULT_DEBUG_LOGGING):
+            _LOGGER.info(
+                "OpenClaw Assist routing: agent=%s session=%s area=%s",
+                resolved_agent_id or "main",
+                conversation_id,
+                voice_headers.get("x-openclaw-area", "unknown") if voice_headers else "none",
+            )
+
         try:
             full_response = await self._get_response(
                 client,

custom_components/openclaw/translations/en.json

@@ -52,7 +52,8 @@
           "allow_brave_webspeech": "Allow Web Speech in Brave (experimental)",
           "voice_provider": "Voice input provider (browser or HA STT)",
           "browser_voice_language": "Browser voice language",
-          "thinking_timeout": "Response timeout (seconds)"
+          "thinking_timeout": "Response timeout (seconds)",
+          "debug_logging": "Enable debug logging"
         }
       }
     }