From 66a0aa47e446b3602db49b1626441b9ff65eddb0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 28 Apr 2026 05:41:22 +0100
Subject: [PATCH] docs(google): clarify gemini 3.1 pro alias

---
 docs/concepts/model-providers.md   | 1 +
 docs/providers/google.md           | 2 ++
 extensions/google/model-id.test.ts | 5 +++++
 extensions/google/model-id.ts      | 2 ++
 4 files changed, 10 insertions(+)

diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md
index 1d93b97d028..cdeeaa69935 100644
--- a/docs/concepts/model-providers.md
+++ b/docs/concepts/model-providers.md
@@ -195,6 +195,7 @@ Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so Ope
 - Optional rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` fallback, and `OPENCLAW_LIVE_GEMINI_KEY` (single override)
 - Example models: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
 - Compatibility: legacy OpenClaw config using `google/gemini-3.1-flash-preview` is normalized to `google/gemini-3-flash-preview`
+- Alias: `google/gemini-3.1-pro` is accepted and normalized to Google's live Gemini API id, `google/gemini-3.1-pro-preview`
 - CLI: `openclaw onboard --auth-choice gemini-api-key`
 - Thinking: `/think adaptive` uses Google dynamic thinking. Gemini 3/3.1 omit a fixed `thinkingLevel`; Gemini 2.5 sends `thinkingBudget: -1`.
 - Direct Gemini runs also accept `agents.defaults.models["google/<model>"].params.cachedContent` (or legacy `cached_content`) to forward a provider-native `cachedContents/...` handle; Gemini cache hits surface as OpenClaw `cacheRead`
diff --git a/docs/providers/google.md b/docs/providers/google.md
index c3edcc161d7..97bf78177d8 100644
--- a/docs/providers/google.md
+++ b/docs/providers/google.md
@@ -102,6 +102,8 @@ Choose your preferred auth method and follow the setup steps.
     - Runtime: `google-gemini-cli`
     - Alias: `gemini-cli`
 
+    Gemini 3.1 Pro's Gemini API model id is `gemini-3.1-pro-preview`. OpenClaw accepts the shorter `google/gemini-3.1-pro` as a convenience alias and normalizes it before provider calls.
+
     **Environment variables:**
 
     - `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
diff --git a/extensions/google/model-id.test.ts b/extensions/google/model-id.test.ts
index 88ee4e7c893..5c4dd4d526a 100644
--- a/extensions/google/model-id.test.ts
+++ b/extensions/google/model-id.test.ts
@@ -23,6 +23,11 @@ describe("google model id helpers", () => {
     expect(normalizeGoogleModelId("gemini-3.1-flash-preview")).toBe("gemini-3-flash-preview");
   });
 
+  it("keeps bare Gemini 3.1 Pro as an alias for Google's preview-suffixed API id", () => {
+    expect(normalizeGoogleModelId("gemini-3.1-pro")).toBe("gemini-3.1-pro-preview");
+    expect(normalizeGoogleModelId("gemini-3.1-pro-preview")).toBe("gemini-3.1-pro-preview");
+  });
+
   it("adds the preview suffix for gemini 3.1 flash-lite", () => {
     expect(normalizeGoogleModelId("gemini-3.1-flash-lite")).toBe("gemini-3.1-flash-lite-preview");
   });
diff --git a/extensions/google/model-id.ts b/extensions/google/model-id.ts
index 076fa1c9059..ea1380f0750 100644
--- a/extensions/google/model-id.ts
+++ b/extensions/google/model-id.ts
@@ -7,6 +7,8 @@ export function normalizeGoogleModelId(id: string): string {
   if (id === "gemini-3-flash") {
     return "gemini-3-flash-preview";
   }
+  // Google exposes Gemini 3.1 Pro in the Gemini API as the preview-suffixed id.
+  // Keep the bare form as a user convenience alias, not as a canonical API id.
   if (id === "gemini-3.1-pro") {
     return "gemini-3.1-pro-preview";
   }