Hướng dẫn kết nối Google Workspace với Hermes Agent chi tiết A-Z

Khi kết nối Google Workspace với Hermes Agent, bạn có thể thực hiện nhiều tác vụ như tìm email, đọc email, gửi phản hồi, kiểm tra lịch, tạo sự kiện, đọc file Google Drive, ghi dữ liệu vào Google Sheets hoặc truy xuất danh bạ từ Google Contacts trên các kênh nhắn tin quen thuộc. Đây là bước quan trọng nếu bạn muốn biến Hermes Agent thành một trợ lý AI có khả năng xử lý công việc thực tế trong hệ sinh thái Google Workspace. Cùng Tino tìm hiểu cách thực hiện qua bài viết dưới đây nhé!

Tại sao nên kết nối Google Workspace với Hermes Agent?

Việc kết nối Google Workspace giúp Hermes Agent có thể làm việc trực tiếp với dữ liệu và công cụ mà doanh nghiệp đang sử dụng hằng ngày. Thay vì phải mở từng ứng dụng Google riêng lẻ, bạn có thể yêu cầu Hermes Agent thực hiện các thao tác thông qua câu lệnh tự nhiên.

Ví dụ, bạn có thể yêu cầu Hermes Agent:

• Tìm một email cụ thể trong Gmail.
• Đọc nội dung email và tóm tắt lại.
• Soạn hoặc phản hồi email.
• Kiểm tra lịch làm việc trên Google Calendar.
• Tạo một sự kiện mới trên Calendar.
• Tìm file trong Google Drive.
• Đọc nội dung Google Docs.
• Ghi dữ liệu vào Google Sheets.
• Truy xuất danh bạ từ Google Contacts.

Nhờ đó, Hermes Agent không chỉ là một chatbot trả lời câu hỏi, mà có thể trở thành trợ lý AI hỗ trợ công việc thực tế trong môi trường Google Workspace.

Thông tin cấu hình cần nắm trước khi thực hiện

Trong hướng dẫn này, Hermes Agent sẽ kết nối Google Workspace bằng OAuth 2.0 dạng Desktop App.

Bạn cần chuẩn bị:

• Tài khoản Google hoặc Google Workspace cần kết nối.
• Quyền truy cập Google Cloud Console.
• Máy chủ/VPS đã cài Hermes Agent.
• Quyền SSH vào máy chủ Hermes.
• Quyền chạy lệnh Python trên máy chủ.
  

Hướng dẫn kết nối Google Workspace với Hermes Agent

Bước 1: Truy cập Google Cloud Console

Đầu tiên, bạn cần truy cập Google Cloud Console bằng tài khoản Google muốn dùng để cấu hình OAuth.

Sau khi đăng nhập, hãy kiểm tra góc trên cùng của giao diện để chắc chắn bạn đang chọn đúng tài khoản Google.

Nếu bạn đang dùng tài khoản Google Workspace của doanh nghiệp, hãy đăng nhập bằng đúng email Workspace cần cấp quyền cho Hermes Agent.

Bước 2: Chọn hoặc tạo Google Cloud Project

Google yêu cầu các API, OAuth client và thông tin xác thực phải nằm trong một Google Cloud Project. Vì vậy, trước khi bật API, bạn cần chọn project hiện có hoặc tạo project mới.

Tại Google Cloud Console, nhấn vào khu vực chọn project ở thanh trên cùng. Sau đó, bạn có thể chọn một project đã có hoặc tạo project mới.

Nếu tạo project mới, hãy thực hiện như sau:

1. Chọn New Project.
2. Nhập tên project, ví dụ: Hermes Google Workspace
3. Nhấn Create.

Chờ Google tạo project xong, bạn chọn lại project vừa tạo để tiếp tục cấu hình.

Lưu ý: Tất cả API và OAuth client ở các bước sau cần được tạo trong đúng project này. Nếu chọn nhầm project, Hermes Agent có thể không hoạt động đúng với thông tin xác thực đã tải về.

Bước 3: Mở API Library trong Google Cloud

Sau khi đã chọn đúng project, bạn cần vào API Library để bật các API cần thiết.

Truy cập nhanh API Library tại: https://console.cloud.google.com/apis/library

Hoặc thao tác thủ công trên Google Cloud Console:

1. Mở menu điều hướng bên trái.
2. Chọn APIs & Services.
3. Chọn Library.

Lưu ý: Đảm bảo project đang chọn là project dùng cho Hermes Agent.

API Library là nơi bạn tìm và kích hoạt các API của Google. Hermes Agent chỉ có thể gọi những dịch vụ đã được bật API trong project.

Bước 4: Bật Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API và Google People API

Trong API Library, thực hiện như sau:

Nhập từ khóa (ví dụ: Gmail API) -> Chọn kết quả -> Nhấn Enable -> Chờ Google bật API cho project.

Sau khi bật thành công, nút Enable sẽ chuyển sang trạng thái đã kích hoạt hoặc giao diện sẽ hiển thị trang quản lý API.

Thực hiện lần lượt cho các API: Google Calendar API, Google Drive API, Google Sheets API, Google Docs API và Google People API.

Bước 5: Kiểm tra lại danh sách API đã bật

Sau khi bật xong các API, bạn nên kiểm tra lại để tránh thiếu API.

Từ Google Cloud Console, vào APIs & Services -> chọn Enabled APIs & services.

Kiểm tra xem các API trong danh sách trên đã xuất hiện hay chưa. Nếu thiếu API nào, hãy quay lại API Library để bật bổ sung.

Bước 6: Cấu hình OAuth consent screen

Trước khi tạo OAuth client, bạn cần cấu hình màn hình đồng ý OAuth. Đây là màn hình Google hiển thị khi bạn đăng nhập và cấp quyền cho Hermes Agent.

Truy cập nhanh khu vực cấu hình OAuth tại: https://console.cloud.google.com/auth/overview

Hoặc trong Google Cloud Console, vào phần liên quan đến Google Auth Platform hoặc OAuth consent screen.

Tại đây, bạn cần điền các thông tin cơ bản như:

• App name: tên ứng dụng hiển thị trên màn hình cấp quyền, ví dụ: Hermes Agent
• User support email: email hỗ trợ người dùng.

Audience: chọn External

Contact information: email liên hệ của nhà phát triển.

Cuối cùng, nhấn Create để hoàn tất tạo ứng dụng.

Nếu bạn chỉ dùng nội bộ hoặc đang thử nghiệm, có thể để ứng dụng ở trạng thái Testing. Khi ứng dụng ở trạng thái Testing, bạn cần thêm tài khoản Google của mình vào danh sách Test users.

Bước 7: Thêm test user nếu app đang ở Testing

Nếu OAuth app đang ở trạng thái Testing, chỉ những tài khoản nằm trong danh sách test users mới có thể đăng nhập và cấp quyền.

Truy cập nhanh trang Audience/Test users tại: https://console.cloud.google.com/auth/audience

Sau đó thực hiện:

1. Chọn đúng project Google Cloud.
2. Tìm phần Test users.
3. Nhấn Add users.
4. Nhập email Google muốn dùng để kết nối Hermes Agent.
5. Lưu lại cấu hình.
   

Ví dụ, nếu bạn muốn cấp quyền bằng email công việc, hãy thêm đúng email đó vào danh sách test users.

Nếu bỏ qua bước này, khi đăng nhập OAuth, Google có thể báo ứng dụng chưa cho phép tài khoản này truy cập.

Bước 8: Tạo OAuth client ID

Sau khi bật API và cấu hình OAuth consent screen, bạn cần tạo OAuth client ID cho Hermes Agent.

Truy cập nhanh trang Credentials tại: https://console.cloud.google.com/apis/credentials

Sau đó thực hiện theo các bước sau:

Vào APIs & Services -> chọn Credentials -> Nhấn Create Credentials.

Chọn OAuth client ID.

Tại mục Application type, chọn Desktop app. Sau đó, đặt tên cho OAuth client, ví dụ: Hermes Agent Desktop.

Nhấn Create để tạo.

Sau khi tạo xong, Google sẽ tạo OAuth client cho project. Đây là thông tin Hermes Agent sẽ dùng để bắt đầu quá trình đăng nhập OAuth.

Bước 9: Tải file JSON client secret

Sau khi tạo OAuth client ID, Google sẽ cho phép bạn tải file JSON chứa thông tin client.

Bạn hãy nhấn Download JSON để tải file về máy.

File này thường có tên dạng: client_secret_xxxxxxxxx.apps.googleusercontent.com.json

Bạn có thể đổi tên file cho dễ quản lý, ví dụ: hermes-google-client-secret

Bước 10: Import client secret vào Hermes Agent

Nếu bạn dùng Windows PowerShell hoặc Terminal trên máy tính, chạy lệnh dạng:

scp "C:\Users\YourName\Downloads\hermes-google-client-secret.json" root@IP_VPS:/root/hermes-google-client-secret.json

Thay:

• YourName bằng tên thiết bị.
• IP_VPS bằng IP thật của VPS.

Ví dụ:

scp "C:\Users\ADMIN\Downloads\hermes-google-client-secret.json" root@103.142.25.84:/root/hermes-google-client-secret.json

Nhập mật khẩu VPS khi được yêu cầu.

Sau đó SSH lại VPS và kiểm tra. Nếu chưa biết cách SSH vào VPS, bạn có thể tham khảo bài viết: Hướng dẫn sử dụng phần mềm Xshell kết nối SSH tới VPS

ls -la /root/hermes-google-client-secret.json

Nếu đã có file, bạn chạy lệnh sau để import:

python3 ~/.hermes/skills/productivity/google-workspace/scripts/setup.py \

--client-secret /root/hermes-google-client-secret.json

Nếu thành công, bạn sẽ nhận được kết quả:

OK: Client secret saved to /root/.hermes/google_client_secret.json

Điều này có nghĩa là Hermes Agent đã lưu client secret vào đúng vị trí: /root/.hermes/google_client_secret.json

Từ bước này trở đi, Hermes Agent đã có thông tin OAuth client để tạo link đăng nhập Google.

Bước 11: Tạo môi trường Python riêng cho Google Workspace

Để chạy quy trình xác thực ổn định hơn, bạn có thể tạo môi trường Python riêng bằng lệnh:

python3 -m venv /root/.hermes/google-workspace-venv

Môi trường này sẽ được dùng để chạy các lệnh xác thực Google Workspace trong những bước tiếp theo.

Bước 12: Tạo link đăng nhập Google OAuth

Chạy lệnh sau để Hermes Agent tạo link đăng nhập Google OAuth:

/root/.hermes/google-workspace-venv/bin/python \

~/.hermes/skills/productivity/google-workspace/scripts/setup.py --auth-url

Sau khi chạy lệnh, Hermes Agent sẽ trả về một đường link đăng nhập Google.

Bạn hãy copy link này và mở trong trình duyệt. Sau đó:

1. Đăng nhập bằng tài khoản Google muốn kết nối.
2. Kiểm tra tên ứng dụng hiển thị trên màn hình cấp quyền.
3. Kiểm tra các quyền truy cập được yêu cầu rồi tích Chọn tất cả để cho phép Hermes Agent truy cập Google Workspace.

Lưu ý: Hãy đăng nhập bằng đúng tài khoản đã thêm vào test users nếu OAuth app đang ở trạng thái Testing.

Sau khi bạn nhấn Allow, Google sẽ chuyển hướng trình duyệt về URL dạng:

http://localhost:1/?state=...&code=...

Trình duyệt có thể hiển thị lỗi không truy cập được localhost. Đây là hiện tượng bình thường, không phải lỗi cấu hình.

Bạn chỉ cần copy toàn bộ URL trên thanh địa chỉ trình duyệt. URL này chính là dữ liệu cần dùng để Hermes Agent đổi authorization code lấy token xác thực.

Bước 13: Đổi authorization code lấy token

Quay lại terminal trên máy chủ Hermes Agent và chạy lệnh sau:

/root/.hermes/google-workspace-venv/bin/python \

  ~/.hermes/skills/productivity/google-workspace/scripts/setup.py \

--auth-code "http://localhost:1/?state=...&code=..."

Trong đó, hãy thay URL mẫu bằng toàn bộ URL redirect bạn đã copy từ trình duyệt.

Nếu xác thực thành công, hệ thống sẽ trả về:

OK: Authenticated. Token saved to /root/.hermes/google_token.json

Token sẽ được lưu tại: /root/.hermes/google_token.json. Đây là file Hermes Agent dùng để gọi API Google trong các lần sử dụng sau.

Bước 14: Kiểm tra token đã hợp lệ hay chưa

Sau khi token được lưu, bạn nên chạy lệnh kiểm tra trạng thái xác thực:

/root/.hermes/google-workspace-venv/bin/python \

~/.hermes/skills/productivity/google-workspace/scripts/setup.py --check

Nếu token hợp lệ, kết quả sẽ hiển thị tương tự:

AUTHENTICATED: Token valid at /root/.hermes/google_token.json

Kết quả này cho biết Hermes Agent đã đọc được token và token còn hiệu lực.

Bước 15: Kiểm tra kết nối API Google thực tế

Tiếp theo, chạy lệnh kiểm tra kết nối thực tế đến API Google:

/root/.hermes/google-workspace-venv/bin/python \

~/.hermes/skills/productivity/google-workspace/scripts/setup.py --check-live

Nếu Hermes Agent gọi API Google thành công, bạn sẽ thấy kết quả:

LIVE_CHECK_OK: Real API call succeeded.

Sau khi kết nối Google Workspace, Hermes Agent dùng được gì?

Sau khi kết nối thành công, Hermes Agent có thể hỗ trợ nhiều thao tác với các dịch vụ Google Workspace.

Ví dụ: Bạn có thể yêu cầu Hermes Agent tạo một file docs:

Lưu ý bảo mật khi kết nối Google Workspace với Hermes Agent

Trong quá trình cấu hình, bạn cần bảo vệ cẩn thận các thông tin xác thực. Không chia sẻ công khai các dữ liệu sau:

• File client secret.
• Authorization code.
• File token OAuth.
• Nội dung file /root/.hermes/google_client_secret.json.
• Nội dung file /root/.hermes/google_token.json.

Nếu đã vô tình chia sẻ client secret hoặc token ở nơi không an toàn, bạn nên tạo OAuth client mới hoặc rotate lại thông tin xác thực.

Ngoài ra, nếu bạn revoke OAuth token trong tài khoản Google, Hermes Agent sẽ mất quyền truy cập Google Workspace. Khi đó, bạn cần chạy lại quy trình đăng nhập OAuth để tạo token mới.

Với các hành động có thể làm thay đổi dữ liệu, chẳng hạn như gửi email, tạo/xóa lịch, share/xóa file Drive hoặc sửa Docs/Sheets, Hermes Agent sẽ hỏi xác nhận trước khi thực hiện.

Một số lỗi thường gặp và cách xử lý

1. Không tạo được OAuth client ID

Nguyên nhân thường gặp là OAuth consent screen chưa được cấu hình. Hãy kiểm tra lại phần Google Auth Platform hoặc OAuth consent screen, sau đó điền đầy đủ thông tin ứng dụng trước khi tạo OAuth client.

2. Không đăng nhập được OAuth vì app đang Testing

Nếu app đang ở trạng thái Testing, bạn cần thêm email Google vào danh sách test users. Hãy truy cập phần Audience/Test users trong Google Cloud và thêm đúng email muốn dùng để cấp quyền.

3. Google redirect về localhost bị lỗi

Đây là hiện tượng bình thường. Bạn không cần truy cập được localhost. Chỉ cần copy toàn bộ URL trên thanh địa chỉ trình duyệt rồi dùng URL đó cho lệnh –auth-code.

4. Lệnh check-live không thành công

Trường hợp này có thể do thiếu API, token chưa hợp lệ hoặc quyền OAuth chưa đầy đủ. Hãy kiểm tra lại danh sách API đã bật, sau đó chạy lại quy trình xác thực nếu cần.

5. Token bị revoke hoặc hết hiệu lực

Nếu token bị revoke, Hermes Agent không thể gọi API Google. Bạn cần tạo lại link đăng nhập OAuth, cấp quyền lại và đổi authorization code để lấy token mới.

Các bài viết liên quan:

• Hướng dẫn kết nối Telegram với Hermes Agent trên VPS Hermes của Tino
• Hướng dẫn kết nối tài khoản Zalo cá nhân với Hermes Agent trên VPS Hermes của Tino
• Hướng dẫn kết nối Discord với Hermes Agent trên VPS Hermes của Tino
• VPS Hermes Agent là gì? 
• Cấu hình tối thiểu để chạy Hermes Agent
• Mua VPS Hermes Agent ở đâu uy tín?
• Có nên mua VPS cài sẵn Hermes Agent?

Kết luận

Kết nối Google Workspace với Hermes Agent giúp mở rộng khả năng tự động hóa công việc trong hệ sinh thái Google. Sau khi hoàn tất cấu hình, Hermes Agent có thể hỗ trợ xử lý email, lịch, file, tài liệu, bảng tính và danh bạ thông qua OAuth 2.0 an toàn, không cần sử dụng mật khẩu Google trực tiếp. Chúc bạn thành công!

Những câu hỏi thường gặp