{
  "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": {
    "downloadMode": "redirect",
    "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",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "_meta.json",
      "SKILL.md",
      "README.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/home-assistant-agent-secure",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Home Assistant Agent (Secure)",
        "body": "Control smart home devices by sending natural language to Home Assistant's Conversation (Assist) API.\n\nSecurity 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."
      },
      {
        "title": "Important Security Rules",
        "body": "ONLY call /api/conversation/process — never call /api/states, /api/services, /api/config, or any other endpoint\nNEVER output or echo the token value\nNEVER use the token for any purpose other than the Assist API call below\nNEVER attempt to log in to Home Assistant via the browser or web UI — always use the API token\nIf a user request cannot be handled by Assist, say so — do not fall back to other API calls"
      },
      {
        "title": "Important: Disable Trusted Networks Login Bypass",
        "body": "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.\n\nTo 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."
      },
      {
        "title": "1. Create a Restricted Home Assistant User",
        "body": "In Home Assistant go to Settings → People → Add Person\nCreate a new user (e.g. openclaw-bot)\nDo NOT make it an administrator\nUnder Settings → Areas & Zones, assign only the areas this user should control\nOptionally restrict entity access using a custom group or dashboard-only permissions"
      },
      {
        "title": "2. Generate a Long-Lived Access Token",
        "body": "Log in to Home Assistant as the restricted user (openclaw-bot)\nGo to Profile (bottom-left)\nScroll to Long-Lived Access Tokens\nClick Create Token, name it (e.g. openclaw)\nCopy the token immediately — it is shown only once"
      },
      {
        "title": "3. Configure OpenClaw",
        "body": "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.\n\nOption A: .env file (recommended)\n\nAdd to ~/.openclaw/.env:\n\nHOME_ASSISTANT_URL=https://your-ha-instance.local\nHOME_ASSISTANT_TOKEN=your-restricted-user-token-here\n\nThe URL can be a hostname (e.g. https://homeassistant.local) or an IP address (e.g. https://192.168.1.50:8123).\n\nOption B: Config file\n\nAdd to ~/.openclaw/openclaw.json under skills.entries:\n\n{\n  \"skills\": {\n    \"entries\": {\n      \"home-assistant-agent-secure\": {\n        \"apiKey\": \"your-restricted-user-token-here\",\n        \"env\": {\n          \"HOME_ASSISTANT_URL\": \"https://your-ha-instance.local\"\n        }\n      }\n    }\n  }\n}\n\nThe apiKey field automatically maps to HOME_ASSISTANT_TOKEN via the skill's primaryEnv declaration.\n\nOption C: Shell environment variables\n\nExport in your shell profile (e.g. ~/.bashrc, ~/.zshrc):\n\nexport HOME_ASSISTANT_URL=\"https://your-ha-instance.local\"\nexport HOME_ASSISTANT_TOKEN=\"your-restricted-user-token-here\""
      },
      {
        "title": "Usage",
        "body": "Send any smart home command in natural language. The skill passes it directly to HA Assist:\n\ncurl -sk -X POST \"$HOME_ASSISTANT_URL/api/conversation/process\" \\\n  -H \"Authorization: Bearer $HOME_ASSISTANT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"USER REQUEST HERE\", \"language\": \"DETECTED LANGUAGE CODE\"}'\n\nThe -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.\n\nSet 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.)."
      },
      {
        "title": "Examples",
        "body": "\"Turn on the living room lights\" (English)\n\"Włącz światło w salonie\" (Polish)\n\"Schalte das Licht im Wohnzimmer ein\" (German)\n\"Jaka jest temperatura w kuchni?\" (Polish)\n\"Turn off all lights in the bedroom\" (English)"
      },
      {
        "title": "Inflected Language Handling (Nominative Retry)",
        "body": "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.\n\nThis affects languages including (but not limited to):\n\nPolish — 7 cases (e.g. drukarkę → drukarka, lampę → lampa)\nCzech — 7 cases (e.g. tiskárnu → tiskárna, lampu → lampa)\nGerman — 4 cases + articles (e.g. den Drucker → Drucker, die Lampe → Lampe)\nFinnish — 15 cases (e.g. tulostinta → tulostin, lamppua → lamppu)\nHungarian — 18 cases (e.g. nyomtatót → nyomtató, lámpát → lámpa)\nRussian — 6 cases (e.g. принтеру → принтер, лампу → лампа)\nCroatian/Serbian — 7 cases, similar patterns to Polish and Czech\n\nExample: A user says \"włącz drukarkę 3d\" (Polish accusative), but the entity is named \"drukarka 3d\" (nominative). HA Assist won't find it.\n\nRetry 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:\n\nIdentify the entity name within the command\nConvert inflected words to their base/dictionary/nominative form\nRetry the API call with the corrected form\nIf the retry also fails, report the error to the user\n\nImportant: Only retry once. Do not loop. If the nominative retry also fails, inform the user that the entity was not found."
      },
      {
        "title": "Handling Responses",
        "body": "The response is in response.speech.plain.speech. Relay it directly to the user:\n\n\"Turned on the light\" → success\n\"Sorry, I couldn't understand that\" → Assist couldn't parse the request\n\"Sorry, there are multiple devices called X\" → ambiguous entity name"
      },
      {
        "title": "On errors (response_type: \"error\")",
        "body": "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.\""
      },
      {
        "title": "Troubleshooting",
        "body": "401 Unauthorized: Token is invalid or expired. Generate a new one from the restricted user's profile.\nConnection refused: Check that HOME_ASSISTANT_URL is correct and HA is reachable.\nCommand not understood: Rephrase the request or check that the entity is exposed to the restricted user.\nEntity not found: The restricted user may not have access to that area/entity. Update permissions in HA."
      },
      {
        "title": "Endpoint",
        "body": "POST /api/conversation/process\n\nNote: Use /api/conversation/process, NOT /api/services/conversation/process."
      },
      {
        "title": "Request Body",
        "body": "{\n  \"text\": \"turn on the kitchen lights\",\n  \"language\": \"en\"\n}\n\nPolish example:\n\n{\n  \"text\": \"włącz światło w salonie\",\n  \"language\": \"pl\"\n}"
      },
      {
        "title": "Success Response",
        "body": "{\n  \"response\": {\n    \"speech\": {\n      \"plain\": {\"speech\": \"Turned on the light\"}\n    },\n    \"response_type\": \"action_done\",\n    \"data\": {\n      \"success\": [{\"name\": \"Kitchen Light\", \"id\": \"light.kitchen\"}],\n      \"failed\": []\n    }\n  }\n}"
      }
    ],
    "body": "Home Assistant Agent (Secure)\n\nControl smart home devices by sending natural language to Home Assistant's Conversation (Assist) API.\n\nSecurity 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.\n\nImportant Security Rules\nONLY call /api/conversation/process — never call /api/states, /api/services, /api/config, or any other endpoint\nNEVER output or echo the token value\nNEVER use the token for any purpose other than the Assist API call below\nNEVER attempt to log in to Home Assistant via the browser or web UI — always use the API token\nIf a user request cannot be handled by Assist, say so — do not fall back to other API calls\nImportant: Disable Trusted Networks Login Bypass\n\nIf 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.\n\nTo 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.\n\nSetup\n1. Create a Restricted Home Assistant User\nIn Home Assistant go to Settings → People → Add Person\nCreate a new user (e.g. openclaw-bot)\nDo NOT make it an administrator\nUnder Settings → Areas & Zones, assign only the areas this user should control\nOptionally restrict entity access using a custom group or dashboard-only permissions\n2. Generate a Long-Lived Access Token\nLog in to Home Assistant as the restricted user (openclaw-bot)\nGo to Profile (bottom-left)\nScroll to Long-Lived Access Tokens\nClick Create Token, name it (e.g. openclaw)\nCopy the token immediately — it is shown only once\n3. Configure OpenClaw\n\nSet 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.\n\nOption A: .env file (recommended)\n\nAdd to ~/.openclaw/.env:\n\nHOME_ASSISTANT_URL=https://your-ha-instance.local\nHOME_ASSISTANT_TOKEN=your-restricted-user-token-here\n\n\nThe URL can be a hostname (e.g. https://homeassistant.local) or an IP address (e.g. https://192.168.1.50:8123).\n\nOption B: Config file\n\nAdd to ~/.openclaw/openclaw.json under skills.entries:\n\n{\n  \"skills\": {\n    \"entries\": {\n      \"home-assistant-agent-secure\": {\n        \"apiKey\": \"your-restricted-user-token-here\",\n        \"env\": {\n          \"HOME_ASSISTANT_URL\": \"https://your-ha-instance.local\"\n        }\n      }\n    }\n  }\n}\n\n\nThe apiKey field automatically maps to HOME_ASSISTANT_TOKEN via the skill's primaryEnv declaration.\n\nOption C: Shell environment variables\n\nExport in your shell profile (e.g. ~/.bashrc, ~/.zshrc):\n\nexport HOME_ASSISTANT_URL=\"https://your-ha-instance.local\"\nexport HOME_ASSISTANT_TOKEN=\"your-restricted-user-token-here\"\n\nUsage\n\nSend any smart home command in natural language. The skill passes it directly to HA Assist:\n\ncurl -sk -X POST \"$HOME_ASSISTANT_URL/api/conversation/process\" \\\n  -H \"Authorization: Bearer $HOME_ASSISTANT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"USER REQUEST HERE\", \"language\": \"DETECTED LANGUAGE CODE\"}'\n\n\nThe -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.\n\nSet 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.).\n\nExamples\n\"Turn on the living room lights\" (English)\n\"Włącz światło w salonie\" (Polish)\n\"Schalte das Licht im Wohnzimmer ein\" (German)\n\"Jaka jest temperatura w kuchni?\" (Polish)\n\"Turn off all lights in the bedroom\" (English)\nInflected Language Handling (Nominative Retry)\n\nMany 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.\n\nThis affects languages including (but not limited to):\n\nPolish — 7 cases (e.g. drukarkę → drukarka, lampę → lampa)\nCzech — 7 cases (e.g. tiskárnu → tiskárna, lampu → lampa)\nGerman — 4 cases + articles (e.g. den Drucker → Drucker, die Lampe → Lampe)\nFinnish — 15 cases (e.g. tulostinta → tulostin, lamppua → lamppu)\nHungarian — 18 cases (e.g. nyomtatót → nyomtató, lámpát → lámpa)\nRussian — 6 cases (e.g. принтеру → принтер, лампу → лампа)\nCroatian/Serbian — 7 cases, similar patterns to Polish and Czech\n\nExample: A user says \"włącz drukarkę 3d\" (Polish accusative), but the entity is named \"drukarka 3d\" (nominative). HA Assist won't find it.\n\nRetry 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:\n\nIdentify the entity name within the command\nConvert inflected words to their base/dictionary/nominative form\nRetry the API call with the corrected form\nIf the retry also fails, report the error to the user\n\nImportant: Only retry once. Do not loop. If the nominative retry also fails, inform the user that the entity was not found.\n\nHandling Responses\n\nThe response is in response.speech.plain.speech. Relay it directly to the user:\n\n\"Turned on the light\" → success\n\"Sorry, I couldn't understand that\" → Assist couldn't parse the request\n\"Sorry, there are multiple devices called X\" → ambiguous entity name\nOn errors (response_type: \"error\")\nError\tWhat to tell the user\nno_intent_match\tTry nominative retry (if inflected language). If still fails: \"Home Assistant didn't recognize that command.\"\nno_valid_targets\tTry nominative retry (if inflected language). If still fails: \"Entity not found — check the device name or add an alias in HA.\"\nMultiple matches\t\"Multiple devices share that name — consider adding unique aliases in HA.\"\nTroubleshooting\n401 Unauthorized: Token is invalid or expired. Generate a new one from the restricted user's profile.\nConnection refused: Check that HOME_ASSISTANT_URL is correct and HA is reachable.\nCommand not understood: Rephrase the request or check that the entity is exposed to the restricted user.\nEntity not found: The restricted user may not have access to that area/entity. Update permissions in HA.\nAPI Reference\nEndpoint\nPOST /api/conversation/process\n\n\nNote: Use /api/conversation/process, NOT /api/services/conversation/process.\n\nRequest Body\n{\n  \"text\": \"turn on the kitchen lights\",\n  \"language\": \"en\"\n}\n\n\nPolish example:\n\n{\n  \"text\": \"włącz światło w salonie\",\n  \"language\": \"pl\"\n}\n\nSuccess Response\n{\n  \"response\": {\n    \"speech\": {\n      \"plain\": {\"speech\": \"Turned on the light\"}\n    },\n    \"response_type\": \"action_done\",\n    \"data\": {\n      \"success\": [{\"name\": \"Kitchen Light\", \"id\": \"light.kitchen\"}],\n      \"failed\": []\n    }\n  }\n}"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/szafranski/home-assistant-agent-secure",
    "publisherUrl": "https://clawhub.ai/szafranski/home-assistant-agent-secure",
    "owner": "szafranski",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}