Markdown 版本

AI-translated from English; not yet reviewed by a fluent editor.

# 透過五項讀取檢查將 Claude Code 連接到 Google Workspace

> 依照文件設定，以限定範圍的 Drive、Sheets、Docs 和 Gmail 讀取，檢查 Claude Code 使用的 Google Workspace CLI 帳戶、OAuth 授權和權限提示。

By BIG CHANGE Editorial

Published: 2026-10-20T09:34:40.461Z
Updated: 2026-10-20T09:34:40.461Z
Canonical: https://bigchange.ai/blog/claude-code-google-workspace-cli-read-checks

![Conceptual charcoal illustration of one person studying abstract command lines on a desktop monitor, with a plain folder, grid sheet, document and sealed envelope on the table.](https://bigchange.ai/api/media/file/gws-claude-read-check-workstation-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

Claude Code 可以透過本機 shell 執行 Google Workspace CLI（`gws`）命令，並使用在 `gws` 中完成身分驗證的 Google 帳戶。獲得授權的帳戶擁有者，可以用 Drive、Sheets、Docs 和 Gmail 中各一筆無敏感內容的紀錄檢查連接。先確認帳戶和授權。本指南依據 2026 年 10 月 20 日檢查的 CLI 儲存庫文件介面編寫。BIG CHANGE 未安裝這兩個工具，也未存取任何帳戶。

## 關鍵變化

- **發生了什麼變化：** 目前的 `gws` CLI 將 Google Workspace API 方法提供為 Claude Code 可以執行的 shell 命令。一個已驗證帳戶可連接多項工作服務，但存取範圍受實際授權和代理程式的 shell 權限約束。
- **為何重要：** 讓代理程式查看指定檔案或郵件的同一連接，也可能存取 OAuth 範圍涵蓋的其他資料。帳戶擁有者可以先比較終端機和 Claude Code 傳回的少量已知結果，再決定是否委派更多工作。
- **需要留意：** 每次設定改變，都要檢查已安裝 CLI 產生的命令和工作階段實際生效的權限規則。CLI 尚未達到 1.0 版本；範圍較小的範例查詢或欄位遮罩，不會縮小整個帳戶的授權。

## 連接前的準備

使用專用且經過核准的 Google 測試帳戶，不放入敏感內容，並使用你有權設定 OAuth 的 Cloud 專案。向管理員確認是否允許這四個 API 及所要求的授權。準備一個名稱唯一的現有 Drive 檔案、一份小範圍內包含已知值的試算表、一份只有一個分頁的簡短純文字 Google Doc，以及一封無敏感內容的 Gmail 郵件。對於 Gmail，取得郵件的 RFC `Message-ID`，來源為 **Show original**。你將把這些原始內容與 CLI 結果比較。這些檢查不會建立或傳送任何內容。

在受控電腦上安裝 Claude Code。安裝 `gws`，下載來源為 [儲存庫中適用於你作業系統的發行版本](https://github.com/googleworkspace/cli/releases)，或在具備 Node.js 18 或更新版本時，使用文件記載的命令：

```bash
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --help
```

私下記錄已安裝的 CLI 和 Claude Code 版本。CLI 仍未達到 1.0 版本，命令根據 Google 的 API 探索文件產生。執行範例前，檢查已安裝版本的說明和下列方法結構。

## 1. 設定範圍受限的 OAuth 登入

在獲核准的 Cloud 專案中啟用 Drive、Sheets、Docs 和 Gmail API。設定 OAuth 對象，並建立 **Desktop app** 類型的用戶端。如果應用程式是 External 且處於測試階段，將選定帳戶加入測試使用者。將下載的用戶端 JSON 儲存到文件指定的 `~/.config/gws/client_secret.json` 位置，或使用透過 `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` 選定的獨立目錄。將該目錄放在 Claude 專案之外，僅供帳戶擁有者存取。

登入前，私下檢查是否設定了 `GOOGLE_WORKSPACE_CLI_TOKEN` 或 `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`，包括是否透過 `.env` 檔案設定。這些來源的優先順序高於已儲存的 OAuth 憑證。不要輸出其值，也不要讓 Claude Code 讀取憑證檔案。使用乾淨的環境和預期的用戶端設定。

明確要求以下四個範圍：

```bash
gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth status
```

由你本人選擇帳戶並完成同意授權。指定版本的 CLI 原始碼也會加入 `openid`、`userinfo.email` 和 `userinfo.profile` 身分範圍。私下將同意頁面與 `gws auth status` 中的帳戶、授權和權杖有效性與預期比較；缺少的狀態欄位仍屬未驗證。若帳戶不正確，或仍有非預期的更廣授權，請停止。登入選擇器中的服務選擇只會篩選選項，不會自行設定這四個唯讀範圍。

這些授權範圍比範例要求更廣。Drive 中繼資料權限可讀取可存取檔案的中繼資料；Sheets 和 Docs 唯讀權限涵蓋可存取的試算表和文件；Gmail 唯讀權限可存取信箱內容。名稱、ID、儲存格範圍、查詢和欄位遮罩限制的是每次回應，不是權杖權限。shell 工具也可能存取本機憑證，因此隱藏檔案路徑或寫一條提示指令，並不能隔離憑證。

## 2. 直接執行限定範圍的讀取

先使用 `gws schema drive.files.list` 檢查各方法，其他方法使用相應的結構名稱。如果參數與已安裝版本不同，請查看產生的 `--help`。下列命令採用 Bash 單引號語法；改用其他 shell 時，請明確調整引號。只替換測試識別碼和名稱。每次執行一個命令，私下保留實際回應或錯誤，不包含權杖或敏感內容。

尋找指定名稱的 Drive 檔案。JSON 中的 `\u0027` 會逸出 Drive 搜尋運算式內的單引號，同時保留 Bash 的引號結構：

```bash
gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'
```

將傳回的 ID 和名稱與 Drive 中的檔案比較。沒有相符結果或出現 `incompleteSearch`，都不能證明已存取到目標檔案。

使用實際試算表 ID 和分頁名稱讀取已知儲存格：

```bash
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'
```

將傳回值與試算表比較。Google 可能省略尾端空白儲存格，因此應準備非空白的已知值。

讀取簡短測試文件的第一個分頁：

```bash
gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'
```

核對 ID、標題和已知文字。這個限定回應不會檢查其他分頁、註解或完整文件結構。

對於 Gmail，使用現有郵件的 RFC `Message-ID` 搜尋，再用傳回的 Gmail ID 要求兩個標頭：

```bash
gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'
```

將傳回的 `Message-ID` 和無敏感內容的主旨與原始郵件比較。第一次呼叫傳回郵件 ID，而不是標頭。第二次要求標頭中繼資料，而非郵件內文。第一次回應為空，就無法完成第二項檢查。較窄的 Gmail 中繼資料 OAuth 範圍不允許此處使用的搜尋查詢；明確的 Gmail 唯讀授權則允許。

## 3. 透過 Claude Code 重複檢查並逐次決定權限

在你控制的專案中啟動 Claude Code，使用同一個已核准的帳戶設定。在 `/permissions` 中檢查實際生效的模式和 shell 規則。使用 Manual（也稱為 `default`）及針對實際 shell 工具的 **Ask** 規則；依組織政策處理任何較廣的允許規則或略過規則。不要為 `gws *` 或 shell 包裝程式提供全面授權。每次提出命令時，檢查完整命令，只核准你要執行的限定讀取。

以一般語言要求 Claude Code，針對相同測試目標提出上述五個命令，並且只在你做出權限決定後逐一執行。要求它回報命令輸出或錯誤，不讀取憑證、不擴大查詢、不執行寫入。接著將每個結果與直接結果及原始物件比較。專案指令可描述任務，但存取權由實際生效的工具權限和 OAuth 授權決定。

| 服務 | 兩種路徑都需要的完成證據 |
| --- | --- |
| Drive | 相同的檔案 ID 和名稱；搜尋完整。 |
| Sheets | 預期分頁、範圍及已知儲存格值。 |
| Docs | 預期 ID、標題和第一個分頁的文字。 |
| Gmail | 清單找到測試郵件；中繼資料讀取結果與其 `Message-ID` 和主旨相符。 |

在私密檢查表中記錄版本、已驗證帳戶、實際授權、目標 ID、直接結果、Claude 結果及錯誤。要求失敗、成功但為空的回應，以及已驗證物件，是三種不同結果。只有四項服務都經兩種路徑驗證，才算完成。

## 檢查失敗時

登入時出現 **Access blocked**，可能是測試帳戶未加入 OAuth 應用程式的測試使用者名單。若出現 API 或範圍錯誤，先確認已啟用的 API、選定帳戶和實際授權，再申請經核准的重新同意。清單為空時，檢查精確目標、查詢和帳戶。如果安裝版本的說明與範例不同，繼續前先使用目前的方法結構。如果 Claude Code 提議修改資料或擴大存取的命令，在權限提示處拒絕，並返回限定讀取。

CLI 儲存庫無須購買付費套件即可使用。帳戶或 Workspace 方案、Cloud 配額，以及 Claude Code 方案或 API 用量，可能產生費用。讀取的內容可能由 Claude Code 設定的供應商處理，因此只使用經核准的非敏感測試資料。CLI 明確表示，它不是 Google 官方支援的產品，並警告 1.0 之前可能有變動。BIG CHANGE 未測試效能或相容性。在任何寫入、傳送或帳戶變更之前停止。 [Claude 獨立的 Google Workspace 外掛程式](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) 透過另一種路徑，在獲得核准後編輯已開啟的檔案。

## Sources

- [Google Workspace CLI 的 README](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — 檢查的是固定提交版本的官方儲存庫，日期為 2026 年 10 月 20 日。它說明安裝、手動 OAuth 設定、動態命令、憑證優先順序、版本不穩定性，以及不受官方產品支援的提示，不能證明 BIG CHANGE 已執行成功。
- [Google Workspace CLI 命令脈絡](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — 固定提交版本的官方命令指南，說明巢狀方法、--params、結構檢查和限定欄位選擇；必須檢查實際安裝版本的說明。
- [Google Workspace CLI 身分驗證實作](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — 固定版本的驗證原始碼確認了自訂 --scopes、獨立服務選擇器行為及附加身分範圍。檢查原始碼不能顯示讀者實際獲得的授權。
- [Google Workspace API 啟用指南](https://developers.google.com/workspace/guides/enable-apis) — Google 關於在 Cloud 專案啟用 API 的說明；存取仍受專案和管理員政策約束。
- [Drive files.list 參考](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — 確認了用於限定中繼資料搜尋的 Drive q、pageSize 和回應欄位。限定要求不會縮小 OAuth 權限。
- [Sheets spreadsheets.values.get 參考](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — 確認透過試算表 ID 和 A1 範圍讀取及其回應結構；尾端空白儲存格可能被省略。
- [Docs documents.get 參考](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — 確認文件讀取方式，以及 includeTabsContent 為 false 時只限第一個分頁的限制。範例使用只有一個分頁的純文字測試文件。
- [Gmail messages.list 和 messages.get 參考](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — list 參考說明依郵件 ID 搜尋和只含 ID 的清單結果；gmail.metadata 不支援 q。配套 get 參考為 https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get，說明 METADATA 格式下的 metadataHeaders。
- [Claude Code 權限](https://code.claude.com/docs/en/permissions) — Anthropic 關於 Manual/default 模式、Ask 規則、實際工具權限和 shell 核准提示的目前參考。它不能證明某個讀者工作階段具有特定規則。