介绍
# Home Assistant Control
使用 `moltbot-ha` CLI 工具通过 Home Assistant API 控制您的智能家居。
## 设置
### 1. 安装 moltbot-ha ```bash uv tool install moltbot-ha ```
### 2. 初始化配置 ```bash moltbot-ha config init ```
设置过程将交互式地询问： - Home Assistant URL（例如 `http://192.168.1.100:8123`） - Token 存储首选项（推荐使用环境变量）
### 3. 设置环境变量 设置您的 Home Assistant 长效访问令牌： ```bash export HA_TOKEN="your_token_here" ```
要创建令牌： 1. 打开 Home Assistant → 个人资料（左下角） 2. 滚动到“长效访问令牌” 3. 点击“创建令牌” 4. 复制令牌并将其设置为 `HA_TOKEN` 环境变量
### 4. 测试连接 ```bash moltbot-ha test ```
## 发现命令
### 列出所有实体 ```bash moltbot-ha list ```
### 按域列出 ```bash moltbot-ha list light moltbot-ha list switch moltbot-ha list cover ```
### 获取实体状态 ```bash moltbot-ha state light.kitchen moltbot-ha state sensor.temperature_living_room ```
## 操作命令
### 打开/关闭 ```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 ```
### 设置属性 ```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 ```
### 调用服务 ```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 ```
### 通用服务调用 ```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}}' ```
## 安全与确认
moltbot-ha 实施了 **3 级安全系统** 以防止意外操作：
### 安全等级 3（默认 - 推荐）
关键操作需要显式确认： - **lock.***：门锁 - **alarm_control_panel.***：安全警报 - **cover.***：车库门、百叶窗
### 确认如何工作
1. **尝试关键操作：** ```bash 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. **Agent 看到此错误并询问您：** > "打开车库门是一项关键操作。您要继续吗？"
4. **您确认：** > "是的，打开它"
5. **Agent 使用 --force 重试：** ```bash moltbot-ha on cover.garage --force ```
6. **操作成功执行。**
### 重要：未经用户同意切勿使用 --force
**⚠️ Agent 的关键规则：**
- **切勿**在没有显式用户确认的情况下添加 `--force` 标志 - **始终**向用户显示正在尝试的关键操作 - 在使用 `--force` 之前 **等待** 明确的“yes” / “confirm” / “approve” - **聪明地**判断什么构成确认：在请求的上下文中，“Yes”、“OK”、“Sure”、“Do it”、“Confirmed”或任何肯定的回复都足够了。您**不需要**用户逐字输入特定短语。
### 受阻止的实体
某些实体可以在配置中被永久阻止： ```toml [safety] blocked_entities = ["switch.main_breaker", "lock.front_door"] ```
这些实体即使使用 `--force` 也 **无法** 被控制。
### 配置
编辑 `~/.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) ```
## 常见工作流程
### 早晨例程 ```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 ```
### 夜间模式 ```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 ```
### 检查传感器 ```bash 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`）：
```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" ```
## Agent 示例
### 发现模式 ``` 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 输出以便程序化解析