diff --git a/DOCS.md b/DOCS.md index f1d7153..e005bc6 100644 --- a/DOCS.md +++ b/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) diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml index 7c2d3cc..60d9646 100644 --- a/openclaw_assistant/config.yaml +++ b/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? diff --git a/openclaw_assistant/oc_config_helper.py b/openclaw_assistant/oc_config_helper.py index f0fe2a2..1fec9d6 100644 --- a/openclaw_assistant/oc_config_helper.py +++ b/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: - print("Usage: oc_config_helper.py apply-gateway-settings ") + if len(sys.argv) != 7: + print("Usage: oc_config_helper.py apply-gateway-settings ") 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" - success = apply_gateway_settings(mode, bind_mode, port, allow_insecure_auth) + enable_openai_api = sys.argv[5].lower() == "true" + 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": diff --git a/openclaw_assistant/run.sh b/openclaw_assistant/run.sh index 3625407..3948099 100644 --- a/openclaw_assistant/run.sh +++ b/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." diff --git a/openclaw_assistant/translations/bg.yaml b/openclaw_assistant/translations/bg.yaml index 91e30f7..be72e85 100644 --- a/openclaw_assistant/translations/bg.yaml +++ b/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. diff --git a/openclaw_assistant/translations/de.yaml b/openclaw_assistant/translations/de.yaml index 2769098..4478793 100644 --- a/openclaw_assistant/translations/de.yaml +++ b/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. diff --git a/openclaw_assistant/translations/en.yaml b/openclaw_assistant/translations/en.yaml index b8ebcbc..d8c7bf1 100644 --- a/openclaw_assistant/translations/en.yaml +++ b/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. diff --git a/openclaw_assistant/translations/es.yaml b/openclaw_assistant/translations/es.yaml index 652c0d7..62de2b8 100644 --- a/openclaw_assistant/translations/es.yaml +++ b/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. diff --git a/openclaw_assistant/translations/pl.yaml b/openclaw_assistant/translations/pl.yaml index 5438bee..ddcc614 100644 --- a/openclaw_assistant/translations/pl.yaml +++ b/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.