做咗 0 / 13 步
🔑 AI 直接讀你個信箱

用 Claude Code
直接讀你個 Gmail

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

⏱ 約 15 分鐘🪜 13 步💰 免費⌨️ 唔使寫程式🔒 唔經第三方
1去 Google 攞鎖匙9 步 · 約 11 分鐘第 1–9 步
2接駁3 步 · 約 4 分鐘第 10–12 步
3開始用1 步 · 約 1 分鐘第 13 步

最快嘅方法：叫 AI 帶你行

唔想自己睇文檔？copy 下面呢句，貼落你個 Claude Code（或者 Codex）：

貼落 Claude Code
讀 https://edwardai-gmail-setup.pages.dev/SOP.md，一步一步帶我接通我個 Gmail。
一次淨係講一步，等我答「做完」先講下一步。

佢會自己讀晒呢份教學，然後好似私人教練咁一步一步帶你行、幫你檢查每步做啱咗未。
想自己跟？下面 13 步每步都寫齊「去邊／撳咩／見到咩就代表成功」，照跟就得。

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
console.cloud.google.com/auth/audience

Audience

Publishing status：Testing（測試中）

Test users —— 只有下面名單入面嘅人用到你個 app

ADD USERS← 撳呢個

撳完會彈個輸入框，打你個 Gmail，再撳 SAVE

✓ 你個 email 地址應該出現喺 Test users 下面

※ 線框示意圖，唔係實際截圖。Google 會改版面，跟掣上面嗰個字搵就唔會錯。

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

搵唔到 Test users？先確認你喺 Audience 嗰版（唔係 Overview），要向下捲一段先見到。成版都冇呢一 section 嘅話，你可能揀咗 Internal —— 見下面撞板急救。

6
轉做 In production　← 唔做 7 日後要重新授權

仲喺 Audience 嗰一版，望上面。

你會見到：一格 Publishing status，而家寫住 Testing，旁邊有粒 PUBLISH APP 掣。
做：撳 PUBLISH APP → 彈個確認框，撳 CONFIRM。
console.cloud.google.com/auth/audience（同一版，望上面）

Publishing status

而家：Testing —— 發出嚟嘅鎖匙得 7 日命

PUBLISH APP← 撳呢個

彈確認框，撳 CONFIRM

✓ Publishing status 變成 In production

※ 線框示意圖，唔係實際截圖。Google 會改版面，跟掣上面嗰個字搵就唔會錯。

點解一定要做：個 app 留喺 Testing 狀態嘅話，Google 發出嚟嘅鎖匙得 7 日命。你今日駁通，下個禮拜就會突然唔 work（爆 invalid_grant），而你完全唔會估到係呢個原因。
做完點知啱？Publishing status 由 Testing 變成 In production。

📌 唔使做 Google 驗證，唔使畀錢。未驗證嘅 app 一樣用得，只係第 12 步會彈「未驗證」畫面（正常），上限 100 個用戶。如果撳完要求你填一大堆驗證資料 —— 唔好填，撳返 cancel，留喺 Testing 都行，只係記住每 7 日要重跑一次第 12 步。

7
建立 OAuth client

左邊選單撳 Clients → 撳 CREATE CLIENT

欄位揀／填
Application typeDesktop app
Nameclaude-code
⚠️ 撳 CREATE 之前先睇定第 8 步。撳落去會即刻彈一個窗，入面有粒 Download JSON —— 未 download 咗唔好撳 OK，撳咗就再攞唔返，要刪咗個 client 重新建過。

睇完第 8 步，先返嚟撳 CREATE。

做完點知啱？撳咗 CREATE 之後會即刻彈一個「OAuth client created」窗 —— 唔好撳 OK，直接做第 8 步。

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

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

OAuth client created

Client ID　　　（一長串字）

Client secret　●●●●●●●●●●●●

※ 閂咗呢個窗就再睇唔到 Client secret
DOWNLOAD JSON← 撳呢個

撳完個檔會落 Downloads folder，之後先撳 OK

※ 線框示意圖，唔係實際截圖。Google 會改版面，跟掣上面嗰個字搵就唔會錯。

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

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

做完點知啱？見到個檔就得，唔使開佢。階段 1 完成。
攞到鎖匙喇，落一步駁埋佢…
2

接駁

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

10
裝個工具

開 Claude Code，貼呢句：

貼落 Claude Code
幫我安裝呢個包：https://edwardai-gmail-setup.pages.dev/install.txt
做完點知啱？見到「✅ 裝好 Gmail 工具」。
11
叫 AI 讀你個 JSON 檔
貼落 Claude Code
我啱啱喺 Google Cloud Console download 咗個 OAuth client JSON，喺我 Downloads folder。
如果有幾個，用最新嗰個，同埋話返我知你用咗邊個檔名。
幫我讀個檔，將入面嘅 client_id 同 client_secret 寫入 ~/gmail-tool/.env，
key 名要一模一樣：GMAIL_CLIENT_ID、GMAIL_CLIENT_SECRET，
再加 GMAIL_ADDRESS 係我個 Gmail 地址。

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

做完點知啱？AI 會報返佢用咗邊個 JSON 檔名。核對下係咪你啱啱 download 嗰個。

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

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

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

做：撳 進階 → 前往 Gmail Connect（不安全） → 繼續
accounts.google.com

Google 未驗證這個應用程式

這個應用程式要求存取您 Google 帳戶中的機密資訊

進階（Advanced）← 撳呢個

↑ 撳咗「進階」，先會出現下面呢一行

前往 Gmail Connect（不安全）← 撳呢個

✓ 再撳「繼續」，就會彈「授權完成」

※ 線框示意圖，唔係實際截圖。Google 會改版面，跟掣上面嗰個字搵就唔會錯。

做完點知啱？Browser 彈一版「✅ 授權完成」，Claude Code 嗰邊顯示 ✅ refresh token 已寫入 .env 同 ✅ IMAP 連線成功。
⚠️ 呢步彈 403 access_denied？即係第 5 步冇做成功。返去 Google Auth Platform → Audience → Test users 加返自己個 email，再跑多次呢步就得。

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

通咗！試下佢…
3

開始用

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

13
試一次
列出最近三日嘅 email
python3 ~/gmail-tool/gmail.py search 'newer_than:3d'
做完點知啱？會列出你最近三日嘅 email。見到有嘢出，即係全部搞掂。
之後點用
常用指令
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，有嘅話講重點俾我聽
想 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