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 這一端，不然捷徑會叫到一個不存在的腳本。

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

登入繼續閱讀使用 Google 登入