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 批准提示的当前参考。它不能证明某个读者会话具有特定规则。