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，下载来源是 仓库中适用于你的操作系统的发布版本，或者在具备 Node.js 18 或更高版本时使用文档命令：

Terminal
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 读取凭据文件。使用干净的环境和预期客户端配置。

明确请求以下四个范围：

Terminal
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 的引号结构：

Terminal
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 和标签页名称读取已知单元格：

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

将返回值与电子表格比较。Google 可能省略末尾空单元格，因此应准备非空的已知值。

读取简短测试文档的第一个标签页：

Terminal
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 请求两个标头：

Terminal
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 插件 通过另一条路径，在获得批准后编辑已打开的文件。