AI guard rail for Home Assistant. Sits between your AI agent and Home Assistant, exposing only the entities you choose with per-entity access control and comprehensive security.

Without ClawBridge, AI agents (via ha-mcp, custom skills, or direct API access) get broad access to your entire Home Assistant instance. ClawBridge acts as a controlled proxy — your AI connects to ClawBridge instead of directly to HA, and ClawBridge enforces per-entity permissions, rate limits, and audit logging.

┌──────────┐        ┌─────────────┐        ┌──────────────────┐
│ OpenClaw │ ──────▶│ ClawBridge  │ ──────▶│ Home Assistant   │
│ (or any  │  :8100 │ (guard rail)│  HA API│ (full access)    │
│  AI)     │◀────── │             │◀────── │                  │
└──────────┘        └─────────────┘        └──────────────────┘
                     Only exposes            Has all entities
                     selected entities       and services
                     with access levels

These projects have different goals. HA MCP gives your AI agent tools to access all aspects of your Home Assistant — entities, services, automations, dashboards, and more. It is designed to maximise what the AI can do. ClawBridge takes the opposite approach: it sits between your AI and Home Assistant to restrict what the agent can see and control, with per-entity permissions, human approval flows, and audit logging. Use HA MCP when you want broad AI capability; use ClawBridge when you want tight control over what the AI is allowed to touch.

1. In Home Assistant, go to Settings > Add-ons > Add-on Store
2. Click the three dots menu (top right) > Repositories
3. Add this repository URL:

   https://github.com/finalbillybong/ClawBridge
   

4. Find "ClawBridge" in the add-on store and click Install
5. Start the add-on and open the Web UI

Open the ClawBridge Web UI (from the HA sidebar or add-on page). Browse your entities by domain and set access levels:

• off — Hidden from AI entirely
• read — AI can see state but not control
• confirm — AI requests action, you approve/deny via phone notification
• control — AI acts directly

Click Save when done.

Click the pencil icon on any entity to add a description (e.g., "Main ceiling light in the home office, 2nd floor"). These descriptions are returned in API responses so the AI understands what devices are and where they are.

Go to the Security tab and create an API key. Each key can be scoped to specific entities with its own rate limit — useful if you run multiple AI agents.

Point your AI agent at ClawBridge instead of directly at Home Assistant:

http://<your-ha-ip>:8100/api/

Give your AI the OPENCLAW_API.md file so it understands the available endpoints. The AI should call GET /api/context first to discover its permissions and available entities.

If using an API key, the AI authenticates with: Authorization: Bearer cb_xxxx

Check the Audit tab in the ClawBridge UI to see your AI's requests. The Dashboard tab shows usage stats.

If you're currently using ha-mcp to give OpenClaw access to Home Assistant:

1. Install ClawBridge using the steps above
2. Expose entities — Select which entities the AI should see and set access levels. ClawBridge starts with everything hidden, so you explicitly opt in.
3. Update your AI's configuration — Instead of connecting via MCP to Home Assistant directly, point your AI at http://<ha-ip>:8100. Give it the OPENCLAW_API.md reference doc and an API key.
4. Remove or disable ha-mcp — Once ClawBridge is handling all AI access, you no longer need ha-mcp. ClawBridge provides a standard HA-compatible REST API, so any AI that works with the HA API will work with ClawBridge out of the box.

Why switch? ha-mcp gives the AI access to everything you've exposed in HA's built-in entity filter with no granularity beyond on/off. ClawBridge adds read/confirm/control per entity, parameter constraints (e.g., thermostat max 24°C), time schedules, human-in-the-loop approval, per-agent API keys, and a full audit trail.

• Four-state entity access: off / read / confirm / control
• HA-compatible REST API on port 8100 (/api/states, /api/services/{domain}/{service}) — standard HA client libraries work out of the box
• WebSocket real-time streaming (/api/websocket) — state changes pushed to connected AI clients
• AI context endpoint (/api/context) — single call returns all permissions, entities, constraints, and schedules
• State history (/api/history/period/{timestamp}) — for AI pattern recognition
• Entity annotations — user-written descriptions visible to AI for context
• Parameter constraints — min/max limits with auto-clamping (e.g., brightness 1-200)
• Multi-agent API keys — per-key entity scoping and rate limits
• Time-based access schedules — restrict when AI can control entities (e.g., 6am-11pm only)
• Human-in-the-loop confirmation — confirm-level entities trigger Approve/Deny push notifications (iOS + Android)
• Entity groups — organise entities by room/function for bulk access control
• Area-based exposure — single toggle to expose all entities in a Home Assistant area
• Usage dashboard with hourly charts, top entities, and action counts
• Audit logging — all AI service calls logged with full action history
• Rate limiting — per-IP and per-key
• IP allowlist — optionally restrict which IPs can access port 8100
• Named presets with import/export
• Sensitive domain warnings — lock, cover, alarm, climate, valve require explicit confirmation
• Read-only domain detection — sensor, binary_sensor, weather, etc. only get off/read
• To-do list support — read items via todo.get_items (works with read access), modify with confirm/control

• Only explicitly exposed entities are visible to AI — everything else is hidden
• Read-only entities cannot be controlled (returns 403)
• Confirm entities require human approval via phone notification (Approve/Deny buttons)
• Parameter constraints prevent extreme AI actions (values auto-clamped)
• Time schedules restrict when AI can act
• API keys isolate different agents with per-key entity scoping
• All service calls are audit-logged
• Rate limiting prevents abuse
• Optional IP allowlist restricts network access

See OPENCLAW_API.md for the full endpoint documentation with examples.

Open an issue on GitHub.