moltbot-ha – OpenClaw Skill

---

name: moltbot-ha description: Control Home Assistant smart home devices, lights, scenes, and automations via moltbot-ha CLI with configurable safety confirmations. homepage: https://github.com/iamvaleriofantozzi/moltbot-ha metadata: {"moltbot":{"emoji":"🏠","requires":{"bins":["moltbot-ha"],"env":["HA_TOKEN"]},"primaryEnv":"HA_TOKEN","install":[{"id":"uv","kind":"uv","package":"moltbot-ha","bins":["moltbot-ha"],"label":"Install moltbot-ha (uv tool)"}]}}

Home Assistant Control

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

Setup

1. Install moltbot-ha

uv tool install moltbot-ha

2. Initialize Configuration

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:

export HA_TOKEN="your_token_here"

To create a token:

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

4. Test Connection

moltbot-ha test

Discovery Commands

List All Entities

moltbot-ha list

List by Domain

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

Get Entity State

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

Action Commands

Turn On/Off

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

# 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

# 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

1. Attempt critical action:

moltbot-ha on cover.garage

2. Tool returns error:

⚠️  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

3. Agent sees this error and asks you:

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

4. You confirm:

"Yes, open it"

5. Agent retries with --force:

moltbot-ha on cover.garage --force

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

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

These cannot be controlled even with --force.

Configuration

Edit ~/.config/moltbot-ha/config.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

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

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

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

[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

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

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

Critical Action Pattern

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

moltbot-ha 🏠

Home Assistant control CLI for Moltbot agents and humans.

Control your smart home via Home Assistant REST API with powerful safety features, configurable confirmations, and agent-friendly design.

---

✨ Features

• 🎮 Full Control: Lights, switches, covers, scenes, climate, and all Home Assistant domains
• 🛡️ Safety First: 3-level safety system with confirmations for critical actions (locks, alarms, garage doors)
• 🤖 Agent-Friendly: Designed for AI agents with clear error messages and confirmation workflows
• ⚙️ Configurable: Flexible allowlist/blocklist, custom critical domains, logging
• 🚀 Fast: Direct REST API calls with retry logic and connection pooling
• 📊 Output Formats: Human-readable tables or JSON for programmatic use

---

📦 Installation

Via uv (recommended)

uv tool install moltbot-ha

Via pip

pip install moltbot-ha

From source (development)

git clone https://github.com/iamvaleriofantozzi/moltbot-ha.git
cd moltbot-ha
uv tool install .

---

🚀 Quick Start

1. Initialize Configuration

moltbot-ha config init

The interactive setup will ask you:

• Home Assistant URL: Your HA instance URL (e.g., http://192.168.1.100:8123)
• Token storage: Environment variable (recommended) or config file

2. Set Token (if using environment variable)

export HA_TOKEN="your_long_lived_access_token"

How to create a token:

1. Open Home Assistant → Profile (bottom left icon)
2. Scroll down to "Long-Lived Access Tokens"
3. Click "Create Token", give it a name (e.g., "moltbot-ha")
4. Copy the token immediately (you can't see it again!)

3. Test Connection

moltbot-ha test

You should see:

✓ Connected to Home Assistant successfully

---

Non-Interactive Setup

If you prefer to set everything via environment variables:

export HA_URL="http://192.168.1.100:8123"
export HA_TOKEN="your_token_here"
moltbot-ha config init --no-interactive
moltbot-ha test

---

📖 Usage

Discovery

# List all entities
moltbot-ha list

# List by domain
moltbot-ha list light
moltbot-ha list switch
moltbot-ha list sensor

# Get entity state (JSON output)
moltbot-ha state light.kitchen

Basic Actions

# Turn on/off
moltbot-ha on light.living_room
moltbot-ha off switch.fan

# Toggle
moltbot-ha toggle light.hallway

Advanced Control

# Set attributes
moltbot-ha set light.bedroom brightness_pct=50
moltbot-ha set light.office brightness_pct=80 color_temp=300

# Call services
moltbot-ha call scene.turn_on entity_id=scene.movie_time
moltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21

# Generic service call with JSON
moltbot-ha call script.turn_on --json '{"entity_id": "script.bedtime", "variables": {"dim": true}}'

---

🛡️ Safety System

moltbot-ha implements a 3-level safety system to prevent accidental or dangerous actions.

Safety Levels

Level	Behavior
0	No safety checks (⚠️ dangerous!)
1	Log actions only, no confirmations
2	Confirm all write operations
3	Confirm critical operations only (🏅 recommended)

Level 3 (Default): Critical Domains

By default, these domains require explicit --force confirmation:

• lock: Door locks
• alarm_control_panel: Security systems
• cover: Garage doors, blinds, shutters

Confirmation Workflow

1. Attempt critical action without --force:

$ moltbot-ha on cover.garage

2. Tool returns error:

⚠️  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

3. After user confirms, retry with --force:

$ moltbot-ha on cover.garage --force
✓ cover.garage turned on

Blocked Entities

Permanently block entities that should NEVER be automated:

# ~/.config/moltbot-ha/config.toml
[safety]
blocked_entities = [
    "switch.main_breaker",      # Never touch the main power!
    "lock.front_door",          # Keep front door manual-only
]

Blocked entities cannot be controlled even with --force.

Allowlist

Restrict access to specific entities only:

[safety]
allowed_entities = [
    "light.*",                  # All lights
    "switch.office_*",          # Office switches only
    "scene.*",                  # All scenes
]

---

⚙️ Configuration

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

[server]
# Home Assistant URL (required)
url = "http://192.168.1.100:8123"

# Token (optional, prefer HA_TOKEN env var)
# token = "eyJ..."

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

# Domains that require confirmation (level 3)
critical_domains = ["lock", "alarm_control_panel", "cover"]

# Entities that are always blocked (even with --force)
blocked_entities = []

# Entities that are allowed (empty = all allowed except blocked)
# Supports wildcards: "light.*", "switch.office_*"
allowed_entities = []

[logging]
# Enable action logging
enabled = true

# Log file path
path = "~/.config/moltbot-ha/actions.log"

# Log level: DEBUG, INFO, WARNING, ERROR
level = "INFO"

Environment Variables

Environment variables override config file settings:

• HA_URL: Home Assistant URL
• HA_TOKEN: Long-lived access token (⭐ recommended for security)
• HA_CTL_CONFIG: Custom config file path

---

🐳 Docker / Moltbot Integration

If running inside Docker (e.g., Moltbot gateway):

Installation in Container

docker exec -it moltbot-gateway uv tool install moltbot-ha

Configuration

docker exec -it moltbot-gateway moltbot-ha config init
docker exec -it moltbot-gateway vi ~/.config/moltbot-ha/config.toml

Set Token via Environment

Add to docker-compose.yml:

environment:
  - HA_TOKEN=${HA_TOKEN}

Then in host .env:

HA_TOKEN=your_token_here

Networking Tips

• IP address (recommended): http://192.168.1.100:8123
• Tailscale: http://homeassistant.ts.net:8123
• Avoid mDNS in Docker: homeassistant.local often doesn't work
• Nabu Casa: https://xxxxx.ui.nabu.casa (requires subscription)

---

🔍 Troubleshooting

Connection Refused

Symptom:

Connection failed: Connection refused

Solutions:

• Verify Home Assistant is running
• Check URL in config matches your HA instance
• Ensure HA is reachable from the machine running moltbot-ha
• Check firewall settings (port 8123 must be open)
• If in Docker, use IP address instead of homeassistant.local

401 Unauthorized

Symptom:

[401] Authentication failed

Solutions:

• Verify HA_TOKEN environment variable is set correctly
• Ensure token is a Long-Lived Access Token (not session token)
• Check token hasn't been revoked in Home Assistant settings
• Regenerate token if necessary

Entity Not Found

Symptom:

Entity not found: light.kitche

Solutions:

• Use moltbot-ha list to discover correct entity IDs
• Entity IDs are case-sensitive
• Check for typos (e.g., kitche vs kitchen)

Blocked Entity

Symptom:

❌ Entity switch.main_breaker is BLOCKED in configuration

Solution:

• This is intentional! The entity is in your blocked_entities list
• Remove from config if you want to allow control
• This safety feature prevents accidental control of critical devices

---

📝 Examples

Morning Routine Script

#!/bin/bash
# morning.sh

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
moltbot-ha call scene.turn_on entity_id=scene.good_morning

Check Temperature Sensors

#!/bin/bash
# check-temps.sh

echo "Living Room:"
moltbot-ha state sensor.temperature_living_room | jq -r '.state'

echo "Bedroom:"
moltbot-ha state sensor.temperature_bedroom | jq -r '.state'

echo "Outside:"
moltbot-ha state sensor.temperature_outside | jq -r '.state'

Night Mode

#!/bin/bash
# night-mode.sh

moltbot-ha call scene.turn_on entity_id=scene.goodnight
moltbot-ha call cover.close_cover entity_id=cover.all_blinds
moltbot-ha call climate.set_temperature entity_id=climate.bedroom temperature=18

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Home Assistant for the amazing smart home platform
• Moltbot for agent infrastructure
• Typer for CLI framework
• Rich for beautiful terminal output

---

🔗 Links

• Home Assistant REST API Docs
• Moltbot Documentation
• ClawdHub (skill registry)

---

Made with ❤️ for smart homes and AI agents