Claude Code×gws×Gemini 3.1 Pro実装ハブ手順

Claude Code・gws・Gemini 3.1 Proをどうつなげば、止まりにくいAIエージェントになるのか。この悩みを持っている人に向けて、2026年3月時点の仕様変更込みで手順をまとめます。この記事を読むと、モデルIDの更新漏れ、OAuthスコープの詰まり、MCP出力の暴走を避けながら、Mac miniで24時間運用できる設計を組めるようになります。僕は福祉事業のIT全般を担当しつつ、AI×SaaS開発を複業で回しているので、実運用で使っている構成だけに絞って話します。

2026年3月の前提整理｜Gemini 3 Pro停止後に3.1 Proへ寄せる理由

まず、日付を固定しておきます。2026年2月19日にGemini 3.1 Pro Previewが公開され、2026年3月9日にgemini-3-pro-previewは停止しました。ここを把握せずに運用すると、古い環境変数のまま本番に出して4xxを踏みやすいです。今の基準はgemini-3.1-pro-previewを明示することです。ツール呼び出しを多く使うなら、gemini-3.1-pro-preview-customtoolsを別枠で持つと安定します。

料金も先に見ておくと判断がぶれません。3.1 Proは1Mトークンあたり入力$2（200k超は$4）、出力$12（200k超は$18）です。つまり長文コンテキストを毎回投げる構成だと、月末に一気に響いてきます。イメージとしては、モデルを上げるより「どの処理で使うか」を上げるほうがコスト差を作れます。

「たまたま動く設定」を本番へ持ち込まない。この1点だけでも障害率はかなり下がります。

全体設計｜Claude Codeを実装ハブ、gwsを実行層、Geminiを推論層に分離

この構成は、1つのAIに全部やらせないのがコツです。Claude Codeは実装ハブとしてオーケストレーションを担当、gwsはWorkspace操作の実行層、Gemini 3.1 Proは高難度推論に集中させます。つまり「判断」「実行」「統合」を分離する設計です。責務を分けると、障害の切り分けが速くなります。

実際の流れは4ステップです。1) Claude Codeが要求を分解、2) gwsへAPI操作を委譲、3) 複雑な推論だけGeminiへ、4) 結果を戻してコードと運用に反映。この順序にすると、速度を落とさずに品質も上げられます。逆に単一モデルへ寄せすぎると、トークン消費とデバッグ時間が同時に増えます。

• 速度優先 — gws中心で処理し、推論呼び出しを最小化
• 品質優先 — 重要タスクだけGemini high thinkingへ振る
• 安全優先 — Claude Code側で承認フローを統一する

設計の壁打ちが必要なら、僕の僕のXへのDMでも実運用ベースで話せます。机上の正解より、実際に壊れたポイントの共有が早いです。

Mac mini実装手順①｜gws導入・認証・スコープ最小化

ここは手を動かせばすぐ形になります。最初にgwsを導入し、OAuthは最小スコープで通します。未検証アプリの同意画面には約25スコープの上限があるため、recommended（85+）をそのまま選ぶと失敗しやすいです。最初はdrive,gmail,calendarのように必要分だけにして、用途ごとに追加するのがおすすめです。

npm install -g @googleworkspace/cli
gws auth setup
gws auth login --scopes drive,gmail,calendar
gws drive files list --params '{"pageSize": 5}'

認証情報の優先順位も運用の要です。GOOGLE_WORKSPACE_CLI_TOKEN → GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE → gws auth loginの順で参照されます。つまり、ローカル検証では通るのにtmux常駐では落ちる問題は、注入経路の違いが原因なことが多いです。僕は「人が触る端末はkeyring」「自動ジョブは環境変数固定」で分けています。

1. read系で疎通 — まず一覧取得だけ成功させる
2. 更新系はdry-run — 破壊操作前に必ず確認する
3. ページング制御 — --page-limitを明示して暴走を防ぐ

この段階で「取得・作成・更新」の3コマンドが通れば、MCP接続へ進めます。

Mac mini実装手順②｜MCP接続・出力上限・承認フロー

次はClaude CodeとgwsをMCPでつなぎます。ここで重要なのは接続成功よりも、暴走させない設計です。Claude CodeのMCP運用では、警告10,000 tokens、既定上限25,000 tokensが目安になります。なので最初から上限値を設定して、長文レスポンスを抑える設計にします。安全運用は機能追加より先に固定するのが近道です。

claude mcp add --transport stdio gws-server -- npx @googleworkspace/cli mcp
claude mcp list
export MAX_MCP_OUTPUT_TOKENS=12000

承認フローは3段で分けると管理しやすいです。1段目はread-only（一覧・取得）、2段目は準破壊（下書き作成やラベル付与）、3段目は破壊的操作（送信・削除）です。3段目だけ手動承認にすると、普段の速度は落とさず事故率だけ下げられます。特にGmail送信とDrive削除はこの線引きが機能します。

補助資料として、Mac mini AIエージェント初期セットアップとClaude常時稼働の監視メモも併読すると、導入から復旧まで一本でつながります。

Gemini 3.1 Pro実装手順｜thinkingLevel・thought signatures・コスト管理

Gemini 3.1 Proは、thinkingLevelの扱いと履歴再送で差が出ます。3.1 Proはlowかhighで、完全なthinking offはできません。低遅延を狙う場面はlowを基本にして、highは難問だけに限定します。さらに関数呼び出しを使う会話で履歴を手動管理しているなら、thought signaturesを次ターンへ再送しないと4xx検証エラーが出ます。ここを実装していないと、本番だけ不安定になります。

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"要件を分解して"}]}],"config":{"thinkingConfig":{"thinkingLevel":"low"}}}'

// thoughtSignatureは履歴に保持して次ターンへ再送
for (const part of responseParts) {
  if (part.thoughtSignature) historyParts.push({ thoughtSignature: part.thoughtSignature });
}

運用テンプレは3点で十分です。1) 週1でモデルID疎通チェック、2) 月1でOAuthスコープ棚卸し、3) token閾値超過でlowへ自動フォールバック。高性能モデルを常時全開にしない設計が、長期運用では一番強いです。運用設計を個別に詰めたい人は、本文で紹介したキャリア相談窓口からどうぞ。

この切替を先延ばしにすると何が起こるか

モデルID更新、最小スコープ化、MCP出力上限。この3つを後回しにすると、障害時に原因を特定できない状態になります。停止済みIDを知らないままだとAPIエラーが増えますし、スコープ管理が曖昧だと認証が突然通らなくなる可能性があります。つまり、開発時間より復旧時間のほうが長くなりやすいです。先に土台を整えておくと、将来のトラブル対応コストを確実に減らせます。

この記事を書いている理由

僕自身、Mac mini M4 Pro（24GB）を24時間運用し、Node.js + TypeScript + npm workspaces + tmuxでエージェントを常駐させています。2026年3月5日時点でgwsとgogcliの比較も行い、Calendarは安定優先、Drive/Sheets/Gmailは段階移行という判断を実運用で決めました。だからこそ、理想論ではなく「今週壊れない構成」を共有したいんです。ITの知見を非IT現場でも使える形に翻訳するのが、僕の価値だと考えています。

次のアクション

まず今日、モデルID更新・gws最小スコープ認証・MCP上限設定の3つだけ実施してみてください。ここが固まると、明日からの改善速度が一気に上がります。