gws-setup

Google Workspace CLI——首次设置

使用 OAuth 凭据和 90 多个适用于 Claude Code 的 Agent 技能设置 gws CLI (@googleworkspace/cli)。完成后即可获得经过完整身份验证的 CLI，以及适用于 Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks 等服务的技能。

前提条件

• Node.js 18+
• 一个 Google 账号（个人账号或 Workspace 账号）
• 可访问 Google Cloud Console (console.cloud.google.com)

工作流

第 1 步：准备情况检查

检查哪些步骤已完成，并跳过已完成的步骤：

# Check if gws is installed
which gws && gws --version

# Check if client_secret.json exists
ls ~/.config/gws/client_secret.json

# Check if already authenticated
gws auth status

如果 gws auth status 显示带有作用域的 "status": "success"，请跳到第 6 步（安装技能）。

第 2 步：安装 CLI

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

第 3 步：创建 GCP 项目和 OAuth 凭据

用户需要在 Google Cloud Console 中创建 OAuth 桌面应用凭据。请逐步引导用户完成每个步骤。

3a. 创建或选择 GCP 项目：

引导用户访问：https://console.cloud.google.com/projectcreate

也可以使用现有项目。询问用户选择哪种方式。

3b. 启用 Google Workspace API：

引导用户访问其项目的 API 库：https://console.cloud.google.com/apis/library?project=PROJECT_ID

启用以下 API（逐一搜索）：

• Gmail API
• Google Drive API
• Google Calendar API
• Google Sheets API
• Google Docs API
• Google Chat API（需要额外配置 Chat 应用——见下文）
• Tasks API
• People API
• Google Slides API
• Google Forms API
• Admin SDK API（可选——用于 Workspace 管理功能）

3c. 配置 Google Chat 应用（Chat API 必需）：

仅启用 Chat API 还不够——即使是以用户身份通过 OAuth 访问，Google 也要求配置 Chat 应用。否则，所有 Chat API 调用都会返回错误。

引导用户访问：https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

1. 点击 Configuration 标签页
2. 填写应用详情（名称、头像、说明——CLI 使用时这些值无关紧要）
3. 在“Functionality”下，勾选 Spaces and group conversations
4. 在“Connection settings”下，选择 Apps Script 或 HTTP endpoint（任选其一——只需确保配置存在）
5. 保存

这会创建 Chat API 所需的应用身份。通过 gws 发送的消息仍会显示为来自经过身份验证的用户（OAuth 用户上下文），而不是来自机器人。

3e. 配置 OAuth 同意屏幕：

引导用户访问：https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID

设置：

• 用户类型：External（适用于任何 Google 账号）
• 应用名称：gws CLI（或任意名称）
• 用户支持电子邮件：用户的电子邮件地址
• 开发者联系信息：用户的电子邮件地址
• 将作用域留空（gws 会在登录时请求作用域）
• 将用户的 Google 账号添加为测试用户（应用处于“Testing”状态时必需）
• 保存，并继续完成所有屏幕上的步骤

3f. 创建 OAuth 客户端 ID：

引导用户访问：https://console.cloud.google.com/apis/credentials?project=PROJECT_ID

1. 点击 Create Credentials → OAuth client ID
2. 应用类型：Desktop app
3. 名称：gws CLI
4. 点击 Create
5. 复制 JSON，或下载 client_secret_*.json 文件

3g. 保存凭据：

请用户提供 client_secret.json 内容（粘贴 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"]
  }
}

步骤 4：选择权限范围

询问用户希望获得何种级别的访问权限：

选项	命令	授予的权限
完整访问权限（推荐）	gws auth login --full	所有 Workspace 权限范围，包括 admin、pubsub、cloud-platform
核心服务	gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks	仅最常用的服务
最小权限	gws auth login -s gmail,calendar	仅邮件和日历

向高级用户推荐 完整访问权限。OAuth 同意屏幕会显示所有请求的权限范围，方便用户在授权前查看。

注意：如果 GCP 应用处于“Testing”状态，权限范围选择会限制在约 25 个范围内。使用 -s service1,service2 请求指定权限范围，或发布应用（Publish → In Production）以获取更广泛的权限范围。

步骤 5：进行身份验证

重要：此步骤会输出一个很长的 OAuth URL（包含 30 多个权限范围），用户必须在浏览器中打开该 URL。URL 太长，无法从终端输出中复制——它会换行并导致链接失效。务必将其提取到文件中，并通过程序打开。

1. 运行登录命令并捕获输出：

gws auth login --full 2>&1 | tee /tmp/gws-auth-output.txt
# Or with specific services:
# gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks 2>&1 | tee /tmp/gws-auth-output.txt

作为后台任务运行也没问题——用户在浏览器中批准后，任务就会完成。

2. 提取并打开 URL（在输出出现后单独运行）：

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

如果 open 无法正常工作，请告诉用户：“身份验证 URL 已保存到 /tmp/gws-auth-url.txt——打开该文件并复制 URL。”

3. 等待用户在浏览器中批准。

用户在浏览器中批准后，gws 会将加密凭据保存到 ~/.config/gws/credentials.enc。

验证：

gws auth status

应显示 "status": "success"，以及经过身份验证的账号和已授予的权限范围。

步骤 6：安装 Agent 技能

为 Claude Code 全局安装 90 多个 gws Agent 技能：

npx skills add googleworkspace/cli -g --agent claude-code --all

验证技能是否已安装：

ls ~/.claude/skills/gws-* | wc -l

应显示 30 多个 gws 技能目录。

步骤 7：为其他设备保存凭据

如果用户还要配置其他设备，建议导出客户端凭据：

gws auth export

这会将解密后的凭据（包括刷新令牌）打印到标准输出。client_secret.json 文件可移植——同一 OAuth 客户端可在任何设备上使用，gws auth login 会为每台设备生成新的用户令牌。

告诉用户将 client_secret.json 的内容保存在安全的位置（密码管理器、加密笔记），以便在其他设备上使用 gws-install 技能。

步骤 8：验证所有功能是否正常

运行几个命令进行确认：

# Check auth
gws auth status

# Check calendar
gws calendar +agenda --today

# Check email
gws gmail +triage

如果任何命令因身份验证错误而失败，请使用所需的权限范围重新运行 gws auth login。

---

关键注意事项

OAuth 应用的 Testing 与 Production 状态

GCP OAuth 应用初始处于“Testing”状态，令牌有效期为 7 天，权限范围限制在约 25 个。若要长期使用：

• 在 OAuth 同意屏幕设置中将应用设为 Production
• Production 应用没有令牌有效期限制
• 对于个人或内部用途，Google 不要求验证

权限范围参考

服务标志	启用的功能
gmail	发送、读取和管理邮件、标签、过滤器
drive	文件、文件夹、共享云端硬盘
calendar	活动、日历、空闲/忙碌状态
sheets	读取和写入电子表格
docs	读取和写入文档
chat	空间、消息
tasks	任务列表和任务
slides	演示文稿
forms	表单和回复
people	联系人和个人资料
admin	Workspace 管理（目录、设备、群组）

环境变量替代方案

除了使用 client_secret.json，也可以通过环境变量提供凭据：

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 发现架构缓存

另请参阅

• gws-install — 使用现有凭据在其他设备上快速设置
• gws-shared — gws 命令的身份验证模式和全局标志