Google Workspace CLI — 初回セットアップ

gws CLI (@googleworkspace/cli) を OAuth 認証情報と 90+ のエージェントスキルを使って Claude Code 向けにセットアップします。Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks 等のスキルを備えた、完全に認証済みの CLI を構築します。

前提条件

• Node.js 18+
• Google アカウント（個人アカウントまたは Workspace アカウント）
• Google Cloud Console へのアクセス（console.cloud.google.com）

ワークフロー

ステップ 1: 事前チェック

既に完了している内容を確認し、完了したステップはスキップします：

# gws がインストールされているか確認
which gws && gws --version

# client_secret.json が存在するか確認
ls ~/.config/gws/client_secret.json

# 既に認証済みか確認
gws auth status

gws auth status が "status": "success" と scopes を表示している場合は、ステップ 6（スキルのインストール）にスキップします。

ステップ 2: CLI をインストール

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

ステップ 3: GCP プロジェクトと OAuth 認証情報を作成

ユーザーが Google Cloud Console で OAuth デスクトップアプリの認証情報を作成する必要があります。各ステップを案内してください。

3a. GCP プロジェクトを作成または選択：

ユーザーを次のURL に案内します：https://console.cloud.google.com/projectcreate

または既存のプロジェクトを使用します。どちらを希望するかユーザーに尋ねます。

3b. Google Workspace API を有効化：

ユーザーのプロジェクト用 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（Chat App の追加設定が必要 — 下記参照）
• Tasks API
• People API
• Google Slides API
• Google Forms API
• Admin SDK API（オプション — Workspace 管理者機能用）

3c. Google Chat App を設定（Chat API に必須）：

Chat API の有効化だけでは不十分です。ユーザーコンテキスト OAuth アクセスの場合でも、Google は Chat App の設定を要求します。これがないと、すべての Chat API 呼び出しがエラーを返します。

ユーザーを次のURL に案内します：https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

1. Configuration タブをクリック
2. アプリの詳細（名前、アバター、説明など）を入力（CLI 使用の場合は値は関係ありません）
3. Functionality で Spaces and group conversations をチェック
4. Connection settings で Apps Script または HTTP endpoint を選択（どちらを選んでも構いません。設定が存在することが重要です）
5. 保存

これにより、Chat API が必要とするアプリ ID が作成されます。gws 経由で送信されたメッセージは、認証されたユーザー（OAuth ユーザーコンテキスト）からのものとして表示され、ボットからのものではありません。

3e. OAuth 同意画面を設定：

ユーザーを次のURL に案内します：https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID

設定：

• User Type: External（すべての Google アカウントで動作）
• App name: gws CLI（または任意の名前）
• User support email: ユーザーのメールアドレス
• Developer contact: ユーザーのメールアドレス
• Scopes は空白のままにする（gws はログイン時に scopes をリクエストします）
• Google アカウントをテストユーザーとして追加（アプリが「Testing」ステータスの間は必須）
• 保存し、すべての画面を進む

3f. OAuth クライアント ID を作成：

ユーザーを次のURL に案内します：https://console.cloud.google.com/apis/credentials?project=PROJECT_ID

1. Create Credentials → OAuth client ID をクリック
2. Application type: Desktop app
3. Name: gws CLI
4. Create をクリック
5. JSON をコピーするか、client_secret_*.json ファイルをダウンロード

3g. 認証情報を保存：

ユーザーに client_secret.json の内容を提供するよう依頼（JSON を貼り付けるか、ダウンロードしたファイルパスを提供）。

mkdir -p ~/.config/gws

JSON を ~/.config/gws/client_secret.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"]
  }
}

ステップ 4: Scopes を選択

ユーザーがどのレベルのアクセスを望むかを尋ねます：

オプション	コマンド	付与内容
完全なアクセス（推奨）	gws auth login --full	管理者、pubsub、cloud-platform を含むすべての Workspace scopes
コアサービス	gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks	最も使用されるサービスのみ
最小限	gws auth login -s gmail,calendar	メールとカレンダーのみ

パワーユーザーには完全なアクセスをお勧めします。OAuth 同意画面はリクエストされたすべての scopes を表示するため、ユーザーは付与前に確認できます。

注意: GCP アプリが「Testing」ステータスの場合、scope の選択は約 25 scopes に制限されます。-s service1,service2 を使用して対象の scopes をリクエストするか、アプリを公開（Publish → In Production）してより広い scope アクセスを取得します。

ステップ 5: 認証

重要: このステップでは非常に長い OAuth URL（30+ scopes）が出力されます。ユーザーはこれをブラウザで開く必要があります。URL は長すぎてターミナル出力からコピーできません。複数行にまたがりますおかしくなります。常にこれをファイルに抽出し、プログラムで開きます。

1. ログインコマンドを実行して出力をキャプチャ：

gws auth login --full 2>&1 | tee /tmp/gws-auth-output.txt
# または特定のサービスを指定：
# gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks 2>&1 | tee /tmp/gws-auth-output.txt

バックグラウンドタスクとして実行しても構いません。ユーザーがブラウザで承認するとコンプリートします。

2. URL を抽出して開く（出力が表示された後に別途実行）：

grep -o 'https://accounts.google.com[^ ]*' /tmp/gws-auth-output.txt > /tmp/gws-auth-url.txt
cat /tmp/gws-auth-url.txt | xargs open

open が機能しない場合、ユーザーに以下のように伝えます：「認証 URL は /tmp/gws-auth-url.txt に保存されています。そのファイルを開いて URL をコピーしてください。」

3. ユーザーがブラウザで承認するまで待機。

ブラウザで承認した後、gws は暗号化された認証情報を ~/.config/gws/credentials.enc に保存します。

確認：

gws auth status

"status": "success" と認証済みアカウント及び付与された scopes を表示する必要があります。

ステップ 6: エージェントスキルをインストール

90+ の gws エージェントスキルをグローバルに Claude Code 向けにインストール：

npx skills add googleworkspace/cli -g --agent claude-code --all

スキルがインストールされているか確認：

ls ~/.claude/skills/gws-* | wc -l

30+ の gws スキルディレクトリが表示される必要があります。

ステップ 7: 他のマシン用に認証情報を保存

ユーザーが他のマシンをセットアップする場合、クライアント認証情報をエクスポートすることを提案します：

gws auth export

これは復号化された認証情報（リフレッシュトークンを含む）を stdout に出力します。client_secret.json ファイルはポータブルな部分です。同じ OAuth クライアントを任意のマシンで使用でき、マシンごとに gws auth login が新しいユーザートークンを生成します。

client_secret.json の内容をセキュアな場所（パスワードマネージャー、暗号化されたメモ）に保存し、他のマシン上の gws-install スキルで使用するようにユーザーに伝えます。

ステップ 8: すべてが機能していることを確認

いくつかのコマンドを実行して確認：

# 認証を確認
gws auth status

# カレンダーを確認
gws calendar +agenda --today

# メールを確認
gws gmail +triage

いずれかのコマンドが認証エラーで失敗した場合、必要な scopes で gws auth login を再実行します。

---

重要なパターン

Testing vs Production OAuth アプリ

GCP OAuth アプリは「Testing」ステータスで開始し、7 日間のトークン有効期限と約 25 scope の制限があります。長期使用の場合：

• アプリを OAuth 同意画面の設定で Production にプッシュ
• Production アプリはトークン有効期限の制限がありません
• 個人使用 / 内部使用の場合、Google は検証を要求しません

Scope リファレンス

サービスフラグ	有効化内容
gmail	メール送受信、管理、ラベル、フィルター
drive	ファイル、フォルダ、共有ドライブ
calendar	イベント、カレンダー、空き時間情報
sheets	スプレッドシートの読み書き
docs	ドキュメントの読み書き
chat	スペース、メッセージ
tasks	タスクリストとタスク
slides	プレゼンテーション
forms	フォームと回答
people	連絡先とプロフィール
admin	Workspace 管理者（ディレクトリ、デバイス、グループ）

環境変数の代替

client_secret.json の代わりに、認証情報を環境変数で提供できます：

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"
gws auth login

設定ディレクトリ

すべての gws 設定は ~/.config/gws/ にあります：

ファイル	目的
client_secret.json	OAuth クライアント認証情報（ポータブル）
credentials.enc	暗号化されたユーザートークン（マシン固有）
token_cache.json	トークンリフレッシュキャッシュ
cache/	API ディスカバリースキーマキャッシュ

参照

• gws-install — 既存の認証情報を使用した追加マシンでのクイックセットアップ
• gws-shared — gws コマンドの認証パターンとグローバルフラグ