# 用 Claude Code 直接讀你個 Gmail

> 接駁一次，之後你講一句「睇下今日有冇新 email」，AI 就自己開你個信箱搵，搵完仲可以幫你覆。
> 全程約 15 分鐘，唔使寫程式，唔使畀錢。

---

```
🤖 俾 AI 助手嘅指示（如果你係人類，跳過呢格，由下面「你會得到咩」開始睇）

如果你係 AI（Claude Code / Codex）：用戶貼咗呢份嘢俾你，即係佢想接通自己個 Gmail。

1. 唔好一次過拋晒所有步驟俾佢。一次帶一步，等佢答「做完」先落下一步。
2. Google Console 個介面經常改版。叫佢跟「掣上面嗰個字」搵，唔好跟位置（「右上角個藍掣」呢類講法會過時）。
3. 行到「加 Test user」嗰步要特別停低確認 —— 呢步跳咗，最後授權一定失敗（403），而且錯誤訊息唔會話你知係呢個原因。
4. 用戶可能同時登入緊幾個 Google account。開始之前先叫佢確認 Console 右上角個頭像係佢想接嗰個 Gmail。
5. Client ID 同 Client secret 係敏感嘢。叫佢用 Download JSON，唔好叫佢喺 chat 度貼出嚟。
6. 佢跑完 auth 之後，用 `search` 行一次真嘅搜尋確認條線通咗，先當完成。
```

---

## 你會得到咩

接通之後，喺 Claude Code 入面可以直接講：

- 「睇下今日有冇新 email」
- 「搵 XXX 寄過嚟嗰封 email，讀俾我聽」
- 「幫我草擬個回覆」

AI 會直接讀你個信箱，唔使你 copy-paste。

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

---

## 開始之前

| 要準備 | 說明 |
|---|---|
| 一個 Gmail account | 你想接通嗰個 |
| Claude Code | 已經裝好 |
| 15 分鐘 | 一次過做完，唔好做一半停 |
| **唔使** 信用卡 | Gmail API 免費。Console 會彈 $300 試用優惠，**唔好撳** |

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

---

## 階段 1｜去 Google 攞鎖匙

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

### 第 1 步：開一個 Google Cloud project

去 https://console.cloud.google.com/projectcreate

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

**做：** Project name 打 `gmail-connect`，撳 **CREATE**。

**跟住會點：** 等十幾秒，右上角會彈個通知話建好咗。之後 Console 頂部會顯示你個 project 名。

---

### 第 2 步：啟用 Gmail API

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

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

**做：** 撳 **ENABLE**。

**跟住會點：** 轉去一版 API 管理畫面，代表已經開通。

> 如果見到嘅係 **MANAGE** 唔係 ENABLE，即係已經開咗，直接落下一步。

---

### 第 3 步：開始設定授權畫面

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

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

**做：** 撳 **Get started**。

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

---

### 第 4 步：填 App 資料

**你會見到：** 一個四格 wizard：App Information → Audience → Contact Information → Finish。

**做：**

| 格 | 填咩 |
|---|---|
| **App Information** | App 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 type 下拉選單。

**做：**

| 欄位 | 揀／填 |
|---|---|
| Application type | **Desktop app** |
| Name | `claude-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-xxxxxxxx.apps.googleusercontent.com.json
```

見到就得，唔使開佢。**階段 1 完成。**

---

## 階段 2｜接駁

### 第 9 步：裝個工具

開 Claude Code，貼呢句：

```
幫我安裝呢個包：https://edwardai-gmail-setup.pages.dev/install.txt
```

見到「✅ 裝好 Gmail 工具」就得。

---

### 第 10 步：叫 AI 讀你個 JSON 檔

貼呢句：

```
我啱啱喺 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 步：授權

貼呢句：

```
python3 ~/gmail-tool/gmail.py auth
```

**跟住會點：** 你部電腦會自動開 browser，去 Google 授權畫面。

**你會見到：** 一版寫住「Google 未驗證這個應用程式」（英文：Google hasn't verified this app）。

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

**做：** 撳 **進階**（Advanced）→ 撳 **前往 Gmail Connect（不安全）**（Go to Gmail Connect (unsafe)）→ 撳 **繼續**（Continue）

**做完點知啱？** Browser 會彈一版「✅ 授權完成」，Claude Code 嗰邊會顯示：

```
✅ refresh token 已寫入 .env
✅ IMAP 連線成功
```

**階段 2 完成。** 呢步一世做一次，之後唔使再撳。

---

## 階段 3｜開始用

### 第 12 步：試一次

貼呢句：

```
python3 ~/gmail-tool/gmail.py search 'newer_than:3d'
```

會列出你最近三日嘅 email。見到有嘢出，即係成功。

### 之後點用

搜尋用 **Gmail 原本嘅搜尋語法** —— 你平時喺 Gmail 個搜尋框打咩，就打咩：

```
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，等你逐字核對真係寄咗啲乜 —— 唔係話「寄咗」就當寄咗。

---

## 撞板急救

### 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

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

```
python3 ~/gmail-tool/gmail.py auth
```

### 話「冇收到 refresh token」

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

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

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

---

## 安全須知

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

---

## 進階：點解要咁行

<details>
<summary>撳開睇技術原理</summary>

呢個工具用 **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 俾你逐字睇。

</details>