Home Assistant 控制

使用moltbot-haCLI 工具通过 Home Assistant API 控制您的智能家居。

设置

1. 安装 moltbot-ha

uv tool install moltbot-ha

2. 初始化配置

moltbot-ha config init

设置过程将交互式地询问：

• Home Assistant URL（例如，http://192.168.1.100:8123）
• 令牌存储偏好（推荐使用环境变量）

3. 设置环境变量

设置您的 Home Assistant 长期访问令牌：

export HA_TOKEN="your_token_here"

创建令牌的步骤：

1. 打开 Home Assistant → 配置文件（左下角）
2. 滚动到"长期访问令牌"
3. 点击"创建令牌"
4. 复制令牌并设置为HA_TOKEN环境变量

4. 测试连接

moltbot-ha test

发现命令

列出所有实体

moltbot-ha list

按域列出

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

获取实体状态

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

操作命令

开启/关闭

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

调用服务

# 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

通用服务调用

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

安全与确认

moltbot-ha 实现了一套三级安全系统以防止意外操作：

安全级别 3（默认 - 推荐）

关键操作需要明确确认：

• lock.*：门锁
• alarm_control_panel.*：安防报警器
• cover.*：车库门、百叶窗

确认机制如何运作

1. 尝试执行关键操作：

moltbot-ha on cover.garage

2. 工具返回错误：

⚠️  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. 代理看到此错误并询问您：

"打开车库门是一个关键操作。您确定要继续吗？"

4. 您确认：

"是的，打开它"

5. 代理使用 --force 参数重试：

moltbot-ha on cover.garage --force

6. 操作执行成功。

重要提示：未经用户同意，切勿使用 --force

⚠️ 代理的关键规则：

• 切勿添加--force标志，除非获得用户的明确确认
• 始终向用户展示正在尝试执行的关键操作
• 等待明确的 "是" / "确认" / "批准" 后再使用--force
• 明智判断什么构成确认：在请求的上下文中，"是"、"好的"、"当然"、"执行"、"确认" 或任何肯定回答都足够。您不需要用户逐字输入特定短语。

被阻止的实体

某些实体可以在配置中被永久屏蔽：

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

这些即使使用--force也无法控制。

配置

编辑~/.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)

常见工作流

早晨例行程序

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

检查传感器

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

故障排除

连接失败

• 验证配置中的 HA_URL是否与您的 Home Assistant URL 匹配
• 确保运行 moltbot-ha 的机器可以访问 Home Assistant
• 检查防火墙设置

401 未授权

• 验证HA_TOKEN设置正确
• 确保令牌是长期访问令牌（非临时令牌）
• 检查令牌是否已在Home Assistant中被撤销

实体未找到

• 使用moltbot-ha list命令来发现正确的实体ID
• 实体ID区分大小写
• 格式为域名.实体名（例如：light.kitchen，而非Light.Kitchen）

Docker网络配置

如果在Docker中运行且无法通过homeassistant.local访问Home Assistant：

• 请改用IP地址：http://192.168.1.100:8123
• 或使用Tailscale实现可靠的网状网络连接

配置参考

完整配置文件 (~/.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"

代理示例

发现模式

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

安全操作模式

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

关键操作模式

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"

注意事项

• 所有写入操作默认记录到~/.config/moltbot-ha/actions.log 安全设置可按安装进行配置
• 通配符 (
• *) 在allowed_entities和blocked_entities中受支持
• 可通过--json标志获取JSON输出，便于程序化解析