Google Cloud Project 前置設定（Google OAuth）¶

[!WARNING] ☁️ 完整體驗 (Real Data World) | ⏱️ 預計 15-20 分鐘
此文檔屬於「30+ 分鐘完整設置體驗」的 第一步。若您只希望進行 5 分鐘快速體驗（無任何成本），請回到 README 選擇「Mock 模式快速開始」。

本文檔涵蓋如何從零建立 Google Cloud Project，並完成 Time Compass 所需的 Google OAuth 設定。

體驗流程：此為【Real Data World 必須步驟】→ OAuth 驗證流程（下一步）→ 完整設置完成。

[!NOTE] 快速進入？ 若您為評審、或已獲得 .env 檔案，可直接使用環境變數 MCP_DEV_MODE=1 來跳過本步驟，使用內建的 mock data 進行測試。

簡介：完整設定流程¶

本指南分為四個主要步驟，從建立 Google Cloud Project、啟用 API、到取得所有必要的 OAuth 憑證。

最終目的: 取得 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET，填入 .env 環境設定檔。

如果你已經熟悉 Google Cloud 設定流程¶

如果您已熟悉 Google Cloud Console，可先依下列精簡步驟完成設定：如果您不熟悉，請直接從下方「準備工作」開始，依序完成完整流程。

TOC - 準備工作 - Step 1：建立 Google Cloud Project - Step 2：設定 Google Auth Platform（OAuth 同意畫面） - Step 3：建立 OAuth Client（Web application） - Step 4：配置環境變數 - 完成後檢查清單 - 官方文檔參考

建立（或選取）Google Cloud Project，並進入該 Project Dashboard
啟用 3 個 API：Google Tasks API、Google Calendar API、Gmail API
完成 Google Auth Platform 設定：依序完成 Branding、Audience (External)、Contact Information，並加入 Test Users
建立 OAuth Client（Web application），完整設定以下 URI 後建立憑證：
Authorized redirect URIs：http://127.0.0.1:8788/auth、http://localhost:8788/auth、http://127.0.0.1:8000/auth、http://localhost:8000/auth
複製 CLIENT ID / CLIENT SECRET 並填入 .env

四大步驟概覽¶

這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步會帶來的結果。

建立 Google Cloud Project
目的與效果：建立或選擇 Project，讓您擁有獨立的 API 配額與計費空間。
完成後您會得到：✅ Google Cloud Project 建立完成、Project ID 已記錄
啟用必要 API
目的與效果：啟用 Google Calendar、Google Tasks、Gmail API，讓這些服務可在您的 Project 中使用。
完成後您會得到：✅ 三個 API 都已啟用、可供認證之用
設定 Google Auth Platform（OAuth 同意畫面）
目的與效果：配置應用資訊與目標對象，讓使用者授權時能看到正確的應用資訊。
完成後您會得到：✅ OAuth 同意畫面配置完成
建立 OAuth Client（Web application）
目的與效果：建立 Web application 類型的 OAuth Client，取得應用程式所需的 OAuth 憑證。
完成後您會得到：✅ GOOGLE_CLIENT_ID 與 GOOGLE_CLIENT_SECRET 已複製

[!NOTE] 關於「執行」：本指南中的「執行 [指令]」表示： 1. 複製下方框框內的完整指令（如適用） 2. 貼到終端機中 3. 按下 Enter 鍵執行

準備工作¶

打開瀏覽器您會看到：瀏覽器開啟
貼上以下網址並按 Enter：
```
https://console.cloud.google.com/projectcreate?hl=zh-tw
```
[!NOTE] 此連結可直接進入新增專案頁面。登入 Google 帳號後（若未登入）即可開始建立新 Project。

Step 1：建立 Google Cloud Project¶

Step 1.1：建立新 Project¶

根據之前的準備工作，您已進入新增專案頁面。現在完成以下步驟：

輸入 Project 名稱（例如 TimeCompass）
選擇「父項資源」（可選）
點擊「建立」按鈕您會看到：系統建立專案中，可能需要數秒時間，之後會自動返回 Console 首頁並顯示專案列表

Step 1.2：選取新建立的 Project¶

建立完成後，系統會自動進入新 Project 的 Dashboard。

確認頁面頂部顯示您的 Project 名稱您會看到：Dashboard 已準備好進行下一步

如果頁面沒有自動跳轉，您會看到「選取專案」列表，列出所有已建立的專案。

在列表中找到 您剛建立的專案（例如 TimeCompass）您會看到：列表顯示新建立的專案在頂部或按時間排序
點擊該專案 您會看到：系統切換至該 Project，自動跳轉至 Project Dashboard（啟用 API）

Step 1.3：開啟導覽選單¶

在設定 API 前，需要進入 Google Cloud Console 的服務選單。

點擊頁面左上角的選單（≡ 圖示）
確認左側邊欄已展開您會看到：可以看到「APIs & Services」等選項

Step 1.4：進入 API 程式庫¶

在左側邊欄中找到並進入 API 程式庫。

在左側邊欄找到並點擊 「API 和服務」您會看到：展開 API 和服務的子選單
點擊「程式庫」您會看到：進入 API 程式庫頁面，顯示所有可用的 Google API 列表

Step 1.5：啟用必要 API¶

進入「APIs & Services」→「Library」（或直接搜尋）您會看到：頁面顯示 API 庫藏類別列表
搜尋並啟用 以下三個 API（逐個執行步驟 1.5.1 ～ 1.5.3）：

Step 1.5.1：啟用 Google Tasks API¶

在搜尋框中輸入 「tasks」您會看到：搜尋框顯示您輸入的關鍵字
按下 Enter 鍵您會看到：搜尋結果列表顯示 Tasks 相關的 API

點擊「Google Tasks API」卡片您會看到：進入 Google Tasks API 詳細頁面

點擊「啟用」或「ENABLE」按鈕您會看到：API 狀態變為「已啟用」或「API is enabled」

返回 API 程式庫 以啟用下一個 API

點擊頁面左上角的返回箭頭 ← 您會看到：返回 API 程式庫，準備啟用下一個 API

Step 1.5.2：啟用 Google Calendar API¶

在搜尋框中輸入 「calendar」您會看到：搜尋框顯示您輸入的關鍵字
按下 Enter 鍵您會看到：搜尋結果列表顯示 Calendar 相關的 API
點擊「Google Calendar API」卡片您會看到：進入 Google Calendar API 詳細頁面
點擊「啟用」或「ENABLE」按鈕您會看到：API 狀態變為「已啟用」或「API is enabled」
返回 API 程式庫 以啟用下一個 API 點擊頁面左上角的返回箭頭 ← 您會看到：返回 API 程式庫

Step 2：設定 Google Auth Platform（OAuth 同意畫面）¶

Step 2.1：進入 OAuth 同意畫面設定¶

進入「APIs & Services」→「OAuth consent screen」您會看到：頁面顯示 OAuth consent 設定表單

Step 2.2：完成 App 資訊（Branding）¶

在「App information」區塊填入：
應用程式名稱 (App name)：例如 time-compass-desktop
使用者支援電子郵件 (User support email)：您的支援郵箱（例如 skywind5487@gmail.com）

您會看到：表單顯示您填入的應用程式名稱和支援郵箱

在「App Logo」（選用）上傳 logo（若無可略過）
滾動至 「Developer contact information」，填入您的郵箱您會看到：表單頂部區塊完成，無紅色警告
點擊「下一步」按鈕繼續設定您會看到：進入 OAuth 同意畫面設定的下一步驟（目標對象）

Step 2.3：選擇 User Type（Audience）¶

選擇 OAuth consent screen 類型： 請選擇選項 B：外部 (External)（推薦公開發佈）
應用可給任何 Google 帳號使用

點擊「下一步」按鈕您會看到：頁面前進至下一個設定區塊

Step 2.3a：填入開發者聯絡資訊¶

在「聯絡資訊」(Contact Information) 區塊填入：
電子郵件地址 (Email address)：您的開發者郵箱（例如 skywind5487@gmail.com）

您會看到：聯絡電子郵件已填入，Google 會通過此電子郵件通知應用異動資訊

點擊「下一步」按鈕您會看到：進入下一個設定區塊

Step 2.3b：同意服務條款並完成設定¶

勾選「我同意《Google API 服務：使用者資料政策》」

您會看到：複選框被勾選

點擊「繼續」按鈕您會看到：OAuth 同意畫面設定完成，頁面返回 APIs & Services 首頁

Step 2.4：加入 Test Users¶

往下滑動 到「測試使用者」(Test Users) 區塊

您會看到：看到「測試使用者」區塊，其中有「+ Add users」按鈕

點擊「+ Add users」按鈕您會看到：彈出對話框，要求輸入電子郵件地址
輸入您的 Google 帳號郵箱（例如 skywind5487@gmail.com）您會看到：郵箱被加入 Test Users 清單

補充：輸入完成後請點擊左下角「儲存」，再按左上角「X」關閉視窗。

Step 3：建立 OAuth Client（Web application）¶

Step 3.1：進入 Credentials 設定¶

進入「APIs & Services」→「Credentials」您會看到：Credentials 頁面開啟，可見「CREATE CREDENTIALS」按鈕

補充：若介面顯示為「Google Auth Platform」，請先點左側「用戶端」，再點上方「+ 建立用戶端」。

Step 3.2：建立 OAuth Client¶

確認 OAuth 同意畫面設定已完成您會看到：頁面顯示所有設定步驟已完成（應用程式資訊 ✓、目標對象 ✓、聯絡資訊 ✓、完成 ✓）
點擊「建立」按鈕您會看到：進入建立 OAuth Client 的選項選擇

Step 3.3：選擇 Application Type¶

在「Application type」區塊選擇 「Web application（網頁應用程式）」 您會看到：表單展開，顯示「Name」與 redirect URI 相關欄位

補充：先選擇「網頁應用程式」，再填入易辨識的名稱（例如 time_compass_local）。

補充：名稱填好後請往下滑，會看到「已授權的 JavaScript 來源」與「已授權的重新導向 URI」兩個區塊。

Step 3.4：設定 Authorized Redirect URIs¶

在「Authorized JavaScript origins」加入：
```
http://127.0.0.1:8788
http://localhost:8788
http://127.0.0.1:8000
http://localhost:8000
```
您會看到：四個 Origin 都被加入清單

在「Authorized redirect URIs」加入：

http://127.0.0.1:8788/auth
http://localhost:8788/auth
http://127.0.0.1:8000/auth
http://localhost:8000/auth

您會看到：四個 callback URI 都被加入清單

補充： - 8788：MCP 與後端 OAuth runtime 使用 - 8000：Gradio 介面使用

[!IMPORTANT] 本專案 runtime callback 路徑是 /auth。若 URI 不含 /auth，會出現 redirect_uri_mismatch。

點擊「CREATE」建立 OAuth Client 您會看到：建立成功，頁面顯示 CLIENT ID 與 CLIENT SECRET

Step 3.5：複製憑證（建議下載 JSON 備份）¶

在 OAuth Client 詳細頁面或彈窗中：
複製 CLIENT ID
複製 CLIENT SECRET

補充：請複製 CLIENT ID 與 CLIENT SECRET（建議直接跳到下一步填入 .env），並點擊「下載 JSON」做備份。

補充：開啟 JSON 後可先找 client_id 欄位；若內容過長顯示不完整，請向右捲動確認完整字串。

補充：同一份 JSON 也可找到 client_secret；此值屬於敏感資訊，請勿外流。

暫存這兩個值（下步驟會填入 .env）您會看到：您的剪貼簿中已複製 Client ID 和 Secret

[!IMPORTANT] 安全提醒 - CLIENT SECRET 是敏感資訊，不要分享給他人或上傳到版本控制 - 若不慎洩露，請立即在 Google Cloud Console 重新刪除並建立此 OAuth Client

Step 4：配置環境變數¶

現在您已取得所有必要的憑證，接下來將它們填入 .env 檔案。

Step 4.1：開啟 `.env` 檔案¶

進入專案根目錄
```
cd time_compass  # 或您的專案目錄路徑
```
您會看到：終端機顯示當前目錄
開啟 .env 檔案（用任意文本編輯器，例如 VSCode、Notepad++）您會看到：.env 檔案在編輯器中開啟

Step 4.2：填入 Google OAuth 憑證¶

找到或新增以下行：

GOOGLE_CLIENT_ID=你在Step_3複製的_client_id
GOOGLE_CLIENT_SECRET=你在Step_3複製的_client_secret

將 你在Step_3複製的_client_id 替換為實際的 Client ID 您會看到：該行顯示您的 Client ID
將 你在Step_3複製的_client_secret 替換為實際的 Client Secret 您會看到：該行顯示您的 Client Secret

Step 4.3：儲存 `.env`¶

按下 Ctrl+S（Windows / Linux）或 Cmd+S（macOS）您會看到：編輯器標題列不再顯示「*」或「改變」標記，表示檔案已儲存

完成後檢查清單¶

本步驟完成後，請確認：

[ ] Google Cloud Project 已建立（Project ID 已記錄）
[ ] 三個 API 都已啟用：Google Tasks、Google Calendar、Gmail
[ ] OAuth 同意畫面已完成設定
[ ] OAuth Client（Web application）已建立
[ ] .env 檔案中有以下兩個環境變數（且值不為空）：
[ ] GOOGLE_CLIENT_ID
[ ] GOOGLE_CLIENT_SECRET
[ ] 您未將 .env 或憑證洩露給他人

下一步：

前往 OAuth 驗證流程，測試您的 OAuth 設定是否正確，並了解如何初始化授權流程。

官方文檔參考¶

若您遇到問題或需要更深入的理解，以下官方文檔提供完整資訊：

OAuth 同意畫面設定 https://developers.google.com/workspace/guides/configure-oauth-consent
Web Server OAuth 2.0（Web application） https://developers.google.com/identity/protocols/oauth2/web-server
Google Calendar API Auth https://developers.google.com/workspace/calendar/api/auth
Google Tasks API Auth https://developers.google.com/tasks/auth
Gmail API Auth https://developers.google.com/gmail/api/auth