TetraHome/Tetra-AI-HA-Integration
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add voice agent and session ID options, update changelog to version 0.1.61

Browse Source 
- Introduced `voice_agent_id` and `assist_session_id` options for enhanced integration.
- Updated request handling to support new headers for voice interactions.
- Preserved existing behavior when new options are left blank.
- Updated changelog for version 0.1.61 to reflect these changes.
This commit is contained in:
techartdev
2026-03-07 14:37:39 +02:00
parent e93c05f2ae
commit 95bfe5e214
10 changed files with 128 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
custom_components/openclaw/__init__.py
+29 -4
View File
@@ -46,9 +46,11 @@ from .const import (
ATTR_DRY_RUN,
ATTR_MESSAGE_CHANNEL,
ATTR_ACCOUNT_ID,
ATTR_SOURCE,
ATTR_TIMESTAMP,
CONF_ADDON_CONFIG_PATH,
CONF_AGENT_ID,
CONF_VOICE_AGENT_ID,
CONF_GATEWAY_HOST,
CONF_GATEWAY_PORT,
CONF_GATEWAY_TOKEN,
@@ -66,6 +68,7 @@ from .const import (
CONF_THINKING_TIMEOUT,
CONTEXT_STRATEGY_TRUNCATE,
DEFAULT_AGENT_ID,
DEFAULT_VOICE_AGENT_ID,
DEFAULT_CONTEXT_MAX_CHARS,
DEFAULT_CONTEXT_STRATEGY,
DEFAULT_ENABLE_TOOL_CALLS,
@@ -92,13 +95,18 @@ _LOGGER = logging.getLogger(__name__)
_MAX_CHAT_HISTORY = 200
_VOICE_REQUEST_HEADERS = {
"x-openclaw-source": "voice",
"x-ha-voice": "true",
}
# Path to the chat card JS inside the integration package (custom_components/openclaw/www/)
_CARD_FILENAME = "openclaw-chat-card.js"
_CARD_PATH = Path(__file__).parent / "www" / _CARD_FILENAME
# URL at which the card JS is served (registered via register_static_path)
_CARD_STATIC_URL = f"/openclaw/{_CARD_FILENAME}"
# Versioned URL used for Lovelace resource registration to avoid stale browser cache
_CARD_URL = f"{_CARD_STATIC_URL}?v=0.1.56"
_CARD_URL = f"{_CARD_STATIC_URL}?v=0.1.60"
OpenClawConfigEntry = ConfigEntry
@@ -107,6 +115,7 @@ OpenClawConfigEntry = ConfigEntry
SEND_MESSAGE_SCHEMA = vol.Schema(
{
vol.Required(ATTR_MESSAGE): cv.string,
vol.Optional(ATTR_SOURCE): cv.string,
vol.Optional(ATTR_SESSION_ID): cv.string,
vol.Optional(ATTR_ATTACHMENTS): vol.All(cv.ensure_list, [cv.string]),
vol.Optional(ATTR_AGENT_ID): cv.string,
@@ -390,11 +399,19 @@ async def _async_add_lovelace_resource(hass: HomeAssistant, url: str) -> bool:
def _async_register_services(hass: HomeAssistant) -> None:
"""Register openclaw.send_message and openclaw.clear_history services."""
def _normalize_optional_text(value: Any) -> str | None:
if not isinstance(value, str):
return None
cleaned = value.strip()
return cleaned or None
async def handle_send_message(call: ServiceCall) -> None:
"""Handle the openclaw.send_message service call."""
message: str = call.data[ATTR_MESSAGE]
source: str | None = call.data.get(ATTR_SOURCE)
session_id: str = call.data.get(ATTR_SESSION_ID) or "default"
call_agent_id: str | None = call.data.get(ATTR_AGENT_ID)
call_agent_id = _normalize_optional_text(call.data.get(ATTR_AGENT_ID))
extra_headers = _VOICE_REQUEST_HEADERS if source == "voice" else None
entry_data = _get_first_entry_data(hass)
if not entry_data:
@@ -404,6 +421,12 @@ def _async_register_services(hass: HomeAssistant) -> None:
client: OpenClawApiClient = entry_data["client"]
coordinator: OpenClawCoordinator = entry_data["coordinator"]
options = _get_entry_options(hass, entry_data)
voice_agent_id = _normalize_optional_text(
options.get(CONF_VOICE_AGENT_ID, DEFAULT_VOICE_AGENT_ID)
)
resolved_agent_id = call_agent_id
if resolved_agent_id is None and source == "voice":
resolved_agent_id = voice_agent_id
try:
include_context = options.get(
@@ -430,7 +453,8 @@ def _async_register_services(hass: HomeAssistant) -> None:
message=message,
session_id=session_id,
system_prompt=system_prompt,
agent_id=call_agent_id,
agent_id=resolved_agent_id,
extra_headers=extra_headers,
)
if options.get(CONF_ENABLE_TOOL_CALLS, DEFAULT_ENABLE_TOOL_CALLS):
@@ -444,7 +468,8 @@ def _async_register_services(hass: HomeAssistant) -> None:
),
session_id=session_id,
system_prompt=system_prompt,
agent_id=call_agent_id,
agent_id=resolved_agent_id,
extra_headers=extra_headers,
)
assistant_message = _extract_assistant_message(response)
custom_components/openclaw/api.py
+15 -4
View File
@@ -85,14 +85,21 @@ class OpenClawApiClient:
"""Update the authentication token (e.g., after addon restart)."""
self._token = token
def _headers(self, agent_id: str | None = None) -> dict[str, str]:
def _headers(
self,
agent_id: str | None = None,
extra_headers: dict[str, str] | None = None,
) -> dict[str, str]:
"""Build request headers with auth token and agent ID."""
effective_agent = agent_id or self._agent_id or "main"
return {
headers = {
"Authorization": f"Bearer {self._token}",
"Content-Type": "application/json",
"x-openclaw-agent-id": effective_agent,
}
if extra_headers:
headers.update(extra_headers)
return headers
async def _get_session(self) -> aiohttp.ClientSession:
"""Get or create an aiohttp session."""
@@ -188,6 +195,7 @@ class OpenClawApiClient:
system_prompt: str | None = None,
stream: bool = False,
agent_id: str | None = None,
extra_headers: dict[str, str] | None = None,
) -> dict[str, Any]:
"""Send a chat message (non-streaming).
@@ -197,6 +205,7 @@ class OpenClawApiClient:
model: Optional model override.
stream: If True, raises ValueError (use async_stream_message).
agent_id: Optional per-call agent ID override.
extra_headers: Optional additional headers for gateway-side routing or hints.
Returns:
Complete chat completion response.
@@ -220,7 +229,7 @@ class OpenClawApiClient:
payload["model"] = model
# Pass session_id as a custom header or param if supported by gateway
headers = self._headers(agent_id=agent_id)
headers = self._headers(agent_id=agent_id, extra_headers=extra_headers)
if session_id:
headers["X-Session-Id"] = session_id
headers["x-openclaw-session-key"] = session_id
@@ -255,6 +264,7 @@ class OpenClawApiClient:
model: str | None = None,
system_prompt: str | None = None,
agent_id: str | None = None,
extra_headers: dict[str, str] | None = None,
) -> AsyncIterator[str]:
"""Send a chat message and stream the response via SSE.
@@ -265,6 +275,7 @@ class OpenClawApiClient:
session_id: Optional session/conversation ID.
model: Optional model override.
agent_id: Optional per-call agent ID override.
extra_headers: Optional additional headers for gateway-side routing or hints.
Yields:
Content delta strings from the streaming response.
@@ -284,7 +295,7 @@ class OpenClawApiClient:
if model:
payload["model"] = model
headers = self._headers(agent_id=agent_id)
headers = self._headers(agent_id=agent_id, extra_headers=extra_headers)
if session_id:
headers["X-Session-Id"] = session_id
headers["x-openclaw-session-key"] = session_id
custom_components/openclaw/config_flow.py
+18
View File
@@ -37,6 +37,7 @@ from .const import (
ADDON_SLUG_FRAGMENTS,
CONF_ADDON_CONFIG_PATH,
CONF_AGENT_ID,
CONF_ASSIST_SESSION_ID,
CONF_GATEWAY_HOST,
CONF_GATEWAY_PORT,
CONF_GATEWAY_TOKEN,
@@ -48,6 +49,7 @@ from .const import (
CONF_INCLUDE_EXPOSED_CONTEXT,
CONF_WAKE_WORD,
CONF_WAKE_WORD_ENABLED,
CONF_VOICE_AGENT_ID,
CONF_ALLOW_BRAVE_WEBSPEECH,
CONF_BROWSER_VOICE_LANGUAGE,
CONF_VOICE_PROVIDER,
@@ -56,6 +58,7 @@ from .const import (
CONTEXT_STRATEGY_CLEAR,
CONTEXT_STRATEGY_TRUNCATE,
DEFAULT_AGENT_ID,
DEFAULT_ASSIST_SESSION_ID,
DEFAULT_GATEWAY_HOST,
DEFAULT_GATEWAY_PORT,
DEFAULT_CONTEXT_MAX_CHARS,
@@ -68,6 +71,7 @@ from .const import (
DEFAULT_BROWSER_VOICE_LANGUAGE,
DEFAULT_VOICE_PROVIDER,
DEFAULT_THINKING_TIMEOUT,
DEFAULT_VOICE_AGENT_ID,
DOMAIN,
OPENCLAW_CONFIG_REL_PATH,
)
@@ -466,6 +470,20 @@ class OpenClawOptionsFlow(OptionsFlowWithReload):
self._config_entry.data.get(CONF_AGENT_ID, DEFAULT_AGENT_ID),
),
): str,
vol.Optional(
CONF_VOICE_AGENT_ID,
default=options.get(
CONF_VOICE_AGENT_ID,
DEFAULT_VOICE_AGENT_ID,
),
): str,
vol.Optional(
CONF_ASSIST_SESSION_ID,
default=options.get(
CONF_ASSIST_SESSION_ID,
DEFAULT_ASSIST_SESSION_ID,
),
): str,
vol.Optional(
CONF_INCLUDE_EXPOSED_CONTEXT,
default=options.get(
custom_components/openclaw/const.py
+5
View File
@@ -24,6 +24,8 @@ CONF_USE_SSL = "use_ssl"
CONF_VERIFY_SSL = "verify_ssl"
CONF_ADDON_CONFIG_PATH = "addon_config_path"
CONF_AGENT_ID = "agent_id"
CONF_VOICE_AGENT_ID = "voice_agent_id"
CONF_ASSIST_SESSION_ID = "assist_session_id"
# Options
CONF_INCLUDE_EXPOSED_CONTEXT = "include_exposed_context"
@@ -38,6 +40,8 @@ CONF_BROWSER_VOICE_LANGUAGE = "browser_voice_language"
CONF_THINKING_TIMEOUT = "thinking_timeout"
DEFAULT_AGENT_ID = "main"
DEFAULT_VOICE_AGENT_ID = ""
DEFAULT_ASSIST_SESSION_ID = ""
DEFAULT_INCLUDE_EXPOSED_CONTEXT = True
DEFAULT_CONTEXT_MAX_CHARS = 13000
DEFAULT_CONTEXT_STRATEGY = "truncate"
@@ -121,6 +125,7 @@ SERVICE_INVOKE_TOOL = "invoke_tool"
# Attributes
ATTR_MESSAGE = "message"
ATTR_SOURCE = "source"
ATTR_SESSION_ID = "session_id"
ATTR_ATTACHMENTS = "attachments"
ATTR_MODEL = "model"
custom_components/openclaw/conversation.py
+34
View File
@@ -22,9 +22,12 @@ from .const import (
ATTR_MODEL,
ATTR_SESSION_ID,
ATTR_TIMESTAMP,
CONF_ASSIST_SESSION_ID,
CONF_CONTEXT_MAX_CHARS,
CONF_CONTEXT_STRATEGY,
CONF_INCLUDE_EXPOSED_CONTEXT,
CONF_VOICE_AGENT_ID,
DEFAULT_ASSIST_SESSION_ID,
DEFAULT_CONTEXT_MAX_CHARS,
DEFAULT_CONTEXT_STRATEGY,
DEFAULT_INCLUDE_EXPOSED_CONTEXT,
@@ -37,6 +40,11 @@ from .exposure import apply_context_policy, build_exposed_entities_context
_LOGGER = logging.getLogger(__name__)
_VOICE_REQUEST_HEADERS = {
"x-openclaw-source": "voice",
"x-ha-voice": "true",
}
async def async_setup_entry(
hass: HomeAssistant,
@@ -110,6 +118,9 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
conversation_id = self._resolve_conversation_id(user_input)
assistant_id = "conversation"
options = self.entry.options
voice_agent_id = self._normalize_optional_text(
options.get(CONF_VOICE_AGENT_ID)
)
include_context = options.get(
CONF_INCLUDE_EXPOSED_CONTEXT,
DEFAULT_INCLUDE_EXPOSED_CONTEXT,
@@ -136,6 +147,7 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
client,
message,
conversation_id,
voice_agent_id,
system_prompt,
)
except OpenClawApiError as err:
@@ -151,6 +163,7 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
client,
message,
conversation_id,
voice_agent_id,
system_prompt,
)
except OpenClawApiError as retry_err:
@@ -191,6 +204,15 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
def _resolve_conversation_id(self, user_input: conversation.ConversationInput) -> str:
"""Return conversation id from HA or a stable Assist fallback session key."""
configured_session_id = self._normalize_optional_text(
self.entry.options.get(
CONF_ASSIST_SESSION_ID,
DEFAULT_ASSIST_SESSION_ID,
)
)
if configured_session_id:
return configured_session_id
if user_input.conversation_id:
return user_input.conversation_id
@@ -205,11 +227,19 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
return "assist_default"
def _normalize_optional_text(self, value: Any) -> str | None:
"""Return a stripped string or None for blank values."""
if not isinstance(value, str):
return None
cleaned = value.strip()
return cleaned or None
async def _get_response(
self,
client: OpenClawApiClient,
message: str,
conversation_id: str,
agent_id: str | None = None,
system_prompt: str | None = None,
) -> str:
"""Get a response from OpenClaw, trying streaming first."""
@@ -219,6 +249,8 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
message=message,
session_id=conversation_id,
system_prompt=system_prompt,
agent_id=agent_id,
extra_headers=_VOICE_REQUEST_HEADERS,
):
full_response += chunk
@@ -230,6 +262,8 @@ class OpenClawConversationAgent(conversation.AbstractConversationAgent):
message=message,
session_id=conversation_id,
system_prompt=system_prompt,
agent_id=agent_id,
extra_headers=_VOICE_REQUEST_HEADERS,
)
extracted = self._extract_text_recursive(response)
return extracted or ""
custom_components/openclaw/manifest.json
+1 -1
View File
@@ -8,7 +8,7 @@
"iot_class": "local_polling",
"issue_tracker": "https://github.com/techartdev/OpenClawHomeAssistant/issues",
"requirements": [],
"version": "0.1.59",
"version": "0.1.61",
"dependencies": ["conversation"],
"after_dependencies": ["hassio", "lovelace"]
}
custom_components/openclaw/strings.json
+2
View File
@@ -39,6 +39,8 @@
"description": "Configure context and tool-calling behavior.",
"data": {
"agent_id": "Agent ID (e.g. main)",
"voice_agent_id": "Voice agent ID (optional)",
"assist_session_id": "Assist session ID override (optional)",
"include_exposed_context": "Include exposed entities context",
"context_max_chars": "Max context characters",
"context_strategy": "When context exceeds max",
custom_components/openclaw/translations/en.json
+2
View File
@@ -41,6 +41,8 @@
"description": "Configure context and tool-calling behavior.",
"data": {
"agent_id": "Agent ID (e.g. main)",
"voice_agent_id": "Voice agent ID (optional)",
"assist_session_id": "Assist session ID override (optional)",
"include_exposed_context": "Include exposed entities context",
"context_max_chars": "Max context characters",
"context_strategy": "When context exceeds max",
custom_components/openclaw/www/openclaw-chat-card.js
+6 -5
View File
@@ -13,7 +13,7 @@
* + subscribes to openclaw_message_received events.
*/
const CARD_VERSION = "0.3.12";
const CARD_VERSION = "0.3.13";
// Max time (ms) to show the thinking indicator before falling back to an error (default; overridable via card config `thinking_timeout` in seconds)
const THINKING_TIMEOUT_MS = 120_000;
@@ -516,7 +516,7 @@ class OpenClawChatCard extends HTMLElement {
this._persistMessages();
}
async _sendMessage(text) {
async _sendMessage(text, source = null) {
if (!text || !text.trim() || !this._hass) return;
await this._subscribeToEvents();
@@ -541,6 +541,7 @@ class OpenClawChatCard extends HTMLElement {
try {
await this._hass.callService("openclaw", "send_message", {
message: message,
source: source || undefined,
session_id: this._config.session_id || undefined,
});
@@ -948,7 +949,7 @@ class OpenClawChatCard extends HTMLElement {
this._voiceStatus = "Sending…";
this._render();
this._sendMessage(transcript);
this._sendMessage(transcript, "voice");
} catch (err) {
console.error("OpenClaw: Assist STT transcription failed", err);
this._voiceStatus = "Assist STT transcription failed.";
@@ -1161,13 +1162,13 @@ class OpenClawChatCard extends HTMLElement {
}
this._voiceStatus = "Sending…";
this._render();
this._sendMessage(command);
this._sendMessage(command, "voice");
return;
}
this._voiceStatus = "Sending…";
this._render();
this._sendMessage(text);
this._sendMessage(text, "voice");
}
};