🔑 AI 直接讀你個信箱

用 Claude Code
直接讀你個 Gmail

接駁一次，之後你講一句「睇下今日有冇新 email」，AI 就自己開你個信箱搵，搵完仲可以幫你草擬回覆。

⏱ 約 15 分鐘💰 免費⌨️ 唔使寫程式🔒 唔經第三方

Claude Code 本身冇內置 Gmail。呢個方法用 Google 官方 API，行你自己個 Google account 授權 —— 即係話你嘅 email 由頭到尾只係喺你部電腦同 Google 之間行，冇經過任何第三方服務。

⚠️ 由頭到尾用同一個 Google account。
好多人部電腦登入緊幾個 Google（工作一個、私人一個）。Google Console 每一版都會用「當前 active 嗰個」，撳錯咗你唔會即刻發現，要行到最後一步先爆錯，然後成個流程要重做。每開一版新頁，望一望右上角個頭像。
1

去 Google 攞鎖匙

叫 Google 發一條「鎖匙」俾你部電腦，等佢有權讀你個 Gmail。八步，呢個階段最長。

1
開一個 Google Cloud project

去 console.cloud.google.com/projectcreate

你會見到：一版叫「New Project」，有個 Project name 輸入框。

Project name 打 gmail-connect，撳 CREATE。

跟住會點：等十幾秒，右上角彈通知話建好咗，Console 頂部顯示你個 project 名。
2
啟用 Gmail API

去 console.cloud.google.com/apis/library/gmail.googleapis.com

你會見到：一版有 Gmail 圖示，寫住「Gmail API」，下面有個藍色掣。

撳 ENABLE。見到嘅係 MANAGE 就代表已經開咗，直接落下一步。

3
開始設定授權畫面

去 console.cloud.google.com/apis/credentials/consent

你會見到：一版寫住「Google Auth Platform not configured yet」，中間有個掣。

撳 Get started。

📌 Google 舊版叫呢度做「OAuth consent screen」，新版改咗名叫「Google Auth Platform」。見到邊個名都係同一樣嘢。

4
填 App 資料
你會見到：一個四格 wizard：App Information → Audience → Contact Information → Finish。
格填咩
App InformationApp name 打 Gmail Connect；User support email 撳 ▼ 揀你個 Gmail
Audience揀 External
Contact Information打返你個 Gmail
Finish剔 I agree to the Google API Services: User Data Policy

最後撳 Create。

⚠️ User support email 個 ▼ 入面搵唔到你想接嗰個 Gmail？停低。即係你而家登入緊第二個 account。切換咗先再做，唔好求其揀一個。
5
加自己做 Test user　← 最多人跳嘅一步

建完之後你會返到 Google Auth Platform。睇左邊嗰行選單。

撳 Audience → 拉到下面搵 Test users → 撳 ADD USERS → 打你個 Gmail → SAVE

點解一定要做：你個 app 而家係「測試中」狀態，Google 只准名單入面嘅人用。你唔加自己落去，最後授權嗰步會直接彈 403 access_denied，而個錯誤訊息唔會話你知係因為呢個。
做完點知啱：Test users 下面應該列住你個 email 地址。
6
建立 OAuth client

左邊選單撳 Clients → 撳 CREATE CLIENT

欄位揀／填
Application typeDesktop app
Nameclaude-code

撳 CREATE。

📌 點解要揀 Desktop app：呢個類型 Google 會自動接受 http://localhost 任何 port，你唔使自己去加 redirect URI。揀錯第二個 type 就要手動加，好易出錯。

7
未撳 OK 之前，先撳 Download JSON
你會見到：一個叫「OAuth client created」嘅彈窗，入面有 Client ID 同 Client secret，仲有一行黃色警告話閂咗就再睇唔到 secret。

撳彈窗下面嘅 Download JSON，個檔會落你 Downloads folder。

⚠️ 先 download，後撳 OK。撳咗 OK 先發現冇抄低 secret 嘅話，唯一辦法係刪咗個 client 重新建過。
8
確認個檔落咗

打開 Downloads folder，應該見到一個好長名嘅檔，類似 client_secret_1234567890-xxxx.apps.googleusercontent.com.json

見到就得，唔使開佢。

攞到鎖匙喇，落一步駁埋佢…
2

接駁

三步。全部喺 Claude Code 入面貼，唔使開 Terminal。

9
裝個工具

開 Claude Code，貼呢句：

貼落 Claude Code
幫我安裝呢個包：https://edwardai-gmail-setup.pages.dev/install.txt
做完點知啱：見到「✅ 裝好 Gmail 工具」。
10
叫 AI 讀你個 JSON 檔
貼落 Claude Code
我啱啱喺 Google Cloud Console download 咗個 OAuth client JSON，喺我 Downloads folder。
幫我讀個檔，將 client_id 同 client_secret 寫入 ~/gmail-tool/.env，
再加返 GMAIL_ADDRESS 係我個 Gmail 地址。

AI 會問你個 Gmail 地址，答佢就得。

💡 用呢個方法唔使你自己抄 Client ID —— 嗰串嘢又長又有好多 1 同 l，人手抄十次有九次錯。

11
授權
貼落 Claude Code
python3 ~/gmail-tool/gmail.py auth
跟住會點：你部電腦會自動開 browser，去 Google 授權畫面。
你會見到：一版寫住「Google 未驗證這個應用程式」（英文：Google hasn't verified this app）。

呢個係正常嘅。因為呢個 app 係你自己頭先建嘅，未經 Google 官方審核 —— 但佢只係你自己一個人用。

撳 進階 → 前往 Gmail Connect（不安全） → 繼續

做完點知啱：Browser 彈一版「✅ 授權完成」，Claude Code 嗰邊顯示 ✅ refresh token 已寫入 .env 同 ✅ IMAP 連線成功。

🎉 呢步一世做一次，之後唔使再撳。

通咗！試下佢…
3

開始用

搜尋語法同你平時喺 Gmail 搜尋框打嘅一模一樣。

12
試一次
列出最近三日嘅 email
python3 ~/gmail-tool/gmail.py search 'newer_than:3d'

見到有嘢出，即係成功 ✅

13
之後點用
常用指令
python3 ~/gmail-tool/gmail.py search 'from:someone@example.com'
python3 ~/gmail-tool/gmail.py search 'is:unread newer_than:7d'
python3 ~/gmail-tool/gmail.py read 1234

或者直接用人話同 Claude Code 講：

用人話叫佢做
用 ~/gmail-tool/gmail.py 睇下今日有冇新 email，有嘅話講重點俾我聽
14
想 AI 幫你覆 email？
先試寄，唔會真寄
python3 ~/gmail-tool/gmail.py reply 1234 draft.txt --dry-run

--dry-run 會顯示佢將會寄啲乜，但唔會真寄。確認冇問題先除咗佢。

寄完個工具會自動由「寄件備份」讀返實物，顯示完整正文同 SHA-256，等你逐字核對真係寄咗啲乜 —— 唔係話「寄咗」就當寄咗。

📄 想要離線版？

Markdown貼俾 AI 帶你行 PDF打印／存檔

Markdown 嗰份最有用 —— 直接貼俾 Claude Code，佢會一步一步帶你行完成個流程，唔使你自己睇文檔。

🚑 撞板急救

App Password 個頁面話 "not available"

唔使理。呢份教學由頭到尾冇用 App Password，行嘅係 OAuth。有啲 Google account 唔提供 App Password（同你有冇開兩步驗證無關），但 OAuth 一定行得通。

授權嗰陣彈 403 access_denied

99% 係第 5 步冇做。返去 Google Auth Platform → Audience → Test users，加自己個 email 落去，再跑多次 auth。

出 invalid_grant

條鎖匙俾人撤銷咗（或者你喺 myaccount.google.com/permissions 度移除咗個 app）。重新跑一次：

重新授權
python3 ~/gmail-tool/gmail.py auth
話「冇收到 refresh token」

Google 對同一個 app 只會發一次 refresh token。去 myaccount.google.com/permissions 搵到你個 app，移除佢，再跑多次 auth。

Console 個介面同呢份教學講嘅唔同

Google 大約每半年改一次版面。跟掣上面嗰個字搵（Get started、CREATE CLIENT、ADD USERS）—— 位置會搬，字通常唔變。

🔒 安全須知

邊個睇到你啲 email？只有你部電腦。條線係你部機直接打 Google，冇經第三方 server
啲鎖匙放咗喺邊？~/gmail-tool/.env，你部機本地。唔好將呢個檔 upload、唔好貼落 chat、唔好放入 Git
點收返個權限？myaccount.google.com/permissions → 搵到 Gmail Connect → 移除。即刻失效
權限有幾大？讀同寄。要收窄嘅話可以改用 Gmail REST API 嘅窄權限，但要改個工具嘅寫法

🔧 進階：點解要咁行

撳開睇技術原理

呢個工具用 IMAP（讀）同 SMTP（寄）連 Google，用 OAuth 2.0 嘅 XOAUTH2 方式認證。全部係 Python 內置功能，冇裝任何第三方套件。

三條寫死咗嘅格式規則（因為呢啲位好易出錯）：

1. 回覆唔會 append 原文引言

好多程式寄 reply 會將原文抄一次落 body 底部，Gmail 顯示出嚟就係一堆 > 引言，好核突。其實 email 串連係靠 In-Reply-To / References 兩個 header，同 body 完全無關 —— 唔抄原文一樣接得返原本條對話。

2. 用 multipart/alternative（純文字 + HTML 兩份）

淨係寄純文字嘅話，Gmail 會自己幫你摺行，中文摺出嚟好醜。寄 HTML 版就可以自己用 <p> 控制段落。

3. 寄完一定讀返實物核對

SMTP 冇報錯 ≠ 寄咗啱嘢。所以寄完會即刻去「寄件備份」讀返，print 完整正文同 SHA-256 俾你逐字睇。

行到未？有問題直接 IG DM 我 💬

更多 AI 慳時間玩法 → @edwardai.tech