gws

**一个用于管理所有 Google Workspace 的 CLI 工具 —— 为人类和 AI 代理而生。**
涵盖 Drive、Gmail、Calendar 以及所有的 Workspace API。零样板代码。结构化的 JSON 输出。内置 40 多种代理技能。

⬇️ **[下载适用于您操作系统的最新版本](https://github.com/googleworkspace/cli/releases)** `gws` 并未附带静态的命令列表。它会在运行时读取 Google 自身的 [Discovery Service](https://developers.google.com/discovery) 并动态构建其整个命令界面。当 Google Workspace 添加新的 API 端点或方法时，`gws` 会自动将其纳入。 ## 目录 - [前置条件](#prerequisites) - [安装说明](#installation) - [快速开始](#quick-start) - [为什么选择 gws？](#why-gws) - [身份验证](#authentication) - [AI 代理技能](#ai-agent-skills) - [高级用法](#advanced-usage) - [环境变量](#environment-variables) - [退出码](#exit-codes) - [架构](#architecture) - [故障排除](#troubleshooting) - [开发](#development) ## 前置条件 - **Node.js 18+** — 用于执行 `npm install`（或者从 [GitHub Releases](https://github.com/googleworkspace/cli/releases) 下载预编译的二进制文件） - **一个 Google Cloud 项目** — 获取 OAuth 凭据的必需条件。您可以通过 [Google Cloud Console](https://console.cloud.google.com/)、[`gcloud` CLI](https://cloud.google.com/sdk/docs/install) 或 `gws auth setup` 命令来创建。 - **一个有权访问 Google Workspace 的 Google 账号** ## 安装说明 安装 `gws` 的推荐方法是从 **[GitHub Releases](https://github.com/googleworkspace/cli/releases)** 页面下载适用于您的操作系统和架构的预编译二进制文件。解压该压缩包并将 `gws` 二进制文件放置在您的 `$PATH` 路径中。 为方便起见，您也可以使用 `npm` 来自动从 GitHub Releases 下载合适的二进制文件： ``` npm install -g @googleworkspace/cli ``` 或者从源码构建： ``` cargo install --git https://github.com/googleworkspace/cli --locked ``` 在 `github:googleworkspace/cli` 处也提供了一个 Nix flake ``` nix run github:googleworkspace/cli ``` 在 macOS 和 Linux 上，您还可以通过 [Homebrew](https://brew.sh/) 进行安装： ``` brew install googleworkspace-cli ``` ## 快速开始 ``` gws auth setup # walks you through Google Cloud project config gws auth login # subsequent OAuth login gws drive files list --params '{"pageSize": 5}' ``` ## 为什么选择 gws？ **为人类而生** — 停止根据 REST 文档手写 `curl` 请求。`gws` 为每个资源提供了 `--help`，用 `--dry-run` 来预览请求，并支持自动分页。 **为 AI 代理而生** — 每一个响应都是结构化的 JSON。结合附带的代理技能，您的 LLM 无需自定义工具即可管理 Workspace。 ``` # 列出最近 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 # 内省任何方法的 request/response schema gws schema drive.files.list # 以 NDJSON 流式传输分页结果 gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name' ``` ## 身份验证 CLI 支持多种身份验证工作流，因此无论是在笔记本电脑、CI 环境还是服务器上，它都能正常运行。 ### 我应该使用哪种设置？ | 我拥有… | 使用 | |---|---| | 已安装并通过 `gcloud` 认证 | [`gws auth setup`](#interactive-local-desktop)（最快） | | 有 GCP 项目但没有 `gcloud` | [手动 OAuth 设置](#manual-oauth-setup-google-cloud-console) | | 现有的 OAuth 访问令牌 | [`GOOGLE_WORKSPACE_CLI_TOKEN`](#pre-obtained-access-token) | | 现有凭据 | [`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`](#service-account-server-to-server) | ### 交互式（本地桌面） 凭据在静态存储时会使用存放在系统密钥环中的密钥（或在设置 `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file` 时存放在 `~/.config/gws/.encryption_key` 中）进行加密（AES-256-GCM）。 ``` gws auth setup # one-time: creates a Cloud project, enables APIs, logs you in gws auth login # subsequent scope selection and login ``` ### 手动 OAuth 设置（Google Cloud 控制台） 当 `gws auth setup` 无法自动执行项目/客户端创建时，或者您希望进行显式控制时，请使用此方法。 1. 在目标项目中打开 Google Cloud 控制台： - OAuth 同意屏幕：`https://console.cloud.google.com/apis/credentials/consent?project=` - 凭据：`https://console.cloud.google.com/apis/credentials?project=` 2. 如果出现提示，请配置 OAuth 品牌信息/受众群体： - 应用类型：**外部**（测试模式即可） 3. 在 **测试用户** 下添加您的账号 4. 创建 OAuth 客户端： - 类型：**桌面应用** 5. 下载客户端 JSON 并将其保存至： - `~/.config/gws/client_secret.json` 然后运行： ``` gws auth login ``` ### 浏览器辅助验证（人类或代理） 您可以手动完成 OAuth，也可以通过浏览器自动化完成。 - **人工流程**：运行 `gws auth login`，打开打印出的 URL，批准权限范围。 - **代理辅助流程**：代理打开 URL、选择账号、处理同意提示，并在 localhost 回调成功后交还控制权。 如果同意屏幕显示 **“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) ``` ### 优先级 | 优先级 | 来源 | 设置方式 | | -------- | ---------------------- | --------------------------------------- | | 1 | 访问令牌 | `GOOGLE_WORKSPACE_CLI_TOKEN` | | 2 | 凭据文件 | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | | 3 | 加密凭据 | `gws auth login` | | 4 | 明文凭据 | `~/.config/gws/credentials.json` | 环境变量也可以存放在 `.env` 文件中。 ## AI 代理技能 该仓库附带了 100 多种代理技能（`SKILL.md` 文件）—— 涵盖了每一个受支持的 API，以及用于常见工作流的更高级别辅助工具，和针对 Gmail、Drive、Docs、Calendar 和 Sheets 的 50 个精选秘诀。完整列表请参阅 [技能索引](docs/skills.md)。 ``` # 一次性安装所有 skills 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 设置

``` # Symlink 所有 skills（与 repo 保持同步） ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/ # 或复制特定的 skills cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/ ``` `gws-shared` 技能包含一个 `install` 块，因此如果 `gws` 不在 PATH 中，OpenClaw 将通过 `npm` 自动安装 CLI。

## 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 ``` ### 分页 | 标志 | 描述 | 默认值 | | ------------------- | ---------------------------------------------- | ------- | | `--page-all` | 自动分页，每页输出一行 JSON (NDJSON) | 关 | | `--page-limit ` | 最大获取页数 | 10 | | `--page-delay ` | 页面之间的延迟 | 100 ms | ### 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]]}' ``` ### 辅助命令 某些服务在自动生成的 Discovery 界面之上附带了一些手工编写的辅助命令。辅助命令以 `+` 为前缀，以便在视觉上加以区分，且不会与 Discovery 生成的方法名发生冲突。 时间感知型辅助命令（`+agenda`、`+standup-report`、`+weekly-digest`、`+meeting-prep`）会自动使用您的 **Google 账号时区**（从 Calendar Settings API 获取并缓存 24 小时）。使用 `+agenda` 时可通过 `--timezone`/`--tz` 进行覆盖，或设置 `--timezone` 标志以进行显式控制。 运行 `gws --help` 可同时查看 Discovery 方法和辅助命令。 ``` gws gmail --help # shows +send, +reply, +reply-all, +forward, +triage, +watch … gws calendar --help # shows +insert, +agenda … gws drive --help # shows +upload … ``` **完整的辅助命令参考：** | 服务 | 命令 | 描述 | |---------|---------|-------------| | `gmail` | `+send` | 发送电子邮件 | | `gmail` | `+reply` | 回复邮件（自动处理邮件线索） | | `gmail` | `+reply-all` | 全员回复邮件 | | `gmail` | `+forward` | 将邮件转发给新收件人 | | `gmail` | `+triage` | 显示未读收件箱摘要（发件人、主题、日期） | | `gmail` | `+watch` | 监控新邮件并以 NDJSON 格式流式传输 | | `sheets` | `+append` | 向电子表格追加一行 | | `sheets` | `+read` | 从电子表格中读取值 | | `docs` | `+write` | 向文档追加文本 | | `chat` | `+send` | 向聊天空间发送消息 | | `drive` | `+upload` | 上传文件并自动生成元数据 | | `calendar` | `+insert` | 创建新事件 | | `calendar` | `+agenda` | 显示即将发生的事件（使用 Google 账号时区；可通过 `--timezone` 覆盖） | | `script` | `+push` | 用本地文件替换 Apps Script 项目中的所有文件 | | `workflow` | `+standup-report` | 今天的会议 + 待办任务生成为站会摘要 | | `workflow` | `+meeting-prep` | 为您的下一次会议做准备：议程、参会者和相关文档 | | `workflow` | `+email-to-task` | 将 Gmail 邮件转换为 Google Tasks 条目 | | `workflow` | `+weekly-digest` | 每周摘要：本周的会议 + 未读邮件数 | | `workflow` | `+file-announce` | 在 Chat 空间中宣布 Drive 文件 | | `events` | `+subscribe` | 订阅 Workspace 事件并以 NDJSON 格式流式传输 | | `events` | `+renew` | 续订/重新激活 Workspace Events 订阅 | | `modelarmor` | `+sanitize-prompt` | 通过 Model Armor 模板清理用户提示词 | | `modelarmor` | `+sanitize-response` | 通过 Model Armor 模板清理模型响应 | | `modelarmor` | `+create-template` | 创建新的 Model Armor 模板 | **示例：** ``` # 发送电子邮件 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" # 晨会站会总结 gws workflow +standup-report # 在特定时区显示今日日程安排 gws calendar +agenda --today --timezone America/New_York ``` ### Model Armor（响应清理） 集成 [Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor)，在 API 响应到达您的代理之前对其进行扫描，以防范提示词注入。 ``` gws gmail users messages get --params '...' \ --sanitize "projects/P/locations/L/templates/T" ``` | 变量 | 描述 | | ---------------------------------------- | ---------------------------- | | `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | 默认的 Model Armor 模板 | | `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE` | `warn`（默认）或 `block` | ## 环境变量 所有变量都是可选的。有关可直接复制粘贴的模板，请参阅 [`.env.example`](.env.example)。 | 变量 | 描述 | |---|---| | `GOOGLE_WORKSPACE_CLI_TOKEN` | 预获取的 OAuth2 访问令牌（最高优先级） | | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | OAuth 凭据 JSON 的路径（用户或服务账号） | | `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth 客户端 ID（`client_secret.json` 的替代方案） | | `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth 客户端密钥（与 `CLIENT_ID` 配对使用） | | `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | 覆盖配置目录（默认：`~/.config/gws`） | | `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | 默认的 Model Armor 模板 | | `GOOGLE_WORKSPACE_CLI_MODE` | `warn`（默认）或 `block` | | `GOOGLE_WORKSPACE_CLI_LOG` | stderr 的日志级别（例如 `gws=debug`）。默认关闭。 | | `GOOGLE_WORKSPACE_CLI_LOG_FILE` | 具有每日轮转功能的 JSON 日志文件目录。默认关闭。 | | `GOOGLE_WORKSPACE_PROJECT_ID` | 用于配额/计费以及作为辅助命令回退方案的 GCP 项目 ID 覆盖 | 环境变量也可以设置在 `.env` 文件中（通过 [dotenvy](https://crates.io/crates/dotenvy) 加载）。 ## 退出码 `gws` 使用结构化的退出码，以便脚本可以根据失败类型进行分支处理，而无需解析错误输出。 | 代码 | 含义 | 示例原因 | |------|---------|---------------| | `0` | 成功 | 命令正常完成 | | `1` | API 错误 | Google 返回了 4xx/5xx 响应 | | `2` | 认证错误 | 凭据缺失、过期或无效 | | `3` | 验证错误 | 参数错误、未知服务、无效标志 | | `4` | Discovery 错误 | 无法获取 API schema 文档 | | `5` | 内部错误 | 意外故障 | ``` gws drive files list --params '{"fileId": "bad"}' echo $? # 1 — API error gws unknown-service files list echo $? # 3 — validation error (unknown service) ``` ## 架构 `gws` 采用了 **两阶段解析** 策略： 1. 读取 `argv[1]` 以识别服务（例如 `drive`） 2. 获取该服务的 Discovery 文档（缓存 24 小时） 3. 根据文档的资源和方法构建 `clap::Command` 树 4. 重新解析剩余的参数 5. 进行身份验证，构建 HTTP 请求，并执行 所有输出 —— 包括成功、错误和下载元数据 —— 都是结构化的 JSON。 ## 故障排除 ### 登录期间出现“访问被阻止”或 403 您的 OAuth 应用处于 **测试模式**，且您的账号未被列为测试用户。 **修复方法：** 在您的 GCP 项目中打开 [OAuth 同意屏幕](https://console.cloud.google.com/apis/credentials/consent) -> **测试用户** -> **添加用户** -> 输入您的 Google 账号电子邮件。然后重试 `gws auth login`。 ### “Google 尚未验证此应用” 当您的应用处于测试模式时，这是预期行为。点击 **高级** -> **继续前往 \（不安全）** 以继续。这用于个人使用是安全的；只有将应用发布给其他用户时才需要验证。 ### 权限范围过多 / 同意屏幕错误 未经验证（测试模式）的应用被限制为大约 25 个 OAuth 范围。`recommended` 范围预设包含许多范围，将会超出此限制。 **修复方法：** 仅选择您需要的范围： ``` gws auth login --scopes drive,gmail,calendar ``` ### 找不到 `gcloud` CLI `gws auth setup` 需要 `gcloud` CLI 来自动化创建项目。您有三个选择： 1. [安装 gcloud](https://cloud.google.com/sdk/docs/install) 并直接使用 `gcloud`。 2. 重新运行封装了 `gcloud` 调用的 `gws auth setup`。 3. 完全跳过 `gcloud` —— 在 [Cloud Console](#manual-oauth-setup-google-cloud-console) 中手动设置 OAuth 凭据。 ### `redirect_uri_mismatch` OAuth 客户端未创建为 **桌面应用** 类型。在 [凭据](https://console.cloud.google.com/apis/credentials) 页面中，删除现有的客户端，创建一个类型为 **桌面应用** 的新客户端，并下载新的 JSON。 ### API 未启用 — `accessNotConfigured` 如果您的 GCP 项目未启用所需的 Google API，您将看到原因为 `accessNotConfigured` 的 403 错误： ``` { "error": { "code": 403, "message": "Gmail API has not been used in project 549352339482 ...", "reason": "accessNotConfigured", "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482" } } ``` `gws` 还会向 **stderr** 打印一条可操作提示： ``` 💡 API not enabled for your GCP project. Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482 After enabling, wait a few seconds and retry your command. ``` **修复步骤：** 1. 点击 `enable_url` 链接（或从 `enable_url` JSON 字段中复制它）。 2. 在 GCP 控制台中，点击 **启用**。 3. 等待约 10 秒钟，然后重试您的 `gws` 命令。 ## 开发 ``` cargo build # dev build cargo clippy -- -D warnings # lint cargo test # unit tests ./scripts/coverage.sh # HTML coverage report → target/llvm-cov/html/ ``` ## 许可证 Apache-2.0 ## 免责声明

标签：AI代理, API安全, API客户端, Discovery Service, Gmail, GNU通用公共许可证, Google Calendar, Google Cloud, Google Docs, Google Drive, Google Sheets, Google Workspace, JSON输出, MITM代理, Node.js, NPM包, OAuth认证, OSV-Scalibr, 办公自动化, 动态构建, 可视化界面, 效率工具, 网络调试, 自动化, 通知系统, 零样板代码