gws

一个用于所有 Google Workspace 的命令行工具——为人类和 AI 代理设计。 提供 Drive、Gmail、Calendar 及所有 Workspace API 的访问。零样板代码。结构化 JSON 输出。内置 40+ 个代理技能。

⚠️ 这不是 Google 官方支持的正式产品。

---

前提条件

• Node.js 18+（如果使用 npm 安装）或直接使用预编译二进制文件（从 GitHub Releases 下载）
• 一个 Google Cloud 项目——用于 OAuth 凭据。可通过 Google Cloud Console 或使用 gcloud CLI 或运行 gws auth setup 创建。
• 一个拥有 Google Workspace 访问权限的 Google 账号

---

快速开始

gws auth setup     # 引导你完成 Google Cloud 项目配置
gws auth login     # 后续 OAuth 登录
gws drive files list --params '{"pageSize": 5}'

---

为什么选择 gws？

对人类用户——不再需要手动编写 curl 调用并查阅 REST 文档。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

# 查看任意方法的请求/响应模式
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（最快）
有 GCP 项目但没有 gcloud	手动 OAuth 设置
已有 OAuth 访问令牌	GOOGLE_WORKSPACE_CLI_TOKEN
已有凭据文件	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

交互式（本地桌面）

凭据以 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。如果没有 gcloud，请使用下面的 手动 OAuth 设置。

⚠️ 测试模式下的作用域限制： 如果你的 OAuth 应用未验证（处于测试模式），Google 会将同意屏幕限制在约 25 个作用域。recommended 作用域预设包含 85+ 个作用域，在未验证的应用中会失败（特别是 @gmail.com 账号）。请选择单个服务来过滤作用域选择器：

gws auth login -s drive,gmail,sheets

### 手动 OAuth 设置（Google Cloud Console）

当 `gws auth setup` 无法自动创建项目/客户端，或者你希望完全控制时使用此方式。

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. 如果提示，配置 OAuth 品牌/受众：
   - 应用类型：**外部**（测试模式即可）
3. 在 **测试用户** 下添加你的账号
4. 创建 OAuth 客户端：
   - 类型：**桌面应用**
5. 下载客户端 JSON 并保存到：
   - `~/.config/gws/client_secret.json`

> ⚠️ **你必须将自己添加为测试用户。** 在 OAuth 同意屏幕中，点击 **测试用户 → 添加用户**，输入你的 Google 账号邮箱。否则登录会失败，显示通用的“访问被屏蔽”错误。

然后运行：

```bash
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 对应一个，外加高级工作流帮助器以及 50 个精选的 Gmail、Drive、Docs、Calendar 和 Sheets 配方。参见完整的 技能索引。

你可以一次性安装所有技能，或只挑选需要的。

OpenClaw 设置

可以创建符号链接或复制特定技能。gws-shared 技能包含一个 install 块，使 OpenClaw 在 gws 不在 PATH 中时自动通过 npm 安装 CLI。

---

Gemini CLI 扩展

1. 先认证 CLI：

   gws auth setup
   

2. 将扩展安装到 Gemini CLI 中。安装后，你的 Gemini CLI 代理可以直接访问所有 gws 命令和 Google Workspace 代理技能。由于 gws 安全地处理自己的认证，你只需在使用代理前在终端中完成一次认证，扩展会自动继承你的凭据。

---

高级用法

多部分上传

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

分页

标志	描述	默认值
--page-all	自动分页，每页输出一行 JSON（NDJSON）	关闭
--page-limit <N>	最大获取页数	10
--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]]}'

帮助器命令

部分服务在自动生成的 Discovery 表面之外额外提供了手写的帮助器命令。帮助器命令以 + 前缀标记，以便与 Discovery 生成的方法名区分且永不冲突。

时间感知的帮助器（+agenda、+standup-report、+weekly-digest、+meeting-prep）会自动使用你的 Google 账号时区（从 Calendar Settings 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 …

帮助器命令完整列表：

服务	命令	描述
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，在响应到达代理之前扫描 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 获取可复制模板。

变量	描述
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_SANITIZE_MODE	warn（默认）或 block
GOOGLE_WORKSPACE_CLI_LOG	stderr 的日志级别（例如 gws=debug）。默认关闭。
GOOGLE_WORKSPACE_CLI_LOG_FILE	JSON 日志文件的目录，每日轮转。默认关闭。
GOOGLE_WORKSPACE_PROJECT_ID	用于配额/计费的 GCP 项目 ID 覆盖，以及帮助器命令的回退。

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

---

退出代码

gws 使用结构化退出代码，脚本可以根据失败类型分支，无需解析错误输出。

代码	含义	示例原因
0	成功	命令正常完成
1	API 错误	Google 返回 4xx/5xx 响应
2	认证错误	凭据缺失、过期或无效
3	验证错误	参数错误、未知服务、无效标志
4	Discovery 错误	无法获取 API 模式文档
5	内部错误	意外失败

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 作用域。recommended 作用域预设包含大量作用域，会超出此限制。

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

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 凭据。

redirect_uri_mismatch

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

API 未启用 —— accessNotConfigured

如果所需的 Google API 未在你的 GCP 项目中启用，你会看到 403 错误，原因为 accessNotConfigured：

{
  "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 中打印一条可操作的提示：

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

修复步骤：

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

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

---

许可

Apache-2.0

免责声明

⚠️ 这不是 Google 官方支持的正式产品。