（おまけ）GWS（Google Workspace CLI）で躓く「スコープ」とは？権限不足エラー（403）の原因と対処法

2026.03.08 | 2 min read

📝 おまけ記事：
brief043・brief044・brief045 の GWS（Google Workspace CLI）連載の補足です。gws を使っていくと「権限がなくて使えない」と出て躓きやすいスコープについて、原因と対処をまとめました。

また、今回は「コーナーをギリギリを攻めるゴリゴリのPowerShell構成」のカステラシステム最終安定版を作成しました。私の凄まじく古い開発環境で動作検証を重ねており、「ここで動くなら、世の中のほとんどのシステムでよりスムーズに動くはず」という 究極の互換性と安定性 を目指しています。

強力な PowerShell 制御により、「カステラ」と送るだけで環境チェックから GWS の情報収集までを自動化し、AI が最も安定して動くお膳立てを整えます。かなり強力なシステムなので、「おいしそうだなぁ～～～」と思ったらぜひ使ってみてください。

（内容は Google OAuth 2.0 スコープおよび gws 利用時の実地メモに基づきます）

GWS（Google Workspace CLI）（gws）でコマンドを実行したときに「403 Request had insufficient authentication scopes」など権限エラーになる原因は、ログイン時に付与したスコープ（権限の範囲）が足りていないためです。スコープとは何か・どう確認・追加するかを解説します。

⚡

最終安定版：kasutera-gws-cli.zip

Antigravity 連携・スコープ自動復旧キット

🚀 3分で始めるクイックスタート

ZIP をダウンロードして解凍。
Antigravity で、解凍したフォルダをプロジェクトルートとして開きます。
AI に「カステラ」と送信。PowerShell が事前情報を収集し、AI 処理の安定性を最大化します。
複雑な権限チェックや環境設定も、この「カステラ」一言で自動完結！

📦 最終安定版を一括ダウンロード

スコープとは

スコープは、gws auth login 時に「どの Google サービスに、どの程度の権限（閲覧だけか・編集も含むか）を許可するか」を指定するものです。OAuth 2.0 の仕組みで、ログイン時に選んだスコープだけがトークンに紐づき、その範囲でしか API を呼べません。足りない操作をしようとすると 403 Request had insufficient authentication scopes が返ります。

現在のスコープを確認する

今のトークンに何が付いているかは次のコマンドで確認できます。

gws auth status

出力の scopes 配列が付与済みスコープです。操作別の「必要スコープ」と照らし合わせると、何が足りないか分かります。kasutera-gws-cli 等のリポジトリに同梱している scope_check.ps1 を使うと、現在のスコープを一覧表示したり、操作（filters / drive / calendar / vacation）ごとに不足スコープと推奨ログインコマンドを表示できます。

.\scope_check.ps1
.\scope_check.ps1 -For filters
.\scope_check.ps1 -ShowLogin full

スコープのはまりポイント

gws auth login で --scopes にプリセット名（recommended など）を指定した場合、思わぬエラーや権限のずれに遭うことがあります。

プリセット名はそのまま送られる：recommended は GWS CLI 側の「おすすめセット」の呼び名であり、Google の OAuth 2.0 が認める正式なスコープ（https://www.googleapis.com/auth/... 形式）ではありません。--scopes recommended のまま実行すると、その文字列がそのまま認証サーバーに送られ、Error 400: invalid_scope になることがあります。
個人の Gmail アカウント（@gmail.com）では想定と違う動きになりやすい：CLI の「おすすめ」には、Google Workspace 管理者向けのスコープ（directory.* や cloud-identity.* など）が含まれる場合があります。個人アカウントではこれらの権限を付与できないため、ログインや同意画面の段階で拒否されたり、付与される権限が「一般的なユーザー向け」の想定と食い違うことがあります。

対策としては、オプションなしの gws auth login でログインするか、必要なスコープを https://... の形式で明示的に指定するのが安全です。原因の詳細と解決手順は、同梱の GWS_AUTH_ERROR_REPORT.md（ダウンロード）にまとめています。

403 が出たときの対処（再ログインでスコープを足す）

対処は必要なスコープを付けて再ログインすることです。gws auth login を再度実行し、ブラウザの同意画面で追加の権限を許可します。注意点：--scopes で指定したスコープのみが付与され、既存のスコープは上書きされます。複数サービスを使う場合は、必要なものをカンマ区切りでまとめて指定してください。

標準（多くの操作に対応）: gws auth login のみ。
サービスを絞る（@gmail.com でテストモード制限に引っかかる場合）: gws auth login --scopes drive,gmail,sheets,calendar
閲覧のみ: gws auth login --scopes readonly

操作・用途別の必要スコープ（要点）

代表例です。詳細は Google 公式の OAuth 2.0 スコープ一覧や各 API の認証ドキュメントを参照してください。

Gmail 送受信・ラベル・メッセージ読取: gmail.modify
Gmail フィルタ作成・不在時オート返信: gmail.modify と gmail.settings.basic の両方が必要。標準の gws auth login だけではフィルタ系は不足することがある。
Drive ファイル一覧・作成・削除: drive（閲覧のみなら drive.readonly）
Calendar 予定の表示・作成・編集: calendar（閲覧のみなら calendar.readonly）
Tasks: tasks / tasks.readonly
Sheets / Docs / Slides: spreadsheets, documents, presentations など

Gmail フィルタで 403 が出た場合の再ログイン例（他サービスは付かなくなるので、Drive 等も使うなら gws auth login でまとめて取り直すのが無難です）:

gws auth login --scopes https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.settings.basic

GWS（Google Workspace CLI）で使う全スコープ一覧（公式ベース）

以下は Google OAuth 2.0 Scopes および各 API 認証ドキュメントに基づく一覧です。gws が利用する Workspace 系 API のスコープを表形式でまとめています。

API	スコープ（略称）	説明
Gmail	`mail.google.com`	メールの読み・作成・送信・恒久削除（最大権限）
	`gmail.modify`	読み・作成・送信（恒久削除除く）※常用
	`gmail.readonly`	メール・設定の閲覧
	`gmail.send`	送信のみ
	`gmail.compose`	下書きの管理・送信
	`gmail.insert`	メールの追加
	`gmail.labels`	ラベルの表示・編集
	`gmail.metadata`	メタデータ（ラベル・ヘッダー）のみ、本文なし
	`gmail.settings.basic`	設定・フィルタの表示・編集・作成※フィルタに必須
	`gmail.settings.sharing`	転送等の機密設定（主にドメイン委任）
	`gmail.addons.current.*`	アドオン用（compose / message.action / message.metadata / message.readonly）
	※ フルURLは `https://www.googleapis.com/auth/` ＋上記（mail.google.com はそのまま）

API	スコープ（略称）	説明
Drive	`drive`	全ファイルの表示・編集・作成・削除
	`drive.readonly`	全ファイルの表示・ダウンロード
	`drive.file`	アプリで開いた/共有されたファイルのみ（非感度推奨）
	`drive.metadata.readonly`	メタデータのみ表示
	`drive.metadata`	メタデータの表示・管理
	`drive.appdata`	アプリの設定データのみ
	`drive.apps.readonly`	Drive アプリ一覧の表示
	`drive.activity` / `.readonly`	ファイルのアクティビティ記録
	`drive.scripts`	Apps Script の挙動変更

API	スコープ（略称）	説明
Calendar	`calendar`	カレンダーの表示・編集・共有・恒久削除
	`calendar.readonly`	カレンダーの表示・ダウンロード
	`calendar.events`	全カレンダーのイベント表示・編集
	`calendar.events.readonly`	イベントの表示のみ
	`calendar.freebusy`	空き情報の表示
	`calendar.settings.readonly`	Calendar 設定の表示
	`calendar.calendarlist` / `.readonly`	購読カレンダー一覧の表示・追加・削除
	`calendar.calendars` / `.readonly`	カレンダー本体のプロパティ・作成
	`calendar.acls` / `.readonly`	共有設定の表示・変更

API	スコープ（略称）	説明
Sheets	`spreadsheets`	スプレッドシートの表示・編集・作成・削除
	`spreadsheets.readonly`	スプレッドシートの表示
Docs	`documents`	ドキュメントの表示・編集・作成・削除
	`documents.readonly`	ドキュメントの表示
Slides	`presentations`	プレゼンの表示・編集・作成・削除
	`presentations.readonly`	プレゼンの表示
Tasks	`tasks`	タスクの作成・編集・整理・削除
	`tasks.readonly`	タスクの表示
People	`contacts`	連絡先の表示・編集・ダウンロード・恒久削除
	`contacts.readonly`	連絡先の表示・ダウンロード
Forms	`forms.body`	フォームの表示・編集・作成・削除
	`forms.body.readonly`	フォームの表示
	`forms.responses.readonly`	回答の表示
Keep	`keep`	Keep データの表示・編集・作成・恒久削除
	`keep.readonly`	Keep データの表示
Chat	`chat.messages`	メッセージの閲覧・送信・更新・削除・リアクション
	`chat.messages.readonly`	メッセージの閲覧
	`chat.messages.create`	メッセージの送信
	`chat.spaces` / `.readonly` / `.create`	スペース・会話の作成・メタデータ
	`chat.memberships` / `.readonly`	メンバーシップの表示・追加・削除

※ Docs/Sheets/Slides はファイル操作に drive または drive.file が必要な場合あり。出典: OAuth 2.0 Scopes for Google APIs, Gmail, Drive, Calendar 各公式ドキュメント。

参照ドキュメント（本記事の元ネタ）

本記事の内容は、kasutera-gws-cli プロジェクト内の以下のリソースにまとめています。gws を利用する環境に同梱したり、ローカルで参照してください。

GWS_AUTH_SCOPES_GUIDE.md — スコープの意味・プリセット（readonly / サービス名指定）・403 対処・Gmail フィルタ用スコープ・ブラウザ必須の説明。
GWS_SCOPE_REFERENCE.md — 操作・用途別の必要スコープ一覧、API 別の公式スコープ、略称⇔フル URL、現在のスコープ確認・付与のコマンド例。
GWS_AUTH_ERROR_REPORT.md — プリセット（recommended 等）指定時の invalid_scope・Gmail アカウントと想定権限のずれの調査レポート。（ダウンロード）
scope_check.ps1 — 現在のスコープ表示、-ShowLogin full|gmail-filters|readonly で推奨ログインコマンド表示、-For filters|drive|calendar|vacation で操作別の不足チェックと再ログイン案内。
kasutera_system_analysis.md — ZIP 同梱物の全体構成・エントリポイント・スクリプト・リソース・子スキル一覧の分析レポート（本記事配下に配置）。（ダウンロード）

これらはすべて kasutera-gws-cli プロジェクト（ZIP）に同梱しています。スコープ確認や 403 対処を手元でやりたい場合は、下記からダウンロードして解凍し、.agent/skills/kasutera_master/resources/ および scripts/scope_check.ps1 を参照してください。

📦 kasutera-gws-cli.zip のダウンロード

※ 本ZIPは 2026-03-08 時点の最終版です。同梱内容の詳細は kasutera_system_analysis.md（ダウンロード）を参照してください。

📦 kasutera-gws-cli.zip

Antigravity で GWS を使いこなすための「設定スキル」と、権限エラーを即座に解決する「スコープガイド」の詰め合わせです。

🚀 カステラスキル 「カステラ」の一言で、環境チェックから自動設定まで即座にスタート。

🛡️ スコープ完全攻略 403不足権限を判定する scope_check.ps1 と各 API 権限ガイドを同梱。

🔧 障害復旧サポート Windows でのインストール障害や認証エラーの解決手順を網羅。

※ client_secret***********.json は各自で用意が必要です。取得後、gws auth login で認証を完了してください。

📦 パッケージを一括ダウンロード

🐯 カステラ・システム完全分析レポート（最終版）

分析日時: 2026-03-08 14:05 JST ／バージョン: v2.0 ／対象: kasutera-gws-cli/.agent/ 配下の全構成要素

📐 システム全体構成図

graph TD subgraph Entry["🎯 Entry Points（ユーザーの入口）"] U["ユーザー: 「カステラ」「カステラ起動」"] W1["/kasutera ワークフロー"] W2["/kasutera-start ワークフロー"] AG["AGENTS.md 総合指令書"] end subgraph Brain["🧠 Brain（司令塔）"] SKILL["SKILL.md kasutera_master"] end subgraph Scripts["⚡ Scripts（実行エンジン）"] IGN["kasutera-ignite.ps1"] SYNC["gws-skills-sync.ps1"] ENV["check_env.ps1"] SCOPE["scope_check.ps1"] end subgraph Resources["📚 Resources（知識ベース）"] R1["GWS_AUTH_SCOPES_GUIDE.md"] R2["GWS_SCOPE_REFERENCE.md"] R3["GWS_CLI_INSTALL_ERROR_GUIDE.md"] R4["GWS_AUTH_REFERENCE.md"] R5["GWS_AUTH_ERROR_REPORT_EN.md"] end subgraph Persistence["💾 Persistence（永続化）"] ENVF[".gws_env.ps1"] CONF[".gws_config/"] end subgraph Squad["🐯 Squad（子スキル × 11）"] S1["kasutera_gmail"] S2["kasutera_drive"] S3["kasutera_sheets"] S4["kasutera_calendar"] end U --> AG AG --> W1 AG --> W2 W1 --> ENVF W2 --> ENVF ENVF --> IGN SKILL --> IGN IGN --> ENV IGN --> SYNC IGN --> CONF IGN -->|setup & auth| SKILL SKILL --> SCOPE SKILL --> R1 SKILL --> R2 SKILL --> R3 SKILL --> R4 SKILL --> R5 SKILL --> S1 SKILL --> S2 SKILL --> S3 SKILL --> S4

🏗️ 起動フロー詳細

sequenceDiagram participant User as 👤 ユーザー participant AI as 🤖 AI participant WF as 📋 Workflow participant ENVF as 💾 .gws_env.ps1 participant IGN as ⚡ kasutera-ignite.ps1 participant SYNC as 🔄 gws-skills-sync.ps1 participant GWS as 🌐 GWS CLI participant Google as ☁️ Google User->>AI: 「カステラ」 AI->>WF: /kasutera 発動 WF->>ENVF: 環境変数復元 WF->>IGN: pwsh -File kasutera-ignite.ps1 IGN->>IGN: 環境チェック・.gws_config 作成 IGN->>GWS: gws --version alt GWS CLI 未インストール IGN-->>AI: ❌ CLI が見つからない end IGN->>SYNC: スキル同期 SYNC->>Google: GitHub API IGN->>GWS: gws auth status alt 未ログイン IGN-->>AI: ❌ ログイン必要 AI-->>User: gws auth login を案内 else ログイン済み IGN->>GWS: Drive API テスト IGN-->>AI: ✅ V-Yanen! 稼働 end

📂 ファイル一覧と役割（抜粋）

① AGENTS.md — AI への総合指令書。トリガー語・Critical Rules・リソースパス一覧。

② Workflows — kasutera.md / kasutera-start.md（「カステラ」で起動、同一内容）。

③ Master Skill — SKILL.md（総帥・セクション 0〜7）、④ Scripts — kasutera-ignite.ps1（一撃セットアップ）、gws-skills-sync.ps1、check_env.ps1、scope_check.ps1。

⑤ Resources — GWS_SCOPE_REFERENCE.md、GWS_AUTH_SCOPES_GUIDE.md、GWS_CLI_INSTALL_ERROR_GUIDE.md、GWS_AUTH_REFERENCE.md、GWS_AUTH_ERROR_REPORT_EN.md。

⑥ 永続化 — .gws_env.ps1（GWS_CONFIG_DIR）、.gws_config/（認証情報）。

⑦ 子スキル 11体 — kasutera_gmail, kasutera_drive, kasutera_sheets, kasutera_calendar, kasutera_docs, kasutera_tasks, kasutera_people, kasutera_slides, kasutera_chat, kasutera_forms, kasutera_keep。

🔍 発見された問題と対応結果（抜粋）

問題1: --scopes recommended で Error 400: invalid_scope — 絶対に使わない。解決策は gws auth login（フラグなし）。

問題2〜6 — SKILL.md セクション番号重複の修正、存在しないリソース参照の差し替え、readonly を URL 形式に変換、GWS_CONFIG_DIR の .gws_env.ps1 永続化、AGENTS.md の Ignite ベース改訂。いずれも対応済み。

📊 システム統計

カテゴリ	数量
総ファイル数	24+
対応 Google サービス	11
発見・修正した問題	6件（全件対応済み）

全文・全表は kasutera_system_analysis.md（ダウンロード）を参照してください。

以上、gws 利用で躓きやすいスコープと権限エラーの原因・対処の要点でした。入門・Antigravity 連携・業務での実例・拡張機能（ダッシュボード）の使い方とあわせて参照してください。

Artist's Perspective

「gws を使い始めると必ず一度は 403 で躓くので、その解決策を形にしたかった。ここだけの話、貧乏すぎるくたびれたおっさんなので、開発環境はポンコツｓっす。。。本当に古い、もう、十数年前のＣＰＵとかで、、、、そんな『ポンコツ環境』で動くなら、世の中のモダンな環境ならもっとスムーズに動くはず、という自負があります笑。」

品質については、最先端のツールでの実験を繰り返し、権限問題や Google Cloud 側の設定など、AI が躓きやすいポイントを PowerShell で徹底的に事前処理する設計にしました。 『PowerShell で環境情報を固定的に集め、それを AI に流し込むことで、AI 処理を想定通りの安定した動きへと導く』。そんな設計思想が、このカステラシステムには詰まっています。あと、気になったのですが、このサイト、広告多くて見ずらいかな、、、どうでしょう、、、今、サイト運営と開発費用　赤字で、、、、、、ご了承いただけたら幸いです。

[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]

葬送のフリーレン（15）（少年サンデーコミックス） [ 山田鐘人 ]
価格：594円（税込、送料無料) (2026/3/6時点)

楽天で購入

データソース・参考リンク

本記事は Google OAuth 2.0 スコープおよび gws 利用時のメモ（GWS_AUTH_SCOPES_GUIDE.md / GWS_SCOPE_REFERENCE.md / scope_check.ps1）に基づいています。内容の正確性は公式をご確認ください。