gws-korean-setup

安装和配置 Google Workspace CLI（gws）

为首次安装 gws CLI 的用户提供的分步指南。 共分 6 个阶段，每个阶段结束时都会确认安装是否正常。

参数处理

从 $ARGUMENTS 中解析以下标志：

• --skip-gcloud → 跳过 Phase 2（安装 gcloud）
• --skip-skills → 跳过 Phase 5（安装 Claude Code 技能）

---

Phase 1：安装 gws CLI

gws 以 npm 软件包的形式分发。需要先安装 Node.js。

1-1. 检查是否已安装

which gws && gws --version

• Windows 上使用 where gws 检查。
• 如果输出了版本号，直接进入 Phase 2。

1-2. 安装

npm install -g @googleworkspace/cli

如果无法安装：

症状	解决方法
npm: command not found	尚未安装 Node.js。请先从 https://nodejs.org/ 下载并安装 LTS 版本。
EACCES: permission denied	macOS/Linux：sudo npm install -g @googleworkspace/cli。Windows：以管理员权限重新打开终端并重试。

1-3. 确认安装

gws --version

如果输出了版本号，即表示成功。

---

Phase 2：安装 gcloud CLI

如果指定了 --skip-gcloud，则跳过此阶段。

gcloud 是用于管理 Google Cloud Platform（GCP）项目的工具。gws 的 OAuth 配置需要 GCP 项目，因此提前安装会更方便。

2-1. 检查是否已安装

gcloud --version

• Windows 上使用 where gcloud 检查。
• 如果输出了版本号，直接进入 2-5（初始登录）。

2-2. 确认操作系统

使用 AskUserQuestion 确认操作系统：

我将为你安装 gcloud CLI。请告知你使用的操作系统：

1. macOS Apple Silicon（M1/M2/M3/M4）
2. macOS Intel
3. Linux x86_64
4. Linux ARM
5. Windows

2-3. 安装 macOS / Linux

根据操作系统下载对应的 URL：

操作系统	下载 URL
macOS Apple Silicon	https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
macOS Intel	https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
Linux x86_64	https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
Linux ARM	https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-arm.tar.gz

# 다운로드
curl -O {위 테이블에서 선택한 URL}

# 압축 해제
tar -xzf google-cloud-cli-*.tar.gz

# 설치 (대화형 프롬프트가 나온다)
./google-cloud-sdk/install.sh

安装脚本询问以下内容时：

• "Modify profile to update your $PATH?" → 输入 Y
• Shell 配置文件路径 → 直接按 Enter（接受默认值）

安装后，将 PATH 应用到当前 Shell：

source ~/.zshrc   # zsh
source ~/.bashrc  # bash

2-4. 安装 Windows 版

在 PowerShell 中按顺序运行以下两条命令：

# 1. 설치 프로그램 다운로드
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

# 2. 설치 프로그램 실행
& $env:Temp\GoogleCloudSDKInstaller.exe

安装界面出现后：

1. 使用默认选项，点击 Next 继续
2. 在最后一个界面中取消勾选 "Run gcloud init"（将在 Phase 3 中单独进行）
3. 点击 Finish

安装后，将 PATH 应用到当前 Shell：

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

2-5. 确认安装并初始登录

gcloud --version

如果输出了版本号，请进行初始登录：

gcloud auth login

浏览器打开后，使用 Google 账号登录。接下来配置 OAuth 时访问 GCP 项目将使用此身份验证。

---

Phase 3：配置 OAuth（gws auth setup）

此阶段将设置 OAuth 身份验证，以便使用 Google API。 首次操作时看起来可能比较复杂，但 gws auth setup 命令会自动完成大部分工作。

运行前，先向用户说明完整流程：

现在开始配置 OAuth 身份验证。总共会自动进行 5 个步骤：

1. 选择现有 GCP 项目或创建新项目
2. 配置 OAuth 同意屏幕（设置应用名称和用户类型）
3. 启用 Google API（Gmail、Drive、Sheets、Docs 等）
4. 创建 OAuth 客户端 ID
5. 保存身份验证信息文件

大部分步骤都会自动完成，只需手动选择几项。

3-1. 确认 GCP 项目

使用 AskUserQuestion 进行确认：

你有现成的 GCP 项目吗？

• 有 → 请告知项目 ID（例如：my-gws-project）
• 没有或不确定 → 我将创建一个新项目（按 Enter）

3-2. 运行 setup

# 기존 프로젝트가 있는 경우
gws auth setup --project {PROJECT_ID} --login

# 새 프로젝트를 생성하는 경우
gws auth setup --login

3-3. 交互式提示说明

运行命令期间，浏览器中会打开设置页面。请按以下顺序引导用户：

1. GCP 项目：选择现有项目，或输入新项目名称
2. OAuth 同意屏幕 — 在浏览器中按顺序填写：
   1. 应用名称：可自由命名（例如："GWS CLI"、"我的工作区"等）
   2. 用户支持邮箱：选择当前登录的 Google 账号邮箱
   3. 开发者联系邮箱：输入同一个邮箱
   4. 受众群体（User Type）：
      • 公司/学校 Google Workspace 账号 → 选择内部（Internal）（推荐，无需额外设置）
      • 个人 Gmail（@gmail.com）→ 选择外部（External）
   5. 点击创建 → 其余项目保留默认值，点击保存并继续，直至完成
   6. 仅当选择了外部（External）时：需要添加测试用户
      • OAuth 同意屏幕 → 受众群体标签页 → 测试用户部分
      • 点击 Add users → 添加用于登录的本人 Gmail 账号 → 保存
      • 如果遗漏此步骤，Phase 4 中会出现**“访问被屏蔽：授权错误”**
3. 启用 API：Gmail、Drive、Sheets、Docs、Calendar 等 — 自动处理
4. OAuth 客户端 ID：自动创建为 Desktop app 类型
5. 保存 client_secret.json：屏幕上显示客户端 ID 和密钥后，点击下载 JSON按钮，或复制显示的 JSON

3-4. 保存 client_secret.json

将下载或复制的 JSON 保存到 ~/.config/gws/client_secret.json：

# 디렉토리가 없으면 생성
mkdir -p ~/.config/gws

# 복사한 JSON을 붙여넣기 (Ctrl+V 후 Ctrl+D로 저장)
cat > ~/.config/gws/client_secret.json

Windows：

mkdir -Force "$env:USERPROFILE\.config\gws"

# 메모장으로 열어서 JSON 붙여넣기 후 저장
notepad "$env:USERPROFILE\.config\gws\client_secret.json"

3-5. 确认配置

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

如果能看到文件，即表示成功。

---

Phase 4：登录（gws auth login）

OAuth 设置已完成，现在登录 Google 账号。

4-1. 选择认证范围

使用 AskUserQuestion 提示用户：

请选择要访问的 Google 服务：

1. 仅限必要服务（推荐） — Gmail、Drive、Sheets、Calendar、Docs
2. 只读 — 只能读取所有服务
3. 完整权限 — 对所有服务具有读写权限（可能会出现 restricted_client 警告）

根据选择，在后台执行命令（run_in_background: true）。 这样做是为了避免 Claude 在等待认证 URL 时停止响应。

# 1번 선택
gws auth login -s gmail,drive,sheets,calendar,docs

# 2번 선택
gws auth login --readonly

# 3번 선택
gws auth login --full

4-2. 在浏览器中登录

命令在后台运行后，向用户说明：

认证 URL 位于 Bash 输出中。 按 Ctrl+O 展开输出，然后复制 URL 并粘贴到浏览器中。 在浏览器中完成认证后，请告知我。

认证页面在浏览器中打开后，按以下顺序操作：

1. 选择 Google 账号
2. 出现 “此应用未经 Google 验证” 的警告——这是正常的。 个人 OAuth 应用未经 Google 审核，因此始终会显示此警告。
3. 点击 “高级”
4. 点击 “前往（应用名称）（不安全）”
5. 查看请求的权限，然后点击 “允许”

4-3. 确认登录

用户表示已完成认证后，使用 gws auth status 确认：

gws auth status

如果显示了已认证的账号和范围，则表示成功。

4-4. 简单功能测试

# Gmail: 최근 메일 1건 조회
gws gmail users.messages list --userId me --maxResults 1

# Drive: 파일 1건 조회
gws drive files list --pageSize 1

如果有结果输出，说明 gws 正常运行。

---

Phase 5：安装 Claude Code 技能

如果使用 --skip-skills，则跳过此 Phase。

安装 gws 的 Claude Code 技能后，即可在 Claude Code 中直接使用 /gws-gmail-send、/gws-drive 等命令。

npx skills add https://github.com/googleworkspace/cli

安装后重启 Claude Code，gws-* 技能就会出现在 / 菜单中。

---

Phase 6：韩文编码说明

说明使用 gws 处理韩文文本时需要了解的核心规则。 详细内容整理在 /gws-korean-encoding 技能中。

向用户说明以下要点：

必须了解的 3 件事

1. 电子邮件地址中的韩文姓名 — 需要使用 RFC 2047 Base64 编码

   # "홍길동 <[email protected]>" → 이렇게 인코딩
   =?UTF-8?B?7ZmN6ri464+Z?= <[email protected]>
   

   # 인코딩 생성 방법
   echo -n "홍길동" | base64
   

2. 用双引号括起韩文参数

   gws gmail users.messages send --userId me --subject "회의 안내"
   

3. 较长的韩文文本使用临时文件

   echo "긴 본문..." > /tmp/body.txt
   gws gmail users.messages send --userId me --bodyFile /tmp/body.txt
   

如果遇到韩文乱码问题，请参阅 /gws-korean-encoding 技能中的调试检查清单。

---

完成确认

所有 Phase 结束后，进行最终检查：

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

向用户展示结果摘要表：

项目	状态	备注
gws CLI	✅ / ❌	版本
gcloud CLI	✅ / ❌ / ⏭️ 跳过	版本
OAuth 设置	✅ / ❌	client_secret.json 是否存在
认证登录	✅ / ❌	已认证的范围
Claude Code 技能	✅ / ❌ / ⏭️ 跳过	gws-* 技能数量
韩文编码	ℹ️ 已完成说明	—

---

问题排查

详细的故障排查请参阅 references/troubleshooting.md。

常见问题：

症状	解决方法
gws: command not found	npm config get prefix → 将 {prefix}/bin 添加到 PATH
gcloud: command not found	重新打开终端，或运行 source ~/.zshrc
restricted_client 警告	正常。只能使用已注册为测试用户的账号
invalid_grant	令牌已过期。重新运行 gws auth login
PERMISSION_DENIED	使用 gws auth setup 重新启用 API，然后运行 gws auth login
Windows 中无法识别命令	重新打开 PowerShell/CMD。检查 PATH