整合服務串接 Integrations
整合(Integration)是 HA 對外的插座。天氣、Spotify、Apple TV、Google 行事曆、手機定位、LINE 通知,全都靠它接進來。這一章把「新增整合」這個動作拆到最細,再帶你一類一類接,最後教你在整合壞掉時怎麼救。
為什麼要學這個
前面 13 章你做的事,幾乎都是在整理「HA 裡面已經有的東西」——區域、命名、儀表板、自動化、腳本。但 HA 剛裝好的時候,裡面其實沒幾樣東西。它像一間剛交屋的空房子:牆壁刷好了、插座裝好了,可是家電還沒買。
整合就是把家電插上去的那個動作。你想讓玄關燈在日落時開,得先有「日落」這個資訊(天氣/太陽整合);你想在下班進門時自動放音樂,得先有「我到家了」(定位整合)跟「音樂」(媒體整合);你想在洗衣機洗完時收到 LINE,得先有一條通知管道。
這章講完你會有這些能力:
- 看懂「整合 → 裝置 → 實體」這條食物鏈,知道刪掉一個整合會連帶死掉哪些東西
- 自己完成一次完整的新增整合流程,包含要輸入帳密/API 金鑰/掃 QR code 的那種
- 看懂 OAuth 授權為什麼常常卡在「網址對不上」,並知道怎麼解
- 判斷一個整合是「雲端」還是「本地」,斷網時會不會全家變磚
- 整合掛掉時,會下載診斷檔、會重新驗證、會重新載入、會乾淨移除
整合、裝置、實體:三層關係與 Config Flow
一句話版本
整合(Integration)是一段「會講某個品牌/服務語言」的程式碼;你設定好一次之後,它會生出裝置(Device);每個裝置底下再掛一堆實體(Entity),實體才是你在儀表板上按得到、在自動化裡面叫得動的東西。
| 層級 | 是什麼 | 客廳的例子 | 你能對它做什麼 |
|---|---|---|---|
| 整合 Integration | 跟某個品牌/雲端服務溝通的模組 | 「Google Cast」整合 | 新增、重新載入、移除、下載診斷 |
| 設定項 Config Entry | 你這次設定所存下來的那一筆帳(一個整合可以有很多筆) | 「客廳 Chromecast」這一筆 | 重新命名、重新設定、停用、刪除 |
| 裝置 Device | 一台實體或邏輯上的機器 | 客廳電視上那顆 Chromecast | 指派區域、看韌體、改名(第 11 章) |
| 實體 Entity | 一個可讀或可控的最小單位 | media_player.living_room_tv | 放上儀表板、寫進自動化(第 12 章) |
binary_sensor,加一個 calendar),裝置頁完全找不到它——因為它背後根本沒有一台機器。這不是壞掉,是正常的,要去實體列表找。
Config Flow 是什麼?為什麼你不用改 YAML 了
早年加整合要手動編輯 configuration.yaml,打錯一個縮排整個 HA 起不來。現在絕大多數整合都改用 Config Flow(設定流程):整合自己定義好「要問使用者哪幾個問題」,HA 就把它渲染成一頁一頁的視窗,你照著填、按下一步就好,填完的結果存成一筆 Config Entry(設定項)。
Config Flow 有好幾種觸發方式,看懂了你就知道畫面為什麼會自己跳出來:
| 流程種類 | 什麼時候發生 | 你會看到什麼 |
|---|---|---|
| 使用者流程 User | 你自己按「新增整合」 | 搜尋品牌 → 填表單 |
| 探索流程 Discovery | HA 在網路上自己聞到設備(mDNS/SSDP/DHCP/藍牙) | 整合頁最上面出現「已探索」區塊,按「新增」即可 |
| 重新驗證 Reauth | 密碼改了、Token 過期、對方 API 把你踢掉 | 整合卡片變紅,出現「重新驗證」按鈕 |
| 重新設定 Reconfigure | 你想換 IP、換帳號,但不想砍掉重練 | 三點選單裡的「重新設定」 |
| 選項流程 Options | 裝好之後想微調(更新頻率、要抓哪些項目) | 整合卡片上的「設定 / 選項」 |
整合文件上那個標籤是什麼意思
你去官方整合頁面時,會看到品質等級(Quality Scale)標籤。它不是評分好玩的,直接影響你會不會踩雷:
| 標籤 | 白話翻譯 |
|---|---|
| Bronze 銅 | 及格線:能用 UI 設定、有基本文件 |
| Silver 銀 | 比較穩:錯誤處理完整,而且有活著的維護者 |
| Gold 金 | 很完整:會自動探索、有韌體更新、文件詳盡 |
| Platinum 白金 | 技術上最漂亮:全非同步、效能最佳化 |
| Legacy 舊制 | 老東西,通常只能用 YAML 設定、沒什麼人維護了 |
| Custom 自訂 | 社群做的,官方沒審過,自己承擔風險(HACS 的都算這類) |
動手:完整跑一次新增整合
我們拿最無痛的天氣整合當練習——不用帳號、不用金鑰、不會弄壞任何東西,跑完一次你就懂所有整合的節奏了。
-
先確認你的位置設好了
天氣整合會直接吃 HA 的家庭座標。左側欄 設定 → 系統 → 家庭資訊(Home information) 裡的緯度經度如果還是預設值,抓出來的天氣會是別的國家。這一頁以前叫「一般(General)」,官方文件已經改稱「家庭資訊」,舊教學上寫的是舊名字。這件事第 2 章已經做過了,沒做的先回去補。
-
打開整合頁
左側欄 設定(Settings)→ 裝置與服務(Devices & services)。這頁上方有幾個分頁:整合、裝置、實體、助手(Helpers)。預設停在「整合」。
圖 14-1整合頁上方分頁:整合/裝置/實體/助手。右下角的「新增整合」是主要入口。 -
先看「已探索」區塊
如果頁面最上面有「已探索(Discovered)」的卡片,那是 HA 自己在你網路上聞到的設備。這裡出現的東西按一下「新增」通常兩三步就完成,比自己搜尋快很多。先看這裡,沒有再往下走。
圖 14-2「已探索」卡片:HA 透過 mDNS/SSDP/DHCP/藍牙自己聞到的裝置,按 Add 就直接進入設定流程。 -
按右下角的「新增整合」
畫面右下角有一顆「新增整合(Add integration)」按鈕。按下去會跳出一個搜尋框。
-
搜尋品牌名稱
輸入
Open-Meteo(或Met.no)。搜尋是比對品牌名,中文打不到,一律打英文。清單出現後點選它。 -
照著表單填完
Open-Meteo 不需要任何 API 金鑰,官方文件明確寫「不需要帳號或 API key」。它會問你要用哪一個 Zone(區域範圍)當作預報地點,選「Home」就好。Zone 是第 5 章設過的東西。
-
指派區域,然後按完成
最後一步 HA 會問你要把它歸到哪個區域(Area)。天氣沒有實體位置,可以留空;如果是實體設備,這裡選對區域可以省掉之後手動歸類的功夫。按 完成(Finish)。
-
回頭看它生出了什麼
整合卡片上會寫「1 個實體」之類的字樣,點進去就看得到。Open-Meteo 每個 Zone 生一個
weather實體,名字跟著 Zone 走。把這個實體丟到儀表板上(第 6 章),你就有天氣卡片了。
OAuth 類整合:為什麼一定卡在網址
Spotify、Google 行事曆、各家車廠 App……這類整合不會叫你直接輸入密碼(那太危險),而是走 OAuth 授權:把你踢到對方網站登入,對方確認後再把「授權碼」丟回你的 HA。
問題就出在「丟回你的 HA」這一步。對方的伺服器要知道往哪裡丟,所以它會要求你事先登記一個 重新導向網址(Redirect URI)。而 http://192.168.1.50:8123(2026.8 之後新裝的 HA OS 預設不帶埠號,會是 http://192.168.1.50,一樣是內網位址)這種東西,Google 跟 Spotify 是不收的。
HA 的解法:My Home Assistant
官方做了一個中繼站 my.home-assistant.io。多數 OAuth 整合的官方文件都直接給你這一串當作要填進對方後台的重新導向網址:
https://my.home-assistant.io/redirect/oauth
Spotify 的官方文件甚至特別強調:「請完整複製貼上上面這個網址,你不需要去改它。」Google 行事曆文件裡的授權重新導向網址也是同一串。
它的運作方式是:你的 HA 網址存在你自己瀏覽器的本機儲存空間裡,My Home Assistant 只負責把瀏覽器再導回你的 HA。官方文件明講你的 instance URL「永遠不會傳給任何外部服務,連 My Home Assistant 服務本身也不會」。
如果你把 My Home Assistant 關掉了
那就要改用你自己的網址加上固定路徑:
<你的 HA 網址>/auth/external/callback
這時候「你的 HA 網址」就必須是對方廠商肯接受的形式(通常要 HTTPS 的網域名稱),這就是為什麼 OAuth 整合常常逼你先把遠端連線搞定。遠端存取的做法(Nabu Casa 雲端、自架反向代理、DDNS)在附錄 A有整理,先去把那件事做完再回來。
自己申請 Client ID / Secret 的那一步
有些服務不允許 HA 內建通用金鑰,必須你自己去開發者後台開一個 App。目前確定要自己申請的包含:
- Spotify:到 Spotify Developer Dashboard 建立 App,勾選 Web API,拿到 Client ID 與 Client Secret。官方文件註明「自 2026 年 2 月起,要進入開發者後台建立 App 需要 Premium 帳號」。
- Google 行事曆:要在 Google Cloud Console 建專案、啟用 Google Calendar API、設定 OAuth 同意畫面、再建一個「網頁應用程式」類型的用戶端。
拿到的 ID 與密鑰在跑 Config Flow 時會被要求貼上。之後要換或刪,路徑是 設定 → 裝置與服務,右上角三點選單 → 應用程式憑證(Application credentials)。
天氣:Met.no、Open-Meteo 與台灣氣象署
天氣是最值得先接的一類,因為它餵養一大堆自動化:下雨了關陽台窗、氣溫超過 30 度提前開冷氣、紫外線高就提醒帶帽子。
| 整合 | 要不要金鑰 | 設定內容 | 適合誰 |
|---|---|---|---|
| Met.no(挪威氣象局) | 不用 | 名稱、緯度、經度、海拔 | 想無腦裝好就走的人;HA 內建、用的人非常多 |
| Open-Meteo | 不用 | 選一個 Zone | 想用 Zone 綁定地點(例如公司)的人 |
| 中央氣象署 CWA | 要(免費申請) | 見下方說明 | 需要台灣本地預報用語、鄉鎮級資料的人 |
Met.no 的兩個細節
- 它有一個「海拔(Elevation)」欄位,官方文件說這會影響溫度預報的準確度,山區特別明顯。住山上的填實際海拔,平地填 0~50 都差不多。
- 更新頻率不是你能調的。官方文件寫的是每 55 到 65 分鐘更新一次,而且刻意做隨機化來分散 API 負載。所以別期待它像室內溫濕度計那樣即時。
台灣中央氣象署(CWA)的實務做法
這裡要講清楚:截至撰稿時,Home Assistant 官方核心整合列表裡沒有中央氣象署的整合。想吃 CWA 的資料,只有兩條路:
-
先去申請授權碼
到氣象資料開放平臺
opendata.cwa.gov.tw註冊一般會員,在會員專區的「取得授權碼」頁面拿到你的 API Key。一般會員是免費的。 -
路線 A:裝社群自訂整合
社群有以 CWA 開放資料為基礎的自訂整合(例如
tsunglung/OpenCWB),透過 HACS 以「自訂儲存庫」方式加入,設定流程會問你 API Key 跟地點名稱。但這是社群維護的東西,更新速度與 CWA API 改版能否跟上都不保證,請自己先看一下該專案最近有沒有在動。 -
路線 B:自己用 RESTful 感測器接
CWA 開放平臺是標準的 REST API,你可以用 HA 內建的 RESTful 感測器直接打它、把 JSON 拆成你要的欄位。做法比較硬,但完全掌握在自己手上,不怕哪天自訂整合沒人維護。
音樂與媒體:Spotify、Apple TV、Chromecast
這三個都會生出 media_player 實體,用第 12 章學過的那套 domain 動作就能控制。差別在於它們是怎麼連上的。
| 整合 | 連線方式 | 生出的實體 | 最大的坑 |
|---|---|---|---|
| Spotify | 雲端 OAuth | media_player | 要 Premium、要自己申請 Client ID/Secret |
| Apple TV | 本地區網 + PIN 配對 | media_player、remote、binary_sensor | AirPlay 存取權限設太嚴會配對失敗 |
| Google Cast | 本地區網 + mDNS 自動探索 | media_player | 跨網段就找不到 |
Spotify
需要 Premium 帳號,官方文件寫得很明白。設定完之後它給你一顆 media_player 實體,可以控播放、可以用「來源(Source)」切換要丟到哪一台喇叭。
Apple TV
設定時 HA 會要你在電視畫面上讀 PIN 碼、輸入回 HA 完成配對。裝好之後你會拿到三種實體:media_player(看現在在播什麼、控制播放)、remote(模擬遙控器按鍵)、還有一個追蹤鍵盤焦點的 binary_sensor——後者很好用,可以在 Apple TV 跳出輸入框時自動把手機鍵盤叫出來。
幾個官方文件講明的限制,先知道免得白折騰:
- 部分功能(例如快速動作選單)需要 tvOS 14.0 以上。
- 按鈕能不能用是各 App 自己決定的,不是整合的問題。某個 App 的暫停鍵沒反應,那是那個 App 沒實作。
- 音量控制只有在接 HomePod 時才可靠;走 HDMI CEC 只有上下微調,走紅外線則完全遙控不到。
- 沒辦法在不互動的情況下偵測電源狀態,官方 FAQ 直接回答「不行」。
remote實體的開關機是只改 HA 這邊記錄的電源狀態,不是真的去把機器叫醒或關掉。所以別拿它當「電視有沒有開」的可靠依據。
Google Cast(Chromecast、Google Nest 喇叭)
正常情況下你什麼都不用做,開機幾分鐘後它就出現在「已探索」裡。找不到的話,官方文件列的網路條件請逐條檢查:
- mDNS 必須通:自動探索完全靠它,官方寫的是「強制必要」。
- 要同一個網段:mDNS 封包不會跨子網路。HA 在 VLAN 10、Chromecast 在 VLAN 20 就是找不到。
- Docker 要用 host 網路模式:用 Container 方式安裝 HA 的話,官方明講要跑在 host network mode。
- Chromecast 有個怪癖:它不用你路由器發的 DNS,官方文件寫的是它直接走 Google 的公共 DNS(8.8.8.8 / 8.8.4.4)。所以你在路由器上自己設的內網域名,Chromecast 查不到。實際影響是:要投放的媒體網址(例如你家 NAS 上的影片、攝影機畫面)必須用直接 IP,或是外面查得到的公開網址,否則電視上只會轉圈圈。
真的探索不到,整合設定裡可以填「已知主機(Known hosts)」,官方說明是用逗號分隔的主機名稱或 IP 清單,直接打進去就能繞過 mDNS 探索。
cast.show_lovelace_view,可以把你的 HA 儀表板直接投到電視上。做一個「回家模式」自動化,進門就把家庭狀態板投到客廳電視,很有感。定位:讓 HA 知道你到家了
定位是「情境自動化」的靈魂。沒有定位,你的自動化只能看時間;有了定位,才能做「離家全關」「進門開燈」。定位資料最後都會變成 device_tracker 實體,再配合第 5 章設好的 Zone(區域範圍)與 Person(人員)來判斷。
| 方案 | 準確度/即時性 | 耗電 | 建議 |
|---|---|---|---|
| Companion App(官方手機 App) | 最好,有地理圍欄即時觸發 | 可調 | 首選,其他都是備案 |
| iCloud | 輪詢,會有延遲 | 低(會自動調整頻率) | 家人不肯裝 App 但有 iPhone 時用 |
| Google Maps 位置分享 | 輪詢 | 低 | 官方標為 Legacy,能不用就不用 |
Companion App(強烈建議走這條)
手機裝好官方 App 並登入,它第一次啟動就會自己建立一個 device_tracker.<你的裝置名> 實體,屬性裡包含 GPS 座標、電量、精確度、海拔、速度。
回報時機(依官方文件):進入或離開你在 HA 裡定義的 Zone、App 啟動時、背景抓取時、收到通知時,以及 iOS 的「重大位置變更」。iOS 會在啟動時自動為所有已設定的 Zone 建立地理圍欄;Android 則要在 App 設定裡把 Zone 追蹤打開。
unavailable,先回去看手機的權限。App 通知與感測器的細節第 7 章已經講過了,這裡不重複。
iCloud
設定時不能直接用你的 Apple ID 密碼,官方文件要求使用App 專用密碼(app-specific password)——到 Apple ID 網站產生一組給 HA 專用的。另外裝置必須有註冊「尋找」(Find My)服務才抓得到。
它會為每台 iCloud 裝置產生 device_tracker 與電量感測器,還提供幾個動作:顯示訊息、啟動遺失模式、播放聲音、要求更新位置。它的輪詢間隔是動態的,會依照裝置在哪個 Zone、離家多遠、電量多少來調整,避免把手機電池吸乾。
Google Maps 位置分享
官方文件上這個整合掛著 Legacy(舊制)標籤,屬於社群維護、不太會有新功能的狀態,官方頁面顯示的安裝數也只有三百多套,非常邊緣。
而且它設定起來一點都不輕鬆,這幾點看完你大概就會放棄了:
- 不能用 UI 設定,只能手寫
configuration.yaml的device_tracker區段——這正是 Legacy 標籤的定義。 - 要兩個 Google 帳號:A 帳號負責分享位置,B 帳號負責讀取。你不能自己分享給自己。
- 要手動從瀏覽器挖出 Google Maps 的 Cookie,存成指定檔名放進 HA 的設定資料夾。Cookie 過期就要再挖一次。
結論:能不用就不用。只在家人死也不肯裝任何 App、又不是用 iPhone 的時候才考慮,而且絕對不要拿它當「家裡沒人了,啟動保全」的唯一判斷依據——輪詢有延遲,它說你不在家的時候你可能還在客廳。
行事曆與通訊軟體通知
Google 行事曆
接進來之後,你「我的日曆」裡的每個行事曆都會變成一個 calendar 實體(例如叫「Personal」的日曆變成 calendar.personal)。它還提供一個動作 google.create_event,可以讓自動化反過來幫你新增行程。
行事曆實體最強的地方是可以當自動化的觸發條件:行程開始時、結束時、或開始前 N 分鐘。這就能做出「明天要倒垃圾 → 前一晚 9 點手機震動」這種東西。
設定成本比較高:要自己建 Google Cloud 專案、啟用 Google Calendar API、設定 OAuth 同意畫面、建立「網頁應用程式」用戶端,授權重新導向網址填 https://my.home-assistant.io/redirect/oauth。第一次弄大概要 15 分鐘,跟著官方文件一步一步走。
CalDAV(Nextcloud、iCloud、Synology)
不想碰 Google Cloud 的話,CalDAV 是好選擇,而且它可以直接用 UI 設定:設定 → 裝置與服務 → 新增整合 → 搜尋 CalDAV,填伺服器網址(例如 https://caldav.icloud.com/)與帳號密碼即可。
官方文件列出實測過的伺服器:Baikal、iCloud Calendar、Nextcloud、Owncloud、Synology Calendar,其他符合 RFC4791 規範的理論上也能通。用 iCloud 的一樣要用 App 專用密碼,不要把 Apple ID 主密碼給 HA。
LINE:先講一件很重要的事
notify-api.line.me 或「發行權杖」這種字眼,直接關掉換一篇。現在要讓 HA 發 LINE,可行的做法是建立一個 LINE 官方帳號(LINE Official Account)並啟用 Messaging API,拿到 Channel Access Token 之後,用 HA 內建的 rest_command 直接打 LINE 的推播端點。
LINE 官方文件記載的推播端點是 POST https://api.line.me/v2/bot/message/push,帶 Authorization: Bearer {channel access token} 與 Content-Type: application/json,body 裡放收件者 to 與 messages 陣列。對應到 configuration.yaml 大概長這樣:
rest_command:
line_push:
url: "https://api.line.me/v2/bot/message/push"
method: post
content_type: "application/json"
headers:
Authorization: "Bearer 你的_CHANNEL_ACCESS_TOKEN"
payload: >-
{"to": "你的_USER_ID",
"messages": [{"type": "text", "text": "{{ msg }}"}]}
自動化裡這樣叫它:
actions:
- action: rest_command.line_push
data:
msg: "洗衣機洗好了,記得去晾"
比較無痛的替代:Telegram
如果通知對象是你自己或家人,而且不排斥多裝一個 App,Telegram 整合會輕鬆非常多——它現在支援 UI 設定流程,不用寫 YAML。流程是:跟 BotFather 對話建立機器人拿到 API Token,再取得你的 Chat ID,在整合設定裡把 Chat ID 加進允許清單。
它提供的動作非常豐富,除了 telegram_bot.send_message,還有送照片、影片、檔案、投票、貼圖,甚至可以編輯或刪除已經送出的訊息(做「門開著」提醒,關門後直接把訊息改成「已關閉」,不會洗版)。你在允許清單裡加幾個 Chat ID,它就幫你生幾個 notify 實體,可以直接用 notify.send_message 叫;另外還保留一組舊式的 notify 寫法給老設定相容。
最省事的方案其實還是 Companion App 推播,那個第 7 章已經教過,不用申請任何東西。
雲端 API 整合 vs 本地整合:怎麼取捨
這是買設備前就該想清楚的事,不是裝完才後悔的事。同樣一顆燈泡,走本地協定跟走原廠雲端,使用體驗差非常多。
| 比較項目 | 本地整合(Zigbee、Matter、ESPHome、區網 IP) | 雲端 API 整合(原廠 App 帳號) |
|---|---|---|
| 斷網時 | 照常運作。你家路由器還活著就好 | 全部變成不可用(unavailable),自動化整組停擺 |
| 原廠倒閉/關 API | 不受影響 | 整合直接死亡,設備變裝飾品 |
| 反應延遲 | 通常 100 毫秒內,按開關幾乎瞬間 | 要繞一圈到國外機房,常見 0.5~3 秒 |
| 隱私 | 資料不出家門 | 你家的開關紀錄、在家時間都在別人伺服器上 |
| 速率限制 | 幾乎沒有 | 有。輪詢太頻繁會被鎖 IP 或暫時封鎖 |
| 設定難度 | 可能要買 USB 協調器、刷韌體 | 通常填個帳密就好,最簡單 |
| 功能完整度 | 偶爾少幾個進階功能 | 通常跟原廠 App 一樣完整 |
整合的日常維運:診斷、驗證、重載、移除
整合裝好不是結束。它會過期、會壞、會被原廠改 API。這四招請記熟,順序也是這個順序——由輕到重,永遠從最輕的開始試。
-
第一招:重新載入(Reload)
整合卡片上的三點選單 → 重新載入。等於把這個整合關掉再開一次,不用重啟整台 HA,通常 3 秒完成。網路閃斷、對方伺服器剛剛維護完,這招八成能救。有問題先按這個。
-
第二招:重新驗證(Reauth)
如果整合卡片變成紅色警示、寫著需要重新驗證,那是帳密或 Token 失效了。按下去會跳出登入視窗,重新授權一次即可。你的 entity_id、區域、自動化全部保留,這是它跟「刪掉重加」最大的差別。
-
第三招:下載診斷(Download diagnostics)
路徑是 設定 → 裝置與服務 → 點進那個整合 → 右上角三點選單 → 下載診斷。會下載一個 JSON 檔,裡面是這個整合當下的狀態、設定(敏感資料會被官方遮罩)、抓到的原始資料。去 GitHub 開 issue 或到論壇求助時,附上這個檔案得到回覆的機率會高很多。不是每個整合都有這個選項,有支援才會出現。
搭配用的是同一個選單裡的啟用除錯記錄(Enable debug logging):打開它 → 重現一次問題 → 回來關掉,HA 會自動把記錄檔給你下載。
-
第四招:移除(Delete)
最後手段。三點選單 → 刪除。刪掉的當下,這個整合底下所有裝置與實體會一起消失,所有引用到它們的自動化、腳本、儀表板卡片全部變成紅字錯誤。
_2),你得手動改回去,否則所有自動化都是壞的。動手前順手做一份備份(第 9 章)永遠不吃虧。rest_command),不是走 UI 的整合,那就到 設定 → 工具(Tools)→ YAML 分頁去按重新載入。這個區塊在 2026.8 版之前叫「開發者工具(Developer tools)」,舊教學上的名字是那個。HACS 自訂整合:好用,但你要知道自己在做什麼
官方整合的數量非常多(官方文件的說法是「支援上千個品牌、一百多種分類」),但總有你的設備不在裡面。這時候就輪到 HACS(Home Assistant Community Store)——它不是官方商店,而是一個「幫你從 GitHub 下載社群整合並管理更新」的工具。HACS 的安裝與基本操作附錄 A有完整版,這裡只補跟「整合」有關的部分。
安裝方式取決於你的 HA 裝法
| 你的安裝方式 | HACS 官方文件的做法 |
|---|---|
| Home Assistant OS / Supervised | 把 https://github.com/hacs/addons 加為儲存庫,再到 設定 → 應用程式(Apps) 安裝並啟動 HACS |
| Container(Docker) | 進到容器裡執行 wget -O - https://get.hacs.xyz | bash - |
| Core | 切換到 HA 使用者身分,執行同一行指令 |
下載完要重啟 HA,然後回到設定 → 裝置與服務 → 新增整合,搜尋 HACS 把它設定起來。過程中會需要一個 GitHub 帳號做裝置授權。HACS 官方 FAQ 解釋過原因:它要一直用 GitHub API 去查各專案有沒有出新版,而 GitHub 對沒登入的請求每小時只給 60 次,根本不夠用;登入之後額度高很多。它拿到的權杖不需要任何特殊權限,只讀得到本來就公開的資料。
自訂整合的四個風險(要真的看懂再裝)
- 沒有審核:官方整合上架前要過程式碼審查,HACS 的沒有。它跟你的 HA 用同樣的權限跑,理論上想幹嘛都可以。
- 會拖垮升級:HA 每個月更新一次,內部 API 常改。維護者跟不上,你升級完那個整合就爆掉,嚴重時整個 HA 起不來。
- 維護者會消失:專案兩年沒動、issue 沒人回,這是常態。裝之前先看 GitHub 上「最後一次 commit」是什麼時候、issue 有沒有人理。
- 不在備份的相容範圍內:還原備份到新版 HA 時,自訂整合是最容易出事的那一塊。
裝之前的三分鐘檢查
看星星數與最後更新日
幾百顆星、最近三個月有 commit,通常還算安全。十幾顆星、三年沒動,慎重考慮。
看 issue 區
搜尋最近一次 HA 大版更新的版本號(例如
2026.8),看有沒有人回報壞掉、維護者有沒有回應。先備份再裝
裝之前做一份完整備份。壞掉時十分鐘就能還原,不然可能整晚在修。
設備買回來,卻找不到整合怎麼辦
這是新手最常見的挫折現場:東西買了、原廠 App 也連上了,可是 HA 的「新增整合」裡怎麼搜都搜不到品牌名。照這個順序查,八成能解。
-
先確認你搜的是「品牌」不是「型號」
HA 的搜尋是比對品牌/整合名稱。你手上是「小米 XX 感測器」,但整合名稱可能是
Xiaomi Miio;你買的是某牌 WiFi 插座,整合名稱可能是它背後代工平台的名字(例如 Tuya)。去官方整合列表用品牌關鍵字瀏覽一次,比在搜尋框亂猜快。 -
看設備盒子上的協定標誌
找 Matter、Thread、Zigbee、Z-Wave、Works with Home Assistant 這些標誌。有標誌代表走的是通用協定,那你要找的不是品牌整合,而是協定整合——加 Matter、加 Zigbee(ZHA 或 Zigbee2MQTT),設備會透過協定進來,跟品牌無關。這是最多人卡住的地方:一直找品牌,其實該找協定。
-
確認你有沒有對應的收發器
Zigbee 跟 Z-Wave 設備不會自己連 WiFi,主機要插一支 USB 協調器(coordinator)才收得到。沒有那支棒子,再怎麼設定都不會出現。Thread 則需要一台 Thread 邊界路由器。
-
試試自動探索有沒有被網路擋住
WiFi 設備通常靠 mDNS/SSDP/DHCP 被發現。檢查:設備與 HA 是不是同一個網段?家裡的 WiFi 有沒有開「AP 隔離/訪客網路」?路由器有沒有擋多播(multicast)?Docker 版 HA 有沒有用 host 網路模式?這幾項任何一項沒過,探索就是靜悄悄。
-
去官方整合列表確認它到底存不存在
直接看官方文件的整合列表。搜不到就代表核心沒有,別再在 UI 裡找了。順便注意有沒有「已移除」的消息——原廠關 API、相依套件沒人維護時,官方會在改版說明裡把整合下架(例如 2026.8 就移除了 Permobil 與 Volvo On Call)。你看的教學可能是它還在的年代寫的。
-
轉往 HACS 找社群版
核心沒有,社群常常有。到 HACS 裡搜品牌名。找到了就照上一節的三分鐘檢查做完再裝。
-
最後手段:走通用管道
如果設備有開放的 HTTP API,可以用 RESTful 感測器或
rest_command自己接;如果它會發 MQTT,就架 MQTT 接。這兩條路等於自己當整合,麻煩但幾乎萬能。 -
認賠的判斷點
如果設備是純雲端、沒有公開 API、社群也沒人做出來,那就是接不了。認賠退貨比在論壇熬三個晚上划算。下次買之前先查一句「品牌名 + home assistant」,三十秒的功課。
常見卡關
-
OAuth 授權完,網頁停在白畫面或「無法連線」
幾乎都是重新導向網址的問題。檢查兩件事:(1) 你貼到對方後台的網址是不是一字不差的
https://my.home-assistant.io/redirect/oauth——結尾多一個斜線就會失敗;(2) 授權完成時,瀏覽器要能連得到你的 HA。用手機 4G 授權但 HA 只有內網位址,就會停在白畫面。解法:在跟 HA 同一個 WiFi 底下、用電腦瀏覽器完成授權。 -
整合卡片變紅色,寫著需要重新驗證
Token 過期或你改了那個服務的密碼。直接按重新驗證,不要刪除重加。如果重新驗證反覆失敗,去對方帳號的「已連結應用程式」頁面看看 HA 的授權是不是被撤銷了,撤銷了就要重新授權一次。
-
設備明明在線,實體卻全是「不可用 unavailable」
先按重新載入。還是不行就下載診斷檔看它回報什麼。雲端整合常見原因是被對方 API 限速——你可能同時裝了兩個整合去打同一個帳號,或輪詢設太密。先把重複的那個關掉。
-
「已探索」裡一直不出現任何東西
照 上一節第 4 步逐項檢查網路:同網段、關閉 AP 隔離、多播沒被擋、Docker 用 host 網路。這四項是自動探索的四根柱子,缺一根就全部安靜。
-
刪掉整合重加之後,自動化全部壞了
因為 entity_id 變了,新的通常會多
_2。到實體列表把名字改回原本的(原本那個要先確定已經不存在),或是回第 4 章用批次改名。這也是為什麼能重新驗證就不要刪除。 -
升級完 HA,某個整合就消失了
兩種可能:核心整合被官方移除(去看那一版的改版說明),或是自訂整合跟不上新版。前者要找替代方案,後者去 GitHub 看有沒有新版;緊急的話還原到升級前的備份,等維護者修好再升。
常見問題
一個整合可以裝很多次嗎?例如兩個 Spotify 帳號
「重新載入」跟「重新啟動 HA」差在哪?
設定 → 工具 → YAML(這區在 2026.8 之前叫「開發者工具」)。我要接 LINE 通知,網路教學說去申請 LINE Notify 權杖,可是我找不到那個頁面
下載診斷檔會不會把我的密碼一起洩漏出去?
token、password、secret、你的 email 跟座標,確認沒有漏網之魚。這是三十秒的事,值得做。我沒有固定 IP 也沒有網域,OAuth 整合是不是就沒救了?
my.home-assistant.io 的整合,是靠你自己的瀏覽器把授權結果帶回 HA,你的 HA 網址存在瀏覽器本機、不會外送給任何服務。所以只要你在跟 HA 同一個網路底下、用瀏覽器完成整個授權流程,內網位址通常也走得通。真的失敗才需要處理對外網址,做法看附錄 A的遠端連線那一段。HACS 裝的整合,官方會幫我修嗎?
Chromecast 在手機上看得到,HA 卻找不到
我該用哪一個天氣整合?
opendata.cwa.gov.tw 申請免費授權碼,再用社群自訂整合或自己寫 RESTful 感測器來接。不要把主要自動化押在社群整合上,官方整合當骨幹、CWA 當補充資訊比較安全。