Google 最近開源了一個統一的命令列工具 gws，可以用一支 CLI 操作 Drive、Gmail、Calendar、Sheets 等所有 Google Workspace 服務。更吸引我的是它附帶 100 多個 agent skill 檔案，讓 AI agent 直接操作 Google Workspace API。

我在 Windows 上裝它，踩了三個坑，花了不少時間。這篇是當時（v0.4.x 時代）的踩坑紀錄，但安裝方式已更新到目前最新版 v0.22.5。

注意：gws 迭代很快，截至 2026-06-18 已到 v0.22.5，gws mcp 子指令也已在 v0.8.0 移除。文章後段會說明現在的 AI agent 整合方式。

gws 是什麼

gws 用 Rust 寫的，最特別的地方是它的指令不是寫死的——而是從 Google Discovery Service 動態建構。Google 新增 API 端點時，gws 自動就能用，不需要更新軟體。

目前支援的服務：

  • Drive — 檔案管理
  • Spreadsheets — 試算表
  • Gmail — 郵件讀寫
  • Calendar — 行事曆
  • Documents — 文件
  • Presentations — 簡報
  • Tasks — 待辦事項

所有回應都是 JSON 格式，很適合寫腳本或讓 AI agent 呼叫。

安裝：npm 裝不起來（v0.4.x 時代的坑）

官方文件說用 npm 裝：

1
npm install -g @googleworkspace/cli

在 Windows 上直接炸了：

1
2
Error fetching release: An error occurred untarring the artifact:
stderr: tar: Cannot connect to C: resolve failed

npm 安裝腳本會從 GitHub Releases 下載壓縮檔，但 Windows 的 tar 處理路徑有問題，解壓失敗。這個問題在 v0.4.x 時期存在；目前版本（v0.22.5）npm 安裝行為可能已改善，但我沒有重驗，保守起見還是建議直接下載二進位檔。

解法：手動下載二進位檔

v0.22.5 的 Windows 版本是 .zip 格式，不再是 .tar.gz：

1
2
3
4
5
# PowerShell 下載並解壓
$ver = "0.22.5"
$url = "https://github.com/googleworkspace/cli/releases/download/v$ver/google-workspace-cli-x86_64-pc-windows-msvc.zip"
Invoke-WebRequest -Uri $url -OutFile gws.zip
Expand-Archive gws.zip -DestinationPath gws-extracted

或用 curl（Git Bash）：

1
2
3
4
# Git Bash
ver="0.22.5"
curl -sL -o gws.zip "https://github.com/googleworkspace/cli/releases/download/v${ver}/google-workspace-cli-x86_64-pc-windows-msvc.zip"
unzip gws.zip -d gws-extracted

解壓後把 gws.exe 丟到 PATH 裡的任何目錄。我放在 Node.js 目錄，因為它已經在 PATH 中：

1
cp gws-extracted/gws.exe "/c/Program Files/nodejs/gws.exe"

注意：如果你之前 npm 安裝失敗，它會留下壞掉的 shim 檔案（gws、gws.cmd、gws.ps1）。這些 shim 會攔截你的指令，導致 Cannot find module run-gws.js 錯誤。先刪掉它們，再放你的 gws.exe：

1
2
3
rm "/c/Program Files/nodejs/gws"
rm "/c/Program Files/nodejs/gws.cmd"
rm "/c/Program Files/nodejs/gws.ps1"

驗證：

1
2
gws --version
# gws 0.22.5

認證設定：需要手動建 OAuth Client

gws 提供了 gws auth setup 自動設定，但它依賴 gcloud CLI。如果你沒裝 gcloud，它會提示你安裝。

就算裝了 gcloud 跑 auth setup，在 Step 5 建立 OAuth Client 時也會失敗——因為 Google Cloud 不允許 API 自動建立 OAuth Client ID，必須手動操作。

手動建立 OAuth 憑證

  1. 到 Google Cloud Console 選擇或建立專案

  2. 設定 OAuth 同意畫面：

    • APIs & Services → OAuth consent screen
    • User Type 選 External
    • App name 填 gws CLI
    • 填入你的 email，一路 Save and Continue

  3. 建立 OAuth Client ID：

    • APIs & Services → Credentials
    • Create Credentials → OAuth client ID
    • Application type 選 Desktop app
    • Name 填 gws CLI
    • 點 Create，記下 Client ID 和 Client Secret

  4. 設定環境變數後登入：

1
2
3
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="你的-client-id.apps.googleusercontent.com"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="你的-client-secret"
gws auth login

瀏覽器會跳出 Google 登入頁面，授權後回到終端機會看到：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "status": "success",
  "message": "Authentication successful. Encrypted credentials saved.",
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/presentations",
    "https://www.googleapis.com/auth/tasks"
  ]
}

看到 success 就以為搞定了？我也是。

最大的坑：加密憑證在 Git Bash 下失效

登入成功後，執行任何 API 呼叫：

1
gws drive files list --params '{"pageSize": 3}'

結果：

1
2
3
4
5
6
7
{
  "error": {
    "code": 401,
    "message": "Access denied. No credentials provided.",
    "reason": "authError"
  }
}

auth status 明明顯示 token_valid: true，但 API 呼叫就是 401。

問題出在 gws 用 AES-256-GCM 加密儲存憑證（credentials.enc），解密金鑰原本設計存放在 Windows Credential Manager。但在早期版本（v0.4.x），當 Credential Manager 回傳失敗或查無條目時，CLI 不會重用既有金鑰，而是每次啟動都產生新的隨機金鑰寫入 ~/.config/gws/.encryption_key——這樣 auth login 寫入時和後續 API 呼叫時用的金鑰不同，credentials.enc 就永遠解不開，導致 401。

解法一：auth export --unmasked（v0.22.5 推薦）

新版本加了 --unmasked 旗標，可以直接匯出明文 token：

1
gws auth export --unmasked > ~/.config/gws/credentials.json

然後設定環境變數（Git Bash 裡路徑用正斜線，反斜線在 bash 字串裡會被解讀）：

1
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="C:/Users/你的使用者/.config/gws/credentials.json"

解法二：Python 手動解密（v0.4.x 備用方案）

如果你卡在舊版或 auth export 仍輸出遮蔽值，可以自己解密 credentials.enc。加密金鑰存在 ~/.config/gws/.encryption_key：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import base64, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

# 讀取加密金鑰
with open('C:/Users/你的使用者/.config/gws/.encryption_key') as f:
    key = base64.b64decode(f.read().strip())

# 讀取加密憑證
with open('C:/Users/你的使用者/.config/gws/credentials.enc', 'rb') as f:
    data = f.read()

# AES-256-GCM 解密：前 12 bytes 是 nonce
nonce = data[:12]
ciphertext = data[12:]
aesgcm = AESGCM(key)
plaintext = aesgcm.decrypt(nonce, ciphertext, None)

# 寫入明文 credentials.json
creds = json.loads(plaintext)
with open('C:/Users/你的使用者/.config/gws/credentials.json', 'w') as f:
    json.dump(creds, f, indent=2)

需要先裝 cryptography 套件：pip install cryptography。

再試一次：

1
gws drive files list --params '{"pageSize": 3}'
1
2
3
4
5
6
7
8
9
10
{
  "files": [
    {
      "id": "1G8UvtYMIIR5gFAqC...",
      "kind": "drive#file",
      "mimeType": "application/vnd.google-apps.spreadsheet",
      "name": "我的試算表"
    }
  ]
}

終於正常了。

永久設定

把環境變數寫進 ~/.bashrc。路徑要用正斜線，不然 bash 會把反斜線當跳脫字元處理：

1
2
3
4
# Google Workspace CLI
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="你的-client-id.apps.googleusercontent.com"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="你的-client-secret"
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="C:/Users/你的使用者/.config/gws/credentials.json"

如果你主要用 PowerShell，改設定使用者層級環境變數：

1
2
3
4
5
[Environment]::SetEnvironmentVariable(
    "GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE",
    "C:\Users\你的使用者\.config\gws\credentials.json",
    "User"
)

基本用法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 列出 Drive 檔案
gws drive files list --params '{"pageSize": 5}'

# 列出 Gmail 郵件
gws gmail users.messages list --params '{"userId": "me", "maxResults": 5}'

# 列出行事曆
gws calendar calendarList list

# 建立 Google 試算表
gws sheets spreadsheets create --json '{"properties": {"title": "新試算表"}}'

# 預覽請求但不實際執行
gws drive files list --dry-run

AI Agent 整合（v0.8.0 後的做法）

原本 v0.4.x 到 v0.7.x 有 gws mcp -s drive,gmail,calendar 可以啟動 MCP 伺服器，v0.8.0 已移除，原因是一次暴露 200-400 個工具會讓 AI context window 爆炸，加上 MCP 工具命名格式和 Google 的 dot-notation API 名稱有衝突。

目前主流有兩條路：

1. 用社群 MCP server（conorbronsdon/gws-mcp-server）

精選 41 個高頻工具，不是把所有 API 一股腦丟進去。設定完之後 Claude Desktop 或 Claude Code 就能直接呼叫。

2. 直接讓 AI 呼叫 gws CLI

gws repo 本身附帶 100+ 個 SKILL.md 檔案，每支 API 一份，格式就是讓 LLM 讀的。把 skill 內容餵給 AI，讓它自己組 gws 指令再透過 shell 執行——不需要 MCP，直接 tool use 呼叫 bash。

兩種方式各有取捨：MCP server 抽象度高，CLI 直呼方式更彈性。

踩坑總結

坑 原因 解法
npm 安裝失敗 Windows tar 路徑解析問題 手動下載 .zip 二進位檔
npm 殘留 shim 攔截指令 失敗的安裝留下壞檔案 刪掉 gws/gws.cmd/gws.ps1
auth setup 無法建 OAuth Client Google 不允許 API 自動建立 手動到 Cloud Console 建立
登入成功但 API 401 Credential Manager 失敗時每次產生新隨機金鑰，credentials.enc 解不開 auth export --unmasked 或 Python 手解密
.bashrc 路徑設定後仍 401 bash 把反斜線當跳脫字元，路徑解析失敗 路徑改正斜線 C:/Users/...
gws mcp unknown command v0.8.0 移除 MCP 子指令 改用社群 MCP server 或直呼 CLI

gws 從 v0.4.2 到 v0.22.5，四個月跑了快 20 個 minor 版本，Windows 體驗比剛出時順很多，但認證這塊在不同環境下仍有雷，遇到 401 先試 auth export --unmasked 再說。