ドキュメント · プロバイダ

Gemini を Claude Code・Codex・Gemini CLI・OpenCode で使う

Google は Gemini を二つの形で提供しています。AI Studio のキーで使う Gemini Developer API と、自分の Google Cloud プロジェクトで使う Vertex AI です。どちらかを magpie に一度追加すれば、Claude Code・Codex・Gemini CLI・OpenCode などつないだすべてのツールが、magpie のゲートウェイ 127.0.0.1:3425 経由で gemini-3.1-pro-preview などの Gemini 3 モデルを使えます。ツールごとに別のモデルを選べます。

Gemini API キーを追加する

1. キーを取得aistudio.google.com/apikey で作ります。
2. プロバイダを追加magpie の プロバイダ で ＋ プロバイダを追加 を押し、Google Gemini を選んでキーを貼り付け、保存します。magpie が Google に提供モデルを問い合わせます。
3. ツールで選ぶエージェント タブで、ツールの行の gemini-3.1-pro-preview などの Gemini モデルを選びます。

magpie provider add google AIza…
magpie provider test google

magpie のモデル ID は プロバイダ/モデル の形なので、Gemini API のモデルは google/gemini-3.1-pro-preview のようになります。前がプロバイダ、後ろが Google 自身の ID です。キーは magpie の設定に保存され、magpie がシェルから読むことはありません。

エンドポイント

プリセットが Gemini API の URL を入れるのは一度だけです。消すと空のままになります。Gemini のクライアント以外から来たリクエストは、すべて Chat Completions に送られます。

モデル一覧

• 一覧の取得元。magpie は OpenAI 互換エンドポイントに一覧を一度だけ問い合わせます。これは Gemini API の一覧でもあるので、二度は聞きません。モデル名・推論レベル・価格は models.dev の google カタログから取ります。
• 画像モデル。Google では、Gemini の画像モデルは Gemini API で画像を作ります。設定 → モデル → 画像 で選びます。

ツールごとの使い方

エージェント タブでツールの行からモデルを選ぶか、ターミナルで切り替えます。各ガイドには、magpie がそのツールの設定に何を書き込むか、元に戻す方法が書いてあります。

magpie claude google/gemini-3.1-pro-preview
magpie codex google/gemini-3.1-pro-preview
magpie gemini model google/gemini-3.8-flash
magpie opencode google/gemini-3.1-pro-preview

• Claude Code は Anthropic Messages を話します。magpie がリクエストを一つずつ Gemini の Chat Completions に変換し、返答を Messages に戻します。ストリーミングもツール呼び出しもそのまま使えます。Claude Code で他のモデル。
• Codex が話すのは OpenAI Responses だけです。magpie が同じように Chat Completions に変換し、返答は Responses に戻して Codex に渡します。Codex で他のモデル。
• Gemini CLI は Gemini 自身の API を話すので、リクエストはそのまま Gemini API に渡り、Google 検索もそこで動きます。Gemini CLI で他のモデル。
• OpenCode は Chat Completions を話すので、リクエストはそのまま Google に渡ります。OpenCode で他のモデル。

思考

• 思考の表示。Gemini の OpenAI 互換 API は、thinking_config で求めたときだけモデルの思考を返します。ツールが推論の表示を求めると、magpie は include_thoughts を付けて思考を求めます。長く考えている間も、最初の一文字が遅れて届くのではなく、考え中として表示されます。
• レベルと予算。Gemini 3 以降には思考レベルを送ります。Gemini 2 のモデルにはレベルの代わりに予算を送ります。minimal と low は 1024 トークン、medium は 8192、high は 24576 です。xhigh と max は high として送り、対応するレベルのない強さはモデルに任せます。
• 推論オフ。Gemini 3 は考えるのを止められません。ツールが推論をオフにすると、magpie はそのモデルのいちばん低いレベルを求めます。
• モデルにないレベル。どの Gemini 3 にもすべてのレベルがあるわけではなく、gemini-3.8-flash には minimal がありません。Google がレベルを 400 で断ると、magpie はそのモデルにあるいちばん近いレベルで問い合わせ直し、magpie を再起動するまで覚えておきます。
• thinking_config を断られたとき。これは別の 400 で、Gemini の前に立つサーバーがこのフィールド自体を受け付けない場合です。magpie は reasoning_effort だけで問い合わせ直し、以後そこには thinking_config を送りません。
• プロキシ。このコンピューターや LAN のプロキシ（localhost やプライベートアドレス上のものなど）の後ろにある Gemini モデルも、同じように扱います。

思考シグネチャとツール

• 思考シグネチャ。Gemini 3 は各ステップの最初の関数呼び出しに署名し、それがないと次のリクエストは 400 “Function call is missing a thought_signature in functionCall parts” で失敗します。ツールはシグネチャを保持しません。magpie はそれをツールに渡す呼び出し ID の中に入れて運び（magpie のフォルダにあるファイルへの短い参照です）、Gemini に送るときに戻します。シグネチャは 90 日間保存されます。
• Gemini が署名していない呼び出し。会話の前のほうで別のモデルが出した呼び出しや、ツールが ID を短くした呼び出しは、Google がドキュメントに載せている skip_thought_signature_validator を付けて送ります。会話の途中から Gemini に切り替えても続けられます。
• シグネチャは出したプロバイダにだけ。シグネチャは、それを出したプロバイダにだけ返します。Vertex AI と Gemini API を含むルーティンググループでは、もう一方のプロバイダには署名なしの履歴として送るので、“Corrupted thought signature” にはなりません。
• ツールのスキーマ。magpie は、ツールのスキーマのうち型のないものに型を付け（Vertex AI では必須です）、真偽値のスキーマと、MCP の x-mcp-header のような x- キーワードを取り除きます。手を入れる必要のないツールはそのまま送ります。
• ストリームの終わり。Gemini の OpenAI 互換 API は、関数呼び出しを一つのチャンクで丸ごと送り、finish_reason を次のチャンクで送ります。使用量が届いたあとにその終了理由が失われた場合、magpie が補います。使用量も届いていなければ、完了した返答として渡さず、途中で切れたと報告します。

キャッシュ・費用・検索

• プロンプトキャッシュ。Gemini はプロンプトをキャッシュしても、そのターンではそう報告しません。magpie はそのターンをキャッシュ書き込みとして数え、次のターンも同じプロバイダとキーに送ります。どれが答えたかは再起動しても覚えています。
• キャッシュと思考のトークン。Chat Completions でも Gemini API でも、magpie は返答ごとにキャッシュされたトークンと推論トークンを読み、使用量 タブで数えます。
• 費用。使用量タブは、models.dev の google カタログの価格で呼び出しごとの費用を計算します。
• Web 検索。Gemini API で Google 検索が動くのは、関数ツールを宣言していないリクエストだけです。Claude Code と Codex のリクエストはツールを宣言しているので、その Web 検索は magpie 自身の検索になり、Google プロバイダがあなたのキーで答えます。その検索は Gemini API の利用分になります。

複数のキーとレート制限

一つの Google Gemini プロバイダに複数のキーを入れられます。その下の 別のキーを追加 を押すか、まとめて貼り付けます。リクエストはオンになっている最初のキーに行き、そのキーが尽きるかレート制限にかかると次のキーが引き継ぎます。プロバイダのルーティングを、順番に回す・重みで分ける・一つを使い切ってから次へ、に変えることもできます。

• 1 分あたりの制限による 429。1 分あたりの上限で返る Gemini の 429 “You exceeded your current quota … Please retry in 33s” は、プランの使い切りではなくレート制限として扱います。Vertex AI の requests_per_minute_per_project も同じです。キーは 1 分休み、そのたびに倍になり、rest-cap まで延びます。
• 速さを抑える。rpm はキーごとに 1 分あたりのリクエスト数を抑えます。超えた分は空きを待ち、2 分待っても空かなければ 429 を返します。
• クォータ切れ。quota-rest は、クォータを使い切ったキーを休ませる長さです。既定は 15 分、最長 8 日で、時刻を指定してそこまで休ませることもできます。
• 支出上限とフォールバック。spend-cap はキーを 1 日・1 か月・合計のドル額で止め、fallback は Gemini がクォータ切れや停止のときのリクエストの行き先を決めます。

magpie provider rpm google 10
magpie provider spend-cap google <key> 20 month
magpie provider fallback google google-vertex/gemini-3.1-pro-preview

Vertex AI

Google Vertex AI プリセットは、API キーなしで、自分の Google Cloud プロジェクトの Gemini を呼びます。プロジェクト ID を指定すれば、リクエストに入ったそのプロジェクトに課金されます。

gcloud auth application-default login
magpie provider add google-vertex project=my-project
magpie claude google-vertex/gemini-3.1-pro-preview

• 認証情報。magpie は gcloud のアプリケーションのデフォルト認証情報（Application Default Credentials）で署名します。credentials= にフルパスでファイルを指定すれば、そちらを使います。ユーザーのサインイン、サービスアカウントキー、なりすましのサービスアカウントのどれでも構いません。impersonate= にはサービスアカウントのメールアドレスを指定し、そのアカウントに対する roles/iam.serviceAccountTokenCreator が必要です。メタデータサーバー、Workload Identity 連携、Vertex AI のエクスプレスモードの API キーは読みません。
• ロケーション。location= は global（既定）、us、eu、または us-central1 などのリージョンです。
• モデル。このプリセットには独自のモデル一覧があり、gemini-3.8-flash、gemini-3.1-pro-preview、gemini-2.5-pro、zai-org/glm-5.2-maas のようなパートナーモデル、claude-opus-5-5 のような Claude モデルが入っています。Gemini は Vertex AI の Gemini API へ、パートナーモデルは OpenAI 互換の Chat Completions へ、Claude は Anthropic の Messages API へ送られ、どれもあなたのプロジェクトで動きます。
• Vertex AI での思考。Gemini 3 のレベルはそのモデルにあるレベルに合わせ、推論オフではいちばん低いレベルを求めます。Gemini 2.5 は予算で、Pro は 128〜32768 トークン（オフで 128）、Flash は 24576 まで（オフで 0）、Flash-Lite は 512〜24576（オフで 0）です。

Google のサインイン

キーなしで Gemini モデルを使える Google のサインインが二つあります。どちらもサブスクで、設定は サブスクを任意のエージェントで のとおりです。

• Gemini（Code Assist）。Gemini CLI の Google サインインで、モデルは gemini/… です。magpie accounts add gemini で追加します。Google が応じるのは、専用の Google Cloud プロジェクトを持つ Code Assist Standard または Enterprise のアカウントだけです。プロジェクトは magpie accounts project gemini <email> <project> で指定します。
• Antigravity。モデルは antigravity/… で、magpie accounts add antigravity で追加します。サインインすると Antigravity の Claude と Gemini のモデルが使えます。

うまくいかないとき

• “Thinking level MINIMAL is not supported for this model”。そのモデルには minimal がありません。magpie がいちばん近いレベルで問い合わせ直すのでツールには返答が届き、magpie を再起動するまでそのレベルを覚えておきます。試せるレベルが残っていないときだけ、Google のエラーがそのままツールに届きます。
• “Function call is missing a thought_signature in functionCall parts”。Gemini 3 の呼び出しがシグネチャを失っています。magpie を通るときは、シグネチャは呼び出し ID に入って運ばれ、送るときに戻されます。シグネチャのない呼び出しには skip_thought_signature_validator が付きます。
• “Corrupted thought signature”。シグネチャが途中で切れているか、別のプロバイダのものです。magpie はシグネチャを、それを出したプロバイダにだけ送ります。
• 429 で “Please retry in 33s”。1 分あたりの上限で、プランを使い切ったわけではありません。キーは少し休みます。rpm を使えば、それ以降のリクエストを上限の内に抑えられます。
• Vertex AI でスキーマが “didn’t specify the schema type field”。magpie は Gemini に送るツールのスキーマすべてに型を付けるので、このエラーがツールまで届くことはないはずです。
• Vertex AI が保存できない。“Google Vertex AI needs the id of your Google Cloud project” と出たら project= を付けます。認証情報のファイルはフルパスで指定してください。
• キーの確認。magpie provider test google は各エンドポイントに、または指定した各モデルに小さなリクエストを送ります。--as codex や --as claude-code を付けると、そのツールと同じ形で送ります。

よくある質問

Claude Code で Gemini を使うには？

magpie に Gemini API キーを追加し（プロバイダ、プロバイダを追加、Google Gemini）、Claude Code の行で gemini-3.1-pro-preview などのモデルを選ぶか、magpie claude google/gemini-3.1-pro-preview を実行します。magpie が Claude Code の settings.json を書き、Messages のリクエストを一つずつ Gemini の Chat Completions に変換します。ツール呼び出しもストリーミングもそのまま使えます。

Codex で Gemini のモデルは使えますか？

使えます。Codex が話すのは Responses API だけなので、magpie が Codex のリクエストを一つずつ Gemini の Chat Completions に変換し、返答を Responses に戻します。magpie codex google/gemini-3.1-pro-preview を実行するか、Codex の行でモデルを選びます。

Claude Code で Gemini 3 Pro にツールを続けて呼ばせても大丈夫ですか？

大丈夫です。Gemini 3 は関数呼び出しに署名し、シグネチャのない次のリクエストを断ります。magpie はシグネチャをツールに渡す呼び出し ID に入れて運び、Gemini に送るときに戻すので、ツールのループは止まりません。別のモデルが出した呼び出しは署名なしとして送ります。

Gemini CLI や OpenCode でも magpie 経由で Gemini のキーを使えますか？

使えます。Gemini CLI のリクエストは Google 検索も含めてそのまま Gemini API に渡ります。OpenCode は Chat Completions を話すので、リクエストはそのまま Gemini の OpenAI 互換 API に渡ります。

Gemini が 429 で “Please retry in 33s” と返すのはなぜですか？

1 分あたりの上限で、クォータを使い切ったわけではありません。magpie はレート制限として扱い、キーを少し休ませます。magpie provider rpm google 10 のように自分の上限で実行すれば、magpie がリクエストをその速さに抑えます。

API キーではなく Vertex AI で Gemini を使えますか？

使えます。プロジェクト ID を付けて Google Vertex AI プリセットを追加します。たとえば magpie provider add google-vertex project=my-project。magpie は gcloud のアプリケーションのデフォルト認証情報か認証情報ファイルで署名し、課金はあなたのプロジェクトに入ります。

Gemini Code Assist や Antigravity のサインインは使えますか？

使えます。どちらもサブスクです。magpie accounts add gemini か magpie accounts add antigravity を実行し、gemini/… か antigravity/… のモデルを選びます。Code Assist には、専用の Google Cloud プロジェクトを持つ Standard または Enterprise のアカウントが必要です。

プロバイダ別：DeepSeek · Kimi と Kimi Code · GLM Coding Plan · Qwen · MiniMax · Grok · Mistral · OpenRouter · GitHub Copilot · Ollama

ツールごとのガイド：Claude Code で他のモデル、Codex で他のモデル、Gemini CLI で他のモデル、OpenCode で他のモデル。困ったときは Discord で質問してください。