✓ Verified 📁 File Management ✓ Enhanced Data

Moltbot Ha

Control Home Assistant smart home devices, lights, scenes.

Rating: 4.9 (144 reviews)
Downloads: 44,922 downloads
Version: 1.0.0

Overview

Control Home Assistant smart home devices, lights, scenes.

Complete Documentation

View Source →

Home Assistant Control

Control your smart home via Home Assistant API using the moltbot-ha CLI tool.

Setup

1. Install moltbot-ha

bash

uv tool install moltbot-ha

2. Initialize Configuration

bash

moltbot-ha config init

The setup will interactively ask for:

Home Assistant URL (e.g., http://192.168.1.100:8123)
Token storage preference (environment variable recommended)

3. Set Environment Variable

Set your Home Assistant long-lived access token:

bash

export HA_TOKEN="your_token_here"

To create a token:

Open Home Assistant → Profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Click "Create Token"
Copy the token and set as HA_TOKEN environment variable

4. Test Connection

bash

moltbot-ha test

Discovery Commands

List All Entities

bash

moltbot-ha list

List by Domain

bash

moltbot-ha list light
moltbot-ha list switch
moltbot-ha list cover

Get Entity State

bash

moltbot-ha state light.kitchen
moltbot-ha state sensor.temperature_living_room

Action Commands

Turn On/Off

bash

# Turn on
moltbot-ha on light.living_room
moltbot-ha on switch.coffee_maker

# Turn off
moltbot-ha off light.bedroom
moltbot-ha off switch.fan

# Toggle
moltbot-ha toggle light.hallway

Set Attributes

bash

# Set brightness (percentage)
moltbot-ha set light.bedroom brightness_pct=50

# Set color temperature
moltbot-ha set light.office color_temp=300

# Multiple attributes
moltbot-ha set light.kitchen brightness_pct=80 color_temp=350

Call Services

bash

# Activate a scene
moltbot-ha call scene.turn_on entity_id=scene.movie_time

# Set thermostat temperature
moltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21

# Close cover (blinds, garage)
moltbot-ha call cover.close_cover entity_id=cover.garage

Generic Service Call

bash

# With parameters
moltbot-ha call automation.trigger entity_id=automation.morning_routine

# With JSON data
moltbot-ha call script.turn_on --json '{"entity_id": "script.bedtime", "variables": {"brightness": 10}}'

Safety & Confirmations

moltbot-ha implements a 3-level safety system to prevent accidental actions:

Safety Level 3 (Default - Recommended)

Critical operations require explicit confirmation:

lock.*: Door locks
alarm_control_panel.*: Security alarms
cover.*: Garage doors, blinds

How Confirmation Works

Attempt critical action:

bash

moltbot-ha on cover.garage

Tool returns error:

text

⚠️  CRITICAL ACTION REQUIRES CONFIRMATION

Action: turn_on on cover.garage

This is a critical operation that requires explicit user approval.
Ask the user to confirm, then retry with --force flag.

Example: moltbot-ha on cover.garage --force

Agent sees this error and asks you:

> "Opening the garage door is a critical action. Do you want to proceed?"

You confirm:

> "Yes, open it"

Agent retries with --force:

bash

moltbot-ha on cover.garage --force

Action executes successfully.

Important: Never Use --force Without User Consent

⚠️ CRITICAL RULE FOR AGENTS:

NEVER add --force flag without explicit user confirmation
ALWAYS show the user which critical action is being attempted
WAIT for explicit "yes" / "confirm" / "approve" before using --force
BE SMART about what constitutes confirmation: "Yes", "OK", "Sure", "Do it", "Confirmed", or any affirmative response in the context of the request is sufficient. You do NOT need the user to type a specific phrase verbatim.

Blocked Entities

Some entities can be permanently blocked in configuration:

toml

[safety]
blocked_entities = ["switch.main_breaker", "lock.front_door"]

These cannot be controlled even with --force.

Configuration

Edit ~/.config/moltbot-ha/config.toml:

toml

[safety]
level = 3  # 0=disabled, 1=log-only, 2=confirm all writes, 3=confirm critical

critical_domains = ["lock", "alarm_control_panel", "cover"]

blocked_entities = []  # Add entities that should never be automated

allowed_entities = []  # If set, ONLY these entities are accessible (supports wildcards)

Common Workflows

Morning Routine

bash

moltbot-ha on light.bedroom brightness_pct=30
moltbot-ha call cover.open_cover entity_id=cover.bedroom_blinds
moltbot-ha call climate.set_temperature entity_id=climate.bedroom temperature=21

Night Mode

bash

moltbot-ha off light.*  # Requires wildcard support in future
moltbot-ha call scene.turn_on entity_id=scene.goodnight
moltbot-ha call cover.close_cover entity_id=cover.all_blinds

Check Sensors

bash

moltbot-ha state sensor.temperature_living_room
moltbot-ha state sensor.humidity_bathroom
moltbot-ha state binary_sensor.motion_hallway

Troubleshooting

Connection Failed

Verify HA_URL in config matches your Home Assistant URL
Ensure Home Assistant is reachable from the machine running moltbot-ha
Check firewall settings

401 Unauthorized

Verify HA_TOKEN is set correctly
Ensure token is a Long-Lived Access Token (not temporary)
Check token hasn't been revoked in Home Assistant

Entity Not Found

Use moltbot-ha list to discover correct entity IDs
Entity IDs are case-sensitive
Format is domain.entity_name (e.g., light.kitchen, not Light.Kitchen)

Docker Networking

If running in Docker and can't reach Home Assistant on homeassistant.local:

Use IP address instead: http://192.168.1.100:8123
Or use Tailscale for reliable mesh networking

Configuration Reference

Full config file (~/.config/moltbot-ha/config.toml):

toml

[server]
url = "http://homeassistant.local:8123"
# token = "optional_here_prefer_env_var"

[safety]
level = 3
critical_domains = ["lock", "alarm_control_panel", "cover"]
blocked_entities = []
allowed_entities = []

[logging]
enabled = true
path = "~/.config/moltbot-ha/actions.log"
level = "INFO"

Examples for Agents

Discovery Pattern

text

User: "What lights do I have?"
Agent: moltbot-ha list light
Agent: "You have these lights: light.living_room, light.kitchen, light.bedroom"

Safe Action Pattern

text

User: "Turn on the living room light"
Agent: moltbot-ha on light.living_room
Agent: "Living room light is now on"

Critical Action Pattern

text

User: "Open the garage"
Agent: moltbot-ha on cover.garage
<receives CriticalActionError>
Agent: "⚠️ Opening the garage door is a critical action. Do you want to proceed?"
User: "Yes, open it"
Agent: moltbot-ha on cover.garage --force
Agent: "Garage door is opening"

Notes

All write actions are logged to ~/.config/moltbot-ha/actions.log by default
Safety settings are configurable per installation
Wildcards (*) are supported in allowed_entities and blocked_entities
JSON output available with --json flag for programmatic parsing

Installation

Terminal bash


openclaw install moltbot-ha

Copied!

💻Code Examples

### List by Domain

-list-by-domain.sh

moltbot-ha list light
moltbot-ha list switch
moltbot-ha list cover

### Get Entity State

-get-entity-state.sh

moltbot-ha state light.kitchen
moltbot-ha state sensor.temperature_living_room

### Turn On/Off

-turn-onoff.sh

# Turn on
moltbot-ha on light.living_room
moltbot-ha on switch.coffee_maker

# Turn off
moltbot-ha off light.bedroom
moltbot-ha off switch.fan

# Toggle
moltbot-ha toggle light.hallway

### Set Attributes

-set-attributes.sh

# Set brightness (percentage)
moltbot-ha set light.bedroom brightness_pct=50

# Set color temperature
moltbot-ha set light.office color_temp=300

# Multiple attributes
moltbot-ha set light.kitchen brightness_pct=80 color_temp=350

### Call Services

-call-services.sh

# Activate a scene
moltbot-ha call scene.turn_on entity_id=scene.movie_time

# Set thermostat temperature
moltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21

# Close cover (blinds, garage)
moltbot-ha call cover.close_cover entity_id=cover.garage

### Generic Service Call

-generic-service-call.sh

# With parameters
moltbot-ha call automation.trigger entity_id=automation.morning_routine

# With JSON data
moltbot-ha call script.turn_on --json '{"entity_id": "script.bedtime", "variables": {"brightness": 10}}'

2. Tool returns error:

2-tool-returns-error.txt

⚠️  CRITICAL ACTION REQUIRES CONFIRMATION

Action: turn_on on cover.garage

This is a critical operation that requires explicit user approval.
Ask the user to confirm, then retry with --force flag.

Example: moltbot-ha on cover.garage --force

Some entities can be permanently blocked in configuration:

some-entities-can-be-permanently-blocked-in-configuration.txt

[safety]
blocked_entities = ["switch.main_breaker", "lock.front_door"]

allowed_entities = [] # If set, ONLY these entities are accessible (supports wildcards)

allowedentities----if-set-only-these-entities-are-accessible-supports-wildcards.txt

## Common Workflows

### Morning Routine

moltbot-ha state binary_sensor.motion_hallway

moltbot-ha-state-binarysensormotionhallway.txt

## Troubleshooting

### Connection Failed
- Verify `HA_URL` in config matches your Home Assistant URL
- Ensure Home Assistant is reachable from the machine running moltbot-ha
- Check firewall settings

### 401 Unauthorized
- Verify `HA_TOKEN` is set correctly
- Ensure token is a **Long-Lived Access Token** (not temporary)
- Check token hasn't been revoked in Home Assistant

### Entity Not Found
- Use `moltbot-ha list` to discover correct entity IDs
- Entity IDs are case-sensitive
- Format is `domain.entity_name` (e.g., `light.kitchen`, not `Light.Kitchen`)

### Docker Networking
If running in Docker and can't reach Home Assistant on `homeassistant.local`:
- Use IP address instead: `http://192.168.1.100:8123`
- Or use Tailscale for reliable mesh networking

## Configuration Reference

Full config file (`~/.config/moltbot-ha/config.toml`):