gws

一套 CLI，适用于所有 Google Workspace——专为人类与 AI 代理打造。
Drive、Gmail、日历，以及所有 Workspace API 都可轻松使用。零样板代码，结构化 JSON 输出，内置 40 多项代理技能。

[！注意] 这并非官方支持的 Google 产品。

npm install -g @googleworkspace/cli

gws 并不提供预装的命令列表。它在运行时会读取 Google 自己的 Discovery Service，并动态构建其完整的命令集。当 Google Workspace 添加了新的 API 端点或方法时，gws 会自动将其纳入支持范围。

[！重要] 本项目正处于积极开发阶段。随着我们迈向 v1.0，预计会频繁出现破坏性变更。

目录

• 前提条件
• 安装
• 快速入门
• [为什么选择 gws？](#为什么选择 gws)
• 身份验证
• [AI 代理技能](#AI 代理技能)
• 高级用法
• 环境变量
• 退出码
• 架构
• 故障排除
• 开发

前提条件

• Node.js 18+ — 用于执行 npm install（或从 GitHub 发布版 下载预编译二进制文件）
• Google Cloud 项目 — 需要 OAuth 凭据。您可以通过 Google Cloud 控制台 创建一个，或使用 gcloud CLI，亦或通过 gws auth setup 命令完成配置。
• Google 账号，且拥有 Google Workspace 的访问权限

安装

npm install -g @googleworkspace/cli

npm 包会为您根据操作系统和架构预编译好原生二进制文件。 无需使用 Rust 工具链。

预编译二进制文件也可在 GitHub 发布版 页面中获取。

或者，您也可以从源代码构建：

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

此外，还提供了 Nix Flake 文件，可在 github:googleworkspace/cli 中找到：

nix run github:googleworkspace/cli

在 macOS 和 Linux 上，您还可以通过 Homebrew 安装：

brew install googleworkspace-cli

快速入门

gws auth setup     # 介绍 Google Cloud 项目配置流程
gws auth login     # 后续进行 OAuth 登录
gws drive files list --params '{"pageSize": 5}'

为什么选择 gws？

面向人类 — 停止手动编写针对 REST 文档的 curl 请求。gws 会在每个资源上显示 --help 选项，提供 --dry-run 以预览请求，并支持自动分页。

面向 AI 代理 — 每个响应均采用结构化 JSON 格式。将此功能与附带的代理技能结合使用，您的大语言模型便能无缝管理 Google Workspace，而无需自定义工具。

# 列出最近的 10 个文件
gws drive files list --params '{"pageSize": 10}'

# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 发送聊天消息
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "部署完成."}' \
  --dry-run

# 了解任意方法的请求/响应模式
gws schema drive.files.list

# 以 NDJSON 格式流式输出分页结果
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

身份验证

CLI 支持多种身份验证流程，因此无论是在笔记本电脑上、在 CI 环境中，还是在服务器上，都能轻松使用。

我该选择哪种设置？

交互式（本地桌面）

凭据在静止状态下经过加密处理（AES-256-GCM），密钥存储于您的操作系统密钥环中（或在 ~/.config/gws/.encryption_key 中，当 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 时）。

gws auth setup       # 一次性操作：创建 Cloud 项目、启用 API、登录用户
gws auth login       # 后续进行权限范围选择与登录

gws auth setup 需要 gcloud CLI（Cloud SDK 安装指南）。如果您尚未安装 gcloud，请改用下方的 [手动 OAuth 配置](#手动 OAuth 配置 Google Cloud 控制台)。

[！警告] 测试模式下的权限范围限制： 如果您的 OAuth 应用未经过验证（处于测试模式），Google 对同意范围的限制约为 25 个。推荐的默认权限范围包含 85 多个权限，但对于未经过验证的应用（尤其是 @gmail.com 账户），这些权限可能会导致失败。 请优先选择单独的服务，以进一步筛选权限选择器：

gws auth login -s drive,gmail,sheets

手动 OAuth 配置（Google Cloud 控制台）

当 gws auth setup 无法自动完成项目或客户端的创建，或您希望获得更精细的控制时，请使用此方式。

1. 在目标项目中打开 Google Cloud 控制台：
   • OAuth 同意页面：https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • 凭据页面：https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 如系统提示，请配置 OAuth 品牌化与受众信息：
   • 应用类型：外部应用（测试模式完全适用）
3. 将您的账户添加至 测试用户 一栏
4. 创建 OAuth 客户端：
   • 类型：桌面应用
5. 下载客户端 JSON 文件，并保存至：
   • ~/.config/gws/client_secret.json

[！重要] 您必须将自己添加为测试用户。 在 OAuth 同意页面中，点击 测试用户 → 添加用户，并输入您的 Google 账号邮箱。若未完成此操作，登录时将收到通用的“访问被阻止”错误提示。

随后运行：

gws auth login

浏览器辅助身份验证（人工或代理）

您可以手动完成 OAuth 身份验证，也可以通过浏览器自动化完成。

• 人工流程：运行 gws auth login，打开打印出的 URL，并对权限范围进行授权。
• 代理辅助流程：代理用户打开 URL，选择账户，处理同意提示，并在本地主机回调成功后将控制权返回。

如果在同意页面显示“Google 未验证此应用”（测试模式），请点击“继续”。 如果出现权限范围复选框，请在继续前选择所需的权限范围（或选择全部）。

无头/CI 流程（导出流程）

1. 在配备浏览器的机器上完成交互式身份验证。
2. 导出凭据：

   gws auth export --unmasked > credentials.json
   

3. 在无头机器上：

   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
   gws drive files list   # 一切正常
   

服务账号（服务器到服务器）

指向您的密钥文件即可，无需登录。

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

预先获取的访问令牌

当其他工具（如 gcloud）已为您环境生成令牌时，此方法非常实用。

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

优先级

环境变量也可以存储在 .env 文件中。

AI 代理技能

该仓库提供了 100 多种代理技能（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

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

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

Gemini CLI 扩展

1. 首先对 CLI 进行身份验证：

   gws auth setup
   

2. 将扩展安装至 Gemini CLI：

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

安装此扩展可让您的 Gemini CLI 代理直接访问所有 gws 命令和 Google Workspace 代理技能。由于 gws 会安全地处理自身身份验证，您只需在使用代理之前在终端进行一次身份验证，扩展便会自动继承您的凭据。

高级用法

多部分上传

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

分页

Google 表格 — Shell 转义

表格中的单元格范围使用 !，而 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]]}'

辅助命令

部分服务会随自动生成的 Discovery 界面一同提供手工编写的辅助命令。这些辅助命令以 + 为前缀，以便在视觉上与 Discovery 生成的方法名称区分开来，并且绝不会与 Discovery 生成的方法名发生冲突。

时间感知型辅助命令（如 +agenda、+standup-report、+weekly-digest、+meeting-prep）会自动使用您的 Google 账户时区（从 Calendar 设置 API 中获取并缓存 24 小时）。您可以通过在 +agenda 中添加 --timezone 或 --tz 参数来覆盖此设置，或者通过指定 --timezone 标志来实现显式控制。

运行 gws <service> --help 命令，即可同时查看 Discovery 方法和辅助命令。

gws gmail --help      # 显示 +send、+reply、+reply-all、+forward、+triage、+watch 等方法
gws calendar --help   # 显示 +insert、+agenda 等方法
gws drive --help      # 显示 +upload 等方法

完整辅助命令参考：

示例：

# 发送电子邮件
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# 回复消息
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# 向电子表格中追加一行数据
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# 显示今天的日历议程
gws calendar +agenda

# 上传文件到 Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# 今日的 Standup 汇报
gws workflow +standup-report

# 在特定时区显示今天的议程
gws calendar +agenda --today --timezone America/New_York

Model Armor（响应安全化）

集成 Google Cloud Model Armor 以在 API 响应到达您的代理之前，对其内容进行检测，防止提示注入攻击。

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

环境变量

所有变量均为可选。请参阅 .env.example 以获取一个复制粘贴模板。

环境变量也可以在 .env 文件中设置（通过 dotenvy 加载）。

退出码

gws 采用结构化的退出码，因此脚本可以根据失败类型进行分支处理，而无需解析错误输出。

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 — API 错误

gws unknown-service files list
echo $?   # 3 — 验证错误（服务未知）

架构

gws 采用 两阶段解析 策略：

1. 读取 argv[1] 以识别服务类型（例如：drive）
2. 获取服务的 Discovery 文档（缓存 24 小时）
3. 从文档的资源和方法构建 clap::Command 树
4. 重新解析剩余的参数
5. 进行身份验证、构建 HTTP 请求并执行

所有输出——成功信息、错误信息、下载元数据——均采用结构化 JSON 格式。

排查故障

登录时出现“访问被阻止”或 403 错误

您的 OAuth 应用处于 测试模式，且您的账户并未被列入测试用户名单。

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

“Google 未验证此应用”

通常在您的应用处于测试模式时会出现此提示。点击 高级 → 前往 <应用名称>（不安全） 以继续操作。此操作适用于个人使用；只有在将应用发布给其他用户时才需要进行验证。

范围过多 / 同意屏幕错误

未经验证（测试模式）的应用程序仅能使用约 25 个 OAuth 范围。预设的“推荐”范围包含众多范围，将超出此限制。

解决方法： 仅选择您所需的范围：

gws auth login --scopes drive,gmail,calendar

未找到 gcloud CLI

gws auth setup 需要 gcloud CLI 来自动创建项目。您有以下三种选择：

1. 安装 gcloud，并直接使用 gcloud。
2. 重新运行 gws auth setup，该命令会自动包裹 gcloud 的调用。
3. 完全跳过 gcloud——在 Cloud Console 中手动设置 OAuth 凭证。

重定向 URI 不匹配

OAuth 客户端并非以 桌面应用 类型创建。在 凭据 页面中，删除现有客户端，创建一个新的客户端，并将其类型设置为 桌面应用，然后下载新的 JSON 文件。

API 未启用 — accessNotConfigured

如果您的 GCP 项目未启用所需 Google API，您将看到一个 403 错误，错误原因显示为 accessNotConfigured：

{
  "error": {
    "code": 403,
    "message": "Gmail API 已未在项目 549352339482 中使用...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

gws 也会在 stderr 中打印一条可操作的提示信息：

💡 未为您的 GCP 项目启用 API。
   请前往：https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   启用后，请等待几秒钟，然后重试您的命令。

解决步骤：

1. 点击 enable_url 链接（或从 enable_url JSON 字段中复制该链接）。
2. 在 GCP 控制台中，点击 启用。
3. 等待约 10 秒，然后重试您的 gws 命令。

[!提示] 您也可以运行 gws auth setup，该命令会自动为您完成项目中所有必需 API 的启用流程。

开发

cargo build                       # 开发构建
cargo clippy -- -D warnings       # 代码检查
cargo test                        # 单元测试
./scripts/coverage.sh             # HTML 盖度报告 → target/llvm-cov/html/

许可证

Apache-2.0

免责声明

[！注意] 这并非官方支持的 Google 产品。

gws (Google Workspace CLI) 快速上手指南

gws 是一个专为人类开发者和 AI 智能体设计的 Google Workspace 统一命令行工具。它支持 Drive、Gmail、Calendar 等所有 Workspace API，无需样板代码，直接输出结构化 JSON，并内置了 40+ 个 AI 智能体技能。

注意：这不是 Google 官方支持的产品。

环境准备

在开始之前，请确保满足以下条件：

• 操作系统：macOS、Linux 或 Windows。
• Node.js：版本 18 或更高（用于通过 npm 安装）。
• Google Cloud 项目：需要用于 OAuth 凭证配置（可通过 gws auth setup 自动创建，或在 Google Cloud Console 手动创建）。
• Google 账号：拥有访问 Google Workspace 的权限。
• 可选依赖：若使用 gws auth setup 自动配置项目，需预先安装 gcloud CLI。

安装步骤

你可以选择以下任意一种方式进行安装：

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

这是最通用的方式，包内已包含针对你操作系统的预构建二进制文件，无需 Rust 环境。

npm install -g @googleworkspace/cli

方式二：通过 Homebrew 安装 (macOS/Linux)

brew install googleworkspace-cli

方式三：通过 Nix 安装

nix run github:googleworkspace/cli

方式四：从源码构建 (需要 Rust/Cargo)

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

基本使用

1. 认证配置

首次使用前需要进行身份验证。如果你已安装 gcloud，可以使用交互式设置自动完成项目创建和登录：

# 一次性设置：创建云项目、启用 API 并登录
gws auth setup

# 后续登录或选择特定范围
gws auth login

提示：如果你的 OAuth 应用处于“测试模式”且未验证，Google 会限制授权范围数量。建议在登录时指定具体服务以避免失败： gws auth login -s drive,gmail,sheets

若无 gcloud，请参考完整文档在 Google Cloud Console 手动配置 OAuth 客户端。

2. 常用命令示例

gws 动态读取 Google Discovery Service，因此所有 API 方法均可直接使用。

列出 Drive 中最新的 5 个文件：

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

创建一个新的 Google 表格：

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

查看某个方法的请求/响应架构（用于调试或 AI 提示）：

gws schema drive.files.list

流式分页输出（配合 jq 处理）：

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

3. AI 智能体集成

该工具专为 AI 设计，所有响应均为结构化 JSON。你可以为 Cursor、OpenClaw 或 Gemini CLI 添加技能：

为 Gemini CLI 安装扩展：

# 先确保终端已认证
gws auth setup

# 安装扩展
gemini extensions install https://github.com/googleworkspace/cli

为其他 Agent 添加技能：

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