# Send Home Assistant Agent (Secure) to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "home-assistant-agent-secure", "name": "Home Assistant Agent (Secure)", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/szafranski/home-assistant-agent-secure", "canonicalUrl": "https://clawhub.ai/szafranski/home-assistant-agent-secure", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/home-assistant-agent-secure", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=home-assistant-agent-secure", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "_meta.json", "SKILL.md", "README.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/home-assistant-agent-secure" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/home-assistant-agent-secure", "downloadUrl": "https://openagent3.xyz/downloads/home-assistant-agent-secure", "agentUrl": "https://openagent3.xyz/skills/home-assistant-agent-secure/agent", "manifestUrl": "https://openagent3.xyz/skills/home-assistant-agent-secure/agent.json", "briefUrl": "https://openagent3.xyz/skills/home-assistant-agent-secure/agent.md" } } ``` ## Documentation ### Home Assistant Agent (Secure) Control smart home devices by sending natural language to Home Assistant's Conversation (Assist) API. Security model: This skill uses ONLY the /api/conversation/process endpoint. Do NOT use the token to call any other HA API endpoint. The token should belong to a restricted, non-admin Home Assistant user with access limited to specific areas and entities. ### Important Security Rules ONLY call /api/conversation/process — never call /api/states, /api/services, /api/config, or any other endpoint NEVER output or echo the token value NEVER use the token for any purpose other than the Assist API call below NEVER attempt to log in to Home Assistant via the browser or web UI — always use the API token If a user request cannot be handled by Assist, say so — do not fall back to other API calls ### Important: Disable Trusted Networks Login Bypass If your Home Assistant instance uses the trusted_networks auth provider with allow_bypass_login: true, any agent or user on the local network can log in as any HA user (including administrators) without a password. This completely bypasses the restricted-user security model of this skill. To fix: In your HA configuration.yaml, set allow_bypass_login: false under the trusted_networks auth provider, or remove the trusted_networks provider entirely. Restart HA after making the change. ### 1. Create a Restricted Home Assistant User In Home Assistant go to Settings → People → Add Person Create a new user (e.g. openclaw-bot) Do NOT make it an administrator Under Settings → Areas & Zones, assign only the areas this user should control Optionally restrict entity access using a custom group or dashboard-only permissions ### 2. Generate a Long-Lived Access Token Log in to Home Assistant as the restricted user (openclaw-bot) Go to Profile (bottom-left) Scroll to Long-Lived Access Tokens Click Create Token, name it (e.g. openclaw) Copy the token immediately — it is shown only once ### 3. Configure OpenClaw Set HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN using any of the methods below. OpenClaw applies them in this precedence order (highest first): process environment → .env file → openclaw.json config. A value set by a higher-priority source is never overridden by a lower one. Option A: .env file (recommended) Add to ~/.openclaw/.env: HOME_ASSISTANT_URL=https://your-ha-instance.local HOME_ASSISTANT_TOKEN=your-restricted-user-token-here The URL can be a hostname (e.g. https://homeassistant.local) or an IP address (e.g. https://192.168.1.50:8123). Option B: Config file Add to ~/.openclaw/openclaw.json under skills.entries: { "skills": { "entries": { "home-assistant-agent-secure": { "apiKey": "your-restricted-user-token-here", "env": { "HOME_ASSISTANT_URL": "https://your-ha-instance.local" } } } } } The apiKey field automatically maps to HOME_ASSISTANT_TOKEN via the skill's primaryEnv declaration. Option C: Shell environment variables Export in your shell profile (e.g. ~/.bashrc, ~/.zshrc): export HOME_ASSISTANT_URL="https://your-ha-instance.local" export HOME_ASSISTANT_TOKEN="your-restricted-user-token-here" ### Usage Send any smart home command in natural language. The skill passes it directly to HA Assist: curl -sk -X POST "$HOME_ASSISTANT_URL/api/conversation/process" \\ -H "Authorization: Bearer $HOME_ASSISTANT_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{"text": "USER REQUEST HERE", "language": "DETECTED LANGUAGE CODE"}' The -k flag allows connections to HA instances using self-signed certificates. If your HA uses a trusted certificate (e.g. Let's Encrypt), you can remove it. Set the language field based on the detected language of the user's input (e.g. "pl" for Polish, "en" for English, "de" for German, etc.). ### Examples "Turn on the living room lights" (English) "Włącz światło w salonie" (Polish) "Schalte das Licht im Wohnzimmer ein" (German) "Jaka jest temperatura w kuchni?" (Polish) "Turn off all lights in the bedroom" (English) ### Inflected Language Handling (Nominative Retry) Many languages use grammatical cases or word inflection, causing entity names to change form in natural speech. Home Assistant entity names are typically in their base/dictionary form (nominative), but users naturally use other grammatical forms in commands. This affects languages including (but not limited to): Polish — 7 cases (e.g. drukarkę → drukarka, lampę → lampa) Czech — 7 cases (e.g. tiskárnu → tiskárna, lampu → lampa) German — 4 cases + articles (e.g. den Drucker → Drucker, die Lampe → Lampe) Finnish — 15 cases (e.g. tulostinta → tulostin, lamppua → lamppu) Hungarian — 18 cases (e.g. nyomtatót → nyomtató, lámpát → lámpa) Russian — 6 cases (e.g. принтеру → принтер, лампу → лампа) Croatian/Serbian — 7 cases, similar patterns to Polish and Czech Example: A user says "włącz drukarkę 3d" (Polish accusative), but the entity is named "drukarka 3d" (nominative). HA Assist won't find it. Retry strategy: If HA responds with an error (no_valid_targets, no_intent_match, or a message indicating the entity was not found), and the user's input is in an inflected language: Identify the entity name within the command Convert inflected words to their base/dictionary/nominative form Retry the API call with the corrected form If the retry also fails, report the error to the user Important: Only retry once. Do not loop. If the nominative retry also fails, inform the user that the entity was not found. ### Handling Responses The response is in response.speech.plain.speech. Relay it directly to the user: "Turned on the light" → success "Sorry, I couldn't understand that" → Assist couldn't parse the request "Sorry, there are multiple devices called X" → ambiguous entity name ### On errors (response_type: "error") ErrorWhat to tell the userno_intent_matchTry nominative retry (if inflected language). If still fails: "Home Assistant didn't recognize that command."no_valid_targetsTry nominative retry (if inflected language). If still fails: "Entity not found — check the device name or add an alias in HA."Multiple matches"Multiple devices share that name — consider adding unique aliases in HA." ### Troubleshooting 401 Unauthorized: Token is invalid or expired. Generate a new one from the restricted user's profile. Connection refused: Check that HOME_ASSISTANT_URL is correct and HA is reachable. Command not understood: Rephrase the request or check that the entity is exposed to the restricted user. Entity not found: The restricted user may not have access to that area/entity. Update permissions in HA. ### Endpoint POST /api/conversation/process Note: Use /api/conversation/process, NOT /api/services/conversation/process. ### Request Body { "text": "turn on the kitchen lights", "language": "en" } Polish example: { "text": "włącz światło w salonie", "language": "pl" } ### Success Response { "response": { "speech": { "plain": {"speech": "Turned on the light"} }, "response_type": "action_done", "data": { "success": [{"name": "Kitchen Light", "id": "light.kitchen"}], "failed": [] } } } ## Trust - Source: tencent - Verification: Indexed source record - Publisher: szafranski - Version: 1.1.0 ## Source health - Status: healthy - Source download looks usable. - Yavira can redirect you to the upstream package for this source. - Health scope: source - Reason: direct_download_ok - Checked at: 2026-04-30T16:55:25.780Z - Expires at: 2026-05-07T16:55:25.780Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/home-assistant-agent-secure) - [Send to Agent page](https://openagent3.xyz/skills/home-assistant-agent-secure/agent) - [JSON manifest](https://openagent3.xyz/skills/home-assistant-agent-secure/agent.json) - [Markdown brief](https://openagent3.xyz/skills/home-assistant-agent-secure/agent.md) - [Download page](https://openagent3.xyz/downloads/home-assistant-agent-secure)