Google Workspace CLI (gws) の導入ガイド — ハマりポイントと解決策

はじめに

Google Workspace CLI (gws) は、Drive・Gmail・Calendar・Sheets・Chat など Google Workspace の全APIを統一的に操作できるCLIツールです。AI エージェントとの連携も想定されており、構造化されたJSON出力や40以上のエージェントスキルが同梱されています。

しかし、実際に導入してみると 認証周りで想像以上にハマるポイント が多かったため、本記事では導入手順とトラブルシューティングをまとめます。

公式リポジトリ: https://github.com/googleworkspace/cli

環境

• Windows 11
• Node.js 18+
• gws v0.22.3
• Google Workspace アカウント（独自ドメイン）

1. インストール

npm install -g @googleworkspace/cli

Homebrew（macOS/Linux）やCargo（Rustビルド）でもインストール可能です。

# macOS / Linux
brew install googleworkspace-cli

# ソースからビルド
cargo install --git https://github.com/googleworkspace/cli --locked

2. GCPプロジェクトの準備

gws CLI は OAuth 認証を使うため、Google Cloud Platform (GCP) プロジェクトが必要です。

方法A: gws auth setup（推奨）

gcloud CLI がインストールされていれば、自動セットアップが使えます。

# gcloud CLI のインストール（未インストールの場合）
# Windows: winget install Google.CloudSDK
# macOS: brew install google-cloud-sdk

# gcloud にログイン
gcloud auth login

# gws のセットアップ（プロジェクト指定）
gws auth setup --project YOUR_PROJECT_ID

gws auth setup は以下を自動で行います：

• GCPプロジェクトの確認
• 必要なAPIの有効化
• OAuthクライアントIDの作成案内

ただし、OAuthクライアントIDの作成はGCPコンソールでの手動操作が必要です。セットアップ中にClient IDとClient Secretの入力を求められます。

方法B: 手動セットアップ

1. GCPコンソール でプロジェクトを作成
2. OAuth同意画面を構成（User Type: External）
3. テストユーザーに自分のメールアドレスを追加（重要！）
4. 認証情報 → OAuthクライアントID → デスクトップアプリ で作成
5. JSONをダウンロードして ~/.config/gws/client_secret.json に配置

注意: OAuthクライアントのタイプは必ず「デスクトップアプリ」を選んでください。「ウェブアプリケーション」では動きません。

3. 使用するAPIの有効化

GCPプロジェクトで、使いたいサービスのAPIを有効化する必要があります。

gcloud services enable \
  drive.googleapis.com \
  sheets.googleapis.com \
  gmail.googleapis.com \
  calendar-json.googleapis.com \
  docs.googleapis.com \
  slides.googleapis.com \
  tasks.googleapis.com \
  chat.googleapis.com \
  --project YOUR_PROJECT_ID

ハマりポイント: APIを有効化する前にログインしてトークンを取得すると、API有効化後もそのトークンでは該当サービスにアクセスできません。API有効化後に再ログインが必要です。

4. ログイン（OAuth認証）

gws auth login

ブラウザが開き、Googleアカウントの認証画面が表示されます。

スコープ選択画面

ログイン時にスコープ（権限）の選択画面が表示されます。ここが最大のハマりポイントです。

選択肢の説明

選択肢	内容	注意
Recommended	Drive, Gmail, Calendar, Docs, Sheets, Slides, Tasks	Chatは含まれない
Read Only	読み取り専用スコープ
Full Access	全スコープ（85以上）	未検証アプリでは失敗する（25スコープ制限）
個別スコープ	chat.messages, chat.spaces 等	必要なものを個別選択

推奨する選択方法

「Recommended」にチェック + Chat関連スコープを個別に追加チェック が最も確実です。

追加すべきChatスコープ：

• chat.messages — メッセージの読み書き
• chat.spaces — スペースの管理
• chat.memberships — メンバーの管理
• chat.customemojis — カスタム絵文字
• chat.users.readstate — 既読状態
• chat.users.spacesettings — スペース設定
• chat.users.sections — セクション管理
• chat.delete — 削除

重要: cloud-identity.devices など一部のスコープは invalid_scope エラーを引き起こします。Full Accessは選ばず、必要なものだけ選択してください。合計25スコープ以内に収めるのがポイントです。

5. Google Chat を使うための追加設定

Chat API は他のサービスと異なり、GCPプロジェクトで「Chat App」の構成が必須です。

1. Chat API の構成ページ を開く
2. 以下を設定：
   • アプリ名: 任意（例: gws CLI）
   • アバターURL: 任意のPNG画像URL
   • 説明: 任意
3. インタラクティブ機能を有効にする
4. 接続設定のトリガー: 「HTTP エンドポイント URL」を選択し、https://localhost と入力
5. 保存

ハマりポイント: Chat APIを有効化しただけでは不十分です。Chat Appの構成をしないと、スコープが正しくても 403 Request had insufficient authentication scopes エラーが出続けます。このエラーメッセージからはChat App未構成が原因だとは分かりにくいので要注意です。

6. 動作確認

# Drive
gws drive files list

# Gmail
gws gmail users messages list --params '{"userId": "me", "maxResults": 3}'

# Calendar（今日の予定）
gws calendar +agenda

# Sheets
gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:C10"

# Chat（スペース一覧）
gws chat spaces list

# Chat（メッセージ送信）
gws chat +send --space "spaces/SPACE_ID" --text "Hello from gws CLI!"

トラブルシューティング

invalid_scope エラー（400）

Some requested scopes cannot be shown: [https://www.googleapis.com/auth/cloud-identity.devices]

原因: Full Access で選択されるスコープの中に、未検証アプリでは使用できないものが含まれている。

解決策: Full Access ではなく、Recommended + 必要なスコープを個別選択する。

Request had insufficient authentication scopes（403）

考えられる原因が複数あります：

1. APIが有効化されていない → gcloud services enable xxx.googleapis.com で有効化後、再ログイン
2. Chat App が構成されていない → GCPコンソールでChat APIの構成を設定
3. トークンキャッシュが古い → ~/.config/gws/token_cache.json を削除して再試行
4. スコープがトークンに含まれていない → gws auth status で現在のスコープを確認

# スコープの確認
gws auth status

# トークンキャッシュの削除
rm ~/.config/gws/token_cache.json

Access blocked: 認証エラー

原因: OAuth同意画面のテストユーザーに自分のアカウントが追加されていない。

解決策: GCPコンソール → OAuth同意画面 → テストユーザー → 自分のメールアドレスを追加。

-s フラグのバグ（Issue #577）

-s（--services）フラグにはバグがあります（2026年4月時点）。

# 単一サービスは動く
gws auth login -s chat     # OK

# 複数サービスを指定するとスコープが消える
gws auth login -s chat,drive,gmail  # NG — スコープがほぼ消失する

回避策: フラグなしの gws auth login でスコープ選択画面から手動で選択する。

トークンキャッシュの問題

API有効化やスコープ変更後にコマンドが失敗する場合、古いアクセストークンが使い回されている可能性があります。

# トークンキャッシュを削除
rm ~/.config/gws/token_cache.json

# 再試行（リフレッシュトークンから新しいアクセストークンが生成される）
gws drive files list

まとめ

gws CLI は非常に便利なツールですが、認証周りのセットアップは以下の理由で複雑です：

1. OAuthスコープの25個制限（未検証アプリの場合）
2. Chat APIだけChat Appの構成が別途必要
3. -s フラグにバグがある（複数サービス指定が動かない）
4. APIの有効化タイミングとトークン発行の順序が重要
5. トークンキャッシュが古いと再ログインしても反映されない

これらを把握しておけば、スムーズに導入できるはずです。一度セットアップが完了すれば、Google Workspace の全サービスをCLIから操作でき、AIエージェントとの連携も可能になります。