openclaw/gogcli

Kết luận: partial · Công nghệ: google-workspace · cli · gmail · gdrive · automation

gogcli là CLI để thao tác Google Workspace ngay trong terminal, bao phủ các mảng chính như Gmail, Drive, Calendar và Contacts. Với ~8.1k stars, đây là công cụ đã được kiểm chứng cho các workflow tự động hóa, đồng bộ dữ liệu và tác vụ cá nhân/devops cần tích hợp Google mà không phải đi qua UI web.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

openclaw/gogcli là dự án cung cấp lệnh gog: một công cụ dòng lệnh giúp bạn dùng Google Workspace ngay trong terminal. Nói đơn giản, thay vì mở Gmail, Drive, Calendar trên trình duyệt, bạn có thể tìm mail, xem lịch, kiểm tra Drive, thao tác Docs/Sheets và nhiều dịch vụ Google khác bằng lệnh.

🎯 Giải quyết vấn đề gì? Dành cho ai?

gogcli giải quyết một nhu cầu rất thực tế: làm việc với Google Workspace nhanh, lặp lại được, và dễ tự động hóa.

Nó phù hợp với:

• Người dùng thích làm việc trong terminal.
• Lập trình viên muốn tích hợp Gmail, Drive, Calendar, Sheets... vào script.
• DevOps hoặc automation engineer cần chạy tác vụ Google trong CI, server, container.
• Người quản trị Google Workspace cần kiểm tra, audit, sao lưu hoặc quản lý tài khoản.
• Coding agents hoặc công cụ tự động cần đọc dữ liệu Google một cách có kiểm soát.

Ví dụ, thay vì vào Gmail để tìm thư chưa đọc trong 7 ngày qua, bạn có thể chạy:

gog gmail search 'is:unread newer_than:7d' --max 10

Hoặc muốn xem lịch hôm nay:

gog calendar events --today

Điểm hay là gog không chỉ “gọi API Google”, mà được thiết kế theo kiểu công việc thực tế: tìm mail, audit chia sẻ Drive, thêm dòng vào Sheet, tạo lịch họp, xuất dữ liệu dạng JSON cho script xử lý tiếp.

⚙️ Hoạt động ra sao?

Cơ chế chính của gogcli có thể hiểu như sau:

• gog là một binary duy nhất, tức là bạn cài một công cụ rồi dùng cho nhiều dịch vụ Google.
• Bạn kết nối gog với tài khoản Google thông qua OAuth. OAuth là cách cấp quyền an toàn để ứng dụng truy cập tài khoản mà không cần biết mật khẩu của bạn.
• Bạn chọn các dịch vụ cần dùng, ví dụ gmail, calendar, drive, docs, sheets, contacts.
• Sau khi xác thực, bạn chạy các lệnh dạng:

gog <dịch-vụ> <hành-động> <tham-số>

Ví dụ:

gog gmail search 'from:boss newer_than:30d' --json
gog calendar events --today
gog drive tree --parent <folderId> --depth 2

• gog hỗ trợ nhiều kiểu xuất dữ liệu:
  • --json: xuất JSON để script hoặc chương trình khác đọc dễ dàng.
  • --plain: xuất dạng văn bản đơn giản.
• Với automation, gog có các chế độ an toàn:
  • --readonly: chỉ đọc, không sửa dữ liệu.
  • --no-input: không hỏi tương tác, phù hợp CI.
  • --gmail-no-send: chặn thao tác gửi Gmail.
  • --dry-run: xem trước kế hoạch, chưa thực sự thực hiện.
• gog hỗ trợ nhiều danh tính:
  • nhiều tài khoản Google,
  • account aliases,
  • OAuth clients,
  • access tokens,
  • service accounts cho Google Workspace.
• Ngoài Gmail, Drive, Calendar, gog còn bao phủ nhiều dịch vụ khác như Docs, Sheets, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts, Tasks, Classroom, Chat, YouTube và Workspace admin.

🆚 Khi nào nên dùng / không nên

Nên dùng gogcli khi:

• Bạn muốn thao tác Google Workspace nhanh trong terminal.
• Bạn cần viết script tự động cho Gmail, Drive, Calendar, Sheets...
• Bạn muốn kết quả dễ xử lý bằng chương trình khác qua --json.
• Bạn cần chạy tác vụ trong CI hoặc container.
• Bạn muốn audit Drive, kiểm tra chia sẻ file, theo dõi thay đổi, sao lưu hoặc đồng bộ dữ liệu.
• Bạn muốn giới hạn rủi ro bằng --readonly, --dry-run, --gmail-no-send.

Không nên dùng gogcli khi:

• Bạn chỉ thỉnh thoảng dùng Gmail hoặc Drive bằng giao diện web và không cần tự động hóa.
• Bạn không quen terminal và muốn thao tác hoàn toàn bằng giao diện kéo-thả.
• Bạn cần quản lý những tính năng Google chưa mở qua API. Ví dụ, Google Calendar appointment schedules không được Calendar API hỗ trợ, nên gog không thể liệt kê hoặc quản lý chúng.
• Bạn muốn một ứng dụng chính thức của Google. gog là mã nguồn mở và không liên kết với Google.

So sánh ngắn:

• Google web UI: dễ dùng bằng mắt, phù hợp thao tác thủ công.
• Google APIs trực tiếp: mạnh, nhưng cần viết code và hiểu API.
• gogcli: nằm giữa hai lựa chọn trên; dùng được ngay bằng lệnh, vẫn đủ tốt cho automation.

🚀 Bắt đầu nhanh

Cách cài phổ biến nhất trên macOS/Linux có Homebrew:

brew install openclaw/tap/gogcli
gog --version

Chạy bằng Docker:

docker run --rm ghcr.io/openclaw/gogcli:latest version

Trên Windows:

# Tải file gogcli_<version>_windows_amd64.zip hoặc gogcli_<version>_windows_arm64.zip
# từ https://github.com/openclaw/gogcli/releases
# Giải nén gog.exe và đưa thư mục chứa gog.exe vào PATH
gog --version

Build từ source:

git clone https://github.com/openclaw/gogcli.git
cd gogcli
make
./bin/gog --version

Thiết lập tài khoản Google lần đầu:

# 1. Tạo Google Cloud project
# 2. Bật các API cần dùng, ví dụ Gmail API, Calendar API, Drive API
# 3. Tạo Desktop OAuth client
# 4. Tải file client_secret_....json về máy

gog auth credentials ~/Downloads/client_secret_....json

gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts

gog auth doctor --check

export GOG_ACCOUNT=you@gmail.com

gog gmail search 'newer_than:7d' --max 10

Ví dụ tối thiểu sau khi đã đăng nhập:

# Tìm email mới trong 7 ngày gần đây
gog gmail search 'newer_than:7d' --max 10

# Xem lịch hôm nay
gog calendar events --today

# Kiểm tra cây thư mục Drive
gog drive tree --parent <folderId> --depth 2

# Xuất kết quả dạng JSON cho script xử lý
gog --readonly --json gmail search 'label:inbox'

Nếu dùng Docker có xác thực, nên lưu trạng thái vào volume riêng:

docker volume create gogcli-state

docker run --rm -it \
  -e GOG_HOME=/persist/gogcli \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-state:/persist/gogcli \
  ghcr.io/openclaw/gogcli:latest \
  auth add you@gmail.com --services gmail,calendar,drive

Lưu ý quan trọng: nếu OAuth app của bạn đang ở trạng thái Testing, refresh token có thể hết hạn sau 7 ngày. Với app cá nhân, nên chuyển app sang In production trong Google Auth Platform trước khi xác thực cuối cùng.

✅ Điểm mạnh & ⚠️ Hạn chế

✅ Điểm mạnh:

• Một lệnh gog dùng được cho rất nhiều dịch vụ Google Workspace.
• Rất hợp cho automation nhờ --json, --plain, --no-input và exit codes rõ ràng.
• Có chế độ an toàn như --readonly, --dry-run, --gmail-no-send.
• Hỗ trợ nhiều tài khoản và nhiều cách xác thực.
• Có nhiều workflow thực tế: tìm mail, audit Drive sharing, xem lịch, tạo sự kiện, thao tác Sheets, quản lý Workspace users.
• Phù hợp cho script, CI, container và coding agents.
• Dự án mã nguồn mở, có cộng đồng sử dụng lớn với khoảng 8.1k stars.

⚠️ Hạn chế:

• Cần biết dùng terminal ở mức cơ bản.
• Bước thiết lập ban đầu hơi dài vì phải tạo Google Cloud project, bật API và cấu hình OAuth.
• Một số tính năng Google không có API thì gog cũng không làm được, ví dụ Calendar appointment schedules.
• Một số API chỉ dành cho Google Workspace domain, không dùng được với tài khoản gmail.com cá nhân.
• Nếu OAuth app để ở trạng thái Testing, token có thể hết hạn sau 7 ngày.
• Đây không phải công cụ chính thức của Google, nên bạn vẫn cần tự cân nhắc quyền truy cập và bảo mật khi cấp quyền.