← Quay lại Tích hợp

📧 Kết nối Gmail — Hướng dẫn từng bước

Setup ~30 phút. Làm 1 lần, dùng mãi mãi.

⚠️ Tại sao cần làm việc này?
Khi kết nối Gmail xong, hệ thống sẽ tự động:
  • Quét inbox mỗi 15 phút tìm email từ trưởng phòng (subject chứa "báo cáo" + có file đính kèm)
  • Tải file → AI Claude phân tích → ghi vào hệ thống
  • Nếu có cảnh báo (margin tụt, runway thấp...) → gửi Telegram cho Danny
Trưởng phòng không cần dùng tool gì khác — chỉ gửi email như bình thường.
1

Tạo project Google Cloud

  1. Mở console.cloud.google.com → đăng nhập bằng Gmail của Danny
  2. Bấm Select a project (góc trên trái) → NEW PROJECT
  3. Đặt tên: nguyen-hung-ceo-os → CREATE
  4. Đợi 30 giây để Google tạo xong → chọn project vừa tạo từ dropdown
2

Bật Gmail API

  1. Vào menu trái → APIs & Services → Library
  2. Search: Gmail API
  3. Bấm vào Gmail API → ENABLE
  4. Đợi vài giây cho API kích hoạt
3

Cấu hình OAuth consent screen

  1. Menu trái → APIs & Services → OAuth consent screen
  2. Chọn External → CREATE
  3. App name: Nguyen Hung CEO OS
  4. User support email + Developer email: dùng email Gmail của Danny
  5. SAVE AND CONTINUE qua các bước Scopes, Test users (có thể skip)
  6. Ở mục Test users → + ADD USERS → thêm chính email Gmail của Danny → SAVE
💡 App ở chế độ "Testing" mặc định — chỉ Danny dùng được. Đủ cho nội bộ, không cần submit Google verify.
4

Tạo OAuth Client ID

  1. Menu trái → APIs & Services → Credentials
  2. + CREATE CREDENTIALS → OAuth client ID
  3. Application type: Web application
  4. Name: Nguyen Hung CEO OS Web
  5. ⚠️ Quan trọng — có 2 ô khác nhau, đừng nhầm:
    📍 Authorized JavaScript origins
    → CHỈ điền host + port, KHÔNG có path. Có thể bỏ trống nếu Google không yêu cầu (*).
    http://localhost:2000
    📍 Authorized redirect URIs
    → Điền URL ĐẦY ĐỦ có path. Bấm + ADD URI.
    http://localhost:2000/api/auth/gmail/callback
    Nếu dán URL có path vào JavaScript origins → Google báo "Invalid Origin: URIs must not contain a path". Ngược lại nếu dán origin (không có path) vào redirect URIs → callback OAuth sẽ fail.
  6. CREATE → popup hiện Client ID và Client secret → copy 2 giá trị
5

Điền vào .env

Mở file .env ở thư mục gốc dự án, sửa 2 dòng:

GMAIL_CLIENT_ID=<Client ID dán vào đây>
GMAIL_CLIENT_SECRET=<Client Secret dán vào đây>

Restart server để load credentials mới:

lsof -ti:2000 | xargs kill -9
node src/index.js
6

Bấm "Kết nối Gmail" — bước cuối

  1. Quay lại trang Tích hợp
  2. Bấm nút 🔗 Kết nối Gmail
  3. Google sẽ hỏi "Continue" → Yes → chọn account Gmail của Danny
  4. Có thể hiện cảnh báo "Google hasn't verified this app" → bấm Advanced → Go to Nguyen Hung CEO OS (unsafe) (vì app self-hosted của Danny, không cần verify)
  5. Cho phép quyền đọc + sửa email
  6. Tự động redirect về hệ thống với thông báo "✅ Kết nối Gmail thành công"
Khi gặp lỗi:
• "redirect_uri_mismatch" → URL Authorized redirect URI ở Bước 4 phải khớp chính xác với GMAIL_REDIRECT_URI trong .env.
• "Không nhận được refresh_token" → Vào Google Account → Apps with access → xoá quyền app → kết nối lại.
• "Access blocked" → Phải thêm email Danny vào Test users ở Bước 3.