Homey 智能家居控制

通过本地（局域网/VPN）或云端 API，使用令牌认证来控制 Athom Homey 设备。

设置

需要 Node.js 版本 >= 18。

1. 选择本地或云端模式

   • 本地模式（局域网/VPN）：使用从 Homey Web 应用获取的本地 API 密钥 + Homey IP 地址
   • 云端模式（远程/无头模式）：使用从开发者工具获取的云端令牌

2. 配置

   本地（当代理运行在您的家庭网络时推荐）：

   homeycli auth discover-local --save --pick 1
   echo "<LOCAL_API_KEY>" | homeycli auth set-local --stdin
   # or interactive (hidden input): homeycli auth set-local --prompt
   

   云端（推荐用于 VPS/无头托管）：

   echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
   # or interactive (hidden input): homeycli auth set-token --prompt
   

   检查状态：

   homeycli auth status
   

3. 测试连接

   homeycli status
   

命令

快照（推荐用于代理）

homeycli snapshot --json
homeycli snapshot --json --include-flows

列出设备

homeycli devices              # Pretty table output
homeycli devices --json       # JSON output for AI parsing (includes latest values)

# Filter by name (returns multiple matches)
homeycli devices --match "kitchen" --json

控制设备

打开/关闭设备：

homeycli device "Living Room Light" on
homeycli device "Bedroom Lamp" off

设置特定能力：

homeycli device "Dimmer" set dim 0.5                    # 50% brightness
homeycli device "Thermostat" set target_temperature 21  # Set temperature
homeycli device "RGB Light" set light_hue 0.5           # Hue (0-1)
homeycli device "Lock" set locked true                  # Lock device

获取能力值：

homeycli device "Thermostat" get measure_temperature
homeycli device "Motion Sensor" get alarm_motion

# Get all values for a device (multi-sensors)
homeycli device "Living Room Air" values
homeycli device "Living Room Air" get

流程（自动化）

homeycli flows                        # List all flows
homeycli flows --json                 # JSON output
homeycli flows --match "good" --json  # Filter flows by name
homeycli flow trigger "Good Night"    # Trigger by name
homeycli flow trigger <flow-id>       # Trigger by ID

区域 (房间)

homeycli zones           # List all zones/rooms
homeycli zones --json    # JSON output

状态

homeycli status    # Show Homey connection info

通用能力

用法homeycli devices查看每个设备支持的功能。

模糊匹配

设备和流程名称支持模糊匹配：

• 精确匹配："客厅灯" → 找到 "客厅灯"
• 子字符串："客厅灯" → 找到 "客厅灯"
• 莱文斯坦距离："客听灯" → 找到 "客厅灯"（容错拼写）

JSON 模式

添加--json到任何命令以获取机器可读的输出：

homeycli devices --json | jq '.[] | select(.class == "light")'
homeycli status --json

示例

晨间例程：

homeycli device "Bedroom Light" on
homeycli device "Bedroom Light" set dim 0.3
homeycli device "Thermostat" set target_temperature 20

检查温度：

homeycli device "Living Room" get measure_temperature

触发场景：

homeycli flow trigger "Movie Time"

列出所有灯光：

homeycli devices --json | jq '.[] | select(.class == "light") | .name'

故障排除

"未配置认证"

本地（局域网/VPN）：

• 保存本地配置：echo "<LOCAL_API_KEY>" | homeycli auth set-local --address http://<homey-ip> --stdin

云端（远程/无头模式）：

• 保存云端令牌：echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
• 云端令牌可在 Homey 开发者工具中创建：https://tools.developer.homey.app/api/clients

"未找到设备" / 匹配不明确

• 使用以下命令列出设备：homeycli devices --json（或homeycli devices --match <查询> --json）以找到正确的id
• 如果查询匹配多个设备，CLI 将返回候选 ID 并要求您通过 ID 指定设备

"不支持的功能"

• 检查可用功能：homeycli devices显示每个设备支持的功能
• 常见问题：尝试打开传感器（请使用获取而不是设置）

API 参考

CLI 使用官方的homey-apinpm 包（版本 3.15.0）。

认证/连接模式：

• 本地模式： HomeyAPI.createLocalAPI({ 地址, 令牌 })使用 Homey Web App 的本地 API 密钥。
• 云端模式： AthomCloudAPI使用云端承载令牌（PAT）创建会话并访问设备/流程/区域。