Blog

Hướng Dẫn Sử Dụng Google Workspace CLI Hiệu Quả

Herve Kom

Herve Kom

17 tháng 3 2026

Hướng Dẫn Sử Dụng Google Workspace CLI Hiệu Quả

Google Workspace CLI

Google Workspace CLI (được gọi là gws) là một công cụ dòng lệnh mã nguồn mở, động, cung cấp cho con người và các tác nhân AI quyền truy cập thống nhất vào Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin và mọi API của Google Workspace – được xây dựng trực tiếp từ Dịch vụ Khám phá (Discovery Service) trực tiếp của Google để các lệnh luôn được cập nhật mà không cần phải cài đặt mới. Cài đặt Google Workspace CLI toàn cầu thông qua npm, xác thực một lần với OAuth, và kết nối với các tác nhân như Claude Code hoặc Cursor bằng các kỹ năng đi kèm. Không cần các luồng OAuth rườm rà hay các SDK riêng biệt.

Google Workspace CLI là gì và tại sao nó lại quan trọng?Đây là một vấn đề mà mọi nhà phát triển, quản trị viên và người dùng tác nhân AI đều gặp phải: bạn muốn tự động hóa hoặc truy vấn các dịch vụ Google Workspace (tệp Drive, gửi Gmail, tạo sự kiện Lịch, thêm vào Sheets, chỉnh sửa Docs, đăng bài trong Chat), nhưng bạn lại phải viết các tập lệnh curl tùy chỉnh, vật lộn với các phạm vi OAuth, tự xử lý phân trang, hoặc phải ghép nối nhiều SDK đã lỗi thời.

Điều này xảy ra vì các API của Google Workspace rất mạnh mẽ nhưng lại bị phân mảnh – mỗi dịch vụ có các điểm cuối, luồng xác thực và những điều đặc biệt riêng. Các công cụ truyền thống buộc bạn phải duy trì mã nguồn rườm rà dễ bị lỗi khi API thay đổi.

Google Workspace CLI giải quyết vấn đề này. Ra mắt vào đầu năm 2026 bởi đội ngũ Google (được Addy Osmani công bố), đây là một CLI duy nhất, được hỗ trợ bởi Rust, tự động khám phá mọi phương thức API Workspace trong thời gian chạy bằng cách sử dụng Dịch vụ Khám phá của Google. Bạn có quyền truy cập tức thì vào các điểm cuối mới mà không cần chờ đợi các bản cập nhật công cụ.

Kết quả: các tập lệnh, tác nhân và công việc hàng ngày trên terminal của bạn luôn chính xác và cập nhật. Google Workspace CLI xuất ra JSON rõ ràng, hỗ trợ chạy thử (dry-runs), các trợ giúp phân trang, và bao gồm hơn 40 phím tắt thân thiện với người dùng (tiền tố là +) như gws gmail +send hoặc gws calendar +agenda.

Google Workspace CLI cũng đi kèm với các kỹ năng tác nhân sẵn sàng để cài đặt, vì vậy các công cụ như Claude Code, Cursor, OpenClaw hoặc Gemini CLI có thể tự động quản lý Workspace của bạn—không yêu cầu định nghĩa công cụ tùy chỉnh.

Nếu bạn đang xây dựng hoặc kiểm tra tích hợp API cùng với tự động hóa Workspace, Apidog sẽ xử lý phần xác minh. Đây là một ứng dụng khách API miễn phí để gửi yêu cầu, kiểm tra phản hồi, quản lý môi trường và chạy bộ kiểm thử. Cùng với nhau, Google Workspace CLI cung cấp quyền truy cập trực tiếp vào dữ liệu của bạn, và Apidog xác nhận mọi lệnh gọi đều hoạt động như mong đợi.

Cài đặt Google Workspace CLIYêu cầu duy nhất là Node.js 18 trở lên. Kiểm tra phiên bản của bạn bằng:

node --version

Chạy mà không cần cài đặtCách nhanh nhất để dùng thử Google Workspace CLI là với npx (kéo bản mới nhất mỗi lần):

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'

Tốt cho các kiểm thử nhanh hoặc các tập lệnh dùng một lần.

Cài đặt toàn cầuĐể sử dụng thường xuyên, hãy cài đặt toàn cầu để lệnh gws luôn khả dụng:

npm install -g @googleworkspace/cli
gws --version

Google Workspace CLI đóng gói các tệp nhị phân đã được tạo sẵn, vì vậy khởi động rất nhanh—không cần biên dịch Rust cục bộ. Bạn cũng có thể lấy các tệp nhị phân từ GitHub Releases, sử dụng Homebrew (brew install googleworkspace/cli), hoặc chạy qua Nix nếu muốn.

Thiết lập Google Workspace CLI cho tác nhân lập trình AI của bạnLệnh gws auth setup xử lý việc tạo dự án, bật API và xác thực OAuth ban đầu trong một quy trình hướng dẫn. Chạy:

gws auth setup

Nó sẽ mở trình duyệt của bạn, tạo một dự án Google Cloud nếu cần, bật các API yêu cầu và lưu trữ thông tin xác thực một cách an toàn trong keyring của hệ điều hành của bạn (được mã hóa AES-256-GCM).

Chọn một tác nhân cụ thể hoặc cài đặt kỹ năngSau khi thiết lập, hãy cài đặt các kỹ năng tác nhân đi kèm:

npx skills add https://github.com/googleworkspace/cli

Hoặc chạy trình cài đặt dành riêng cho tác nhân (ví dụ: cho Claude Code hoặc Cursor). Khởi động lại tác nhân của bạn để nó tự động phát hiện các lệnh Google Workspace CLI.

Thiết lập cấp dự án so với thiết lập toàn cầuTheo mặc định, thiết lập áp dụng toàn cầu. Đối với cấu hình chỉ dành cho dự án:

gws auth setup --project

Xác thựcXác thực lại hoặc chuyển đổi tài khoản bất cứ lúc nào:

gws auth login

Kiểm tra người dùng hiện tại và phạm vi:

gws auth whoami

Đăng xuất khi cần:

gws auth logout

Để sử dụng không đầu (headless)/CI, xuất thông tin xác thực:

gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

Hoặc sử dụng lại token của gcloud: export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token).

TelemetryTắt thu thập dữ liệu sử dụng ẩn danh:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1

Sử dụng các lệnh cốt lõi trong Google Workspace CLI (Drive, Gmail, Calendar, Sheets, Docs, Chat)Google Workspace CLI khám phá các lệnh một cách động – không có danh sách cố định. Chạy gws --help để xem các dịch vụ khả dụng.

Tệp và thư mục DriveLiệt kê các tệp gần đây:

gws drive files list --params '{"pageSize":10, "q":"name contains report"}'

Tải lên bằng trợ giúp:

gws drive +upload ./budget.xlsx --name "2026 Budget"

GmailGửi email:

gws gmail +send --to colleague@example.com --subject "Cập nhật" --body "Xem tệp đính kèm." --attach ./file.pdf

Trả lời hoặc phân loại hộp thư đến:

gws gmail +reply --message-id <ID> --body "Cảm ơn!"
gws gmail +triage

LịchTạo sự kiện:

gws calendar +insert --summary "Lên kế hoạch Sprint" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"

Hiển thị lịch trình hôm nay:

gws calendar +agenda --today

SheetsThêm hàng:

gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"

DocsChèn văn bản:

gws docs +write --documentId <ID> --text "Phần mới được thêm qua Google Workspace CLI"

ChatĐăng tin nhắn:

gws chat +send --space <SPACE_ID> --text "Triển khai hoàn tất 🚀"

Sử dụng --dry-run trên bất kỳ lệnh nào để xem trước lệnh gọi API chính xác mà không cần thực thi. Thêm --page-all để phân trang đầy đủ dưới dạng NDJSON.

Cấu hình nâng cao và tùy chọn toàn cục trong Google Workspace CLILưu trữ cài đặt bằng biến môi trường hoặc tệp .env:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'

Điều chỉnh thời gian chờ, định dạng đầu ra (--json, --yaml) hoặc buộc sử dụng keyring dựa trên tệp. Xem cấu hình:

gws config

Tích hợp Google Workspace CLI với các tác nhân AI và lời nhắcSau khi cài đặt kỹ năng, các tác nhân gọi Google Workspace CLI một cách tự nhiên.

Mẫu "sử dụng gws"Trong các lời nhắc: "Liệt kê các tệp Drive gần đây của tôi bằng Google Workspace CLI" hoặc "Gửi email theo dõi qua Google Workspace CLI".

Quy tắc tự động gọiThêm vào hướng dẫn của tác nhân của bạn (ví dụ: CLAUDE.md hoặc các quy tắc của Cursor):

"Bất cứ khi nào tác vụ liên quan đến Gmail, Drive, Calendar, Sheets, Docs hoặc Chat, hãy tự động sử dụng các lệnh Google Workspace CLI trước khi phản hồi. Trước tiên hãy giải quyết dịch vụ và phương thức."

Các tác nhân trả về đường dẫn tệp hoặc kết quả JSON, giữ cho ngữ cảnh gọn gàng.

Kết hợp với Apidog để có được sự tin cậy API hoàn chỉnhGoogle Workspace CLI giúp truy cập tức thì vào các API Workspace, nhưng khi gỡ lỗi các tải trọng (payloads), phạm vi (scopes) hoặc phản hồi, bạn cần khả năng hiển thị.

Apidog là một ứng dụng khách API miễn phí cho phép bạn gửi yêu cầu, kiểm tra phản hồi thô, thiết lập môi trường với token OAuth và tự động hóa các xác nhận.

Quy trình làm việc thực tế:

Google Workspace CLI + Apidog cung cấp quyền truy cập dữ liệu trực tiếp cùng với kiểm thử API đã được xác minh, có thể lặp lại.

Câu hỏi thường gặpGoogle Workspace CLI có gửi dữ liệu của tôi ra bên ngoài không?Không có cuộc gọi nào trực tiếp đến API của Google. Nội dung của bạn không bao giờ rời khỏi tài khoản Google của bạn.

Google Workspace CLI hỗ trợ những dịch vụ nào?Mọi API Workspace được khám phá một cách động: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script, và nhiều dịch vụ khác.

Các lệnh được cập nhật đến mức nào?Google Workspace CLI truy vấn Dịch vụ Khám phá trực tiếp – các phương thức mới tự động xuất hiện.

Nó có yêu cầu khóa API không?Sử dụng OAuth tiêu chuẩn của Google hoặc tài khoản dịch vụ—không có khóa riêng biệt nào ngoài thông tin xác thực.

Google Workspace CLI hỗ trợ những tác nhân và trình chỉnh sửa nào?Claude Code, Cursor, OpenClaw, Gemini CLI, tiện ích mở rộng VS Code—bất kỳ công cụ nào tương thích với MCP hoặc Agent Skills.

Sự khác biệt giữa các lệnh thô và các trợ giúp + là gì?Thô = các phương thức Discovery chính xác (ví dụ: drive.files.list). + trợ giúp = các phím tắt cho các tác vụ phổ biến (ví dụ: +upload, +send).

Tôi có thể sử dụng Google Workspace CLI mà không cần tác nhân AI không?Có, hoàn hảo cho các tập lệnh, tự động hóa hoặc sử dụng terminal hàng ngày.

button

Tài nguyên bổ sung

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống