gws-korean-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Workspace CLI(gws) 설치 및 설정

Google Workspace CLI(gws) 安装与设置

gws CLI를 처음 설치하는 사용자를 위한 단계별 안내. 총 6단계로 진행되며, 각 단계가 끝날 때마다 정상 설치를 확인한다.

本文为首次安装gws CLI的用户提供分步指引，共分为6个阶段，每个阶段结束后请确认是否安装正常。

인수 처리

参数处理

$ARGUMENTS

에서 다음 플래그를 파싱한다:

```
--skip-gcloud
```
→ Phase 2(gcloud 설치)를 건너뛴다
```
--skip-skills
```
→ Phase 5(Claude Code 스킬 설치)를 건너뛴다

从

$ARGUMENTS

中解析以下标志：

```
--skip-gcloud
```
→ 跳过阶段2（gcloud安装）
```
--skip-skills
```
→ 跳过阶段5（Claude Code技能安装）

Phase 1: gws CLI 설치

阶段1: gws CLI 安装

gws는 npm 패키지로 배포된다. Node.js가 설치되어 있어야 한다.

gws以npm包形式发布，需提前安装Node.js。

1-1. 이미 설치되어 있는지 확인

1-1. 检查是否已安装

bash

which gws && gws --version

Windows에서는
```
where gws
```
로 확인한다.
버전이 출력되면 Phase 2로 바로 진행한다.

bash

which gws && gws --version

Windows系统请使用
```
where gws
```
命令检查
若能输出版本号，可直接进入阶段2

1-2. 설치

1-2. 安装

bash

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: 관리자 권한으로 터미널을 다시 열고 재시도.

bash

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. 설치 확인

1-3. 确认安装成功

bash

gws --version

버전 번호가 출력되면 성공.

bash

gws --version

输出版本号即为安装成功

Phase 2: gcloud CLI 설치

阶段2: gcloud CLI 安装

--skip-gcloud
이면 이 Phase를 건너뛴다.
gcloud는 Google Cloud Platform(GCP) 프로젝트를 관리하는 도구다. gws의 OAuth 설정에서 GCP 프로젝트가 필요하므로 미리 설치해두면 편하다.

若使用
--skip-gcloud
标志，则跳过本阶段
gcloud是管理Google Cloud Platform(GCP)项目的工具，由于gws的OAuth设置需要GCP项目，提前安装会更便捷

2-1. 이미 설치되어 있는지 확인

2-1. 检查是否已安装

bash

gcloud --version

Windows에서는
```
where gcloud
```
로 확인한다.
버전이 출력되면 2-5(초기 로그인)로 바로 진행한다.

bash

gcloud --version

Windows系统请使用
```
where gcloud
```
命令检查
若能输出版本号，可直接进入2-5（初始登录）

2-2. OS 확인

2-2. 确认操作系统

AskUserQuestion

으로 OS를 확인한다:

gcloud CLI를 설치할게요. 사용 중인 OS를 알려주세요:

macOS Apple Silicon (M1/M2/M3/M4)

macOS Intel

Linux x86_64

Linux ARM

Windows

通过

AskUserQuestion

确认操作系统：

即将为您安装gcloud CLI，请告知您正在使用的操作系统：

macOS Apple Silicon (M1/M2/M3/M4)

macOS Intel

Linux x86_64

Linux ARM

Windows

2-3. macOS / Linux 설치

2-3. macOS / Linux 安装

OS에 맞는 URL로 다운로드한다:

OS	다운로드 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`

bash

undefined

根据操作系统选择对应的下载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`

bash

undefined

다운로드

下载

curl -O {위 테이블에서 선택한 URL}

curl -O {从上方表格中选择的URL}

압축 해제

解压

tar -xzf google-cloud-cli-*.tar.gz

설치 (대화형 프롬프트가 나온다)

安装（会出现交互式提示）

./google-cloud-sdk/install.sh


설치 스크립트가 질문하는 항목:
- **"Modify profile to update your $PATH?"** → `Y` 입력
- **쉘 프로파일 경로** → 그냥 Enter (기본값 수락)

설치 후 PATH를 현재 셸에 반영한다:

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

./google-cloud-sdk/install.sh


安装脚本的提问项：
- **"Modify profile to update your $PATH?"** → 输入`Y`
- **Shell配置文件路径** → 直接按Enter（接受默认值）

安装完成后，将PATH更新到当前Shell：

```bash
source ~/.zshrc   # zsh环境
source ~/.bashrc  # bash环境

2-4. Windows 설치

2-4. Windows 安装

PowerShell에서 다음 두 명령어를 순서대로 실행한다:

powershell

undefined

在PowerShell中依次执行以下两条命令：

powershell

undefined

1. 설치 프로그램 다운로드

1. 下载安装程序

(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

2. 설치 프로그램 실행

2. 运行安装程序

& $env:Temp\GoogleCloudSDKInstaller.exe


설치 화면이 뜨면:
1. 기본 옵션으로 **Next** 클릭하며 진행
2. 마지막 화면에서 **"Run gcloud init" 체크를 해제** (Phase 3에서 별도 진행)
3. **Finish** 클릭

설치 후 PATH를 현재 셸에 반영한다:

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

& $env:Temp\GoogleCloudSDKInstaller.exe


出现安装界面后：
1. 选择默认选项点击**Next**继续
2. 在最后一步取消勾选**"Run gcloud init"**（将在阶段3单独进行）
3. 点击**Finish**完成安装

安装完成后，将PATH更新到当前Shell：

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

2-5. 설치 확인 및 초기 로그인

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

bash

gcloud --version

버전이 나오면 초기 로그인을 한다:

bash

gcloud auth login

브라우저가 열리면 Google 계정으로 로그인한다. 이 인증은 다음 단계(OAuth 설정)에서 GCP 프로젝트에 접근할 때 사용된다.

bash

gcloud --version

若能输出版本号，进行初始登录：

bash

gcloud auth login

浏览器将自动打开，请使用Google账号登录，该认证将在后续步骤（OAuth设置）中用于访问GCP项目

Phase 3: OAuth 설정 (gws auth setup)

阶段3: OAuth 配置 (gws auth setup)

이 단계에서는 Google API를 사용할 수 있도록 OAuth 인증을 설정한다. 처음 하면 복잡해 보이지만,
gws auth setup
명령이 대부분 자동으로 처리해준다.

실행 전에 사용자에게 전체 흐름을 미리 안내한다:

이제 OAuth 인증을 설정합니다. 총 5단계가 자동으로 진행됩니다:

GCP 프로젝트 선택 또는 새로 만들기

OAuth 동의 화면 구성 (앱 이름, 사용자 유형 설정)

Google API 활성화 (Gmail, Drive, Sheets, Docs 등)

OAuth 클라이언트 ID 생성

인증 정보 파일 저장

대부분 자동이고, 몇 가지만 직접 선택하면 됩니다.

本阶段将配置OAuth认证，以实现对Google API的调用初次操作可能看似复杂，但
gws auth setup
命令会自动完成大部分流程

执行前，提前向用户说明整体流程：

接下来将进行OAuth认证配置，共分为5个自动执行的步骤：

选择或创建GCP项目

配置OAuth同意屏幕（设置应用名称、用户类型）

启用Google API（Gmail、Drive、Sheets、Docs等）

创建OAuth客户端ID

保存认证信息文件

大部分流程为自动执行，仅需您进行少量选择操作

3-1. GCP 프로젝트 확인

3-1. 确认GCP项目情况

AskUserQuestion

으로 확인한다:

기존 GCP 프로젝트가 있으신가요?
있다면 → 프로젝트 ID를 알려주세요 (예:
my-gws-project
)
없거나 모르겠다면 → 새로 만들겠습니다 (Enter)

通过

AskUserQuestion

确认：

您是否已有GCP项目？
有 → 请告知项目ID（示例：
my-gws-project
）
没有或不清楚 → 将为您创建新项目（直接按Enter）

3-2. setup 실행

3-2. 执行setup命令

bash

undefined

bash

undefined

기존 프로젝트가 있는 경우

已有GCP项目的情况

gws auth setup --project {PROJECT_ID} --login

새 프로젝트를 생성하는 경우

创建新项目的情况

gws auth setup --login

undefined

gws auth setup --login

undefined

3-3. 대화형 프롬프트 안내

3-3. 交互式提示指引

명령 실행 중 브라우저에서 설정 화면이 열린다. 사용자에게 다음 순서로 안내한다:

GCP 프로젝트: 기존 프로젝트를 선택하거나 새 이름을 입력
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에서 "액세스 차단됨: 승인 오류" 가 발생한다
API 활성화: Gmail, Drive, Sheets, Docs, Calendar 등 — 자동으로 처리됨
OAuth 클라이언트 ID: Desktop app 타입으로 자동 생성됨
client_secret.json 저장: 화면에 클라이언트 ID와 시크릿이 표시되면 JSON 다운로드 버튼을 클릭하거나, 표시된 JSON을 복사한다

执行命令后，浏览器将打开设置界面，请引导用户按以下步骤操作：

GCP项目：选择已有项目或输入新项目名称
OAuth同意屏幕 — 在浏览器中按以下步骤操作：
1. 应用名称：可自由命名（示例："GWS CLI"、"我的工作区"等均可）
2. 用户支持邮箱：选择当前登录的Google账号邮箱
3. 开发者联系邮箱：输入同一邮箱
4. 用户类型（User Type）：
  - 公司/学校Google Workspace账号 → 选择内部(Internal)（推荐，无需额外设置）
  - 个人Gmail(@gmail.com)账号 → 选择外部(External)
5. 点击创建 → 其余选项均保持默认，点击保存并继续直到完成
6. 仅当选择外部(External)时：需要注册测试用户
  - 进入OAuth同意屏幕 → 用户类型标签页 → 测试用户区域
  - 点击Add users → 添加用于登录的个人Gmail账号 → 保存
  - 若跳过此步骤，阶段4将出现**"访问被阻止：授权错误"**问题
API启用：Gmail、Drive、Sheets、Docs、Calendar等将自动启用
OAuth客户端ID：将自动创建Desktop app类型的客户端ID
保存client_secret.json：当屏幕显示客户端ID和密钥时，点击JSON下载按钮，或复制显示的JSON内容

3-4. client_secret.json 저장

3-4. 保存client_secret.json

다운로드하거나 복사한 JSON을

~/.config/gws/client_secret.json

에 저장한다:

bash

undefined

将下载或复制的JSON保存到

~/.config/gws/client_secret.json

：

bash

undefined

디렉토리가 없으면 생성

若目录不存在则创建

mkdir -p ~/.config/gws

복사한 JSON을 붙여넣기 (Ctrl+V 후 Ctrl+D로 저장)

粘贴复制的JSON内容（按Ctrl+V后按Ctrl+D保存）

cat > ~/.config/gws/client_secret.json


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

cat > ~/.config/gws/client_secret.json


Windows系统操作：
```powershell
mkdir -Force "$env:USERPROFILE\.config\gws"

메모장으로 열어서 JSON 붙여넣기 후 저장

打开记事本粘贴JSON内容后保存

notepad "$env:USERPROFILE.config\gws\client_secret.json"

undefined

notepad "$env:USERPROFILE.config\gws\client_secret.json"

undefined

3-5. 설정 확인

3-5. 确认配置成功

bash

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

파일이 보이면 성공.

bash

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

若能看到文件，则配置成功

Phase 4: 로그인 (gws auth login)

阶段4: 登录 (gws auth login)

OAuth 설정이 끝났으니, 이제 실제로 Google 계정에 로그인한다.

OAuth配置完成后，现在可以登录您的Google账号了

4-1. 인증 범위 선택

4-1. 选择认证范围

AskUserQuestion

으로 안내한다:

어떤 Google 서비스에 접근할지 선택해주세요:

필요한 서비스만 (권장) — Gmail, Drive, Sheets, Calendar, Docs

읽기 전용 — 모든 서비스를 읽기만

전체 권한 — 모든 서비스에 읽기/쓰기 (restricted_client 경고가 나올 수 있음)

선택에 따라 명령어를 백그라운드로 실행한다 (

run_in_background: true

). 인증 URL 대기 중 Claude가 멈추지 않도록 하기 위함이다.

bash

undefined

通过

AskUserQuestion

引导用户选择：

请选择需要访问的Google服务：

仅必要服务（推荐） — Gmail、Drive、Sheets、Calendar、Docs

只读权限 — 仅可读取所有服务内容

完整权限 — 可读写所有服务内容（可能会出现restricted_client提示）

根据用户选择，在后台执行对应命令（

run_in_background: true

），避免Claude在等待认证URL时停滞：

bash

undefined

1번 선택

选择1的情况

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

2번 선택

选择2的情况

gws auth login --readonly

3번 선택

选择3的情况

gws auth login --full

undefined

gws auth login --full

undefined

4-2. 브라우저에서 로그인

4-2. 在浏览器中完成登录

명령이 백그라운드에서 실행되면 사용자에게 안내한다:

인증 URL이 Bash 출력에 있습니다. Ctrl+O 를 눌러 출력을 펼친 뒤, URL을 복사해서 브라우저에 붙여넣기 해주세요. 브라우저에서 인증을 완료하면 알려주세요.

브라우저에서 인증 페이지가 열리면 다음 순서로 진행된다:

Google 계정을 선택한다
"이 앱은 Google의 인증을 받지 않았습니다" 라는 경고가 나온다 — 이것은 정상이다. 개인용 OAuth 앱은 Google 심사를 받지 않으므로 항상 이 경고가 표시된다.
"고급" 을 클릭한다
"(앱 이름)(으)로 이동 (안전하지 않음)" 을 클릭한다
요청된 권한을 확인하고 "허용" 을 클릭한다

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

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

浏览器打开认证页面后，按以下步骤操作：

选择Google账号
出现**"此应用未获得Google认证"**提示 — 此为正常现象，个人OAuth应用未经过Google审核，因此会显示该提示
点击**"高级"**
点击**"前往(应用名称)（不安全）"**
确认请求的权限后，点击**"允许"**

4-3. 로그인 확인

4-3. 确认登录成功

사용자가 인증을 마쳤다고 하면

gws auth status

로 확인한다:

bash

gws auth status

인증된 계정과 스코프가 표시되면 성공.

用户告知认证完成后，执行

gws auth status

确认：

bash

gws auth status

若显示已认证的账号和权限范围，则登录成功

4-4. 간단한 동작 테스트

4-4. 简单功能测试

bash

undefined

bash

undefined

Gmail: 최근 메일 1건 조회

Gmail: 查询最近1封邮件

gws gmail users.messages list --userId me --maxResults 1

Drive: 파일 1건 조회

Drive: 查询1个文件

gws drive files list --pageSize 1


결과가 나오면 gws가 정상 작동하는 것이다.

---

gws drive files list --pageSize 1


若能返回结果，则说明gws已正常运行

---

Phase 5: Claude Code 스킬 설치

阶段5: Claude Code 技能安装

--skip-skills
이면 이 Phase를 건너뛴다.
gws의 Claude Code 스킬을 설치하면
/gws-gmail-send
,
/gws-drive
같은 명령을 Claude Code에서 바로 쓸 수 있다.

bash

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

설치 후 Claude Code를 재시작하면 gws-* 스킬들이

메뉴에 나타난다.

若使用
--skip-skills
标志，则跳过本阶段
安装gws的Claude Code技能后，可在Claude Code中直接使用
/gws-gmail-send
、
/gws-drive
等命令

bash

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

安装完成后，重启Claude Code，gws-*技能将出现在

菜单中

Phase 6: 한국어 인코딩 안내

阶段6: 韩语编码说明

gws로 한국어 텍스트를 다룰 때 알아야 할 핵심 규칙을 안내한다. 자세한 내용은
/gws-korean-encoding
스킬에 정리되어 있다.

사용자에게 다음 핵심 사항을 안내한다:

为您介绍使用gws处理韩语文本时需了解的核心规则，详细内容可参考
/gws-korean-encoding
技能

向用户说明以下核心要点：

꼭 알아야 할 3가지

必须掌握的3项规则

이메일 주소의 한글 이름 — RFC 2047 Base64 인코딩이 필요하다

# "홍길동 <hong@example.com>" → 이렇게 인코딩
=?UTF-8?B?7ZmN6ri464+Z?= <hong@example.com>

bash

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

한글 파라미터는 큰따옴표로 감싸기

bash

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

긴 한글 텍스트는 임시 파일 사용

bash

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

한글이 깨지는 문제가 생기면
/gws-korean-encoding
스킬의 디버깅 체크리스트를 참조하세요.

邮箱地址中的韩语名称 — 需要使用RFC 2047 Base64编码

# "홍길동 <hong@example.com>" → 编码后格式
=?UTF-8?B?7ZmN6ri464+Z?= <hong@example.com>

bash

# 生成编码的方法
echo -n "홍길동" | base64

韩语参数需用双引号包裹

bash

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

长韩语文本请使用临时文件

bash

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

若出现韩语乱码问题，请参考
/gws-korean-encoding
技能中的调试检查清单

완료 확인

完成确认

모든 Phase가 끝나면 최종 점검을 한다:

bash

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

사용자에게 결과를 요약 테이블로 보여준다:

항목	상태	비고
gws CLI	✅ / ❌	버전
gcloud CLI	✅ / ❌ / ⏭️ 스킵	버전
OAuth 설정	✅ / ❌	client_secret.json 존재 여부
인증 로그인	✅ / ❌	인증된 스코프
Claude Code 스킬	✅ / ❌ / ⏭️ 스킵	gws-* 스킬 수
한국어 인코딩	ℹ️ 안내 완료	—

所有阶段完成后，进行最终检查：

bash

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` → PATH에 `{prefix}/bin` 추가
`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 확인

详细故障排除方法请参考

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配置