Home Assistant

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.

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 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:

openclaw mcp set home-assistant '{"url":"https://mcp-<id>.selorabox.com/api/selora_ai/mcp"}'

Or edit ~/.openclaw/openclaw.json directly:

{
  "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 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 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.

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.