name: moltbot-ha
description: 通过 moltbot-ha CLI 控制 Home Assistant 智能家居设备、灯光、场景和自动化，支持可配置的安全确认机制。
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":"安装 moltbot-ha (uv 工具)"}]}}

Home Assistant 控制

使用 moltbot-ha CLI 工具通过 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

操作命令

开启/关闭

# 开启
moltbot-ha on light.living_room
moltbot-ha on switch.coffee_maker

# 关闭
moltbot-ha off light.bedroom
moltbot-ha off switch.fan

# 切换状态
moltbot-ha toggle light.hallway

设置属性

# 设置亮度 (百分比)
moltbot-ha set light.bedroom brightness_pct=50

# 设置色温
moltbot-ha set light.office color_temp=300

# 设置多个属性
moltbot-ha set light.kitchen brightness_pct=80 color_temp=350

调用服务

# 激活场景
moltbot-ha call scene.turn_on entity_id=scene.movie_time

# 设置恒温器温度
moltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21

# 关闭覆盖物 (百叶窗、车库门)
moltbot-ha call cover.close_cover entity_id=cover.garage

通用服务调用

# 带参数调用
moltbot-ha call automation.trigger entity_id=automation.morning_routine

# 带 JSON 数据调用
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. 工具返回错误：

⚠️  关键操作需要确认

操作：对 cover.garage 执行 turn_on

这是一个需要用户明确批准的关键操作。
请询问用户以确认，然后使用 --force 标志重试。

示例：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=禁用，1=仅记录日志，2=确认所有写入操作，3=确认关键操作
critical_domains = ["lock", "alarm_control_panel", "cover"]
blocked_entities = []  # 添加永远不应自动化的实体
allowed_entities = []  # 如果设置，则仅可访问这些实体 (支持通配符)

常见工作流

早晨例程

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.*  # 需要未来版本支持通配符
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 区分大小写
• 格式为 domain.entity_name (例如：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"

代理使用示例

发现模式

用户：“我有哪些灯？”
代理：moltbot-ha list light
代理：“您有以下这些灯：light.living_room, light.kitchen, light.bedroom”

安全操作模式

用户：“打开客厅的灯”
代理：moltbot-ha on light.living_room
代理：“客厅的灯现已打开”

关键操作模式

用户：“打开车库”
代理：moltbot-ha on cover.garage
<收到 CriticalActionError>
代理：“⚠️ 打开车库门是一个关键操作。您确定要继续吗？”
用户：“是的，打开它”
代理：moltbot-ha on cover.garage --force
代理：“车库门正在打开”

注意事项

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