Merge pull request #37 from techartdev/ha_ai_pipeline_integration

Integrating OpenClaw with Home Assistant Assist pipeline

DOCS.md

@@ -169,6 +169,11 @@ Control how the OpenClaw gateway operates and binds to the network:
   - Port number for the gateway to listen on
   - Only applies when `gateway_mode` is **local**
 
+- **`enable_openai_api`** (bool, default **false**)
+  - Enable the OpenAI-compatible Chat Completions endpoint (`/v1/chat/completions`)
+  - Required for integrating with HA Assist pipeline via [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation)
+  - See section 6 for full setup instructions
+
 - **`allow_insecure_auth`** (bool, default **false**)
   - Allow HTTP authentication for gateway access on LAN
   - **WARNING**: Only enable if using HTTP (not HTTPS) for `gateway_public_url`
@@ -209,6 +214,81 @@ How to provide the key:
 
 ---
 
+## 6) Integrate with Home Assistant Assist Pipeline
+
+OpenClaw's Gateway exposes an **OpenAI-compatible Chat Completions endpoint**. This means you can use OpenClaw as a **conversation agent** in Home Assistant's Assist pipeline — enabling voice control, automations, and smart home commands powered by OpenClaw.
+
+### How it works
+
+1. OpenClaw Gateway serves `POST /v1/chat/completions` (same port as the gateway)
+2. [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation) (HACS integration) connects HA's Assist pipeline to any OpenAI-compatible endpoint
+3. Both run on the same machine, so communication is via `127.0.0.1`
+
+### Step 1 — Enable the OpenAI API endpoint
+
+**Via add-on configuration (recommended)**:
+1. Go to Home Assistant → **Settings → Add-ons → OpenClaw Assistant → Configuration**
+2. Set `enable_openai_api`: **true**
+3. Restart the add-on
+
+**Via terminal (manual)**:
+```sh
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+```
+
+### Step 2 — Install Extended OpenAI Conversation
+
+1. Install [HACS](https://hacs.xyz/) if you haven't already
+2. In HACS, add **Extended OpenAI Conversation** as a custom repository:
+   - Repository: `https://github.com/jekalmin/extended_openai_conversation`
+   - Category: **Integration**
+3. Install it and restart Home Assistant
+
+### Step 3 — Get your Gateway token
+
+In the add-on terminal, run:
+
+```sh
+openclaw config get gateway.auth.token
+```
+
+Copy the token — you'll need it as the API key.
+
+### Step 4 — Configure Extended OpenAI Conversation
+
+1. Go to **Settings → Devices & Services → Add Integration**
+2. Search for **Extended OpenAI Conversation**
+3. Configure:
+   - **API Key**: Paste your gateway token
+   - **Base URL**: `http://127.0.0.1:18789/v1` or a LAN url if you use `gateway_bind_mode: lan`
+   - **Api Version**: leave empty
+   - **Organization**: leave empty
+   - **Skip Authentication**: **true**
+
+### Step 5 — Set as Conversation Agent
+
+1. Go to **Settings → Voice Assistants**
+2. Edit your assistant (default: "Home Assistant")
+3. Under **Conversation agent**, select **Extended OpenAI Conversation**
+
+### Step 6 — Expose entities
+
+Expose the entities you want OpenClaw to control:
+- Go to `http://{your-ha}/config/voice-assistants/expose`
+- Toggle on the entities OpenClaw should be able to see and control
+
+### Done!
+
+You can now use Assist (voice or text) and OpenClaw will handle the conversation. It can:
+- Control your smart home devices
+- Answer questions using its skills
+- Create automations
+- Query entity history
+
+**Tip**: If using LAN access (`gateway_bind_mode: lan`), other HA instances on your network can also connect to this endpoint.
+
+---
+
 ## Troubleshooting
 
 ### Some skills fail to install (Homebrew errors)

openclaw_assistant/config.yaml

@@ -1,5 +1,5 @@
 name: OpenClaw Assistant
-version: "0.5.36"
+version: "0.5.37"
 slug: openclaw_assistant
 description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
 url: https://github.com/techartdev/OpenClawHomeAssistant
@@ -65,6 +65,11 @@ options:
   # Gateway port to listen on
   gateway_port: 18789
 
+  # 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
+
   # Allow insecure HTTP authentication (required for HTTP gateway access on LAN)
   # WARNING: Only enable if you're using HTTP (not HTTPS) for gateway_public_url
   # Default is false for security.
@@ -87,5 +92,6 @@ schema:
   gateway_mode: list(local|remote)?
   gateway_bind_mode: list(loopback|lan)?
   gateway_port: int(1,65535)?
+  enable_openai_api: bool?
   allow_insecure_auth: bool?
 

openclaw_assistant/oc_config_helper.py

@@ -57,7 +57,7 @@ def set_gateway_setting(key, value):
     return write_config(cfg)
 
 
-def apply_gateway_settings(mode: str, bind_mode: str, port: int, allow_insecure_auth: bool):
+def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_api: bool, allow_insecure_auth: bool):
     """
     Apply gateway settings to OpenClaw config.
     
@@ -65,6 +65,7 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, allow_insecure_
         mode: "local" or "remote"
         bind_mode: "loopback" or "lan"
         port: Port number to listen on (must be 1-65535)
+        enable_openai_api: Enable OpenAI-compatible Chat Completions endpoint
         allow_insecure_auth: Allow insecure HTTP authentication
     """
     # Validate gateway mode
@@ -95,11 +96,21 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, allow_insecure_
     if "controlUi" not in gateway:
         gateway["controlUi"] = {}
     
+    # http.endpoints.chatCompletions should be nested inside gateway
+    if "http" not in gateway:
+        gateway["http"] = {}
+    if "endpoints" not in gateway["http"]:
+        gateway["http"]["endpoints"] = {}
+    if "chatCompletions" not in gateway["http"]["endpoints"]:
+        gateway["http"]["endpoints"]["chatCompletions"] = {}
+    
     control_ui = gateway["controlUi"]
+    chat_completions = gateway["http"]["endpoints"]["chatCompletions"]
     
     current_mode = gateway.get("mode", "")
     current_bind = gateway.get("bind", "")
     current_port = gateway.get("port", 18789)
+    current_openai_api = chat_completions.get("enabled", False)
     current_insecure = control_ui.get("allowInsecureAuth", False)
     
     changes = []
@@ -116,6 +127,10 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, allow_insecure_
         gateway["port"] = port
         changes.append(f"port: {current_port} -> {port}")
     
+    if current_openai_api != enable_openai_api:
+        chat_completions["enabled"] = enable_openai_api
+        changes.append(f"chatCompletions.enabled: {current_openai_api} -> {enable_openai_api}")
+    
     if current_insecure != allow_insecure_auth:
         control_ui["allowInsecureAuth"] = allow_insecure_auth
         changes.append(f"allowInsecureAuth: {current_insecure} -> {allow_insecure_auth}")
@@ -128,7 +143,7 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, allow_insecure_
             print("ERROR: Failed to write config")
             return False
     else:
-        print(f"INFO: Gateway settings already correct (bind={bind_mode}, port={port}, allowInsecureAuth={allow_insecure_auth})")
+        print(f"INFO: Gateway settings already correct (mode={mode}, bind={bind_mode}, port={port}, chatCompletions={enable_openai_api}, allowInsecureAuth={allow_insecure_auth})")
         return True
 
 
@@ -141,14 +156,15 @@ def main():
     cmd = sys.argv[1]
     
     if cmd == "apply-gateway-settings":
-        if len(sys.argv) != 6:
+        if len(sys.argv) != 7:
-            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <loopback|lan> <port> <true|false>")
+            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <loopback|lan> <port> <enable_openai_api:true|false> <allow_insecure:true|false>")
             sys.exit(1)
         mode = sys.argv[2]
         bind_mode = sys.argv[3]
         port = int(sys.argv[4])
-        allow_insecure_auth = sys.argv[5].lower() == "true"
+        enable_openai_api = sys.argv[5].lower() == "true"
-        success = apply_gateway_settings(mode, bind_mode, port, allow_insecure_auth)
+        allow_insecure_auth = sys.argv[6].lower() == "true"
+        success = apply_gateway_settings(mode, bind_mode, port, enable_openai_api, allow_insecure_auth)
         sys.exit(0 if success else 1)
     
     elif cmd == "get":

openclaw_assistant/run.sh

@@ -48,6 +48,7 @@ CLEAN_LOCKS_ON_EXIT=$(jq -r '.clean_session_locks_on_exit // true' "$OPTIONS_FIL
 GATEWAY_MODE=$(jq -r '.gateway_mode // "local"' "$OPTIONS_FILE")
 GATEWAY_BIND_MODE=$(jq -r '.gateway_bind_mode // "loopback"' "$OPTIONS_FILE")
 GATEWAY_PORT=$(jq -r '.gateway_port // 18789' "$OPTIONS_FILE")
+ENABLE_OPENAI_API=$(jq -r '.enable_openai_api // false' "$OPTIONS_FILE")
 ALLOW_INSECURE_AUTH=$(jq -r '.allow_insecure_auth // false' "$OPTIONS_FILE")
 
 export TZ="$TZNAME"
@@ -233,7 +234,7 @@ fi
 
 if [ -f "$OPENCLAW_CONFIG_PATH" ]; then
   if [ -f "$HELPER_PATH" ]; then
-    if ! python3 "$HELPER_PATH" apply-gateway-settings "$GATEWAY_MODE" "$GATEWAY_BIND_MODE" "$GATEWAY_PORT" "$ALLOW_INSECURE_AUTH"; then
+    if ! python3 "$HELPER_PATH" apply-gateway-settings "$GATEWAY_MODE" "$GATEWAY_BIND_MODE" "$GATEWAY_PORT" "$ENABLE_OPENAI_API" "$ALLOW_INSECURE_AUTH"; then
       rc=$?
       echo "ERROR: Failed to apply gateway settings via oc_config_helper.py (exit code ${rc})."
       echo "ERROR: Gateway configuration may be incorrect; aborting startup."

openclaw_assistant/translations/bg.yaml

@@ -51,6 +51,10 @@ configuration:
     name: Порт на Gateway
     description: Номер на порт, на който OpenClaw gateway да слуша (по подразбиране - 18789)
   
+  enable_openai_api:
+    name: Активиране на OpenAI API
+    description: Активиране на OpenAI-съвместим Chat Completions ендпойнт. Позволява използването на OpenClaw като разговорен агент в HA Assist pipeline чрез Extended OpenAI Conversation (HACS) или всеки OpenAI-съвместим клиент.
+  
   allow_insecure_auth:
     name: Разрешаване на HTTP автентикация
     description: Разрешаване на HTTP автентикация за достъп до gateway в локалната мрежа. ВНИМАНИЕ - Активирайте само ако използвате HTTP (не HTTPS) за gateway_public_url. Необходимо за достъп от браузър през HTTP.

openclaw_assistant/translations/de.yaml

@@ -51,6 +51,10 @@ configuration:
     name: Gateway-Port
     description: Portnummer, auf der das OpenClaw-Gateway lauscht (Standard - 18789)
   
+  enable_openai_api:
+    name: OpenAI API aktivieren
+    description: OpenAI-kompatiblen Chat Completions Endpunkt aktivieren. Ermöglicht die Verwendung von OpenClaw als Gesprächsagent in der HA Assist Pipeline über Extended OpenAI Conversation (HACS) oder jeden OpenAI-kompatiblen Client.
+  
   allow_insecure_auth:
     name: Unsichere HTTP-Authentifizierung erlauben
     description: HTTP-Authentifizierung für Gateway-Zugriff im LAN erlauben. WARNUNG - Nur aktivieren, wenn HTTP (nicht HTTPS) für gateway_public_url verwendet wird. Erforderlich für Browser-Zugriff über HTTP.

openclaw_assistant/translations/en.yaml

@@ -51,6 +51,10 @@ configuration:
     name: Gateway Port
     description: Port number for the OpenClaw gateway to listen on (default - 18789)
   
+  enable_openai_api:
+    name: Enable OpenAI API
+    description: Enable OpenAI-compatible Chat Completions endpoint. Allows using OpenClaw as a conversation agent in HA Assist pipeline via Extended OpenAI Conversation (HACS) or any OpenAI-compatible client.
+  
   allow_insecure_auth:
     name: Allow Insecure HTTP Auth
     description: Allow HTTP authentication for gateway access on LAN. WARNING - Only enable if using HTTP (not HTTPS) for gateway_public_url. Required for browser access over HTTP.

openclaw_assistant/translations/es.yaml

@@ -51,6 +51,10 @@ configuration:
     name: Puerto del Gateway
     description: Número de puerto en el que el gateway de OpenClaw escuchará (predeterminado - 18789)
   
+  enable_openai_api:
+    name: Activar API OpenAI
+    description: Activar endpoint de Chat Completions compatible con OpenAI. Permite usar OpenClaw como agente de conversación en HA Assist pipeline mediante Extended OpenAI Conversation (HACS) o cualquier cliente compatible con OpenAI.
+  
   allow_insecure_auth:
     name: Permitir autenticación HTTP insegura
     description: Permitir autenticación HTTP para acceso al gateway en LAN. ADVERTENCIA - Solo habilitar si usa HTTP (no HTTPS) para gateway_public_url. Requerido para acceso desde navegador por HTTP.

openclaw_assistant/translations/pl.yaml

@@ -47,6 +47,10 @@ configuration:
     name: Port Gateway
     description: Numer portu na którym gateway OpenClaw będzie nasłuchiwał (domyślnie - 18789)
   
+  enable_openai_api:
+    name: Włącz API OpenAI
+    description: Włącz endpoint Chat Completions kompatybilny z OpenAI. Pozwala używać OpenClaw jako agenta konwersacji w HA Assist pipeline przez Extended OpenAI Conversation (HACS) lub dowolnego klienta kompatybilnego z OpenAI.
+  
   allow_insecure_auth:
     name: Zezwól na niezabezpieczone uwierzytelnianie HTTP
     description: Zezwól na uwierzytelnianie HTTP dla dostępu do gateway w sieci LAN. UWAGA - Włącz tylko jeśli używasz HTTP (nie HTTPS) dla gateway_public_url. Wymagane dla dostępu przez przeglądarkę przez HTTP.