Home Assistant 控制：智能家居 REST API 集成 - Openclaw Skills

什么是 Home Assistant 控制？

Home Assistant 控制是一个专门为希望通过 AI 编码代理管理其智能家居生态系统的开发人员和高级用户设计的集成。通过利用 Home Assistant REST API 和长效访问令牌，此技能实现了与实体、服务、场景和脚本的无缝交互。它弥补了复杂的家庭自动化逻辑与自然语言执行之间的差距，使其成为使用 Openclaw Skills 构建个性化自动化工作流的基础。

该技能的构建侧重于可靠性和开发人员体验，具有用于实体发现、状态验证和安全操作执行的脚本。无论您是在调整照明、监控传感器数据，还是触发复杂的安全场景，此技能都提供了一种结构化且安全的方式，直接从您的开发环境与 Home Assistant 实例进行交互。

下载入口:https://github.com/openclaw/skills/tree/main/skills/hogar23/home-assistant-control

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install home-assistant-control

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 /skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 home-assistant-control。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Home Assistant 控制 应用场景

• 通过命令行或 AI 提示切换智能灯、插座和家电。
• 监控全屋的实时传感器数据和气候状态。
• 触发复杂的 Home Assistant 场景和脚本以执行自动化例程。
• 执行关键安全操作，如锁门或布防安全系统，并带有内置确认检查。
• 盘点家庭实体，将自然语言别名映射到技术实体 ID。

Home Assistant 控制 工作原理

1. AI 代理通过解释用户请求，识别涉及的特定 Home Assistant 服务或实体。
2. 它检查本地引用文件中的命名别名，以确保针对正确的实体 ID。
3. 该技能在尝试任何状态更改之前验证实体的当前状态和存在性。
4. 使用配置的访问令牌向 Home Assistant REST API 发送安全的 POST 或 GET 请求。
5. 该技能分析 API 响应并执行后续状态检查，以确认操作成功并向用户报告结果。

Home Assistant 控制 配置指南

要开始在您的 Openclaw Skills 集合中使用此集成，请按照以下步骤操作：

# 设置您的 Home Assistant 凭据
export HA_TOKEN="your_long_lived_access_token"
export HA_URL_PUBLIC="https://your-ha-instance.duckdns.org"

# 可选：设置本地 URL 以实现更快的网络访问
export HA_URL_LOCAL="http://192.168.1.100:8123"

# 运行自检脚本以验证连接性
./scripts/self_check.sh

# 生成您的实体清单
./scripts/fill_entities_md.sh

确保您的环境中可以使用 bash、curl 和 jq。

Home Assistant 控制 数据架构与分类体系

该技能通过以下文件结构组织其操作数据和上下文：

文件路径	描述	数据类型
references/entities.md	可用 Home Assistant 实体及其当前状态的完整清单。	Markdown 表格
references/naming-context.md	将自然语言名称链接到技术实体 ID 的自定义映射。	Markdown 列表
scripts/ha_call.sh	用于处理 HTTP 请求和身份验证的核心 API 封装程序。	Bash 脚本
scripts/ha_safe_action.sh	用于执行带有手动确认触发器的高风险服务的逻辑。	Bash 脚本

name: home-assistant-control
description: Control and inspect Home Assistant via REST API for entities, states, services, scenes, scripts, and automations. Use when the user asks to turn devices on/off, set values like brightness or temperature, trigger scenes/scripts/automations, or check current home/sensor status.
homepage: https://github.com/Hogar23/home-assistant-control
metadata:
  {
    "openclaw": {
      "emoji": "??",
      "requires": {
        "bins": ["bash", "curl", "jq"],
        "env": ["HA_TOKEN", "HA_URL_PUBLIC"]
      }
    }
  }

Home Assistant Control

Use Home Assistant REST API with a long-lived access token.

Requirements

For skill users (runtime)

• bash
• curl
• jq
• Home Assistant long-lived token (HA_TOKEN)
• Home Assistant public base URL (HA_URL_PUBLIC)

For skill maintainers (packaging/validation)

• python3
• pyyaml (required by skill-creator validator/packager scripts)

Required environment variables

• HA_TOKEN (required)
• HA_URL_PUBLIC (required; canonical target and fallback)
• Optional URL behavior:
  • if HA_URL_LOCAL is set (and no HA_URL override), local is tried first, then fallback to HA_URL_PUBLIC
  • HA_URL is an explicit override (if set, used directly)

Secrets handling (publish-safe)

• Keep keys/URLs in an external file, not in the skill folder.
• Set HA_ENV_FILE=/absolute/path/to/file.env when you want file-based secret loading.
• If HA_ENV_FILE is not set, scripts only use environment variables already present in the shell.
• scripts/ha_call.sh and scripts/self_check.sh load env file only when HA_ENV_FILE is provided.

Core workflow

1. Parse the user request into target entity/service + desired action.
2. Check references/naming-context.md for manual alias mappings first.
3. Verify entity exists before changing state.
4. Execute service call.
5. Re-check state and report outcome clearly.

Useful endpoints

• List states: GET /api/states
• Single state: GET /api/states/{entity_id}
• Call service: POST /api/services/{domain}/{service}

Headers:

• Authorization: Bearer $HA_TOKEN
• Content-Type: application/json

Scripts

• scripts/ha_env.sh — loads env file only when HA_ENV_FILE is explicitly set, using safe KEY=VALUE parsing (no source/eval).
• scripts/ha_call.sh — generic API caller for Home Assistant.
• scripts/fill_entities_md.sh — generate references/entities.md from GET /api/states.
  • Full map: ./scripts/fill_entities_md.sh
  • Filter domains: ./scripts/fill_entities_md.sh --domains light,switch,climate,sensor
• scripts/save_naming_context.sh — refresh references/naming-context.md for user-specific naming.
  • ./scripts/save_naming_context.sh
• scripts/ha_entity_find.sh — search entities by partial entity id or friendly name.
  • ./scripts/ha_entity_find.sh kitchen
  • ./scripts/ha_entity_find.sh temp --domains sensor,climate --limit 30
• scripts/ha_safe_action.sh — execute service actions with safety checks and risk confirmation.
  • ./scripts/ha_safe_action.sh light turn_on light.kitchen '{"brightness_pct":60}'
  • ./scripts/ha_safe_action.sh lock unlock lock.front_door --dry-run
  • Add --yes to bypass interactive confirmation for risky domains.
• scripts/self_check.sh — verify prerequisites and API connectivity/auth before running actions.
  • ./scripts/self_check.sh

Safety

• Confirm before high-impact actions (locks, alarms, garage/doors, heating shutdown).
• Do not print raw token values.
• If target entity is ambiguous, ask a follow-up question.
• Keep API paths scoped to Home Assistant endpoints only (/api/...).
• Use only HTTP(S) Home Assistant base URLs (HA_URL*), prefer HTTPS for public access.
• Avoid code execution when loading env files: parse key/value pairs, do not use source on untrusted paths.

Reference files

• references/entities.md — entity inventory
• references/naming-context.md — user alias memory for natural names (e.g. "living room light")

Publishing notes

• Keep examples generic (example_* IDs), no personal hostnames/tokens.
• Do not commit .env or any private env file with real tokens.
• Keep the skill focused: API workflow + reusable scripts + entity reference.