gws-setup

用途

gws-setup 用于从零开始完成 Google Workspace CLI（gws，包名 @googleworkspace/cli）的首次配置，并安装 90+ 个 Claude Code 的 agent 技能。目标是得到一个完全通过认证、可用于 Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks 等服务的命令行工具。

主要能力

安装 gws CLI 并验证版本。
引导在 Google Cloud Console 中创建或选择 GCP 项目。
启用所需的 Google Workspace API（Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks、People、Slides、Forms，Admin SDK 为可选）。
配置 Google Chat App（Chat API 要求，即便是用户上下文的 OAuth 访问也需要）。
配置 OAuth 同意屏幕并创建 OAuth 客户端 ID（Desktop app 类型）。
保存 client_secret.json 到本地配置目录。
选择 OAuth 范围并完成登录认证。
安装 gws agent 技能到 Claude Code。
导出凭证供其他机器使用。
通过若干命令验证配置是否可用。

使用方式

工作流分为 8 个步骤，并在开头进行预检（pre-flight checks），检查 gws 是否已安装、client_secret.json 是否存在、是否已认证，已完成的部分会被跳过。

Step 1：前置检查

which gws && gws --version
ls ~/.config/gws/client_secret.json
gws auth status

若 gws auth status 显示 "status": "success" 且带有 scope，可直接跳到 Step 6（安装技能）。

Step 2：安装 CLI

npm install -g @googleworkspace/cli
gws --version

Step 3：创建 GCP 项目与 OAuth 凭证

在 Google Cloud Console 中完成以下操作：

创建或选择 GCP 项目。
启用所需的 Google Workspace API。
配置 Google Chat App：开启 Configuration 标签，填写应用详情，在 Functionality 中勾选 Spaces and group conversations，在 Connection settings 中选择 Apps Script 或 HTTP endpoint，保存。
配置 OAuth 同意屏幕：User Type 选择 External，填写应用名称、用户支持邮箱、开发者联系邮箱，scope 留空，并将自己的 Google 账号添加为测试用户。
创建 OAuth 客户端 ID：Application type 选择 Desktop app，创建后复制 JSON 或下载 client_secret_*.json。
保存凭证：

mkdir -p ~/.config/gws

将 JSON 写入 ~/.config/gws/client_secret.json，预期格式：

{
  "installed": {
    "client_id": "...",
    "project_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "...",
    "redirect_uris": ["http://localhost"]
  }
}

Step 4：选择范围

完全访问（推荐）：gws auth login --full，包含 admin、pubsub、cloud-platform 在内的所有 Workspace 范围。
核心服务：gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks。
最小范围：gws auth login -s gmail,calendar。

若 GCP 应用处于 Testing 状态，范围选择被限制在约 25 个，可通过 -s service1,service2 指定范围，或将应用发布到 Production 以获得更广的范围访问。

Step 5：认证

登录命令会输出很长的 OAuth URL（30+ 个 scope），建议将其提取到文件后再打开：

gws auth login --full 2>&1 | tee /tmp/gws-auth-output.txt
grep -o 'https://accounts.google.com[^ ]*' /tmp/gws-auth-output.txt > /tmp/gws-auth-url.txt
cat /tmp/gws-auth-url.txt | xargs open

在浏览器中批准后，gws 将加密凭证存储于 ~/.config/gws/credentials.enc，可用 gws auth status 验证。

Step 6：安装 Agent 技能

npx skills add googleworkspace/cli -g --agent claude-code --all
ls ~/.claude/skills/gws-* | wc -l

Step 7：为其他机器保存凭证

gws auth export

client_secret.json 是可移植部分；同一 OAuth 客户端可在任何机器上使用，gws auth login 会为每台机器生成新的用户令牌。建议将 client_secret.json 内容保存到安全位置。

Step 8：验证

gws auth status
gws calendar +agenda --today
gws gmail +triage

若命令因认证错误失败，使用所需 scope 重新运行 gws auth login。

关键模式

Testing 与 Production OAuth 应用：GCP OAuth 应用初始处于 Testing 状态，令牌 7 天过期，scope 限制约 25 个。长期使用可将其推送到 Production，Production 应用没有令牌过期限制。用于个人/内部用途时 Google 不要求验证。
环境变量替代方案：

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"
gws auth login

配置目录：所有 gws 配置位于 ~/.config/gws/，包括 client_secret.json（可移植的 OAuth 客户端凭证）、credentials.enc（每台机器加密的用户令牌）、token_cache.json（令牌刷新缓存）、cache/（API discovery schema 缓存）。

适用场景

需要一个已认证的 Google Workspace CLI，并在 Claude Code 中使用 Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks 等服务的用户；需要在多台机器上完成配置的用户（配合 gws-install 与 gws-shared）。

限制

需要 Node.js 18+、Google 账号以及对 Google Cloud Console 的访问权限。Chat API 必须配置 Chat App，否则调用报错。Testing 状态应用存在令牌 7 天过期与约 25 个 scope 的限制。文档未提供具体收费标准或价格信息。