Antigravity 讀不了 Gmail？從只能寄信到能讀信，Gmail API 權限升級實戰

你把 Antigravity 接上 Gmail，興沖沖打了一句「幫我看一下今天有什麼重要的信」，結果它回你一串紅字：403 ACCESS_TOKEN_SCOPE_INSUFFICIENT。奇怪，前幾天叫它寄信明明好好的，怎麼換成讀信就翻臉？我們在課堂上帶學員接 AI email 自動化時，這一關幾乎每個人都會卡，而卡點其實不在 AI，在 Google 給的權限範圍。

原因一句話講完：Antigravity 內建的 Gmail 技能預設只申請了「寄信」權限（gmail.send），沒有「讀信」權限（gmail.readonly）。所以它能替你寄，卻不能替你看。要解決，得回到 Google Cloud 把讀信權限加回來，重新換一張授權金鑰，再更新到 Antigravity 的設定檔。這篇就照著我們實際操作的四個階段走一遍，每一步都標清楚在哪個介面做，照著點就會通。還沒裝好 Antigravity 的，先看安裝入門指南再回來。

先搞懂：為什麼會跳 403？

Google 的 API 權限是「一個蘿蔔一個坑」。你申請什麼範圍（Scope），就只能做那個範圍內的事。Antigravity 的 send-gmail-email 技能出廠時，只要了最低限度的發信權限：

• 發信：https://www.googleapis.com/auth/gmail.send
• 讀信與查詢收件匣：https://www.googleapis.com/auth/gmail.readonly（這條預設沒有）

當你要求 AI「看今天的信」，它會去呼叫 Gmail 的 messages.list 或 messages.get 這類讀取 API。但你手上的存取權杖（Access Token）只帶著 gmail.send，Google 伺服器一看權限不夠，直接退回 403 PERMISSION_DENIED。這不是 bug，是權限設計本來就這樣。解法就是把 gmail.readonly 補進去、重新授權一次。

這種「AI 能不能動手做某件事，取決於你給它開了哪些權限」的觀念，其實是所有 AI agent 接外部工具的共同基礎，我們在 MCP、API 與 CLI 的差異解析裡談得更完整。

三個介面，先認清楚你會在哪裡操作

整個流程橫跨三個地方，先有個地圖，操作時就不會迷路：

第一階段：Google Cloud Console 設定專案與憑證

這一段全在 Google Cloud Console 網頁上做。

步驟 1.1　建立或選擇專案

前往 console.cloud.google.com 登入，點頂部的專案下拉選單，選現有專案，或按「新建專案」開一個新的（取個好認的名字，例如 Antigravity-Gmail-Skill）。

步驟 1.2　啟用 Gmail API

左側選單進「API 和服務」→「已啟用的 API 和服務」，點上方「+ 啟用 API 和服務」，搜尋「Gmail API」，點進去按「啟用」。這步是告訴 Google：這個專案要用 Gmail 的功能。

步驟 1.3　設定 OAuth 同意畫面

進「API 和服務」→「OAuth 同意畫面」。User Type 個人帳號選「外部（External）」，按建立。填三個必要欄位：應用程式名稱、使用者支援信箱、開發人員聯絡信箱。接著到「範圍（Scopes）」，點「新增或移除範圍」，把這兩條都加進去：

• https://www.googleapis.com/auth/gmail.send
• https://www.googleapis.com/auth/gmail.readonly

最後在「測試使用者」步驟，點「+ ADD USERS」，把你自己要用的 Gmail 帳號加進去（例如 you@gmail.com）。‼️ 這步很關鍵，沒加進測試名單的帳號授權時會被擋。

步驟 1.4　建立 OAuth 2.0 憑證

進「API 和服務」→「憑證」，點「+ 建立憑證」→「OAuth 用戶端 ID」。應用程式類型選「Web 應用程式」，取個名字。關鍵一步：在「已授權的重新導向 URI」新增這一條，一個字都不能錯：

https://developers.google.com/oauthplayground

按建立，彈出視窗會顯示 Client ID 和 Client Secret，先複製保存好，下一階段要用。

第二階段：用 OAuth Playground 換一張新的 Refresh Token

Cloud Console 只是把「權限的坑」挖好，真正拿到「帶著讀信權限的鑰匙」要靠 OAuth Playground。這段全在 Playground 網頁做。

步驟 2.1　填入你自己的憑證

前往 OAuth 2.0 Playground，點右上角齒輪圖示，勾選「Use your own OAuth credentials」，把剛剛拿到的 Client ID 和 Client Secret 貼進去。

步驟 2.2　勾選要的權限

在左側 Step 1 的輸入框，直接把兩條 Scope 貼進去（中間用空格隔開）：

https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/gmail.readonly

按藍色的「Authorize APIs」。

步驟 2.3　完成帳號授權

瀏覽器會跳到 Google 授權頁，選你的 Gmail 帳號。如果跳出「Google 尚未驗證這個應用程式」的警告，別慌，這是自建測試專案的正常現象，點「進階」→「前往…（不安全）」即可。接著勾選同意「傳送電子郵件」與「檢視您的電子郵件訊息」，按繼續，網頁會自動跳回 Playground。

步驟 2.4　兌換並複製 Refresh Token

網頁自動進到 Step 2，點「Exchange authorization code for tokens」。右側 JSON 回應裡找到 Refresh Token（格式通常是 1//0g... 開頭），整串複製起來。這張 Token 就是能讓 Antigravity 長期自動刷新的關鍵金鑰。

第三階段：更新 Antigravity 的本機設定檔

金鑰拿到了，最後一步是餵給 Antigravity。這段在你自己電腦的檔案系統做。

步驟 3.1　找到設定檔

打開檔案總管，找到這個路徑（Windows）：

C:\Users\User\.gemini\antigravity\skills\send-gmail-email\config.json

把路徑裡的 User 換成你自己的使用者名稱。

步驟 3.2　寫入新金鑰

用記事本或 VS Code 打開 config.json，把三個欄位換成你剛拿到的值：

{
  "clientId": "你的_CLIENT_ID.apps.googleusercontent.com",
  "clientSecret": "你的_CLIENT_SECRET",
  "refreshToken": "剛才在 Playground 取得的_REFRESH_TOKEN"
}

存檔。‼️ 安全提醒：這個 config.json 裝的是能讀你整個信箱的憑證，絕對不要分享給別人、也不要傳上 GitHub。真的外洩了，回 Cloud Console 把該憑證撤銷重建即可。

第四階段：測試，確認讀信真的通了

設定完直接對 Antigravity 下兩個指令驗收：

1. 測發信：「幫我寄一封測試信到 you@gmail.com」→ 應該成功寄出、回傳 Message ID。
2. 測讀信：「幫我看一下今天有什麼重要的信」→ 這次應該成功列出寄件者、主旨與摘要，不再跳 403。

兩個都過，就代表 Antigravity 從「只能幫你寄」升級成「能幫你讀、幫你整理」了。接下來就能玩更進階的：早上請它掃收件匣挑出重要的信、自動歸類、擬草稿回覆。想把這種 email 自動化接進團隊日常流程，正是我們替企業做 AI 導入時最常落地的場景之一。

資料來源與延伸閱讀

本文操作流程實測於 2026 年 7 月，Google 介面偶有調整，以官方為準：

• Google OAuth 2.0 Playground
• Google Cloud Console

站內延伸閱讀：

• Antigravity 安裝入門指南，第一次用先看這篇。
• 用 Antigravity 四步做市場分析簡報，我們課堂教的另一套實戰流程。
• MCP、API、CLI 差在哪，看懂 AI 接外部工具的權限邏輯。
• 把個人經驗沉澱成團隊技能，讓整組人都會這套設定。

想把 AI 接進公司的信箱與流程？

權限設定只是第一步，真正難的是把 AI 讀信、分類、回覆這條線接進實際的營運流程還不出錯。這正是我們在做的事，預約 30 分鐘免費診斷聊聊你們想自動化哪一段，或先看看作品案例裡的 AI 導入專案。