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の場合、このPhaseをスキップします。

gcloudはGoogle Cloud Platform（GCP）プロジェクトを管理するツールです。gwsのOAuth設定にはGCPプロジェクトが必要なため、事前にインストールしておくと便利です。

2-1. すでにインストールされているか確認

gcloud --version

• Windowsではwhere gcloudで確認します。
• バージョンが表示された場合は、2-5（初回ログイン）に進みます。

2-2. OSの確認

AskUserQuestionでOSを確認します：

gcloud CLIをインストールします。お使いのOSを教えてください：

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

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

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

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

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

インストールスクリプトで質問された項目：

• 「Modify profile to update your $PATH?」 → Yを入力
• シェルプロファイルのパス → そのままEnterを押します（デフォルト値を受け入れます）

インストール後、PATHを現在のシェルに反映します：

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

2-4. Windowsへのインストール

PowerShellで次の2つのコマンドを順番に実行します：

# 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を現在のシェルに反映します：

$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）

この段階では、Google APIを使用できるようにOAuth認証を設定します。 初めてだと複雑に見えますが、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

ファイルが表示されたら成功です。

---

フェーズ 4：ログイン（gws auth login）

OAuth の設定が完了したので、Google アカウントにログインします。

4-1. 認証スコープを選択する

AskUserQuestion で案内します：

アクセスする Google サービスを選択してください：

1. 必要なサービスのみ（推奨） — Gmail、Drive、Sheets、Calendar、Docs
2. 読み取り専用 — すべてのサービスで読み取りのみ
3. すべての権限 — すべてのサービスで読み取り／書き込み（restricted_client の警告が表示される場合があります）

選択に応じて、コマンドをバックグラウンドで実行します（run_in_background: true）。 認証 URL を待つ間、Claude が停止しないようにするためです。

# 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 は正常に動作しています。

---

フェーズ 5：Claude Code スキルをインストールする

--skip-skills が指定されている場合、このフェーズをスキップします。

gws の Claude Code スキルをインストールすると、/gws-gmail-send や /gws-drive などのコマンドを Claude Code ですぐに使えるようになります。

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

インストール後に Claude Code を再起動すると、gws-* スキルが / メニューに表示されます。

---

フェーズ 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 スキルのデバッグチェックリストを参照してください。

---

完了の確認

すべてのフェーズが完了したら、最終確認を行います：

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 を確認してください