Google Workspace 連携設定ガイド

方針決定（D5、2026-08-04）：DuDuClaw は自社の Google OAuth client id / secret を組み込みません。3つの接続経路はいずれも「あなた （運用者）またはお客様自身が Google に認証情報を申請する」方式です。 DuDuClaw の役割は、申請済みの認証情報を暗号化してローカルに保存し、 自動的に更新し続けることだけです。今後お客様から「自分で申請するのは 手間がかかりすぎる」という声が多く上がれば、嘟嘟（DuDuClaw）側が共有 認証を提供する方式を検討する可能性はありますが、現時点ではまだその 段階にありません。

このガイドは一つの問いに答えます。AI 社員に Gmail／カレンダー／ Sheets などの Google サービスを使わせたい場合、どの接続経路を選び、 各ステップで何を用意すればよいか？ 完全なツール一覧、セキュリティ 設計、トラブルシューティング、既知の制限は以下の3つの詳細ドキュメント にまとめてあります。このページでは「経路の選び方＋手順」だけを扱います。

• google-workspace.md — ネイティブ MCP ツール19個の 完全な一覧、セキュリティ設計（下書きは送信されない、追記は上書きしない）、 re-auth のトラブルシューティング。
• google-no-oauth-client.md — サービスアカウント 委任と Apps Script ブリッジのセキュリティ特性、失敗事例、除外された案の 実測データ。
• google-mcp.md — Google 公式の remote MCP マウント （上級者向けオプション、自分用のみで顧客への出荷は不可）。

3つの経路、どう選ぶか

経路	対象者	カバーするツール	誰が操作するか
① 自前の OAuth client	個人の @gmail.com、または管理者を煩わせたくない Workspace ユーザー	19ツール全て利用可	あなた自身が Google Cloud Console で申請
② サービスアカウントのドメイン全体委任（DWD）	すべてのアカウントで同意画面を通したくない企業 Workspace のお客様	19ツール全て利用可	お客様のドメインスーパー管理者が一度だけ承認
③ Apps Script ブリッジ	Cloud Console に一切触れたくない個人の @gmail.com	Gmail／カレンダー／Sheets のみ（19ツール中3種類）	ユーザー自身がスクリプトをデプロイ

3つの経路が付与するのは同じ一組のツールです。dashboard 上では 「三者択一」であり、同時に重ねがけすることはできません。いずれかを保存 すると、サーバーはもう一方の保存済み認証情報を消去し、「有効だと思って いる経路」と「実際に有効な経路」が食い違わないようにしています。

スコープ一覧（11個）

会議記録とのズレ：計画書には「19個の scopes」と書かれていますが、 これは「MCP ツール数」を「OAuth scope 数」と混同した誤記です。コード （crates/duduclaw-gateway/src/google_workspace.rs:98-116 の REQUIRED_SCOPES）を確認すると、実際にリクエストされる scope は 11個であり、19個ではありません。19はこの認証情報が解錠する MCP ツールの数を指しています。UI 文言（google.cred.intro などの i18n key）や既存ドキュメントはいずれも「19個のツール」という表現で 一致しているため、本ドキュメントはコードに基づき scope 数を11個に 訂正します。

#	Scope	用途（一言で）
1	gmail.readonly	AI が Gmail のメール内容を検索・閲覧できるようにする（読み取り専用、削除や変更は不可）。
2	gmail.compose	AI が Gmail の下書きを作成できるようにする（下書き保存のみ、送信権限はない）。
3	calendar.events	AI がメインカレンダーの予定を読み取り・作成できるようにする（Google Meet の会議リンク作成を含む）。
4	spreadsheets	AI が Google スプレッドシートのデータを読み取り、末尾に行を追加できるようにする。
5	drive.readonly	AI が Drive ファイルを検索・読み取り（エクスポート）できるようにする。読み取り専用で、ファイルの作成や変更は行わない。
6	documents	AI が Google ドキュメントの全文を読み取り、文書の末尾にテキストを追記できるようにする（既存内容の書き換えや削除はできない）。
7	presentations.readonly	AI が Google スライドのテキストをページ単位で読み取れるようにする。読み取り専用で、対応する書き込みツールはない。
8	forms.body.readonly	AI が Google フォームの設問構造（タイトル、設問形式、選択肢）を読み取れるようにする。
9	forms.responses.readonly	AI が Google フォームで既に収集された回答を読み取れるようにする。
10	tasks	AI が Google タスクの ToDo を読み取り・作成し、完了マークを付けられるようにする。
11	userinfo.email	現在接続されている Google アカウントをシステムが識別できるようにする。接続状態の表示や診断に使い、メール内容には一切関与しない。

設定ページの場所とボタンの機能

場所：管理メニュー → 連携 → Google（URL は /manage/integrations?tab=google）。

このタブ自体は v1.49.0 から初期状態で表示されています（それ以前のバージョン では Google 純正の OAuth App 審査の進捗を待つ間、非表示にしていました。 その後、審査が制限するのは「自前の OAuth client」の経路だけで、サービス アカウント委任や Apps Script ブリッジには影響しないことが確認できたため、 タブを隠しておく理由がなくなりました）。ただしタブが見えることと、 ツールが有効になることは別です。バックエンドには独立したマスター スイッチ config.toml [integrations] google_workspace があり、初期値は false です。スイッチが入っていない状態でも、認証情報の設定はでき、 「接続テスト」も緑色を表示できますが、ツールは AI 社員の前には一切 現れません。ページ上には黄色い注意書きでこの点が明示されており、 サイレント障害ではありません。有効化するには次のようにします。

[integrations]
google_workspace = true

ページは2つのブロックに分かれます。

1. 上部の接続パネル（経路①自前の OAuth client 専用）：Client ID / Client secret を入力 →「Google に接続」をクリック → Google の 同意画面がポップアップ → 完了するとパネルが「Google 接続済み」に 切り替わり、許可済みのアクセス範囲が一覧表示されます。接続済みの 状態では「認証情報を編集」で別のクライアントに切り替えるか、 「接続を解除」できます。接続解除ではアクセストークンのみが失効し、 クライアント設定は残るため、ワンクリックで再接続できます。
2. 下部の「認証方式」カード（3つのタブ：OAuth 接続／サービス アカウント／Apps Script ブリッジ）：タブはどの方式を編集するかを 選ぶだけで、実際に有効な経路はカード上の「現在有効」バッジで 判断します。「保存」は設定を書き込むだけで検証は行いません。 「接続テスト」は実際に Google API を一度呼び出し、現在有効な アカウントか、具体的なエラーメッセージを返します。そのため、まず 保存し、次に接続テストを行う必要があります。両者は別の操作です。

経路① 自前の OAuth client（個人 / 管理者を煩わせたくない Workspace ユーザー向け）

対象者：個人の @gmail.com、または Workspace ドメインに所属していても IT にサービスアカウントのフローを依頼したくないユーザー。19個のツール すべてが利用可能です。

1. Google Cloud Console → Credentials を開く（先にプロジェクトを作成または選択）。

2. 左側の「API とサービス → ライブラリ」から、次の8つの API を有効化 します：Gmail、Calendar、Sheets、Drive、Docs、Slides、Forms、Tasks。 有効化していないと対応するツールが 403 を返します。1行のコマンド でもまとめて有効化できます。

   gcloud services enable gmail.googleapis.com calendar-json.googleapis.com \
     sheets.googleapis.com drive.googleapis.com docs.googleapis.com \
     slides.googleapis.com forms.googleapis.com tasks.googleapis.com \
     --project=PROJECT_ID

3. 「API とサービス → OAuth 同意画面」で同意画面を設定します（外部・ 内部どちらでも可）。アプリが「テスト中」の状態のままの場合、必ず 自分の Google アカウントを「テストユーザー」リストに追加してください。 追加しないと Google 側で認証がブロックされます。さらに、テスト中の 状態で発行される refresh token は有効期限が7日間しかなく、 期限切れ後は再度接続をやり直す必要があります。

4. 「認証情報 → 認証情報を作成 → OAuth クライアント ID」で、種類は ウェブ アプリケーションを選択します。

5. 「承認済みのリダイレクト URI」に以下を追加します。

   http://localhost:18789/api/mcp/oauth/callback

   18789 は gateway のデフォルトポートです。DUDUCLAW_PORT でポートを 変更している場合、dashboard のこのページに変更後の正しい URL が 表示されるので、画面表示に従ってください。ここでポート番号が一致 しないとサイレントに失敗します。Google はブラウザを誰も listen していないポートへリダイレクトし、画面は「未接続」のまま止まり、 明確なエラーは表示されません。

6. 生成された Client ID と Client secret をコピーします。

7. dashboard の「連携 → Google」に戻り、上部の接続パネルに Client ID / Client secret を貼り付け、「Google に接続」をクリックします。

8. Google の同意画面がポップアップします。承認するとウィンドウが閉じ、 パネルが「Google 接続済み」に切り替わり、許可済みのアクセス範囲が 一覧表示されます。

経路② サービスアカウントのドメイン全体委任（企業 Workspace 向け）

対象者：Workspace ドメインの企業のお客様。ドメインのスーパー管理者が 一度承認するだけで済み、以降は個々のユーザーが Google の同意画面を通す 必要はありません。さらに Google アプリの審査も不要で、これが経路① に対する優位点です。19個のツールすべてが利用可能です。個人の @gmail.com はどのドメインにも属さないため、この経路は使えません。

1. あなた（サービス提供者）の Google Cloud プロジェクトでサービス アカウントを作成し、JSON キーをダウンロードします。サービス アカウントの詳細ページに表示される数字のクライアント ID （client id。キーファイル内の client_email とは別物）を控えて おきます。

2. キーファイルを DuDuClaw のホストに保存し、権限を絞ります。

   mkdir -p ~/.duduclaw/keys && mv ~/Downloads/sa-key.json ~/.duduclaw/keys/google-sa.json
   chmod 600 ~/.duduclaw/keys/google-sa.json

3. 前のステップの client id と、以下の scope 一覧（dashboard の認証情報 カードにコピーボタンがあります。次のステップ参照）を、お客様の ドメインスーパー管理者に渡し、次の手順を順番に実行してもらいます。

   Admin console → セキュリティ（Security）→ アクセスとデータ管理 （Access and data control）→ API の管理（API controls）→ ドメイン 全体の委任を管理（Manage Domain Wide Delegation）→ 新規追加 （Add new） → client id を貼り付け → scope 一覧（カンマ区切り 1行）を貼り付け → 保存。

   反映は通常すぐですが、Google の公式ドキュメントでは最大24時間 かかる可能性があるとされています。ドメインで「複数人承認」 （2024年8月から利用可能）が有効な場合、2人目のスーパー管理者の 承認も必要になるため、お客様には時間に余裕を持ってもらうよう伝えて ください。

4. dashboard の「連携 → Google」に戻り、下部の「認証方式」カードを サービスアカウントタブに切り替えます。

   • 「サービスアカウントキーファイルのパス」を入力します（相対パスは ~/.duduclaw を基準に解決されます。例：keys/google-sa.json）。
   • 「代理するユーザーのメールアドレス」を入力します（API 呼び出しを どの Workspace アカウントの権限で行うか。例：boss@customer.com）。
   • 上部に「管理者に渡す scope 一覧」ブロックがあり、「コピー」を 押せばステップ3の管理者にそのまま渡せます。手入力の必要は ありません。
   • 「保存」を押し、続けて「接続テスト」を押します。これは実際に token を要求する処理で、緑色の表示だけが管理者の承認が本当に 反映されたことの証明です。設定しただけでは承認が成功したことに はなりません。

経路③ Apps Script ブリッジ（個人向け、Cloud Console に一切触れない）

対象者：個人の @gmail.com（Workspace アカウントでも、管理者が Apps Script を無効化していなければ利用可能）で、OAuth client の申請も IT への 依頼も避けたい人。カバー範囲はサブセットです：Gmail（検索／読み取り／ 下書き作成）、カレンダー（一覧／作成）、Sheets（読み取り／行の追加）のみ 対応します。Drive、Docs、Slides、Forms、Tasks はこの経路では未対応で、 呼び出すと「Apps Script ブリッジは未対応」という明確なエラーが返り、 サイレントに空の結果を返すことはありません。

1. https://script.google.com を開き、新しいプロジェクトを作成します。

2. デフォルトのファイル内容全体を templates/apps-script/duduclaw-bridge.gs の内容で置き換えます。

3. ランダムな秘密鍵を生成し、スクリプト内の CHANGE_ME_TO_A_LONG_RANDOM_STRING を置き換えます。

   openssl rand -base64 32

4. デプロイ → 新しいデプロイ → ウェブアプリ：

   • 実行するユーザー：自分
   • アクセスできるユーザー：全員

5. Google に「未確認のアプリ」画面が表示されますが、これは想定内の 動作です（未確認のアプリとは、あなた自身のスクリプトのことです）。 「詳細設定 →（プロジェクト名）に移動」を選び、承認します。

6. /exec で終わる URL をコピーします（/dev ではありません。/dev はスクリプト所有者自身のブラウザセッションだけを認可するもので、 DuDuClaw からは呼び出せません）。

7. dashboard の「連携 → Google」に戻り、下部の「認証方式」カードを Apps Script ブリッジタブに切り替えます。

   • ウェブアプリの URL（/exec 終わり）を貼り付けます。
   • ステップ3で生成した秘密鍵を貼り付けます（以降の編集で URL だけ 変更し秘密鍵欄を空欄にした場合は、保存済みの秘密鍵がそのまま 使われ、消去されません）。
   • 「保存」を押し、続けて「接続テスト」を押します。緑色の表示は スクリプトが実際にどの Google アカウントで実行されているかを そのまま示すため、「間違ったログインでデプロイしてしまった」 というミスに最も早く気付ける方法です。

トラブルシューティング

3つの経路それぞれのエラーメッセージ、re-auth の流れ、既知の制限は、 対応する詳細ドキュメントにまとめてあります。

• OAuth client 経路の 401／403／redirect URI 不一致 → google-workspace.md#troubleshooting
• サービスアカウントの unauthorized_client（多くは管理者が貼り付けた scope 一覧に抜けがある場合）、Apps Script の URL／秘密鍵の検証ルール → google-no-oauth-client.md

google_status MCP ツールはいつでも利用でき、現在有効な認証情報の出所 と許可されたアクセス範囲を報告します。最初の診断ステップとして最も 早い方法です。