hass-config-flow

Home Assistant REST API

文档：https://developers.home-assistant.io/docs/api/rest/

NixOS 的 extraComponents 会捆绑集成代码，但仅支持 config flow 的集成（Spotify、Matter、HomeKit Controller、Cast 等）需要通过 REST API 或 UI 完成设置。

hass-cli（检查和简单调用时优先使用）

NUC 上已安装 home-assistant-cli。列出实体、调用服务、管理设备/区域以及监听事件时，优先使用它，而不是原始 curl。

# On NUC (after getting a token):
export HASS_SERVER=http://localhost:8123
export HASS_TOKEN=<token>

hass-cli state list 'light.*'          # list entities by glob
hass-cli state get light.office        # get single entity (yaml)
hass-cli service call homeassistant.toggle --arguments entity_id=light.office
hass-cli device list                   # all devices with area
hass-cli area list                     # all areas
hass-cli device assign Kitchen --match "Kitchen Light"  # bulk assign area
hass-cli event watch                   # watch all events
hass-cli event watch deconz_event      # watch specific event type
hass-cli -o yaml state list            # yaml output
hass-cli -o json state list 'light.*' | jq '[.[] | {entity: .entity_id, name: .attributes.friendly_name, state: .state}]'
hass-cli -o json state list 'light.*' | python3 -c "import json,sys; d=json.load(sys.stdin); print([x['entity_id'] for x in d if x['state']=='on'])"

**注意：**当前 HA 中的 hass-cli info 无法使用（端点已弃用）。其他命令均可正常使用。

对于 config flow、应用凭据，以及 hass-cli 不支持的操作，请使用原始 curl（如下所示）。

查询 API（内联 SSH）

scripts/ 中的脚本仅存在于本地，无法通过路径在 NUC 上引用。请改用内联 SSH 命令。

获取令牌

TOKEN=$(ssh nuc "sudo python3 -c '
import hashlib, hmac, base64, time, json
auth = json.load(open(\"/var/lib/hass/.storage/auth\"))
for t in auth[\"data\"][\"refresh_tokens\"]:
    if t.get(\"client_name\") == \"agent-automation\":
        header = base64.urlsafe_b64encode(json.dumps({\"alg\":\"HS256\",\"typ\":\"JWT\"}).encode()).rstrip(b\"=\")
        now = int(time.time())
        payload = base64.urlsafe_b64encode(json.dumps({\"iss\":t[\"id\"],\"iat\":now,\"exp\":now+86400*365}).encode()).rstrip(b\"=\")
        sig_input = header + b\".\" + payload
        sig = base64.urlsafe_b64encode(hmac.new(t[\"jwt_key\"].encode(), sig_input, hashlib.sha256).digest()).rstrip(b\"=\")
        print((sig_input + b\".\" + sig).decode())
        break
'" 2>/dev/null)

列出实体（按域）

ssh nuc "curl -s -H 'Authorization: Bearer $TOKEN' http://localhost:8123/api/states" | python3 -c "
import json, sys
states = json.load(sys.stdin)
for s in sorted(states, key=lambda x: x['entity_id']):
    eid = s['entity_id']
    name = s['attributes'].get('friendly_name', '')
    domain = eid.split('.')[0]
    if domain in ('light', 'switch', 'cover', 'media_player', 'fan', 'binary_sensor', 'scene', 'humidifier'):
        print(f'{eid:55s} {name}')
"

根据需要修改 domain in (...) 过滤条件，或者移除该条件以列出所有实体。

调用服务

ssh nuc "curl -s -X POST -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{\"entity_id\": \"media_player.tv\"}' \
  http://localhost:8123/api/services/media_player/turn_off"

启动 config flow

ssh nuc "curl -s -X POST -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{\"handler\": \"spotify\"}' \
  http://localhost:8123/api/config/config_entries/flow"

辅助脚本（参考）

scripts/ 中的脚本可用于参考 API 模式，但必须通过 SSH 管道传输或直接内联；这些脚本不会部署到 NUC 上。

脚本	用途
ha-token.sh	从身份验证存储生成 JWT
ha-api.sh	通用 API 包装器
ha-entities.sh	按域列出实体
ha-integrations.sh	列出已配置的集成
ha-call.sh	在实体上调用服务
ha-flow.sh	管理 config flow（启动/提交）

参考资料

请阅读以下内容以了解详细信息：

文件	内容
references/integration-flows.md	各集成的 config flow 行为、中止原因、mDNS 发现命令
references/default-integrations.md	NixOS 的 defaultIntegrations 列表——自动加载的内容、Nix 配置示例
references/device-protocols.md	根据设备注册表识别设备协议（Matter/Zigbee/Thread/HomeKit）；厂商型号命名惯例；ZHA 迁移决策树

令牌生成

HA 长期令牌是 HS256 JWT，使用 /var/lib/hass/.storage/auth 中每个令牌对应的密钥签名。请使用 scripts/ha-token.sh 或内联执行：

ssh nuc "sudo bash ha-token.sh"           # uses "agent-automation" token
ssh nuc "sudo bash ha-token.sh my-token"  # use a different token name

如果尚无令牌，请通过 HA UI 创建： 个人资料 → 安全性 → 长期访问令牌 → 创建令牌

验证：curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8123/api/ → {"message":"API running."}

API 快速参考

所有请求均发送至 http://127.0.0.1:8123，并携带 Authorization: Bearer $TOKEN。

操作	方法	端点	请求体
健康检查	GET	/api/	—
HA 配置	GET	/api/config	—
列出状态	GET	/api/states	—
获取实体状态	GET	/api/states/{entity_id}	—
设置实体状态	POST	/api/states/{entity_id}	{"state": "...", "attributes": {...}}
触发事件	POST	/api/events/{event_type}	{...event_data}
调用服务	POST	/api/services/{domain}/{service}	{"entity_id": "..."} + 服务数据
列出服务	GET	/api/services	—
列出配置条目	GET	/api/config/config_entries/entry	—
启动配置流程	POST	/api/config/config_entries/flow	{"handler": "domain"}
提交流程步骤	POST	/api/config/config_entries/flow/{flow_id}	步骤专属数据
中止流程	DELETE	/api/config/config_entries/flow/{flow_id}	—
删除配置条目	DELETE	/api/config/config_entries/entry/{entry_id}	—
添加应用凭据	POST	/api/config/application_credentials	{"domain":"...","client_id":"...","client_secret":"..."}
渲染模板	POST	/api/template	{"template": "{{ states('...') }}"}
检查配置	POST	/api/config/core/check_config	—

关键工作流

配置流程（非 OAuth）

ha-flow.sh start cast           # auto-discovery, usually creates entry immediately
ha-flow.sh start matter         # returns form → submit with URL
ha-flow.sh submit <flow_id> '{"url":"ws://localhost:5580/ws"}'

OAuth 集成（Spotify、Google 等）

1. 先注册应用凭据（中止原因：missing_credentials）
2. 启动配置流程 — 返回供用户使用的授权 URL

ha-api.sh POST /api/config/application_credentials \
  '{"domain":"spotify","client_id":"ID","client_secret":"SECRET"}'
ha-flow.sh start spotify

有关各集成的详细信息，请参阅 references/integration-flows.md。

NixOS 环境

• 身份验证存储：/var/lib/hass/.storage/auth
• API：http://127.0.0.1:8123（仅限本地主机），通过 Tailscale serve 使用 HTTPS
• 公共 URL：https://homeassistant.cinnamon-rooster.ts.net/
• defaultIntegrations 会自动加载输入助手、自动化、场景、脚本等 — 请参阅 references/default-integrations.md