Google Workspace CLI（gws）用一套命令操作 Gmail、Drive、Calendar 等 Workspace API，並回傳結構化資料。 安裝可選對應系統的官方 Release 執行檔，或在 Node.js 18+ 環境透過 npm 取得。首次登入前要準備 Google Cloud 專案與 OAuth client；gws auth setup 另需 gcloud，已有 client 時則可直接進入 gws auth login。依上游 v0.22.5 README整理。
專案位於 Google Workspace GitHub 組織，但 README 明確標示它不是 Google 正式支援的產品；目前仍為 v1.0 前開發，可能有不相容更新。專案聲明
安裝與第一次登入：先看指令
上游優先建議從 GitHub Releases 下載對應作業系統與架構的檔案、核對附帶 SHA-256，再把執行檔放入 PATH。若使用 npm，下面固定在本頁查證的 v0.22.5；npm 途徑需要 Node.js 18+，它會協助下載平台執行檔。安裝說明、套件版本
npm install -g @googleworkspace/cli@0.22.5
只有在 OAuth client 已備妥、Drive API 已啟用，而且帳號可使用該 app 後，才執行下列登入指令。 這個例子只請求 Drive 的唯讀服務範圍，另包含登入識別所需的基本 scopes；它仍可讀取獲授權的資料，不是沒有資料權限。v0.22.5 登入參數與範圍解析
gws auth login --readonly --services drive
gws auth status
登入會開啟或提供瀏覽器 OAuth 網址，讓你選帳號並檢查同意項目。auth status 用於查看本機認證與設定來源，不能單憑它成功返回，就認定每個 API 的權限與配額都已通過。認證說明
第一次登入前，設定走哪一條路？
| 目前狀態 | 設定方式 | 要留意什麼 |
|---|---|---|
已安裝並可登入 gcloud |
gws auth setup 引導選擇或建立 Cloud 專案、啟用 API、設定 OAuth |
這會配置 Cloud 資源，不只是登入；使用有權管理的專案，核對它引導的設定 |
不使用 gcloud，或要手動控制 client |
在 Google Cloud Console 配置 OAuth，建立 Desktop app client，下載 client JSON | 個人外部測試 app 需加入獲准的 Test users；公司帳號另外受管理員政策限制 |
gcloud 路徑的設定指令如下；完成後回到前面的窄範圍登入。如果設定工具詢問是否立即登入，也要先看清它將請求的範圍。設定說明、setup 原始碼
gws auth setup
手動路徑要在正確專案配置 OAuth 的 Branding／Audience／Data Access，按使用情境選擇 Internal 或 External；若 External 且採測試模式，將登入帳號列為 Test user。再建立 Desktop app client，將下載的 JSON 放在預設 ~/.config/gws/client_secret.json；若另外設定 config 目錄或環境變數，則須核對實際生效來源。詳見上游手動設定、Google OAuth 設定與Desktop app 憑證。
Gwarket 自製流程示意，依上游 v0.22.5 與 Google OAuth 文件整理，2026-11-05。寫入前的人工確認是本文建議的工作流程。
先列少量 Drive 資料，再決定要不要加 Gmail
以下沿用上游的 Bash 形式 JSON 引號寫法，列出最多五個 Drive 檔案；其他 shell 要確認原樣傳入 JSON。這會讀取已登入帳號有權看到的資料，先核對登入帳號與要交給 Agent 的資料範圍。官方 Quick Start
gws drive files list --params '{"pageSize":5}'
若任務確實需要 Gmail，再啟用 Gmail API 並重新檢查 OAuth 範圍。下面是由 CLI 語法與 Google API 組合的唯讀範例：先請求 Drive／Gmail 唯讀 scopes，再列出最多五筆郵件識別資料；users.messages.list 回傳的每筆內容只有 id 與 threadId，不是完整信件。CLI 登入參數、Gmail messages.list
gws auth login --readonly --services drive,gmail
gws gmail users messages list --params '{"userId":"me","maxResults":5}'
整理判斷一：以任務縮小服務與 scopes，不因為支援多服務就一次全開。 只列 Drive 檔案時，不需要順便授權 Gmail。--services 用來縮小服務範圍，--readonly 用來請求唯讀範圍；若程序另外帶有 access token 或 credentials file，還要核對認證優先序，不能只看剛剛登入的帳號。上游認證優先序
它可以幫你處理什麼？
gws 會依 Google Discovery Service 的文件建立命令介面，並提供 --help、schema 查詢、分頁及 JSON 等輸出。常見工作包括彙整 Drive 檔案清單、查詢 Gmail、讀取行事曆，以及透過相應 API 建立試算表或更新資源。方法存在於 schema，不代表該帳號已有相應 API、scope 或資料存取權。運作原理與範例
它適合有重複查詢或多服務流程、能核對資源 ID 和輸出的人。若只是偶爾查看一封信，網頁介面通常已足夠；若組織需要正式支援與服務承諾，不能把這個開源專案的組織名稱當成支援保證。
寫入前的 dry-run 能確認什麼？
上游提供 --dry-run 做本機請求檢查，不執行目標 API 方法。它不能證明伺服器會接受請求、帳號有足夠權限、內容正確或配額足夠；CLI 仍可能為建立命令介面取得 Discovery 文件，因此也不能把它當成完全不連網。共享參考、Discovery 架構
整理判斷二：把「預覽請求」和「同意寫入」分成兩步。 讓 Agent 先列出目標帳號、資源 ID、收件人或變更內容，再由你確認是否要執行。這是工作流程的審核安排；--dry-run 不會替後續另一個命令建立永久的人工核准鎖。郵件與文件內容也只能作輸入材料，不能因為出現在 API 回傳裡，就成為 Agent 應遵守的新指令。
登入或查詢失敗，按錯誤分開看
- 找不到
gcloud：auth setup有這個依賴；可改採手動 OAuth 設定，不要把缺少工具當成 Google 帳號失效。 Access blocked： 個人外部測試 app 先查 Test users；公司帳號還要看管理員的 app／scope 存取政策。不要把所有被擋原因都當成同一個測試名單問題。上游排錯、Google 管理員控制redirect_uri_mismatch： 核對 OAuth client 是否為 Desktop app，並確認實際載入的是哪份 client JSON。上游排錯accessNotConfigured： 回到錯誤指出的 Cloud 專案與 API，確認服務已啟用；更改登入scope不能代替啟用API。上游 API 錯誤說明- scope 同意錯誤： 不要直接選全部。上游提醒測試模式與過多scopes會出問題；Issue #258也有使用者回報scope錯誤。排除Read Only預設中的管理類scope之PR #977在查證時仍未合併，不當成已發布修正。
費用、版本與限制
查證時正式 Release 與 npm latest 均為 v0.22.5，GitHub Release 於2026-03-31發布；本頁指令與參數依該版本核對，沒有把後續主線改動全部當成已發布功能。Release、npm
程式採 Apache-2.0，但這不會取消 Google API 的配額、服務條件或 Agent／模型的費用。Google Drive API 另有專案與使用者的用量限制，批次工作應查看適用專案的當前限制與計費說明。Drive API 用量
下一步
- AI 工作的資料與授權邊界：先確認公司資料能否交給外部服務。
- Plugin、Connector、MCP 怎麼分：釐清 CLI 與 Agent 連線工具的不同層次。
- 核對 AI 的事實、推論與判斷：查詢結果進報告前，再核對來源與推論。
資料來源與查證日期
查證日期：2026-11-05。CLI範例固定於v0.22.5；Google OAuth、管理與API文件以查證當日內容為準。圖解與兩項整理判斷為Gwarket自製。
- googleworkspace/cli v0.22.5 README：定位、前提、安裝、認證、排錯與產品聲明。
- 登入原始碼、setup、共享參考：readonly／services／status與dry-run範圍。
- Google OAuth設定、建立client及管理員app控制：憑證與組織限制。
- Gmail list與Drive用量：範例回傳內容、scopes與配額。
- 正式Release、npm、Issue258與未合併PR977：版本及有歸因的社群材料。