Cloudflare Wrangler OAuth 權限怎麼選？optional scopes 與重新授權排錯

Wrangler 的 optional scopes 解決什麼問題#

Cloudflare 官方把 scope 分成 required 與 optional。required scope 會固定保留；optional scope 可以在同意畫面取消，且預設仍會先選取。對 Wrangler 與 API MCP server 而言，這代表你可以先用唯讀或較窄的權限完成查詢，等真的需要部署、修改設定或操作資源時再補權限。

這不是把 Cloudflare API 變成匿名讀取，也不是讓 OAuth token 取代 API token。它只改變授權時如何選擇已由 client 宣告的 scope，實際能做什麼仍由 scope、帳號與資源範圍共同決定。

先列出 scope，再決定要給哪些#

目前 Wrangler 的 general commands 文件提供兩個與 scope 有關的選項：--scopes-list 列出可用 scope 與說明，--scopes 則接受以空白分隔的 scope 清單。不要只從指令名稱猜權限，先在實際使用的 Wrangler 版本查看清單：

1
npx wrangler login --scopes-list

如果目前只需要讀取帳號與使用者資訊，可以用官方文件示範的窄範圍形式重新登入；實際 scope 名稱仍以你執行 --scopes-list 得到的清單為準：

1
npx wrangler login --scopes account:read user:read

沒有提供 --scopes 時，Wrangler 會使用可用 scope。這對快速開始很方便，但不適合拿來當長期的最小權限策略。若你要使用具名 auth profile，wrangler auth create <name> --scopes ... 也有相同的 scope 選擇入口；profile 負責選帳號，scope 負責限制授權範圍，兩者不要混為同一層設定。可以參考 Wrangler auth profiles 的帳號防呆方式。

用工作流反推權限，而不是先勾滿所有寫入權限#

可以先把本機操作分成三類，避免「為了讓一個指令通過，就把所有權限全部打開」：

這份表不是一個可直接套用的固定 scope 清單，因為 Worker、KV、R2、D1 與其他產品需要的權限不同。真正可靠的做法是先查 scope 清單，再用目標指令或 MCP tool 的錯誤訊息驗證缺少哪一項。

缺少 scope 時，先重新授權再改設定檔#

Cloudflare 的更新說明指出，如果指令或工具呼叫需要你先前取消的 scope，就重新授權 client 並把該 scope 選回來。這類錯誤通常不是 wrangler.toml 或 wrangler.jsonc 的 binding 寫錯，而是目前 OAuth 授權沒有包含操作所需的權限。

可以用下面的流程保留變更前後的證據：

1. 保存指令、完整 endpoint 或 MCP tool 名稱，以及錯誤中的資源範圍；不要保存 access token。
2. 執行 npx wrangler login --scopes-list，確認待補的 scope 名稱與說明。
3. 重新執行 npx wrangler login --scopes ...，只加入這次工作流需要的 scope。
4. 用同一個只讀或部署指令重試，確認成功後再把結果記在專案的部署紀錄。
5. 若這是一次性排錯，完成後檢查授權清單，必要時撤銷不再需要的 OAuth authorization。

如果登入流程卡在遠端 SSH、容器或 Codespaces 的 localhost callback，這是另一個問題。Wrangler 文件提供 --device 的 Device Authorization Grant；先用它完成登入，再處理 scope，不要把 callback 連線問題誤判成權限拒絕。

1
npx wrangler login --device

MCP server 與 CI API token 要分開看#

Cloudflare API MCP server 也採用 optional scopes。MCP 工具的好處是可以依工作需要選擇權限，但它仍然代表一個能呼叫 Cloudflare API 的 client。先用只讀權限測試工具列出資源，再逐項開啟寫入能力；不要因為 agent 需要查詢一個 Worker，就把整個帳號的管理 scope 一次授予。

CI 則不應等待瀏覽器 OAuth。Cloudflare 官方將 API token 作為 headless 或 continuous integration 的認證路徑；把 CLOUDFLARE_API_TOKEN 放在 CI 的 secret store，並依 pipeline 工作切成部署、讀取或單一產品用途。OAuth scope 的選擇不會自動縮小既有 API token 的權限，兩套憑證要各自盤點。

1
# CI 中只從 secret store 讀取，不要在 repository 寫入 token
2
pnpm wrangler deploy

完成條件不是「OAuth 對話框少勾幾個選項」，而是本機、MCP 與 CI 都能回答：目前 client 是誰、允許哪些資源、哪一個工作流需要寫入，以及如何撤銷這份授權。

結論：先縮小授權，再用錯誤補回#

Wrangler 與 Cloudflare API MCP server 的 optional scopes 讓授權流程更接近實際工作需求。先列 scope、按工作流給最小範圍、用同一個請求驗證；遇到缺少權限時重新授權，不要直接重建所有設定或把 API token 改成全域管理權限。多帳號本機用 profile 分流，CI 則維持獨立的 API token，這樣才知道每一份憑證到底負責哪件事。

常見問題#