gws-setup

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

Claude Code 用の OAuth 認証情報と 90 以上のエージェントスキルを使用して、gws CLI（@googleworkspace/cli）をセットアップします。Gmail、Drive、Calendar、Sheets、Docs、Chat、Tasks などのスキルを備えた、認証済みの CLI を作成します。

前提条件

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

ワークフロー

Step 1: 事前確認

すでに完了している項目を確認し、完了済みの手順はスキップします。

# Check if gws is installed
which gws && gws --version

# Check if client_secret.json exists
ls ~/.config/gws/client_secret.json

# Check if already authenticated
gws auth status

gws auth status にスコープとともに "status": "success" と表示される場合は、Step 6（スキルのインストール）に進みます。

Step 2: CLI をインストールする

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

Step 3: GCP プロジェクトと OAuth 認証情報を作成する

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

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

ユーザーに次のページを案内します：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 アプリ設定が必要です。下記を参照）
• Tasks API
• People API
• Google Slides API
• Google Forms API
• Admin SDK API（省略可能 — Workspace 管理機能用）

3c. Google Chat アプリを設定する（Chat API に必須）：

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

ユーザーに次のページを案内します：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 同意画面を設定する：

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

設定：

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

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

ユーザーに次のページを案内します：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：スコープを選択する

必要なアクセスレベルをユーザーに確認します。

オプション	コマンド	付与される権限
フルアクセス（推奨）	gws auth login --full	admin、pubsub、cloud-platform を含むすべての Workspace スコープ
コアサービス	gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks	よく使われるサービスのみ
最小限	gws auth login -s gmail,calendar	メールとカレンダーのみ

パワーユーザーにはフルアクセスを推奨します。OAuth 同意画面には、要求されているすべてのスコープが表示されるため、ユーザーは許可する前に確認できます。

注：GCP アプリが「Testing」ステータスの場合、選択できるスコープは約 25 個に制限されます。対象を絞ったスコープを要求するには -s service1,service2 を使用するか、より広いスコープにアクセスできるよう、アプリを公開します（Publish → In Production）。

ステップ 5：認証する

重要：このステップでは、ユーザーがブラウザーで開く必要がある、非常に長い OAuth URL（30 以上のスコープ）が出力されます。URL が長すぎて、ターミナル出力からコピーできません。複数行に折り返されて壊れてしまうため、必ずファイルに抽出してプログラムから開いてください。

1. ログインコマンドを実行し、出力を取得します。

gws auth login --full 2>&1 | tee /tmp/gws-auth-output.txt
# Or with specific services:
# 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" と表示されます。

ステップ 6：エージェントスキルをインストールする

Claude Code 用の 90 個以上の gws エージェントスキルをグローバルにインストールします。

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

スキルがインストールされていることを確認します。

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

30 個以上の gws スキルディレクトリが表示されます。

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

ユーザーがほかのマシンもセットアップする場合は、クライアント認証情報のエクスポートを提案します。

gws auth export

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

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

ステップ 8：すべてが動作することを確認する

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

# Check auth
gws auth status

# Check calendar
gws calendar +agenda --today

# Check email
gws gmail +triage

認証エラーでコマンドが失敗した場合は、必要なスコープを指定して gws auth login を再実行します。

---

重要なパターン

テスト用 OAuth アプリと本番用 OAuth アプリ

GCP OAuth アプリは、トークンの有効期限が 7 日で、スコープが約 25 個に制限された「Testing」ステータスで開始します。長期的に使用するには、次の手順を実行します。

• OAuth 同意画面の設定で、アプリを本番環境に移行します
• 本番アプリにはトークンの有効期限の制限がありません
• 個人用または内部用では、Google による検証は不要です

スコープのリファレンス

サービスフラグ	有効になる機能
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 コマンドの認証パターンとグローバルフラグ