快速摘要： Google Workspace 团队在 GitHub 上开源了命令行工具 gws（Google Workspace CLI），用 Rust 编写，通过 npm 分发。它最大的亮点在于「动态构建」机制——不预装任何静态命令列表，而是在运行时实时读取 Google Discovery Service 来生成所有可用命令。 这意味着当 Google 新增任何 API 端点时，gws 无需更新即可自动支持。更关键的是，gws 内置了 MCP（Model Context Protocol）服务器和 100 多个 Agent Skills，所有输出均为结构化 JSON，天然适配 AI Agent 调用。往下看，莫潇羽@无忆研习社 将为你详细拆解这个项目的技术原理、安装配置流程、实战操作和排错指南。
一、gws 是什么？为什么值得关注？
如果你是一个经常和 Google Workspace（Gmail、Drive、Calendar、Sheets、Docs 等）打交道的开发者或者运维人员，你一定深有体会：想要用程序化的方式去操作这些服务，是一件多么痛苦的事情。你需要在 Google Cloud Console 里创建项目、配置 OAuth 2.0 同意屏幕、处理 Token 刷新、手写 curl 调用 REST API、还要应对复杂的分页逻辑……整个过程繁琐到让人崩溃。
gws 的出现，就是为了从根本上解决这个问题。它提供了一种统一的、简洁的方式来操作所有 Google Workspace 服务，而且不仅仅是给人类用的——更重要的是，它为 AI 智能体操控这些服务提供了一个标准化的接口。
gws 的全称是 Google Workspace CLI，由 Google Workspace 团队在 GitHub 上以开源形式发布，项目地址为 https://github.com/googleworkspace/cli。它使用 Rust 语言编写，通过 npm 包的形式分发预构建的原生二进制文件，在 macOS、Linux、Windows 上都可以直接运行，不需要你本地安装 Rust 工具链。
gws 覆盖的服务范围非常广泛，基本上你能想到的 Google Workspace 服务它都支持。以下是目前已经确认支持的主要服务：
- Google Drive：文件和文件夹管理、共享云端硬盘操作
- Gmail：邮件的发送、阅读、搜索和管理
- Google Calendar：日历事件的创建、查询、修改和删除
- Google Sheets：电子表格的创建和数据读写
- Google Docs：文档的读写操作
- Google Slides：演示文稿的读写操作
- Google Chat：聊天空间和消息管理
- Google Admin SDK：用户、群组和设备管理
- Google Tasks：任务列表和任务管理
- Google People：联系人和个人资料管理
- Google Vault：电子发现保留和导出管理
- Google Groups Settings：Google 群组设置管理
- Google Workspace Reseller：Workspace 订阅管理
- Google Workspace License Manager：产品许可证管理
而且，由于 gws 的动态构建机制（后面会详细解释），当 Google 在未来添加新的 Workspace 服务 API 时，gws 可以自动支持，甚至不需要用户更新工具本身。
这个项目在开源社区引起了巨大反响。发布后短短几天内，就在 GitHub 上积累了数千颗 Star，在 Hacker News 上也引发了大量讨论。开发者社区之所以如此兴奋，并不仅仅因为它是「又一个 CLI 工具」，而是因为它代表了一种全新的思路——让 AI Agent 能够原生地、无缝地操作整个 Google Workspace 生态。
需要注意的是，虽然 gws 托管在 googleworkspace 这个 GitHub 组织下，并且有 Google DevRel 团队的参与，但项目自身包含了一个免责声明：「This is not an officially supported Google product」（这不是 Google 官方支持的产品）。同时，项目仍在活跃开发中，官方明确表示在迈向 v1.0 的过程中可能会有破坏性变更。所以在使用时，莫潇羽@无忆研习社 建议你保持关注项目的更新日志，及时跟进版本变化。
从社区反馈来看，开发者们对 gws 的评价总体是积极且务实的。许多人认为 gws 在代码生成工具和 AI 编程助手的场景中具有极高的实用价值——因为这些工具需要频繁地与 Google Workspace 交互，而 gws 的 MCP 支持让这种交互变得几乎零成本。也有不少经验丰富的开发者指出了当前认证流程过于繁琐的问题，并积极在 GitHub 上提交改进方案。项目目前有大量活跃的 Pull Request，涵盖了认证流程优化、OAuth 作用域选择改进、错误处理增强等方面，社区的参与度非常高。
从更长远的角度来看，gws 的出现也预示着一个趋势：传统的 SaaS 产品正在被重新定义为「AI Agent 可调用的服务」。过去我们通过网页界面或移动应用来使用这些服务，未来我们可能越来越多地通过 AI Agent 来使用它们。gws 就是这个转变过程中的一个重要基础设施组件，它让 Google Workspace 从一个「面向人类的产品」变成了一个「同时面向人类和 AI Agent 的平台」。
二、核心技术原理：动态构建机制深度解析
gws 最令人眼前一亮的技术设计，就是它的「动态构建」（Dynamic Discovery）机制。要理解这个机制为什么巧妙，我们需要先了解传统 CLI 工具是怎么做的，再看 gws 做了什么不同的事情。
2.1 传统 CLI 的痛点
传统的命令行工具，无论是 Google 自家的 gcloud CLI，还是社区维护的 GAM（Google Apps Manager），它们的命令列表都是在代码中硬编码的。也就是说，开发者需要手动为每一个 API 端点编写对应的命令处理代码。当 Google Workspace 新增了一个 API 方法，或者修改了某个参数的名称，这些工具就需要发布新版本来跟进。
这种模式带来了两个严重的问题。其一是「同步滞后」——API 已经更新了，但工具还没跟上，用户要么等新版本，要么自己去手写 curl。其二是「维护负担」——Google Workspace 涵盖的服务非常多（Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin、Vault、Tasks、People、Slides 等等），每个服务又有大量的资源和方法，全部手动维护的工作量是巨大的。
2.2 Google Discovery Service——gws 的核心依赖
gws 的动态构建机制，依赖于 Google 提供的一项基础设施服务——Google APIs Discovery Service。
Google APIs Discovery Service 是 Google 在 2011 年就推出的一项服务，它为 Google 旗下所有的 API 提供了机器可读的元数据描述。具体来说，它提供了两类核心资源：
第一类是 APIs Directory（API 目录），你可以通过 GET https://discovery.googleapis.com/discovery/v1/apis 这个端点获取到 Google 所有支持的 API 列表，包括每个 API 的名称、版本、简要描述和文档链接。
第二类是 Discovery Document（发现文档），每一个 API 的每一个版本都有一份独立的 Discovery Document。这份 JSON 格式的文档详细描述了该 API 的所有信息：有哪些资源、每个资源有哪些方法、每个方法需要什么参数（参数名、类型、是否必填、默认值等）、返回什么数据结构、支持哪些 OAuth 作用域，甚至还包括内联的文档说明。
举个例子，你可以通过以下 URL 获取 Google Drive API v3 的 Discovery Document：
GET https://www.googleapis.com/discovery/v1/apis/drive/v3/rest这份 JSON 文档的体量通常非常大（Drive API 的 Discovery Document 有数千行），它的顶层结构大致如下：
{
"kind": "discovery#restDescription",
"discoveryVersion": "v1",
"id": "drive:v3",
"name": "drive",
"version": "v3",
"title": "Google Drive API",
"description": "...",
"protocol": "rest",
"baseUrl": "https://www.googleapis.com/drive/v3/",
"auth": {
"oauth2": {
"scopes": { ... }
}
},
"schemas": { ... },
"resources": {
"files": {
"methods": {
"list": { ... },
"get": { ... },
"create": { ... },
"delete": { ... }
}
},
"permissions": { ... },
"comments": { ... }
}
}其中 resources 部分定义了 API 的所有资源（files、permissions、comments 等），每个资源下面的 methods 定义了可以对该资源执行的操作（list、get、create、delete 等），每个方法又包含了详细的参数定义（参数名、数据类型、是否必填、有效值范围等）。schemas 部分则用 JSON Schema 格式描述了请求体和响应体的数据结构。auth 部分列出了该 API 支持的所有 OAuth 作用域。
这份文档不仅仅是用来看的——Google 自家的 JavaScript 客户端库、Python 客户端库等，其实也是基于 Discovery Document 来自动生成 API 调用方法的。比如 Python 的 google-api-python-client 库中的 build() 函数，底层就是在读取 Discovery Document 并动态构建 API 调用对象。gws 的思路与此一脉相承，只不过它把这个「动态构建」的能力从 SDK 层面提升到了 CLI 层面。
2.3 gws 的两阶段解析策略
理解了 Discovery Service 之后，gws 的工作原理就非常清晰了。gws 采用了一种「两阶段解析」（Two-Phase Parsing）策略：
第一阶段：识别目标服务。 当你输入一条命令（比如 gws drive files list），gws 首先读取命令行参数中的第一个词（在这个例子中是 drive），以此确定你要操作的是哪个 Google Workspace 服务。
第二阶段：动态构建命令树。 确定了目标服务后，gws 会去获取该服务对应的 Discovery Document（这份文档会被缓存 24 小时，避免每次都发网络请求）。然后，gws 使用 Rust 生态中著名的命令行解析库 clap，根据 Discovery Document 中描述的资源和方法，动态构建出一棵完整的命令树。最后，gws 用这棵动态生成的命令树来解析你输入的剩余参数，完成认证，并执行对应的 HTTP 请求。
用一段伪代码来表示这个流程：
1. 读取 argv[1] → 识别服务名称（如 "drive"）
2. 获取该服务的 Discovery Document（24小时缓存）
3. 解析 Discovery Document → 动态生成 clap::Command 命令树
4. 用生成的命令树解析剩余参数
5. 执行 OAuth 认证
6. 构造并发送 HTTP 请求
7. 以 JSON 格式输出结果这种设计的精妙之处在于：gws 的代码中完全不包含任何特定 API 的硬编码逻辑。项目的 AGENTS.md 文件中明确写道：「This project does NOT use generated Rust crates (e.g., google-drive3) for API interaction.」——它不使用预生成的 Rust API 客户端库。当你需要添加一个新的服务支持时，只需要在 src/services.rs 中注册该服务，并在 src/discovery.rs 中确认其 Discovery URL 模式即可，不需要为每个 API 编写专门的代码。
这意味着什么？意味着当 Google 明天给 Workspace 加了一个全新的 API 端点，gws 用户什么都不需要做——下次运行命令时，gws 会自动拉取到包含新端点的 Discovery Document，新命令就直接可用了。
2.4 所有输出均为结构化 JSON
gws 的另一个重要设计决策是：所有的输出——包括成功的响应、错误信息、下载元数据——全部以结构化的 JSON 格式返回。
这个设计看似简单，却对 AI Agent 的集成至关重要。因为大语言模型在处理结构化数据（尤其是 JSON）时，远比处理自由格式的文本输出要准确和可靠。当 AI Agent 调用 gws 命令时，它可以直接解析 JSON 输出，提取所需信息，而不需要去猜测和解析各种格式不一致的文本。
三、为什么说 gws 是 AI Agent 时代的基础设施？
gws 之所以在开发者社区引起如此大的关注，最根本的原因不是它「让人类能在终端里操作 Google Workspace」——这件事其实用 curl 也能做到。真正让人兴奋的是：gws 为 AI Agent 直接操控 Google Workspace 铺平了道路。
3.1 MCP 协议：AI Agent 的「USB-C 接口」
要理解 gws 在 AI Agent 生态中的位置，必须先了解 MCP（Model Context Protocol，模型上下文协议）。
MCP 是 Anthropic（Claude 的开发公司）在 2024 年 11 月推出的一项开放标准协议。它的目标是标准化 AI 应用程序与外部系统之间的连接方式。在 MCP 出现之前，如果你想让一个 AI 助手去读取 Google Drive 中的文件、在 Slack 中发消息、或者查询数据库，你需要为每一个数据源编写专门的连接器代码。这就形成了一个 N×M 的集成难题——N 个 AI 应用要对接 M 个外部工具，需要 N×M 个定制化集成。
MCP 的做法类似于 USB-C 标准。就像 USB-C 让任何设备都能通过同一种接口连接各种外设一样，MCP 让任何 AI 模型都能通过同一种协议连接各种外部工具和数据源。
2025 年 3 月，OpenAI 正式宣布采纳 MCP 协议，这是一个标志性事件——它意味着两大 AI 巨头在工具调用标准上达成了共识。此后不久，Google DeepMind 也加入了支持阵营。2025 年 12 月，Anthropic 更进一步，将 MCP 捐赠给了 Linux 基金会旗下新成立的 Agentic AI Foundation（AAIF），联合创始成员包括 Anthropic、Block 和 OpenAI，得到了 Microsoft、AWS、Cloudflare 等公司的支持。
MCP 的技术实现上，它重用了语言服务器协议（LSP，即 VS Code 等编辑器用来实现代码补全、跳转定义等功能的协议）的消息流思路，通信层基于 JSON-RPC 2.0。MCP 的架构分为三个角色：Host（宿主，通常是 AI 应用本身）、Client（客户端，负责管理与服务器的连接）和 Server（服务器，负责暴露具体的工具和数据源）。在 gws 的场景中，Claude Desktop 或 Gemini CLI 是 Host，它们内置的 MCP 客户端会与 gws 启动的 MCP Server 进行通信。
到 2026 年初，MCP 已经从一个实验性概念发展为生产就绪的协议标准，被广泛应用于各种 AI Agent 框架和工具中。可以说，MCP 正在成为 AI 时代的「USB-C 接口」，而 gws 正是 Google Workspace 生态接入这个标准接口的关键基础设施。
3.2 gws 的 MCP 服务器功能
gws 内置了原生的 MCP 服务器支持。通过 gws mcp 命令，你可以启动一个通过标准输入输出（stdio）通信的 MCP 服务器，将 Google Workspace API 暴露为结构化的工具（tools）。任何兼容 MCP 协议的客户端——包括 Claude Desktop、Gemini CLI、VS Code 等——都可以直接调用这些工具。
启动 MCP 服务器的基本命令如下：
# 只暴露 Drive 相关工具
gws mcp -s drive
# 同时暴露多个服务的工具
gws mcp -s drive,gmail,calendar
# 暴露所有服务（工具数量会很多）
gws mcp -s all每个服务大约会添加 10 到 80 个工具。实际使用时，建议只暴露你真正需要的服务，以避免超过 MCP 客户端通常允许的工具数量上限（一般在 50 到 100 个之间）。
如果你使用的是 Claude Desktop 或者 Gemini CLI，可以在 MCP 客户端的配置文件中这样配置：
{
"mcpServers": {
"gws": {
"command": "gws",
"args": ["mcp", "-s", "drive,gmail,calendar"]
}
}
}配置完成后，你就可以在 AI 助手中用自然语言让它帮你操作 Google Workspace 了。比如你可以说「帮我查看最近收到的 5 封邮件」或者「在下周三下午两点创建一个会议邀请」，AI 助手会通过 MCP 协议调用 gws 来执行这些操作。
3.3 100+ Agent Skills：AI 的「操作手册」
除了 MCP 服务器，gws 仓库还附带了 100 多个 Agent Skills 文件（SKILL.md）。这些文件本质上是为大语言模型编写的「操作手册」——它们用自然语言描述了如何使用 gws 命令来完成各种具体的工作流。
这些 Skills 分为几个层次。最基础的是每个 API 服务对应的 Skill 文件，比如 gws-drive/SKILL.md、gws-gmail/SKILL.md 等，它们描述了对应服务的基本操作方法。在此之上，还有面向具体工作流的高级 Skill，比如「创建 Gmail 过滤器来自动分类邮件」、「查找 Google Drive 中占用大量存储空间的文件」、「创建 Google Docs 事后总结并在 Calendar 上安排回顾会议」等。
项目文档中列出了 50 个精选的工作流示例（recipes），涵盖了 Gmail、Drive、Docs、Calendar 和 Sheets 的常见操作场景。以下是莫潇羽@无忆研习社 为你整理的一些典型示例：
Gmail 相关：
- 创建 Gmail 过滤器来自动标记、加星或分类收到的邮件
- 发送、阅读和管理邮件
Drive 相关：
- 列出并下载指定文件夹中的所有文件
- 识别占用大量存储配额的大文件
- 创建共享云端硬盘并添加成员
- 在用户之间转移文件所有权
Calendar 相关：
- 创建带有与会者的周期性日历事件
- 查询多个用户的空闲/忙碌状态以找到合适的会议时间
- 删除日历事件并通过 Gmail 发送取消通知
Sheets 相关：
- 向 Google Sheets 销售跟踪表追加状态更新
- 检索和查看 Google Forms 的回复
跨服务协作：
- 创建 Google Docs 事后总结，安排 Calendar 回顾会议，并通过 Chat 发送通知
- 设置 Google Tasks 任务列表，查找逾期任务
你可以使用以下命令一次性安装所有 Skills：
npx skills add https://github.com/googleworkspace/cli或者只选择安装你需要的特定服务的 Skills：
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail3.4 内置 Model Armor 防护
当 AI Agent 自动处理 Google Workspace 中的数据时，一个不容忽视的问题是——这些数据中可能包含恶意的提示注入（Prompt Injection）内容。比如，一封邮件的正文中可能故意嵌入了误导性的指令，试图让 AI Agent 执行非预期的操作。
gws 集成了 Google Cloud 的 Model Armor 功能，可以在 API 响应送达 AI Agent 之前，扫描其中是否包含提示注入风险。使用方法是在命令中添加 --sanitize 参数：
gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"你还可以通过环境变量来设置默认的防护模板和模式：
export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="warn" # 或者 "block"warn 模式会在检测到风险时发出警告但仍然返回数据，block 模式则会直接阻止包含风险内容的响应。
四、安装与环境准备：手把手教你从零开始
接下来，莫潇羽@无忆研习社 将带你一步步完成 gws 的安装和配置。这部分内容会尽可能详细，即使你是第一次接触 Google Cloud 的 OAuth 配置，也能跟着操作。
4.1 前置要求
在安装 gws 之前，你需要确保以下条件已经满足：
- Node.js 18 或更高版本：如果你选择通过 npm 安装 gws（这也是推荐的方式），需要 Node.js 环境。如果你的机器上还没有 Node.js，可以从
https://nodejs.org下载安装。你可以通过node --version命令来检查当前版本。 - 一个 Google Cloud 项目：gws 需要使用 OAuth 凭据来代表你访问 Google Workspace API，而 OAuth 凭据必须关联到一个 Google Cloud 项目。如果你还没有，可以通过 Google Cloud Console（
https://console.cloud.google.com）创建，也可以通过 gcloud CLI 创建，或者直接使用 gws 自带的gws auth setup命令来引导创建。 - 一个有权访问 Google Workspace 的 Google 账号：这通常就是你日常使用的 Gmail 账号或者企业 Google Workspace 账号。
4.2 安装 gws
gws 提供了多种安装方式，你可以根据自己的偏好和环境来选择。
方式一：通过 npm 全局安装（推荐）
这是最简单的方式。npm 包会自动为你的操作系统和 CPU 架构捆绑预构建的原生二进制文件，不需要安装 Rust 工具链：
npm install -g @googleworkspace/cli安装完成后，你就可以在终端中直接使用 gws 命令了。
方式二：下载预构建的二进制文件
如果你不想安装 Node.js，可以直接从 GitHub Releases 页面（https://github.com/googleworkspace/cli/releases）下载适合你操作系统的预构建二进制文件。下载后将其放到系统 PATH 中即可。
方式三：通过 Shell 脚本一键安装
在 macOS 或 Linux 上，你可以使用官方提供的安装脚本：
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/googleworkspace/cli/releases/download/v0.7.0/gws-installer.sh | sh在 Windows 上使用 PowerShell：
powershell -ExecutionPolicy Bypass -c "irm https://github.com/googleworkspace/cli/releases/download/v0.7.0/gws-installer.ps1 | iex"方式四：从源码构建
如果你的机器上已经安装了 Rust 工具链，也可以直接从源码构建：
cargo install --git https://github.com/googleworkspace/cli --locked方式五：使用 Nix
项目还提供了 Nix flake 支持：
nix run github:googleworkspace/cli4.3 配置认证——最关键的一步
安装完成后，最重要的一步就是配置认证。这也是许多开发者反馈最容易遇到问题的环节，所以这里会讲得特别详细。
方式 A：使用 gws auth setup 自动配置（需要 gcloud CLI）
如果你的机器上已经安装了 gcloud CLI 并且已经登录，这是最快的方式：
# 第一步：引导你完成 Google Cloud 项目配置（创建项目、启用 API、设置 OAuth）
gws auth setup
# 第二步：完成 OAuth 登录
gws auth logingws auth setup 会自动帮你完成以下操作：创建或选择一个 Google Cloud 项目、启用所需的 Workspace API、配置 OAuth 同意屏幕、创建 OAuth 客户端凭据。
方式 B：手动配置 OAuth（不需要 gcloud CLI）
如果你没有安装 gcloud CLI，或者想要更精细的控制，可以按照以下步骤手动完成配置。莫潇羽@无忆研习社 帮你梳理了完整的操作流程。
第 1 步：创建或选择 Google Cloud 项目
打开 Google Cloud Console（https://console.cloud.google.com），如果还没有项目，先创建一个新项目。记下项目的 ID。
第 2 步：配置 OAuth 同意屏幕
在 Google Cloud Console 中，导航到「API 和服务」→「OAuth 同意屏幕」（URL 格式为 https://console.cloud.google.com/apis/credentials/consent?project=你的项目ID）。
在这个页面中：
- 应用类型选择「External」（外部），即使你只打算自己使用也需要选这个
- 填写应用名称（随便起一个，比如 "gws-cli"）
- 填写用户支持电子邮件（你的 Google 邮箱）
- 其他字段可以留空
第 3 步：添加测试用户（极其重要）
这一步是很多人容易遗漏的，也是导致登录失败最常见的原因。
在 OAuth 同意屏幕页面中，找到「测试用户」部分，点击「添加用户」，然后输入你自己的 Google 账号邮箱。如果不做这一步，后续登录时会遇到「访问被阻止」的错误。
第 4 步：创建 OAuth 客户端凭据
导航到「API 和服务」→「凭据」（https://console.cloud.google.com/apis/credentials?project=你的项目ID）。
点击「创建凭据」→「OAuth 客户端 ID」。应用类型必须选择「桌面应用（Desktop app）」。这一点很重要，如果选了其他类型（比如 Web 应用），后续会遇到 redirect_uri_mismatch 错误。
创建完成后，点击「下载 JSON」按钮，将下载的文件保存到 ~/.config/gws/client_secret.json。
第 5 步：启用所需的 API
你需要在 Google Cloud Console 中为你的项目启用你要使用的 Google Workspace API。比如，如果你想使用 Gmail，就需要启用 Gmail API；想使用 Drive，就需要启用 Drive API。
你可以在「API 和服务」→「库」中搜索并启用这些 API。当然，如果你有 gcloud CLI，也可以用 gws auth setup 来自动化这一步。
第 6 步：完成 OAuth 登录
以上配置完成后，运行：
gws auth logingws 会在你的默认浏览器中打开一个 Google 登录页面。选择你在第 3 步中添加的测试用户账号，然后按照提示授权。
你可能会看到一个警告页面，提示「Google 尚未验证此应用」。这是正常的——因为你的应用处于测试模式。点击「高级」→「前往 xxx（不安全）」继续即可。这对个人使用是完全没问题的，只有当你要将应用发布给其他用户时才需要通过 Google 的验证审核。
如果登录页面上出现了作用域（Scopes）复选框，建议你根据实际需要选择，或者全选后继续。需要注意的是，测试模式的应用最多只能请求约 25 个 OAuth 作用域。如果你选择的作用域太多，可能会遇到问题。这时可以使用以下命令只请求特定服务的作用域：
gws auth login --scopes drive,gmail,calendar登录成功后，凭据会使用 AES-256-GCM 加密存储在你操作系统的密钥链（Keyring）中，存储路径为 ~/.config/gws/。
4.4 其他认证方式
除了上面介绍的交互式 OAuth 认证，gws 还支持多种其他认证方式，以适应不同的使用场景。
无头/CI 环境：
在服务器或 CI/CD 环境中，你没有浏览器可以完成 OAuth 授权。解决方法是先在有浏览器的本地机器上完成认证，然后导出凭据文件：
# 在本地机器上
gws auth export --unmasked > credentials.json将导出的 credentials.json 文件传输到服务器上，然后通过环境变量指定凭据路径：
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list # 直接可用服务账号（Service Account）：
如果你需要进行服务器到服务器的通信（Server-to-Server），可以使用 Google Cloud 的服务账号。将服务账号的密钥文件路径设置为环境变量即可：
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files listgws 还支持通过 GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER 环境变量实现 Domain-Wide Delegation（域范围委派），即用服务账号代表域内的某个用户执行操作。
预获取的访问令牌：
如果你的环境中已经有其他工具（比如 gcloud）能够生成访问令牌，可以直接将令牌传给 gws：
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list4.5 环境变量一览
gws 支持通过环境变量来配置各种行为，这些环境变量也可以写在项目根目录的 .env 文件中。以下是主要的环境变量：
|
环境变量 |
说明 |
|
|
OAuth 客户端 ID（可替代 client_secret.json） |
|
|
OAuth 客户端密钥 |
|
|
覆盖配置目录（默认 ~/.config/gws） |
|
|
OAuth 凭据 JSON 文件路径 |
|
|
预获取的访问令牌 |
|
|
多账号使用时的默认账号邮箱 |
|
|
默认的 Model Armor 模板 |
|
|
warn（默认）或 block |
|
|
GCP 项目 ID 回退值 |
五、实战操作：从基础到进阶
认证配置完成后，让我们来看看 gws 的实际使用。莫潇羽@无忆研习社 将从最基本的操作开始，逐步深入到高级功能。
5.1 第一条命令：验证安装
安装和认证都完成后，先用一条简单的命令来验证一切正常：
gws drive files list --params '{"pageSize": 5}'这条命令会列出你 Google Drive 中最近的 5 个文件，输出是 JSON 格式。如果你能看到 JSON 输出中包含了文件信息，说明安装和认证都没有问题。
5.2 理解 gws 的命令结构模式
在深入具体操作之前，先理解 gws 的命令结构模式会让后面的学习事半功倍。gws 的命令遵循一个统一的模式：
gws <服务名> <资源名> <方法名> [--params 'JSON'] [--json 'JSON'] [其他标志]这个结构直接对应了 Google Workspace REST API 的层级关系。以 gws drive files list 为例：
drive是服务名，对应 Google Drive APIfiles是资源名，对应 Drive API 下的 files 资源list是方法名，对应 files 资源的 list 方法
--params 用于传递 URL 路径参数和查询参数（对应 REST API 中 URL 里的参数），--json 用于传递请求体（对应 REST API 中 POST/PUT/PATCH 请求的 Body）。
了解了这个模式之后，即使 gws 没有提供详尽的命令手册，你也可以通过 Google Workspace 的 REST API 文档来推断 gws 的命令用法。比如你在 Google 的文档中看到一个 API 端点是 POST /gmail/v1/users/{userId}/messages/send，你就知道对应的 gws 命令应该是 gws gmail users messages send --params '{"userId": "me"}' --json '{...}'。
5.3 查看帮助和 API Schema
gws 的一大优势是每个资源和方法都有完整的帮助文档，这些文档是从 Discovery Document 中动态生成的。
查看某个服务的所有可用资源和方法：
gws gmail --help
gws drive --help
gws calendar --help查看某个具体方法的请求参数和响应结构：
gws schema drive.files.list
gws schema gmail.users.messages.getgws schema 命令非常有用——它会告诉你某个方法需要哪些参数、参数的类型、是否必填、以及返回的 JSON 结构是什么样的。在你不确定怎么构造请求时，先用 gws schema 看一下是个好习惯。
5.4 预览请求（Dry Run）
在执行实际操作之前，你可以使用 --dry-run 参数来预览 gws 会发送什么样的 HTTP 请求，而不实际执行：
gws drive files list --params '{"pageSize": 5}' --dry-run这会输出 gws 即将发送的 HTTP 方法、URL、Headers 和 Body，但不会真正发出请求。这在调试和学习阶段非常有用。
5.5 Gmail 操作示例
列出收件箱中最近的邮件：
gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'读取特定邮件的内容：
gws gmail users messages get --params '{"userId": "me", "id": "邮件ID"}'其中「邮件ID」可以从上一步的列表结果中获取。
发送一封邮件：
发送邮件稍微复杂一些，因为 Gmail API 要求邮件内容使用 Base64 编码的 RFC 2822 格式。你需要先构造原始邮件，然后进行 Base64URL 编码，再通过 gws 发送。
5.6 Google Drive 操作示例
列出最近的 10 个文件：
gws drive files list --params '{"pageSize": 10}'搜索特定名称的文件：
gws drive files list --params '{"q": "name contains '\''报告'\''", "pageSize": 5}'上传文件到 Drive（多部分上传）：
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf这是 gws 的一个高级功能——多部分上传。它允许你同时指定文件的元数据（通过 --json）和文件内容（通过 --upload），一条命令就能完成文件上传。
5.7 Google Calendar 操作示例
列出即将到来的事件：
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10, "orderBy": "startTime", "singleEvents": true, "timeMin": "2026-03-06T00:00:00Z"}'创建一个新的日历事件：
gws calendar events insert \
--params '{"calendarId": "primary"}' \
--json '{
"summary": "项目评审会议",
"start": {"dateTime": "2026-03-10T14:00:00+08:00"},
"end": {"dateTime": "2026-03-10T15:00:00+08:00"},
"attendees": [{"email": "colleague@example.com"}]
}'5.8 Google Sheets 操作示例
创建一个新的电子表格：
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'读取单元格数据：
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "电子表格ID", "range": "Sheet1!A1:C10"}'这里有一个非常重要的 Shell 转义注意事项：Sheets 的范围表达式使用 ! 符号（比如 Sheet1!A1:C10），而在 Bash 中，! 会被解释为历史命令展开。所以你一定要用单引号来包裹包含 ! 的值，避免 Shell 进行意外的展开操作。
追加数据行：
gws sheets spreadsheets values append \
--params '{"spreadsheetId": "电子表格ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["姓名", "分数"], ["Alice", 95], ["Bob", 87]]}'5.9 Google Chat 操作示例
发送一条消息到 Chat 空间（预览模式）：
gws chat spaces messages create \
--params '{"parent": "spaces/xyz"}' \
--json '{"text": "部署完成。"}' \
--dry-run5.10 分页控制
当你要获取的数据量很大时（比如列出 Drive 中的所有文件），gws 提供了灵活的分页控制功能：
# 自动分页，每页一行 JSON（NDJSON 格式）
gws drive files list --params '{"pageSize": 100}' --page-all
# 最多获取 N 页
gws drive files list --params '{"pageSize": 100}' --page-limit 5
# 设置页面之间的延迟（默认 100 毫秒）
gws drive files list --params '{"pageSize": 100}' --page-all --page-delay 200--page-all 特别有用——它会自动处理 API 返回的分页游标（pageToken），持续获取数据直到所有结果都被取回。输出格式是 NDJSON（Newline Delimited JSON），即每一页的 JSON 结果占一行，非常方便用管道传给 jq 等工具进行进一步处理：
# 列出所有文件名
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'六、实战工作流：将多个 gws 命令串联起来
在实际工作中，真正有价值的往往不是单条命令，而是将多个命令串联起来组成完整的自动化工作流。莫潇羽@无忆研习社 在这里展示几个实用的工作流示例。
6.1 工作流示例：自动化周报生成
假设你每周五需要整理本周收到的重要邮件、新增的 Drive 文件和已完成的日历事件，汇总成一份周报。你可以编写一个 Shell 脚本来自动化这个流程：
#!/bin/bash
# weekly-report.sh - 自动化周报数据收集
echo "===== 本周重要邮件 ====="
gws gmail users messages list \
--params '{"userId": "me", "q": "is:important after:2026/03/01 before:2026/03/07", "maxResults": 20}' \
| jq -r '.messages[]?.id'
echo "===== 本周新增 Drive 文件 ====="
gws drive files list \
--params '{"pageSize": 20, "orderBy": "createdTime desc", "q": "createdTime > '\''2026-03-01T00:00:00'\''"}' \
| jq -r '.files[]? | "\(.name) - \(.createdTime)"'
echo "===== 本周日历事件 ====="
gws calendar events list \
--params '{"calendarId": "primary", "timeMin": "2026-03-01T00:00:00Z", "timeMax": "2026-03-07T23:59:59Z", "singleEvents": true, "orderBy": "startTime"}' \
| jq -r '.items[]? | "\(.su
