Google Workspace CLI：统一管理所有 Google 服务的命令行工具

Google Workspace CLI (gws) 是一个统一的命令行工具，用于管理 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等所有 Google Workspace 服务。它从 Google Discovery Service 动态构建命令，提供零样板代码的结构化 JSON 输出，并包含 100+ AI 代理技能。

项目简介

Google Workspace CLI（简称 gws）是一个开源的命令行工具，使用 Rust 编写，目前在 GitHub 上已获得超过 15,700 个 star。该项目的核心理念是：一个 CLI 统管所有 Google Workspace 服务，为人类和 AI 代理而构建。

与传统的 Google API 工具不同，gws 不发布静态命令列表。它在运行时读取 Google 自己的 Discovery Service，并动态构建整个命令体系。当 Google Workspace 添加新的 API 端点或方法时，gws 会自动获取。

核心特性

为人类设计

零样板代码 - 停止编写 curl 调用，gws 为每个资源提供 --help
预览请求 - 使用 --dry-run 预览请求内容
自动分页 - 智能处理大量数据的分页请求
Shell 友好 - 支持 NDJSON 流式输出，便于与其他工具配合

为 AI 代理设计

结构化 JSON - 每个响应都是结构化 JSON
100+ Agent Skills - 包含针对每个支持 API 的技能
50+ 精选配方 - Gmail、Drive、Docs、Calendar、Sheets 的常用工作流
MCP 协议支持 - 可连接到模型上下文协议服务器

技术亮点

动态命令生成 - 从 Discovery Service 实时构建命令
多认证方式 - 支持交互式、无头、服务账户等多种认证流程
凭证加密 - 使用 AES-256-GCM 加密，密钥存储在系统密钥链
Model Armor 集成 - 扫描 API 响应以防止提示注入

安装指南

前置要求

Node.js 18+ - 用于 npm install（或从 GitHub Releases 下载预构建二进制文件）
Google Cloud 项目 - OAuth 凭证所需
Google Workspace 账户 - 有访问权限的 Google 账户

NPM 安装（推荐）

bash

npm install -g @googleworkspace/cli

npm 包捆绑了针对你的操作系统和架构的预构建原生二进制文件，无需 Rust 工具链。

其他安装方式

从源码构建

bash

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

Nix Flakes

bash

nix run github:googleworkspace/cli

预构建二进制文件

从 GitHub Releases 页面下载。

快速开始

基本使用流程

bash

# 1. 设置认证（首次使用）
gws auth setup     # 引导你完成 Google Cloud 项目配置

# 2. 后续登录
gws auth login     # 后续的 OAuth 登录

# 3. 开始使用
gws drive files list --params '{"pageSize": 5}'

常用示例

bash

# 列出最近的 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 支持多种认证工作流程，适用于笔记本电脑、CI 环境和服务器。

认证方式对比

场景	推荐方式
已安装并认证 `gcloud`	`gws auth setup`（最快）
有 GCP 项目但无 `gcloud`	手动 OAuth 设置
现有 OAuth 访问令牌	`GOOGLE_WORKSPACE_CLI_TOKEN`
现有凭证文件	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`

交互式认证（本地桌面）

凭证使用 AES-256-GCM 加密存储，密钥存储在操作系统密钥链中。

bash

gws auth setup       # 一次性：创建 Cloud 项目、启用 API、登录
gws auth login       # 后续：范围选择和登录

无头/CI 环境

在有浏览器的机器上完成交互式认证

导出凭证：

bash

gws auth export --unmasked > credentials.json

在无头机器上：

bash

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # 直接使用

服务账户（服务器到服务器）

bash

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

预获取的访问令牌

bash

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

AI 代理技能

该仓库提供了 100+ Agent Skills（SKILL.md 文件）—— 每个支持的 API 都有一个技能，加上常用工作流的更高级助手。

安装技能

bash

# 一次性安装所有技能
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 设置

bash

# 符号链接所有技能（与仓库保持同步）
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# 或复制特定技能
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

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

Gemini CLI 扩展

首先认证 CLI：
bash
```
gws auth setup
```

安装扩展到 Gemini CLI：

bash

gemini extensions install https://github.com/googleworkspace/cli

安装此扩展后，你的 Gemini CLI 代理将直接访问所有 gws 命令和 Google Workspace 代理技能。

高级用法

多部分上传

bash

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

分页控制

标志	描述	默认值
`--page-all`	自动分页，每页一行 JSON（NDJSON）	关闭
`--page-limit <N>`	最大获取页数	10
`--page-delay <MS>`	页面间延迟	100 ms

Google Sheets - Shell 转义

Sheets 范围使用 !，bash 会将其解释为历史扩展。始终用单引号包裹值：

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]]}'

Model Armor（响应清理）

集成 Google Cloud Model Armor 在 API 响应到达代理之前扫描提示注入：

bash

gws gmail users.messages.get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

环境变量

所有变量都是可选的，可以设置在 .env 文件中：

变量	描述
`GOOGLE_WORKSPACE_CLI_TOKEN`	预获取的 OAuth2 访问令牌（最高优先级）
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	OAuth 凭证 JSON 路径（用户或服务账户）
`GOOGLE_WORKSPACE_CLI_CLIENT_ID`	OAuth 客户端 ID
`GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`	OAuth 客户端密钥
`GOOGLE_WORKSPACE_CLI_CONFIG_DIR`	覆盖配置目录（默认：`~/.config/gws`）
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	默认 Model Armor 模板
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn`（默认）或 `block`
`GOOGLE_WORKSPACE_PROJECT_ID`	GCP 项目 ID 回退

架构设计

gws 使用两阶段解析策略：

读取 argv[1] 识别服务（如 drive）
获取服务的 Discovery Document（缓存 24 小时）
从文档的资源和方法构建 clap::Command 树
重新解析剩余参数
认证、构建 HTTP 请求、执行

所有输出 — 成功、错误、下载元数据 — 都是结构化 JSON。

故障排查

"Access blocked" 或登录时 403

你的 OAuth 应用处于测试模式，且你的账户未列为测试用户。

解决方法：在 GCP 项目中打开 OAuth 同意屏幕 → Test users → Add users → 输入你的 Google 账户邮箱，然后重试 gws auth login。

"Google hasn't verified this app"

当你的应用处于测试模式时会出现此提示。点击 Advanced → Go to (unsafe) 继续。这对个人使用是安全的；只有发布给其他用户时才需要验证。

范围过多 / 同意屏幕错误

未验证（测试模式）应用限制约 25 个 OAuth 范围。recommended 范围预设包含许多范围，会超出此限制。改用个别服务：

bash

gws auth login -s drive,gmail,sheets

支持的服务

Drive - 文件存储和共享
Gmail - 邮件管理
Calendar - 日历和事件
Sheets - 电子表格
Docs - 文档
Chat - 即时消息
Admin - 管理控制台
更多 - 所有 Google Workspace API

项目链接

GitHub 仓库: https://github.com/googleworkspace/cli
官方文档: https://developers.google.com/workspace
NPM 包: @googleworkspace/cli
许可证: Apache-2.0

总结

Google Workspace CLI (gws) 是一个强大的统一命令行工具，通过动态命令生成和多认证支持，简化了 Google Workspace 服务的管理。无论你是开发者、系统管理员还是 AI 代理构建者，gws 都能提供零样板代码的结构化 JSON 输出，帮助你高效管理 Google Workspace。如果你正在寻找一个可以统一管理所有 Google Workspace 服务的工具，gws 是一个值得尝试的选择。

文章来源: Google Workspace CLI GitHub 仓库
最后更新: 2026-03-08

字节笔记本

Google Workspace CLI：统一管理所有 Google 服务的命令行工具

项目简介

核心特性

为人类设计

为 AI 代理设计

技术亮点

安装指南

前置要求

NPM 安装（推荐）

其他安装方式

从源码构建

Nix Flakes

预构建二进制文件

快速开始

基本使用流程

常用示例

认证配置

认证方式对比

交互式认证（本地桌面）

无头/CI 环境

服务账户（服务器到服务器）

预获取的访问令牌

AI 代理技能

安装技能

OpenClaw 设置

Gemini CLI 扩展

高级用法

多部分上传

分页控制

Google Sheets - Shell 转义

Model Armor（响应清理）

环境变量

架构设计

故障排查

"Access blocked" 或登录时 403

"Google hasn't verified this app"

范围过多 / 同意屏幕错误

支持的服务

项目链接

总结