Skill: lafoush/homeassistant-selora (version 1.0.5)

--- name: home-assistant description: >- Connect Home Assistant to OpenClaw via OAuth 2.0 through Selora Connect. Authenticate and use Selora AI tools to inspect your home, create automations, and act on proactive suggestions. license: MIT compatibility: openclaw metadata: version: 1.0.5 category: setup --- # Home Assistant MCP Setup Connect your Home Assistant to OpenClaw. Authentication is handled via OAuth 2.0 through Selora Connect — no manual tokens needed. ## Prerequisites 1. **Home Assistant** 2025.1+ with the [Selora AI](https://selorahomes.com/docs/selora-ai/installation/) integration installed. 2. A **Selora Connect** account with your HA installation linked. 3. **OpenClaw** installed. ## 1. Get Your MCP URL | Access | URL | |--------|-----| | Local | `http://homeassistant.local:8123/api/selora_ai/mcp` | | Remote | `https://mcp-<id>.selorabox.com/api/selora_ai/mcp` | Your remote MCP URL (including your `mcp-<id>`) is shown in Selora Connect once MCP remote access is enabled. Enable it to provision a SeloraBox tunnel URL. > Use your HA IP (e.g. `192.168.x.x`) instead of `homeassistant.local` if mDNS is slow. ## 2. Add the MCP Server Add the server via the CLI: ```bash openclaw mcp set home-assistant '{"url":"https://mcp-<id>.selorabox.com/api/selora_ai/mcp"}' ``` Or edit `~/.openclaw/openclaw.json` directly: ```json { "mcp": { "servers": { "home-assistant": { "url": "https://mcp-<id>.selorabox.com/api/selora_ai/mcp" } } } } ``` For local access, use `http://homeassistant.local:8123/api/selora_ai/mcp` as the URL. ## 3. Authenticate 1. Restart the OpenClaw gateway after editing the config. 2. Use any tool from the server (e.g. ask *"Get a snapshot of my home"*). OpenClaw connects and receives a `401 Unauthorized`. 3. OpenClaw surfaces an authorization URL. Open it in a browser. 4. Approve access on the Selora Connect consent screen. 5. The browser redirects back to OpenClaw's callback to complete the exchange. 6. Tokens are cached and refresh silently from then on. > **The callback must reach OpenClaw's listener.** If the browser and OpenClaw are on the same machine, the redirect completes automatically. If they are on different machines, see [Cross-device callback mismatch](#cross-device-callback-mismatch) below. ## 4. Verify Ask your agent: *"Get a snapshot of my home"*. You should see `selora_get_home_snapshot` return your entities grouped by area. ## Available Tools Read tools: | Tool | Description | |------|-------------| | `selora_get_home_snapshot` | Entity states grouped by area — call this first | | `selora_list_automations` | Selora automations with status and risk (filterable) | | `selora_get_automation` | Full detail: YAML, versions, risk | | `selora_validate_automation` | Validate and risk-assess YAML without creating | | `selora_list_sessions` | Recent chat sessions | | `selora_list_patterns` | Detected behavior patterns | | `selora_get_pattern` | Full pattern detail with linked suggestions | | `selora_list_suggestions` | Proactive suggestions with YAML previews | Mutating tools (🔒 require admin authorization): | Tool | Description | |------|-------------| | `selora_chat` 🔒 | Natural-language chat — proposes automations with YAML and risk | | `selora_create_automation` 🔒 | Create automation from YAML (disabled by default) | | `selora_accept_automation` 🔒 | Enable a pending automation | | `selora_delete_automation` 🔒 | Delete permanently | | `selora_accept_suggestion` 🔒 | Create automation from a suggestion | | `selora_dismiss_suggestion` 🔒 | Dismiss a suggestion | | `selora_trigger_scan` 🔒 | Trigger immediate suggestion scan (rate-limited 60s) | ## Workflows ### Explore your home 1. `selora_get_home_snapshot` — understand entities and areas. 2. `selora_list_automations` / `selora_get_automation` for existing automations. ### Create from YAML 1. `selora_validate_automation` — check YAML and surface risk. 2. Show normalized YAML + risk, ask user confirmation. 3. `selora_create_automation` with `enabled=false`. 4. `selora_accept_automation` after explicit approval. ### Create from natural language 1. `selora_chat` — describe what you want; Selora returns YAML + risk. 2. Summarize risk, ask user confirmation. 3. `selora_create_automation` or `selora_accept_automation`. ### Act on suggestions 1. `selora_list_suggestions` (optionally `selora_trigger_scan` first). 2. Show suggestion details, ask user confirmation. 3. `selora_accept_suggestion` or `selora_dismiss_suggestion`. ## Safety Rules 1. Never invent IDs — resolve from tool output only. 2. Never mutate without explicit user confirmation. 3. Always surface `risk_assessment` before mutating. High or missing risk requires a second confirmation. 4. Create automations disabled by default. 5. Do not skip validation for externally provided YAML. ## How OAuth Works 1. OpenClaw discovers Connect's OAuth server from the MCP endpoint's `.well-known/oauth-authorization-server` metadata. 2. OpenClaw registers itself dynamically (`POST /oauth/register`). 3. OpenClaw starts an authorization code flow with PKCE and surfaces an authorization URL. 4. You open the URL and approve access on the Selora Connect consent screen. 5. OpenClaw exchanges the code for access + refresh tokens. 6. Tokens refresh automatically — no re-auth needed until you revoke access. On `401 Unauthorized`, OpenClaw reads the `WWW-Authenticate` header, attempts a token refresh, and falls back to a full OAuth flow if refresh fails. No manual re-configuration is needed. ## Troubleshooting | Symptom | Fix | |---------|-----| | `401 Unauthorized` (auth URL shown) | Open the authorization URL, approve access on Selora Connect, and the flow completes automatically. If refresh fails later, OpenClaw triggers a new flow. | | `401 Unauthorized` loop (no auth URL shown) | OpenClaw's native OAuth flow is not surfacing the authorization URL — check gateway logs for `401`, auth URL emission, and MCP startup failures. See [Debugging with mcp-remote](#debugging-with-mcp-remote) below. | | Connection refused | Verify HA is running and URL is correct | | Timeout | Check firewall; for remote, ensure SeloraBox tunnel is active | | Tools not listed | Ensure Selora AI integration is installed and enabled | | Admin tools rejected | Selora Connect role must be `owner` or `member` (not `viewer`) | ### Cross-device callback mismatch The OAuth redirect targets `localhost` on the machine running OpenClaw. If your browser is on a different machine (e.g. OpenClaw on a server, browser on a laptop), the callback cannot reach OpenClaw's listener and the flow fails silently. As a fallback, ask the user to copy the full callback URL (including the `code` and `state` parameters) from their browser's address bar after approving, and paste it back so the agent can complete the token exchange. ### Debugging with mcp-remote If OpenClaw keeps returning `401` without surfacing an authorization URL, use `mcp-remote` (requires **Node.js 18+**) to isolate the problem. It is not part of the normal setup — only a debugging tool. ```bash npx -y mcp-remote https://mcp-<id>.selorabox.com/api/selora_ai/mcp ``` This helps verify the endpoint supports OAuth correctly and that the token exchange works end-to-end. If `mcp-remote` completes the flow successfully, the endpoint is working — the issue is in OpenClaw's OAuth runtime, not your HA setup.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)