Back to Details

gws-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Workspace CLI — First-Time Setup

Google Workspace CLI — 首次设置指南

Set up the 
gws
CLI (@googleworkspace/cli) with OAuth credentials and 90+ agent skills for Claude Code. Produces a fully authenticated CLI with skills for Gmail, Drive, Calendar, Sheets, Docs, Chat, Tasks, and more.
为Claude Code配置带有OAuth凭证和90+个Agent技能的
gws
CLI（@googleworkspace/cli）。完成后将获得一个已完成身份验证的CLI，支持Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks等服务的技能。

Prerequisites

前置要求

  • Node.js 18+
  • A Google account (personal or Workspace)
  • Access to Google Cloud Console (console.cloud.google.com)
  • Node.js 18+
  • 一个Google账户（个人版或Workspace版）
  • 可访问Google Cloud Console（console.cloud.google.com）

Workflow

操作流程

Step 1: Pre-flight Checks

步骤1：预检查

Check what's already done and skip completed steps:
bash
undefined
检查已完成的操作，跳过已完成的步骤：
bash
undefined

Check if gws is installed

检查gws是否已安装

which gws && gws --version
which gws && gws --version

Check if client_secret.json exists

检查client_secret.json是否存在

ls ~/.config/gws/client_secret.json
ls ~/.config/gws/client_secret.json

Check if already authenticated

检查是否已完成身份验证

gws auth status

If `gws auth status` shows `"status": "success"` with scopes, skip to Step 6 (Install Skills).
gws auth status

如果`gws auth status`显示`"status": "success"`并包含权限范围，则直接跳至步骤6（安装技能）。

Step 2: Install the CLI

步骤2：安装CLI

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

Step 3: Create a GCP Project and OAuth Credentials

步骤3：创建GCP项目和OAuth凭证

The user needs to create OAuth Desktop App credentials in Google Cloud Console. Walk them through each step.
3a. Create or select a GCP project:
Direct the user to: 
https://console.cloud.google.com/projectcreate
Or use an existing project. Ask the user which they prefer.
3b. Enable Google Workspace APIs:
Direct the user to the API Library for their project: 
https://console.cloud.google.com/apis/library?project=PROJECT_ID
Enable these APIs (search for each):
  • Gmail API
  • Google Drive API
  • Google Calendar API
  • Google Sheets API
  • Google Docs API
  • Google Chat API
  • Tasks API
  • People API
  • Google Slides API
  • Google Forms API
  • Admin SDK API (optional — for Workspace admin features)
3c. Configure OAuth consent screen:
Direct the user to: 
https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID
Settings:
  • User Type: External (works for any Google account)
  • App name: 
    gws CLI
    (or any name)
  • User support email: their email
  • Developer contact: their email
  • Leave scopes blank (gws requests scopes at login time)
  • Add their Google account as a test user (required while app is in "Testing" status)
  • Save and continue through all screens
3d. Create OAuth client ID:
Direct the user to: 
https://console.cloud.google.com/apis/credentials?project=PROJECT_ID
  1. Click Create Credentials → OAuth client ID
  2. Application type: Desktop app
  3. Name: 
    gws CLI
  4. Click Create
  5. Copy the JSON or download the 
    client_secret_*.json
    file
3e. Save the credentials:
Ask the user to provide the client_secret.json content (paste the JSON or provide the downloaded file path).
bash
mkdir -p ~/.config/gws
Write the JSON to 
~/.config/gws/client_secret.json
. The expected format:
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"]
  }
}
用户需要在Google Cloud Console中创建OAuth桌面应用凭证。以下是详细步骤引导。
3a. 创建或选择GCP项目：
引导用户访问：
https://console.cloud.google.com/projectcreate
也可以使用现有项目。询问用户的偏好。
3b. 启用Google Workspace APIs：
引导用户进入对应项目的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
  • Tasks API
  • People API
  • Google Slides API
  • Google Forms API
  • Admin SDK API（可选 — 适用于Workspace管理员功能）
3c. 配置OAuth同意屏幕：
引导用户访问：
https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID
设置项：
  • 用户类型：外部（适用于所有Google账户）
  • 应用名称：
    gws CLI
    （或自定义名称）
  • 用户支持邮箱：用户本人的邮箱
  • 开发者联系邮箱：用户本人的邮箱
  • 权限范围留空（gws会在登录时请求权限范围）
  • 添加用户的Google账户为测试用户（应用处于"测试"状态时必填）
  • 保存并完成所有页面的配置
3d. 创建OAuth客户端ID：
引导用户访问：
https://console.cloud.google.com/apis/credentials?project=PROJECT_ID
  1. 点击创建凭证 → OAuth客户端ID
  2. 应用类型：桌面应用
  3. 名称：
    gws CLI
  4. 点击创建
  5. 复制JSON内容或下载
    client_secret_*.json
    文件
3e. 保存凭证：
询问用户提供client_secret.json的内容（粘贴JSON或提供下载文件的路径）。
bash
mkdir -p ~/.config/gws
将JSON内容写入
~/.config/gws/client_secret.json
。预期格式如下：
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: Choose Scopes

步骤4：选择权限范围

Ask the user what level of access they want:
OptionCommandWhat it grants
Full access (recommended)
gws auth login --full
All Workspace scopes including admin, pubsub, cloud-platform
Core services
gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks
Most-used services only
Minimal
gws auth login -s gmail,calendar
Just email and calendar
Recommend full access for power users. The OAuth consent screen shows all requested scopes so the user can review before granting.
Note: If the GCP app is in "Testing" status, scope selection is limited to ~25 scopes. Use 
-s service1,service2
to request targeted scopes, or publish the app (Publish → In Production) for broader scope access.
询问用户所需的访问级别：
选项命令授权范围
完全访问（推荐）
gws auth login --full
所有Workspace权限范围，包括管理员、pubsub、cloud-platform
核心服务
gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks
仅包含最常用的服务
最小权限
gws auth login -s gmail,calendar
仅包含邮件和日历
为高级用户推荐完全访问权限。OAuth同意屏幕会显示所有请求的权限范围，用户可在授权前查看。
注意：如果GCP应用处于"测试"状态，权限范围选择限制为约25个。使用
-s service1,service2
来请求特定权限范围，或者将应用发布为正式版（发布 → 正式环境）以获得更广泛的权限范围访问权限。

Step 5: Authenticate

步骤5：身份验证

Run the login command. This opens a browser — the user signs in with their chosen Google account and approves the scopes.
bash
gws auth login --full
运行登录命令。这会打开浏览器 — 用户使用选定的Google账户登录并批准权限范围。
bash
gws auth login --full

Or with specific services:

或指定特定服务：

gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks

After browser approval, gws stores encrypted credentials at `~/.config/gws/credentials.enc`.

Verify:

```bash
gws auth status
Should show 
"status": "success"
with the authenticated account and granted scopes.
gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks

浏览器批准后，gws会将加密后的凭证存储在`~/.config/gws/credentials.enc`。

验证：

```bash
gws auth status
应显示
"status": "success"
，并包含已认证账户和已授权的权限范围。

Step 6: Install Agent Skills

步骤6：安装Agent技能

Install the 90+ gws agent skills globally for Claude Code:
bash
npx skills add googleworkspace/cli -g --agent claude-code --all
Verify skills are installed:
bash
ls ~/.claude/skills/gws-* | wc -l
Should show 30+ gws skill directories.
为Claude Code全局安装90+个gws Agent技能：
bash
npx skills add googleworkspace/cli -g --agent claude-code --all
验证技能是否安装成功：
bash
ls ~/.claude/skills/gws-* | wc -l
应显示30+个gws技能目录。

Step 7: Save Credentials for Other Machines

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

If the user has other machines to set up, suggest exporting the client credentials:
bash
gws auth export
This prints decrypted credentials (including refresh token) to stdout. The 
client_secret.json
file is the portable part — the same OAuth client can be used on any machine, with 
gws auth login
generating fresh user tokens per machine.
Tell the user to save the 
client_secret.json
content somewhere secure (password manager, encrypted note) for use with the 
gws-install
skill on other machines.
如果用户需要在其他设备上设置，建议导出客户端凭证：
bash
gws auth export
这会将解密后的凭证（包括刷新令牌）输出到标准输出。
client_secret.json
文件是可移植的部分 — 同一个OAuth客户端可在任何设备上使用，通过
gws auth login
为每个设备生成新的用户令牌。
告知用户将
client_secret.json
内容保存在安全的地方（密码管理器、加密笔记），以便在其他设备上使用
gws-install
技能。

Step 8: Verify Everything Works

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

Run a few commands to confirm:
bash
undefined
运行以下命令确认功能正常：
bash
undefined

Check auth

检查身份验证状态

gws auth status
gws auth status

Check calendar

查看日历

gws calendar +agenda --today
gws calendar +agenda --today

Check email

查看邮件

gws gmail +triage

If any command fails with auth errors, re-run `gws auth login` with the needed scopes.

---
gws gmail +triage

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

---

Critical Patterns

关键注意事项

Testing vs Production OAuth Apps

测试版与正式版OAuth应用

GCP OAuth apps start in "Testing" status with a 7-day token expiry and ~25 scope limit. For long-term use:
  • Push the app to Production in the OAuth consent screen settings
  • Production apps have no token expiry limit
  • For personal/internal use, Google does not require verification
GCP OAuth应用初始处于"测试"状态，令牌有效期为7天，且权限范围限制为约25个。如需长期使用：
  • 在OAuth同意屏幕设置中将应用升级为正式版
  • 正式版应用无令牌有效期限制
  • 对于个人/内部使用，Google不需要进行应用验证

Scope Reference

权限范围参考

Service flagWhat it enables
gmail
Send, read, manage email, labels, filters
drive
Files, folders, shared drives
calendar
Events, calendars, free/busy
sheets
Read and write spreadsheets
docs
Read and write documents
chat
Spaces, messages
tasks
Task lists and tasks
slides
Presentations
forms
Forms and responses
people
Contacts and profiles
admin
Workspace admin (directory, devices, groups)
服务标识功能说明
gmail
发送、读取、管理邮件、标签、过滤器
drive
文件、文件夹、共享驱动器
calendar
事件、日历、忙闲状态
sheets
读写电子表格
docs
读写文档
chat
空间、消息
tasks
任务列表和任务
slides
演示文稿
forms
表单和响应
people
联系人和个人资料
admin
Workspace管理员功能（目录、设备、群组）

Environment Variable Alternative

环境变量替代方案

Instead of 
client_secret.json
, credentials can be provided via environment variables:
bash
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"
gws auth login
除了
client_secret.json
，还可通过环境变量提供凭证：
bash
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"
gws auth login

Config Directory

配置目录

All gws config lives in 
~/.config/gws/
:
FilePurpose
client_secret.json
OAuth client credentials (portable)
credentials.enc
Encrypted user tokens (per-machine)
token_cache.json
Token refresh cache
cache/
API discovery schema cache
所有gws配置存储在
~/.config/gws/
：
文件用途
client_secret.json
OAuth客户端凭证（可移植）
credentials.enc
加密的用户令牌（每设备唯一）
token_cache.json
令牌刷新缓存
cache/
API发现模式缓存

See Also

相关链接

  • gws-install — Quick setup on additional machines with existing credentials
  • gws-shared — Auth patterns and global flags for gws commands
  • gws-install — 使用现有凭证在其他设备上快速设置
  • gws-shared — gws命令的身份验证模式和全局参数