OpenClaw Home Assistant 技能指南

OpenClaw Home Assistant 技能概述

Home Assistant 技能將 OpenClaw 連接到你的 Home Assistant 實例，讓你的 AI 智慧體成為強大的智慧家庭控制器。無需瀏覽儀表板或編輯 YAML 設定檔，你可以透過自然語言管理整個智慧家庭——切換燈光、檢查感測器數據、建立自動化和排除裝置問題，一切都在終端中完成。

Home Assistant 是全球最大的開源家庭自動化平台，支援超過 2,000 種整合，涵蓋 Philips Hue、Zigbee、Z-Wave、Matter 等數百種裝置。OpenClaw Home Assistant 技能利用 Home Assistant REST API 讓你的智慧體直接存取實例上執行的實體、服務、自動化和腳本。

典型工作流程：

1. 讓 OpenClaw 關閉客廳所有燈光，並將恆溫器設定為 20°C。
2. 智慧體呼叫 Home Assistant API，識別相關實體並執行服務呼叫。
3. 確認訊息即刻回傳——無需開啟 Home Assistant 應用程式或儀表板。

該技能非常適合已經運行 Home Assistant 並希望更快速、可編程方式存取智慧家庭的開發者。它與 Slack 技能搭配良好，可將智慧家庭通知傳送到你的團隊頻道，也與基於 Docker 的部署自然整合（如果你在容器中運行 Home Assistant）。

Home Assistant 技能安裝前的準備

安裝 Home Assistant 技能之前，請確保你具備以下條件：

• OpenClaw 已安裝並運行（v1.0+）
• 一個可透過網路存取的 Home Assistant 實例（v2023.1+）——安裝指南
• 從你的 Home Assistant 個人資料中產生的長期存取權杖
• 從你的機器到 Home Assistant 實例的網路存取（本機或遠端）
• 已安裝 clawhub CLI 用於技能管理

驗證你的環境：

# 檢查 OpenClaw 版本
openclaw --version

# 測試 Home Assistant API 連線
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# 檢查 clawhub CLI
clawhub --version

如果 API 回傳 {"message": "API running."}，你的 Home Assistant 實例已就緒。

如何安裝 Home Assistant 技能

使用一條命令安裝 Home Assistant 技能：

npx clawhub@latest install home-assistant

驗證安裝：

clawhub list

你應該能在已安裝技能列表中看到 home-assistant。透過 clawhub CLI 安裝可獲得最快的設定體驗。

Home Assistant 技能設定指南

該技能需要 Home Assistant URL 和長期存取權杖來驗證 API 請求。

產生長期存取權杖

1. 在 http://YOUR_HA_HOST:8123 開啟你的 Home Assistant 儀表板。
2. 點擊左下角的個人資料圖示。
3. 滑動到長期存取權杖區域，點擊建立權杖。
4. 將其命名為 openclaw-agent 並複製產生的權杖。

環境設定

設定以下環境變數：

# Home Assistant 實例 URL（如使用非標準連接埠請包含連接埠號）
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# 長期存取權杖
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

你可以將這些新增到 shell 設定檔（~/.bashrc、~/.zshrc）或搭配金鑰管理器使用 .env 檔案。

重要提示： 切勿將權杖硬編碼到設定檔中或提交到版本控制。請使用環境變數或專用的金鑰管理器，例如 1Password。

可選：遠端存取

如果你的 Home Assistant 實例不在同一網路上，可透過以下方式設定遠端存取：

| 方式 | 說明 | |------|------| | Nabu Casa | Home Assistant Cloud——最簡單的選項，提供遠端 URL | | 反向代理 | 使用 Nginx 或 Caddy 進行 SSL 終止 | | Tailscale/WireGuard | VPN 隧道，提供安全的區域網路存取體驗 |

Home Assistant 技能使用範例

1. 控制燈光和裝置

你： "關閉臥室所有燈光，並將客廳亮度設定為 40%。"

智慧體對臥室實體呼叫 light.turn_off，並對客廳燈光呼叫 light.turn_on（設定 brightness_pct: 40）。它會根據房間分配識別實體，並回傳確認摘要。

2. 查詢感測器資料

你： "目前辦公室的溫度是多少？今天的總能源使用量呢？"

智慧體查詢 sensor.office_temperature 和 sensor.energy_daily 實體，回傳格式化的讀數："辦公室溫度：22.3°C。今日能源使用量：14.7 kWh。"它會處理單位轉換並格式化資料以提升可讀性。

3. 建立自動化

你： "建立一個自動化，在日落時開啟門廊燈，每晚 11 點關閉。"

智慧體使用 sun 觸發器（日落）和 time 觸發器（23:00）建立 Home Assistant 自動化。它透過 API 註冊自動化、指定描述性名稱，並確認已啟用。

4. 啟動場景

你： "啟動電影之夜場景。"

智慧體對 scene.movie_night 呼叫 scene.turn_on，這會調暗燈光、關閉窗簾，並將媒體播放器設定到正確的輸入源——所有這些都在你現有的場景定義中設定。

5. 排除裝置狀態問題

你： "哪些裝置目前不可用或離線？"

智慧體查詢所有狀態為 unavailable 或 unknown 的實體，按整合分組，並回傳診斷報告："3 個裝置離線——Zigbee 動態感測器（2 小時前最後偵測到）、廚房智慧插座（無法連線）、天氣整合（API 逾時）。"

安全與最佳實踐

請遵循以下指南確保你的智慧家庭安全：

• 使用最小權限。 為 OpenClaw 建立專用的 Home Assistant 使用者，僅授予你希望智慧體控制的房間和裝置的權限。避免使用管理員帳戶的權杖。
• 執行前確認。 智慧體在執行刪除自動化或停用整合等破壞性操作前，會描述其計畫。務必檢視操作摘要。
• 妥善保管權杖。 長期存取權杖提供完整的 API 存取權限。將其儲存在環境變數中，切勿放在純文字檔案中。定期從 Home Assistant 個人資料頁面輪換權杖。
• 使用 HTTPS。 如果遠端存取 Home Assistant，務必使用具有有效 SSL 憑證的 HTTPS。切勿在沒有加密的情況下將實例暴露在公共網路上。
• 限制網路存取。 使用 Home Assistant 的 ip_bans 或防火牆規則將 API 存取限制在受信任的 IP 範圍內。查看安全檢查清單了解通用的 OpenClaw 安全指南。

常見錯誤與故障排除

"401 Unauthorized — Invalid access token"

長期存取權杖無效或已過期。

1. 驗證權杖是否已正確設定：

echo $HOMEASSISTANT_TOKEN

2. 從 Home Assistant 個人資料頁面產生新的權杖。
3. 確保權杖值中沒有多餘的空格或換行符。

"Connection refused — Cannot reach Home Assistant"

智慧體無法連線到你的 Home Assistant 實例。

1. 驗證 URL 是否正確且包含連接埠：

curl -s http://YOUR_HA_HOST:8123/api/

2. 檢查 Home Assistant 是否正在運行：sudo systemctl status homeassistant（適用於 Supervised 安裝）。
3. 如果使用 Docker，確認容器正在運行：docker ps | grep homeassistant。
4. 檢查防火牆規則——連接埠 8123 必須從你的機器可存取。

"Entity not found — light.living_room"

實體 ID 與 Home Assistant 中的任何裝置不匹配。

1. 列出所有可用實體：

curl -s -H "Authorization: Bearer $HOMEASSISTANT_TOKEN" \
  http://YOUR_HA_HOST:8123/api/states | jq '.[].entity_id' | grep light

2. 實體 ID 區分大小寫且使用底線——請檢查是否有拼寫錯誤。
3. 如果裝置是最近新增的，重新啟動 Home Assistant 以重新整理實體註冊。