原文參考：@ci.fullstack 於 Threads 發布（2026.04.05） https://www.threads.com/@ci.fullstack/post/DWwT_PjlN5f 本文依照原文方法實際操作後整理，加入完整步驟與疑難排解說明。
你的 Gmail 有多少封信？如果你也是那種「看到就不想開」的人，這篇文章是寫給你的。這不是叫你一封一封手動刪，而是讓 AI 幫你做這件事——自動搜尋、分類、批次清除，你只需要在旁邊按幾次確認。
整個流程大約 30 分鐘，其中真正「AI 在跑」的時間只有 6 分鐘。我實際操作清掉了 1,425 封郵件。
安全性說明：所有郵件只會移到「垃圾桶」，不是永久刪除。Gmail 垃圾桶保留 30 天，隨時可以救回。
為什麼 AI 可以幫你刪信？
很多人以為直接跟 Claude 或 ChatGPT 說「幫我清 Gmail」就可以，但其實不行——這些 AI 助理只有「讀信」的權限，沒有「刪信」的權限，這是平台的安全設計。
這篇教學用的是另一條路：gws CLI，一個讓你透過終端機直接呼叫 Gmail 官方 API 的工具。它不是在幫你「點網頁」，而是直接跟 Google 後端溝通，所以可以一次處理幾千封信。
搭配 Claude Code（一個跑在終端機裡的 AI），它會幫你規劃清理策略、自動寫腳本、同時管理三個清理任務。你不需要自己寫任何程式碼。
工作流程：你下指令 → Claude Code 規劃 → gws CLI 執行 → Gmail 批次移到垃圾桶
開始之前：你需要什麼
以下都免費：Mac 電腦（Windows 可以做但步驟略有不同）、Homebrew（Mac 套件管理工具）、Google 帳號（就是你要清的 Gmail）、Claude Code、Google Cloud 帳號（用你的 Google 帳號登入即可）。
完整操作步驟
Step 01｜安裝 gws CLI
打開 Terminal（Mac 的「應用程式 → 工具程式」），執行以下指令：
brew install googleworkspace-cli
安裝完看到版本號（如 googleworkspace-cli 0.22.5）就成功了。如果出現「command not found: brew」，代表你還沒裝 Homebrew，先去 brew.sh 安裝再回來。
Step 02｜建立 Google Cloud OAuth 憑證
這一步是告訴 Google：「我允許這個工具存取我的帳號」。只需要做一次，之後所有任務都可以重複使用。
- 建立 GCP 專案：去 console.cloud.google.com，用你的 Google 帳號登入，建立一個新專案，名字隨意（例如 my-tools）。
- 啟用 Gmail API：頂部搜尋欄輸入「Gmail API」，點進去，按「啟用」。
- 建立 OAuth 憑證：左側選單 → APIs & Services → 憑證 → 建立憑證 → OAuth 用戶端 ID。應用程式類型選「桌面應用程式」，名稱填 gws-cli，按建立。建立完成後，點「下載 JSON」。注意：這個視窗關掉後就看不到用戶端密碼了，一定要先下載 JSON。
- 2-4 把 JSON 檔放到正確位置，在 Terminal 執行：
mkdir -p ~/.config/gws mv ~/Desktop/client_secret_*.json ~/.config/gws/client_secret.json ls ~/.config/gws/看到 client_secret.json 就完成了。
Step 03｜把自己加入測試使用者，然後授權登入
加入測試使用者：在 GCP Console → APIs & Services → OAuth 同意畫面 → 測試使用者 → 加入你的 Gmail 地址。
沒有這步，瀏覽器授權時會出現「Access blocked」的錯誤。
gws auth login畫面會出現權限選擇清單，用上下鍵移動、空白鍵勾選。
至少要勾選：gmail.modify（最關鍵）、gmail.readonly、gmail.labels。勾好按 Enter，Terminal 會產生授權 URL，複製貼到瀏覽器完成授權。瀏覽器顯示「You may now close this window」就成功了。
Step 04｜測試 gws 可以讀取 Gmail
gws gmail users messages list --params '{"userId": "me", "q": "category:promotions", "maxResults": 5}'看到一串 JSON 格式的郵件 ID，代表環境設定完成。
Step 05｜啟動 Claude Code，開始清理
先建立工作資料夾：
你是一個 Gmail 清理 Orchestrator。
我的環境：
gws CLI 已安裝並授權
gws 指令格式：gws gmail users messages list --params '{"userId": "me", "q": "...", "maxResults": 500}'
批次移到垃圾桶：gws gmail users messages batchModify --json '{"ids": [...], "addLabelIds": ["TRASH"]}'
請依序規劃並執行以下 3 個清理任務： Agent 1 - 促銷郵件：category:promotions older_than:1y Agent 2 - 社群通知：category:social older_than:6m Agent 3 - 驗證碼：subject:驗證碼 older_than:1m 或 subject:OTP older_than:1m
執行前先列出每個 Agent 預計處理的郵件數量讓我確認，確認後再執行刪除。 每批處理上限 1000 封。 所有郵件移到垃圾桶，不是永久刪除，30 天內可救回。
Claude Code 會先統計數量讓你確認。確認沒問題後，輸入「確認」，它就開始執行。遇到「Do you want to proceed?」時，選「2. Yes, and don't ask again for: gws gmail:*」，之後就全自動跑完。
三個 Agent 各自在清什麼
- Agent 1 — 促銷郵件：條件 category:promotions older_than:1y，超過一年的促銷信，foodpanda、Uber One 這類。
- Agent 2 — 社群通知：條件 category:social older_than:6m，LinkedIn、Facebook、Twitter 的通知，六個月以上的。
- Agent 3 — 驗證碼：條件 subject:驗證碼 OR subject:OTP older_than:1m，超過一個月的驗證碼，確定不會再用到。
疑難雜症排除
Q：執行 gws auth login 出現「No OAuth client configured」
A：client_secret.json 沒放對位置。確認在 ~/.config/gws/client_secret.json，用 ls ~/.config/gws/ 確認。
Q：瀏覽器授權時出現「Access blocked」
A：忘記把自己加入 OAuth App 的測試使用者。回到 GCP Console → OAuth 同意畫面 → 測試使用者 → 加入你的 Gmail 地址。
Q：gws 指令出現「unrecognized subcommand」
A：gws 的正確格式是 gws gmail users messages list，執行 gws --help 查看完整格式。
Q：Claude Code 一直問我要不要執行
A：遇到詢問時選「Yes, and don't ask again for: gws gmail:*」，之後同類指令就不會再問。
Q：清完之後想救回某封信
A：去 Gmail 網頁版，點左側「垃圾郵件」，找到目標，點「移出垃圾桶」。30 天內都可以。
Q：我想清除其他類型的郵件
A：在 Orchestrator prompt 裡新增 Agent，用寄件者（from:[email protected]）、主旨（subject:關鍵字）或 Gmail 分類（category:updates）來組合搜尋條件。
清完之後可以做什麼
gws CLI 不只能清 Gmail。你已經授權了 Google Workspace 的存取，同樣的方式也可以操作 Google Calendar（整理過期行程）和 Google Drive（找出長期未開啟的檔案）。
GCP 憑證和 gws 授權只需要設定一次。下次想再清 Gmail，進到 gmail-cleaner 資料夾啟動 Claude Code，貼入 prompt 就好。
