Cloudflare 在 2026 年 11 月 3 日調整 AI Gateway 的建立規則:新 Gateway 預設且必須啟用 authentication,API 建立時省略 authentication 會視為 true,明確送出 false 則回傳 HTTP 400。既有尚未啟用驗證的 Gateway 可以繼續運作,也能主動開啟;但一旦啟用,Dashboard 與 API 都不能再關閉。

這不是既有 AI Gateway 全面中斷,也不是上游 OpenAI、Anthropic 或其他模型供應商的金鑰規則改變。Cloudflare Gateway authentication 驗證呼叫者能不能進入你的 Gateway;provider credential 則決定 Cloudflare 能不能代表你呼叫上游。兩層憑證用途不同,若把 provider key 當成 Cloudflare token 放錯 header,請求仍會失敗。

為什麼新舊 Gateway 會出現不同結果

同一套部署腳本若在舊環境連到未驗證 Gateway,沒有 Cloudflare token 也可能成功;在 11 月 3 日後新建的 staging、災難復原或客戶環境,則會因缺少驗證而失敗。最危險的作法是遇到 401 就重建 Gateway 或放寬其他安全設定,因為根因通常只是程式仍依賴舊 Gateway 的歷史例外。

先建立 Gateway inventory,記錄 account、gateway ID、建立日期、authentication 狀態、呼叫端、endpoint 類型、provider credential 來源、是否使用 Unified Billing,以及 owner。特別檢查 server、browser、Worker、排程、queue consumer、AI agent、preview deployment 與本機測試工具;任何會直接呼叫 Gateway 的地方都要知道如何取得 Cloudflare token。

對既有未驗證 Gateway,官方沒有公告強制轉換日期,因此不必在沒有測試的情況下立即翻開關。不過未驗證入口可能被未授權請求使用,增加模型費用或 log storage 使用量;應把它列為要遷移的安全債,而不是永久相容模式。

先確認 endpoint,再放對 header

使用 Cloudflare REST API api.cloudflare.com 的新整合,應在標準 Authorization header 傳送 Cloudflare API token。使用 gateway.ai.cloudflare.com 的 provider-native endpoint 時,Cloudflare token 放在 cf-aig-authorization;上游 provider credential 仍依對應協定放在另一個 header,或使用 Gateway 中已安全保存的 BYOK key。

若從 Cloudflare Worker 透過 AI binding 呼叫,官方文件說 binding 已在同一 account 內預先驗證,不需要手動加入 cf-aig-authorization。這也是遷移時要按 caller type 分類的原因:不能把一段 header middleware 不加區分地塞進所有 runtime,更不能把 Cloudflare token 打包到公開前端 JavaScript。

API token 至少要有執行 Gateway 所需的 AI Gateway Run 權限。Cloudflare 特別提醒,目前 AI Gateway 的 Read、Run 與 Edit 權限是 account-scoped,不能像 R2 bucket 一樣限制到單一 Gateway。也就是說,同一 account 內只要 token 有 Run,就可能經過其他 Gateway 使用其中保存的 provider keys。多租戶或高隔離需求不應只靠 gateway ID,應考慮拆分 Cloudflare account,或改用 Worker-side binding 建立更明確的邊界。

不可逆開關要用分批方式上線

第一階段先替所有呼叫端部署「能帶 token」的版本,但暫時不切既有 Gateway。Token 放在 deployment secret 或受管密碼系統,不寫入 repository、映像、前端 bundle、錯誤訊息與 request log。把正式、staging、CI 與開發環境分開發 token,設定 owner、輪替時間與撤銷 runbook。

第二階段建立一個已驗證的測試 Gateway,逐一跑過同步請求、串流、重試、fallback、背景 job 與 provider error。至少驗證:正確 token 成功、缺少 token 失敗、無效 token 失敗、上游 key 錯誤能與 Cloudflare 401 區分、秘密輪替後新舊版本不會同時停擺。

第三階段才替既有 Gateway 啟用 authentication。由於開啟後不能關閉,回滾方案不是把開關切回 off,而是回滾呼叫端版本時仍保留 token 支援,或在切換前準備另一條已驗證且測試完成的路徑。不要以建立新的未驗證 Gateway 當回滾,因為新 Gateway 已不允許關閉驗證。

上線可按非正式環境、低風險服務、內部工具、再到正式客戶流量分批。每批觀察 401、403、400、請求量、provider errors、延遲與費用;對串流與長任務也要確認 token 更新不會只讓新連線成功、舊 worker 持續使用已撤銷值。

401 不一定是同一層的錯

Cloudflare troubleshooting 文件把驗證問題分成多層。缺少 Gateway authorization、Cloudflare API token 權限不足、provider-native endpoint 的 header 放錯,以及上游 provider 拒絕自己的 credential,都可能呈現驗證相關錯誤。排查時記錄 endpoint 類型、gateway ID、Cloudflare response code 與 request ID,但遮蔽 authorization 與 provider key。

建立監控時,把 Gateway authentication failure 與 provider credential failure 分開計數。前者通常要檢查 Authorization 或 cf-aig-authorization、Cloudflare token 與 account;後者要檢查 OpenAI、Anthropic 等上游 header、BYOK alias、scope 或撤銷狀態。盲目重試無效憑證只會增加雜訊,應在有限次失敗後停止並通知 owner。

如何選擇遷移節奏

新專案沒有相容性選擇,從第一天就把驗證與 secret distribution 納入架構。既有單一後端服務可以先部署 token,再開啟 authentication;呼叫端分散、包含第三方客戶或舊版桌面程式的 Gateway,則應先建立版本支援矩陣與淘汰時程,避免不可逆切換後才發現無法遠端更新的 client。

多租戶 SaaS 若需要每個客戶嚴格隔離,不要把 account-scoped Run token 當成單一 Gateway 的最小權限憑證。可以用不同 account 隔離高風險租戶,或讓 client 只呼叫自己的後端,由受控 Worker binding 代表它進入 Gateway。這會增加架構與維運成本,但邊界比把廣權限 token 分送到多個 client 清楚。

完成標準應包含:所有 Gateway 有 inventory、所有 caller 知道正確 endpoint 與 header、token 沒進入公開產物、缺少與錯誤 token 都能安全失敗、監控能區分 Cloudflare 與上游驗證錯誤,並且不可逆切換有可執行的回復路徑。這次預設值改變真正提醒的是:不能再用舊環境的成功,證明新環境的安全設定與部署腳本完整。