Hermes Agent kết nối Google Workspace qua skill Google Workspace đi kèm, dùng OAuth 2.0: bạn tạo Google Cloud project, bật API Gmail, Calendar, Drive, Docs, Sheets, People, tạo OAuth client loại Desktop app, nạp file client secret lên VPS rồi đăng nhập Google một lần để Hermes lưu token. Hermes không cần mật khẩu Google của bạn.
Bài thuộc nhóm skills và tích hợp cho Hermes Agent; phần giới thiệu agent có ở Hermes Agent là gì. Sau khi kết nối, bạn nhờ Hermes tìm và tóm tắt email, kiểm tra lịch, tạo sự kiện, đọc Google Docs, ghi Google Sheets hoặc tra danh bạ ngay trên kênh nhắn tin quen thuộc.
Tại sao nên kết nối Google Workspace với Hermes Agent?
Kết nối Google Workspace cho phép Hermes Agent làm việc trực tiếp với email, lịch, file và bảng tính mà bạn dùng hằng ngày. Thay vì mở từng ứng dụng Google, bạn nhắn một câu tự nhiên và Hermes gọi API tương ứng. Đây là skill có sẵn của Hermes, nằm ở skills/productivity/google-workspace/.
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
Hermes Agent kết nối Google Workspace bằng OAuth 2.0 dạng Desktop App, token được lưu trên VPS và tự làm mới. Bạn làm thủ công theo 15 bước dưới đây, hoặc nhắn Hermes “set up Google Workspace” để agent dẫn từng bước. Chỉ cần email thì skill himalaya với App Password của Gmail nhanh hơn.
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ủ.
Đối chiếu với docs skill Google Workspace của Hermes ngày 26/10/2026: quy trình 4 phần (tạo project và bật API, tạo OAuth Desktop app, đăng nhập và dán URL redirect, token tự làm mới) vẫn đúng như bài; ảnh chụp tháng 6/2026.
Hướng dẫn kết nối Google Workspace với Hermes Agent
Quy trình gồm 15 bước: chín bước đầu làm trên Google Cloud Console (chọn project, bật 6 API, cấu hình màn hình đồng ý OAuth, thêm test user, tạo OAuth client Desktop app và tải JSON), sáu bước sau làm trên VPS (nạp client secret, tạo link đăng nhập, đổi code lấy token và kiểm tra kết nối).
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:
- Chọn New Project.
- Nhập tên project, ví dụ: Hermes Google Workspace
- 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:
- Mở menu điều hướng bên trái.
- Chọn APIs & Services.
- 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:
- Chọn đúng project Google Cloud.
- Tìm phần Test users.
- Nhấn Add users.
- Nhập email Google muốn dùng để kết nối Hermes Agent.
- 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.jsonThay:
- 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.jsonNhậ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, tham khảo bài cách 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.jsonNế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-venvMô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.
Nếu lệnh ở các bước sau báo ModuleNotFoundError, docs Hermes hướng dẫn chạy lại script setup với tham số --install-deps để cài thư viện Google cần thiết.
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 đó:
- Đăng nhập bằng tài khoản Google muốn kết nối.
- Kiểm tra tên ứng dụng hiển thị trên màn hình cấp quyền.
- 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 --checkNế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-liveNế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.
Toàn bộ chuỗi từ bước 10 đến bước 15 chỉ làm một lần. Sơ đồ dưới tóm tắt file nào được tạo ở đâu và khi nào phải đăng nhập lại.
Sau khi kết nối Google Workspace, Hermes Agent dùng được gì?
Sau khi kết nối, Hermes Agent đọc và thao tác được trên sáu dịch vụ: Gmail, Calendar, Drive, Docs, Sheets và Contacts. Skill ưu tiên Google Workspace CLI (gws) nếu máy có cài để hỗ trợ nhiều thao tác hơn, nếu không thì dùng thư viện Python của Google. Kết quả trả về dạng JSON để agent xử lý tiếp.
Dịch vụ Tác vụ có thể thực hiện Gmail Tìm email, đọc email, gửi/reply email, thêm hoặc bỏ label Google Calendar Xem lịch, tạo lịch, xóa event Google Drive Tìm file, upload/download, tạo folder, share file, đưa file vào thùng rác Google Docs Đọc tài liệu, tạo Google Docs, append nội dung Google Sheets Tạo spreadsheet, đọc dữ liệu, ghi dữ liệu, append dữ liệu Google Contacts Đọc danh bạ thông qua People API
Lệnh mẫu trong docs (26/10/2026) có tìm, đọc, gửi, trả lời, gắn nhãn Gmail; xem, tạo, xoá sự kiện Calendar; tìm file Drive; đọc, ghi, nối dòng Sheets; đọc Docs; liệt kê danh bạ. Các thao tác khác trong bảng phụ thuộc phiên bản skill và việc có cài gws hay không.
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
Bảo mật kết nối Google Workspace xoay quanh hai file trên VPS: client secret và token OAuth. Ai có token là đọc được email, lịch, file của bạn qua API cho tới khi token bị thu hồi, nên đặt quyền đọc hạn chế cho hai file này và 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 hành động làm thay đổi dữ liệu như gửi email, tạo hoặc xoá lịch, chia sẻ hoặc xoá file Drive, sửa Docs/Sheets, hãy yêu cầu Hermes nêu rõ việc sẽ làm và chờ bạn xác nhận trước khi thực hiện; có thể ghi quy tắc này vào memory để agent nhớ cho các lần sau.
Nếu OAuth app để ở trạng thái Testing với loại người dùng External, Google cấp refresh token hết hạn sau 7 ngày (Google Identity, OAuth 2.0, xem ngày 26/10/2026). Khi đó Hermes báo lỗi làm mới token và bạn cần chạy lại bước 12–13.
Một số lỗi thường gặp và cách xử lý
Phần lớn lỗi khi kết nối Google Workspace với Hermes nằm ở Google Cloud Console chứ không ở Hermes: thiếu màn hình đồng ý OAuth, thiếu test user, chưa bật API, hoặc token đã bị thu hồi hay hết hạn. Đọc mã lỗi skill trả về để biết cần sửa ở đâu.
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 hoặc hết hạn (app Testing: 7 ngày), Hermes Agent không gọi được API Google và skill báo REFRESH_FAILED. Bạ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. Lỗi HttpError 403: Insufficient Permission nghĩa là thiếu quyền, cần đăng nhập lại và chọn đủ quyền.
Khi nào không nên kết nối Google Workspace với Hermes Agent?
Không nên cấp quyền Google Workspace đầy đủ cho Hermes khi agent chạy trên máy dùng chung, khi nhiều người cùng nhắn lệnh cho agent, hoặc khi tài khoản chứa dữ liệu khách hàng nhạy cảm mà công ty chưa cho phép dùng AI. Token trên VPS cho phép đọc và gửi email thay bạn.
- Chỉ cần email: dùng skill himalaya với App Password, phạm vi hẹp hơn.
- Tài khoản Workspace của công ty: hỏi quản trị viên trước, có thể tổ chức chặn ứng dụng OAuth chưa được duyệt.
- Agent nhận lệnh từ nhiều kênh: giới hạn người dùng được phép và cân nhắc Docker sandbox cho Hermes Agent.
Các bài viết liên quan:
- Hướng dẫn kết nối Google Chat với Hermes Agent
- Cách cài đặt và sử dụng Hermes Agent trên VPS
- Sử dụng cron job trên Hermes Agent
- Cấu hình tối thiểu để chạy Hermes Agent
- 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 mở rộng khả năng tự động hoá trong hệ sinh thái Google: xử lý email, lịch, file, tài liệu, bảng tính và danh bạ qua OAuth 2.0, không dùng mật khẩu Google. Giữ kín file client secret và token, đưa app sang In production nếu dùng lâu dài để tránh token hết hạn sau 7 ngày.
Muốn chạy Hermes Agent 24/7 mà không tự cài? VPS Hermes Agent của Tino cài sẵn Hermes Agent trên VPS NVMe đặt tại Việt Nam; bạn vẫn có quyền root để cấu hình. Xem cấu hình và giá trên trang sản phẩm.
Bạn dùng trong 30 ngày, không hài lòng được hoàn 100% (xem điều kiện).
Những câu hỏi thường gặp
Kết nối Google Workspace với Hermes Agent có cần nhập mật khẩu Google không?
Không. Hermes Agent kết nối Google Workspace thông qua OAuth 2.0, không yêu cầu nhập hoặc lưu mật khẩu Google. Bạn chỉ cần đăng nhập tài khoản Google trên trình duyệt, cấp quyền truy cập và Hermes Agent sẽ sử dụng token xác thực để làm việc với các dịch vụ Google.
Cần bật những API nào trong Google Cloud?
Bạn cần bật các API sau trong Google Cloud Project: Gmail API; Google Calendar API; Google Drive API; Google Sheets API; Google Docs API; People API. Nếu thiếu một trong các API này, Hermes Agent có thể không sử dụng được đầy đủ tính năng liên quan đến Gmail, Calendar, Drive, Docs, Sheets hoặc Contacts.
Vì sao phải chọn OAuth client loại Desktop App?
Hermes Agent sử dụng luồng xác thực OAuth phù hợp với loại ứng dụng Desktop App. Khi chọn đúng loại này, Google sẽ tạo file client secret JSON để Hermes Agent dùng trong quá trình tạo link đăng nhập, lấy authorization code và đổi sang token xác thực.
Vì sao token Google của Hermes Agent hết hạn sau một tuần?
Vì OAuth app loại External đang ở trạng thái Testing: Google cấp refresh token chỉ có hiệu lực 7 ngày. Chạy lại bước tạo link đăng nhập và đổi code để lấy token mới, hoặc chuyển app sang In production để token không hết hạn theo chu kỳ này.
