iOS 捷徑接 Home Assistant：四個從零做到會動的範例（含 HA 那一端的完整設定）

charles

這篇的內容（8 段）

1. 步驟 1：選一種呼叫方式
2. 方式 B：Webhook（不用權杖）
3. 方式 C：REST API + 長期存取權杖
4. 範例一：一鍵睡前模式
5. 範例三：離家檢查清單
6. iOS 端：建個人自動化
7. 安全：四件一定要做的事
8. 疑難排解對照

「家庭」App 只能開開關關。iOS 的捷徑（Shortcuts）配上 Home Assistant，
可以做到「問它家裡現在怎麼樣」、「出門前一次檢查完」、
「鬧鐘一按掉就開燈煮咖啡」這類事情。

這篇的每個範例都包含兩端：捷徑那一邊怎麼點，
以及 Home Assistant 這一邊要先有什麼設定。
照著做完，四個捷徑都會真的動。



步驟 1：選一種呼叫方式

三種，先給結論：從第一種開始，遇到做不到的再用第三種。

方式 A：Companion App 的內建捷徑動作（App Intents）

裝了 Home Assistant Companion App 之後，捷徑的動作清單裡搜尋
Home Assistant 就會出現一整組。

• Perform action（執行動作）—— 相當於在開發者工具裡呼叫任何一個動作。需要 iOS 17 以上
  
• Render template（算範本）—— 把一段範本丟給 Home Assistant 算，拿回文字。iOS 16.4 以上
  
• Activate scene、Run Script、Trigger automation —— 場景／腳本／自動化。iOS 16.4 以上
  
• Update location、Update sensors、Reload widgets —— iOS 16.4 以上
  
• Get camera snapshot、Open Entity —— iOS 17 以上
  
• Control light / switch / fan / cover、Press button、Assist in app、Open Page、Open Camera List —— iOS 18 以上
  

⚠ 舊教學講的「Call Service」和「Fire Event」已經棄用，
現在在捷徑清單裡會顯示成 (Deprecated) Call Service。
它們還能用，但不要拿來寫新的東西。Call Service 的替代品是 Perform action；
Fire Event 沒有直接替代品，改用 Perform action 或在 Home Assistant 那邊寫自動化。

優點是完全不用管網址和權杖。缺點是只能做清單上那幾件事。

方式 B：Webhook（不用權杖）

捷徑用「取得 URL 內容」POST 到一個網址，Home Assistant 那邊用 webhook 觸發器接。

適合「單向通知 Home Assistant 發生了某件事」。不能拿資料回來。
而且 webhook_id 本身就是密碼，誰拿到誰就能觸發。

方式 C：REST API + 長期存取權杖

能查能寫，什麼都做得到。代價是要保管一串權杖。

步驟 2：確認你的 Home Assistant 網址（這一關很多人卡住）

在電腦瀏覽器打開 Home Assistant，看網址列。

⚠ Home Assistant 2026.8 起，Home Assistant OS 的預設埠改成 80（Container 安裝仍然是 8123）。

所以：

• HA OS 新裝的：http://192.168.1.50（後面沒有 :8123）
  
• Container 安裝的：http://192.168.1.50:8123
  
• 從舊版升上來的 HA OS：兩種都可能，以你瀏覽器網址列看到的為準
  

照舊教學硬打 :8123 的症狀是連線逾時，而在捷徑裡它長得跟「權杖錯誤」
一模一樣（都是一個沒有內容的失敗），所以會往錯的方向查很久。

步驟 3：產生長期存取權杖（走方式 C 才需要）

• 在電腦瀏覽器登入 Home Assistant
  
• 點左下角你自己的名字，進入個人資料
  
• 切到「安全性」分頁
  
• 捲到最下面的「長期存取權杖」，按建立權杖
  
• 取一個看得出用途的名字，例如 iphone-shortcuts
  

你會看到什麼：跳出一串很長的英數字（大約 180 個字元，中間有兩個點）。
這串只會出現這一次，關掉就再也看不到，先貼到備忘錄。

立刻測一下它有沒有效。在 Mac 或任何有 curl 的地方跑：

1. curl -s -H "Authorization: Bearer 你的權杖" \
2.      -H "Content-Type: application/json" \
3.      http://192.168.1.50/api/

複製代碼

你會看到什麼：

1. {"message":"API running."}

複製代碼

回傳 401 Unauthorized → 權杖貼錯了（最常見是複製時少了結尾，或多了換行）。
完全沒有回應 / 逾時 → 網址或埠不對，回步驟 2。
回 404 → 網址結尾的斜線掉了。必須是 /api/ 不是 /api。

範例一：一鍵睡前模式

先做 Home Assistant 這一端，不然捷徑會叫到一個不存在的腳本。

Home Assistant 端：在 scripts.yaml 加一個腳本。
（找不到這個檔案的話，在 configuration.yaml 確認有 script: !include scripts.yaml 這一行。）

1. # scripts.yaml
2. bedtime:
3.   alias: 睡前模式
4.   icon: mdi:weather-night
5.   mode: single
6.   sequence:
7.     - action: light.turn_off
8.       target:
9.         entity_id:
10.           - light.living_room_ceiling
11.           - light.dining_room
12.           - light.kitchen
13.     - action: light.turn_on
14.       target:
15.         entity_id: light.hallway
16.       data:
17.         brightness_pct: 10
18.         color_temp_kelvin: 2000
19.     - action: climate.set_temperature
20.       target:
21.         entity_id: climate.bedroom_ac
22.       data:
23.         temperature: 27
24.         hvac_mode: cool
25.     - action: lock.lock
26.       target:
27.         entity_id: lock.front_door
28.     - action: input_select.select_option
29.       target:
30.         entity_id: input_select.house_mode
31.       data:
32.         option: sleep

複製代碼

上面用到的 input_select 也要定義，不然那一步會出錯：

1. # configuration.yaml
2. input_select:
3.   house_mode:
4.     name: House Mode
5.     icon: mdi:home-heart
6.     options:
7.       - home
8.       - away
9.       - sleep
10.       - vacation
11.     initial: home

複製代碼

存檔 → 開發者工具 → YAML → 重新載入「腳本」與「輸入選擇」。

你會看到什麼：到「設定 → 工具 → 狀態」，輸入 script. 應該會看到
script.bedtime（英文，不是中文）。
沒看到，代表 scripts.yaml 沒有被載入或縮排錯了，看「設定 → 系統 → 日誌」。

先在網頁上手動跑一次確認它會動：點 script.bedtime 旁邊的執行。
燈沒全關就是 entity_id 打錯，這時候先修好，不要帶著問題往下做捷徑。

捷徑端（方式 A，最簡單）：

• 打開「捷徑」App，右上角加號
  
• 搜尋動作 Run Script（Home Assistant）
  
• Server 選你的 Home Assistant，Script 選睡前模式
  
• 再加一個動作「顯示通知」，內容打「晚安，已關燈鎖門」
  
• 捷徑命名為「晚安」
  

你會看到什麼：在捷徑編輯畫面按右上角的播放鍵，
燈應該會真的關掉，而且畫面上跳出那則通知。

跳出「Unknown Action」：這是 Companion App 某些版本的已知問題
（2026.9.0 有人回報過），先到 App Store 把 Home Assistant 更新到最新版，
再把那個動作刪掉重新加一次。

捷徑端（方式 C，需要更多彈性時）：

• 動作 1：文字 → 內容填 http://192.168.1.50/api/services/script/turn_on
  
• 動作 2：字典 → 加一個鍵 entity_id，值填 script.bedtime
  
• 動作 3：取得 URL 內容
  

第三個動作要展開設定：

1. URL：（選上面那個「文字」的結果）
2. 方法：POST
3. 標頭：
4.   Authorization  = Bearer 你的權杖
5.   Content-Type   = application/json
6. 要求內容：JSON  →（選上面那個「字典」的結果）

複製代碼

你會看到什麼：執行後 Home Assistant 會回傳一個陣列，
裡面是這次執行過程中狀態有變動的所有實體，長得像這樣：

1. [{"entity_id":"light.living_room_ceiling","state":"off", ...},
2. {"entity_id":"lock.front_door","state":"locked", ...}]

複製代碼

回傳空陣列 [] 代表呼叫成功但沒有任何東西改變 ——
通常是燈本來就已經是關的，不是失敗。

把它放到主畫面：捷徑詳細資料（上方的資訊鍵）→ 加入主畫面。

範例二：問「家裡現在怎麼樣」，它會講出來

這個用 Siri 叫最順，而且不需要權杖。

捷徑端：

• 動作 1：Render template（Home Assistant）
  
• 動作 2：說出文字，內容選上一步的結果
  
• 捷徑命名為「家裡狀況」
  

Render template 的範本內容貼這一段：

以下還有約 61% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入