moltbot-ha（蜕皮哈）

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

1. 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

1. Agent sees this error and asks you:

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

1. You confirm:

"Yes, open it"

1. Agent retries with --force:

moltbot-ha on cover.garage --force

1. 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