Google 开源 gws！一天暴涨 10K+ Star，把整个 Google Workspace 搬进终端。

如果说最近几个月，开源社区的极客们在疯狂地给 AI Agent 造“手脚”；那么如今，真正的行业巨头 Google 终于下场了。

它没有发什么花哨的 Chatbot，而是极其硬核地在 GitHub 上开源了一个命令行工具——gws (Google Workspace CLI)。

仅仅一天时间，就狂揽 10K+ Star。

现在已经有 12.5K 标星了。

在开发者眼里，这绝对是一个“核武器”级别的存在。为什么？

因为过去，如果你想让你的 AI 助手（比如 Claude Code 或 OpenClaw）去读一下你的 Gmail 邮件，或者在 Google Calendar 里建个日程，你会被 Google 云控制台里那极其变态的 OAuth 2.0 鉴权、Token 刷新、API 翻页逻辑折磨到怀疑人生。

而现在，Google 自己把这层窗户纸捅破了。

gws 不仅仅是一个让你在终端里发邮件的 CLI 工具，它是一个原生的、全副武装的 AI 代理接口。

它直接宣布：整个 Google Workspace 生态，现在全面向 AI Agent 敞开大门。

什么是 gws？

gws 是 Google Workspace 团队开源的一个命令行工具，它的全称是 "Google Workspace CLI"。

这个工具最大的特点就是「动态构建」——它不会预装一个静态的命令列表，而是在运行时从 Google 的 Discovery Service 读取 API 信息，实时构建整个命令界面。

当 Google Workspace 添加新的 API 端点或者方法时，gws 会自动支持，你甚至不需要更新工具本身。这种设计真的太聪明了，完全避免了工具和 API 不同步的问题。

而且 gws 不仅是给人用的，更是为 AI 代理设计的。所有的输出都是结构化的 JSON 格式，配合内置的 100+ 个 Agent Skills，你的 LLM 可以直接管理整个 Workspace，完全不需要自定义工具。

核心亮点

1、一站式操作整个 Google Workspace 生态

gws 支持的服务多得让人眼花缭乱：Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin……基本上你能想到的 Google Workspace 服务，它都支持。

而且每个服务的 API 都被完整地映射成了命令行操作。

2、为人类设计，也为 AI 代理设计

gws 的设计理念很有意思，它同时考虑了人类用户和 AI 代理的需求。

对于人类用户来说，它提供了：

• • --help：每个资源都有完整的帮助文档
• • --dry-run：可以预览请求而不实际执行
• • auto-pagination：自动处理分页，不需要你手动处理

对于 AI 代理来说，它提供了：

• • 结构化的 JSON 输出：所有响应都是 JSON 格式，AI 可以直接解析
• • 100+ Agent Skills：内置了大量的技能文件，涵盖常见工作流
• • MCP 服务器支持：可以直接集成到 Claude Desktop、Gemini CLI 等客户端

3、灵活的认证方式

gws 支持多种认证工作流，可以在你的笔记本、CI 环境和服务器上都能正常工作：

• • 交互式认证（本地桌面）：凭据会用 AES-256-GCM 加密存储在系统钥匙串中
• • 无头/CI 环境：可以在有浏览器的机器上完成认证，然后导出凭据
• • 服务账号：直接指向密钥文件，无需登录
• • 预获取的访问令牌：当其他工具已经为你生成令牌时使用

而且认证的优先级也很清晰，从访问令牌到加密凭据再到明文凭据，一应俱全。

4、内置 Model Armor

gws 还集成了 Google Cloud Model Armor，可以在 API 响应到达你的代理之前扫描其中的提示注入风险。这对于使用 AI 代理来处理 Workspace 数据的场景来说，简直是必备功能。

你可以通过 --sanitize 参数来启用这个功能，还可以设置环境变量来配置默认的防护模板和模式（警告或阻止）。

5、MCP 服务器协议

gws 支持 MCP 服务器，可以通过标准输入输出启动一个 MCP 服务器，将 Google Workspace API 暴露为结构化工具，任何 MCP 兼容的客户端（Claude Desktop、Gemini CLI 等）都可以调用。

你可以在 Claude Desktop 里直接让 AI 帮你操作 Google Workspace，体验非常丝滑。

快速安装与使用

1、前置要求

在安装 gws 之前，你需要准备：

• • Node.js 18+
• • 一个 Google Cloud 项目（用于 OAuth 凭据，可以通过 Google Cloud Console、gcloud CLI 或 gws auth setup 命令创建）
• • 一个有权访问 Google Workspace 的 Google 账号

2、安装方法

gws 提供了多种安装方式，你可以根据自己的喜好选择：

方式一：通过 npm 安装（推荐）

npm install -g @googleworkspace/cli

npm 包会为你的操作系统和架构捆绑预构建的原生二进制文件，不需要 Rust 工具链。

方式二：下载预构建的二进制文件

你可以直接从 GitHub Releases 页面下载适合你系统的二进制文件。

方式三：从源码构建

如果你有 Rust 工具链，可以从源码构建：

cargo install --git https://github.com/googleworkspace/cli --locked

方式四：使用 Nix

项目还提供了 Nix flake：

nix run github:googleworkspace/cli

3、开始使用

安装完成后，让我们来试试基本操作：

第一步：设置认证

如果你已经安装并认证了 gcloud，这是最快的方式：

gws auth setup     # 引导你完成 Google Cloud 项目配置
gws auth login     # 后续的 OAuth 登录

如果你没有 gcloud，可以使用手动 OAuth 设置。

第二步：试试第一个命令

列出最近的 5 个文件：

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

手动 OAuth 设置

当 gws auth setup 无法自动化项目/客户端创建，或者你想要明确的控制权时，使用这种方式。

1. 1. 在目标项目中打开 Google Cloud Console：
   • • OAuth 同意屏幕：https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • • 凭据：https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 2. 如果提示，配置 OAuth 品牌/受众：
   • • 应用类型：External（测试模式就可以）
3. 3. 在测试用户下添加你的账号
4. 4. 创建 OAuth 客户端：
   • • 类型：Desktop app
5. 5. 下载客户端 JSON 并保存到：~/.config/gws/client_secret.json

重要：你必须将自己添加为测试用户。在 OAuth 同意屏幕中，点击「测试用户 → 添加用户」并输入你的 Google 账号邮箱。如果没有这一步，登录会失败并显示通用的「访问被阻止」错误。

然后运行：

gws auth login

当然也可以通过浏览器辅助认证（人类或代理）

你可以手动或通过浏览器自动化完成 OAuth：

• • 人类流程：运行 gws auth login，打开打印的 URL，批准作用域
• • 代理辅助流程：代理打开 URL，选择账号，处理同意提示，一旦 localhost 回调成功就返回控制权

如果同意显示「Google 尚未验证此应用」（测试模式），点击「继续」。

如果出现作用域复选框，在继续之前选择所需的作用域（或全选）。

AI Agent Skills

gws 仓库附带了 100+ 个 Agent Skills（SKILL.md 文件）—— 每个支持的 API 都有一个，还有针对常见工作流的高级助手，以及 Gmail、Drive、Docs、Calendar 和 Sheets 的 50 个精选食谱。

你可以一次性安装所有技能：

npx skills add https://github.com/googleworkspace/cli

或者只选择你需要的：

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-gmail

OpenClaw 设置

你可以符号链接所有技能（与仓库保持同步）：

ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

或者复制特定的技能：

cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

gws-shared 技能包含一个安装块，所以如果 gws 不在 PATH 上，OpenClaw 会通过 npm 自动安装 CLI。

MCP 服务

gws mcp 通过 stdio 启动一个 MCP 服务器，将 Google Workspace API 暴露为结构化工具，任何 MCP 兼容的客户端（Claude Desktop、Gemini CLI、VS Code 等）都可以调用。

启动 MCP 服务器：

gws mcp -s drive                  # 暴露 Drive 工具
gws mcp -s drive,gmail,calendar   # 暴露多个服务
gws mcp -s all                    # 暴露所有服务（工具很多！）

在你的 MCP 客户端中配置：

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

提示：每个服务大约添加 10-80 个工具。保持列表为你实际需要的，以保持在客户端的工具限制（通常 50-100 个工具）以下。

基本操作示例

列出最近的 10 个文件：

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

创建一个电子表格：

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

发送一条 Chat 消息（预览模式）：

gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

查看任意方法的请求/响应模式：

gws schema drive.files.list

流式输出分页结果（NDJSON 格式）：

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

高级功能

多部分上传：

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

分页控制：

• • --page-all：自动分页，每页一行 JSON（NDJSON）
• • --page-limit <N>：最多获取 N 页
• • --page-delay <MS>：页面之间的延迟（默认 100 毫秒）

Google Sheets 的 Shell 转义：

Sheets 的范围使用 !，而 bash 会将其解释为历史展开。所以一定要用单引号包裹值：

# 读取 "Sheet1" 的 A1:C10 单元格
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# 追加行
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

常见问题解决

使用 gws 时可能会遇到一些问题，这里是一些常见问题的解决方案：

问题 1：登录时出现「访问被阻止」或 403 错误

原因：你的 OAuth 应用处于测试模式，而你的账号没有被列为测试用户。

解决方法：在 GCP 项目中打开 OAuth 同意屏幕 → 测试用户 → 添加用户 → 输入你的 Google 账号邮箱。然后重试 gws auth login。

问题 2：出现「Google 尚未验证此应用」

这是预期的，当你的应用处于测试模式时会出现。点击「高级 → 前往 <应用名称>（不安全）」继续。这对于个人使用是安全的；只有在向其他用户发布应用时才需要验证。

问题 3：作用域太多 / 同意屏幕错误

未经验证（测试模式）的应用限制为约 25 个 OAuth 作用域。推荐的作用域预设包含许多作用域，会超过此限制。

解决方法：只选择你需要的作用域：

gws auth login --scopes drive,gmail,calendar

问题 4：找不到 gcloud CLI

gws auth setup 需要 gcloud CLI 来自动化项目创建。你有三个选择：

1. 1. 安装 gcloud 并直接使用 gcloud
2. 2. 重新运行 gws auth setup，它会包装 gcloud 调用
3. 3. 完全跳过 gcloud — 在 Cloud Console 中手动设置 OAuth 凭据

问题 5：redirect_uri_mismatch

OAuth 客户端没有创建为 Desktop app 类型。在凭据页面中，删除现有客户端，创建一个类型为 Desktop app 的新客户端，并下载新的 JSON。

问题 6：API 未启用 — accessNotConfigured

如果所需的 Google API 未为你的 GCP 项目启用，你会看到 403 错误，原因为 accessNotConfigured。gws 还会向 stderr 打印一个可操作的提示。

解决方法：

1. 1. 点击 enable_url 链接（或从 enable_url JSON 字段复制它）
2. 2. 在 GCP Console 中，点击「启用」
3. 3. 等待约 10 秒，然后重试你的 gws 命令

提示：你也可以运行 gws auth setup，它会引导你自动为项目启用所有必需的 API。

写在最后

gws 的出现，为 Google Workspace 的自动化操作带来了全新的可能性。它不仅让人类用户能够更高效地操作 Workspace，还为 AI 代理提供了一个完美的接口，让 AI 能够直接帮助我们处理日常工作。

如果你是 Google Workspace 的用户，或者你正在开发与 Workspace 相关的自动化工具，那么 gws 绝对值得你一试。

GitHub：

https://github.com/googleworkspace/cli

如果本文对您有帮助，也请帮忙点个 赞👍 + 在看 哈！❤️

在看你就赞赞我！