docs(google): document supported auth paths

2026-08-02 05:41:37 +00:00 · 2026-07-30 22:56:26 +08:00
parent 5e5d436579
commit d540255ce7
15 changed files with 100 additions and 127 deletions
--- a/docs/cli/openclaw.md
+++ b/docs/cli/openclaw.md
@@ -265,8 +265,10 @@ a single OpenClaw authority tool plus the inert native planning utility. In all
 three cases, setup writes remain confined to OpenClaw's audited approval
 contract.

-Gemini CLI remains available for normal agents, but it cannot enforce the
-tool-free probe required by the inference gate, so it cannot host OpenClaw.
+Gemini CLI remains available as an explicitly configured runtime for normal
+agents, but Gemini CLI and Antigravity are not inference-gate setup routes.
+Use AI Studio API-key or Vertex AI for the inference gate. The optional Gemini
+CLI runtime specifically requires an AI Studio API-key profile.

 ## Switching to an agent

--- a/docs/cli/setup.md
+++ b/docs/cli/setup.md
@@ -41,8 +41,9 @@ automatic pass. Detected local runtimes are auto-tested after CLI and API-key
 candidates; when several local models are available, OpenClaw prefers the
 strongest tool-calling instruct family. The selected candidate must answer a
 real completion before its provider and model configuration is saved.
-Installed Gemini, Antigravity, Pi, and OpenCode CLIs are also reported when
-they cannot serve as the reusable inference route for guided setup.
+Pi and OpenCode CLIs may also be reported for context when they cannot serve as
+the reusable inference route for guided setup. Gemini CLI and Antigravity are
+not offered as detected setup routes.

 `setup` accepts the same onboarding flags as `openclaw onboard`, including
 auth (`--auth-choice`, `--token`, provider key flags), Gateway
--- a/docs/concepts/model-providers.md
+++ b/docs/concepts/model-providers.md
@@ -234,49 +234,18 @@ Claude CLI reuse (`claude -p`) is a sanctioned OpenClaw integration path. Anthro
 - 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`

-### Google Vertex and Gemini CLI
+### Google Vertex and Gemini CLI runtime

- Providers: `google-vertex`, `google-gemini-cli`
- Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow
+- `google-vertex`: managed Google Cloud access through gcloud Application
+  Default Credentials.
+- `google-gemini-cli`: optional local runtime for an explicitly configured
+  canonical `google/*` model.

-<Warning>
-Gemini CLI OAuth in OpenClaw is an unofficial integration. Some users have reported Google account restrictions after using third-party clients. Review Google terms and use a non-critical account if you choose to proceed.
-</Warning>
-
-Gemini CLI OAuth is shipped as part of the bundled `google` plugin.
-
-<Steps>
-  <Step title="Install Gemini CLI">
-    <Tabs>
-      <Tab title="brew">
-        ```bash
-        brew install gemini-cli
-        ```
-      </Tab>
-      <Tab title="npm">
-        ```bash
-        npm install -g @google/gemini-cli
-        ```
-      </Tab>
-    </Tabs>
-  </Step>
-  <Step title="Enable plugin">
-    ```bash
-    openclaw plugins enable google
-    ```
-  </Step>
-  <Step title="Login">
-    ```bash
-    openclaw models auth login --provider google-gemini-cli --set-default
-    ```
-
-    Default model: `google-gemini-cli/gemini-3-flash-preview`. You do **not** paste a client id or secret into `openclaw.json`. The CLI login flow stores tokens in auth profiles on the gateway host.
-
-  </Step>
-  <Step title="Set project (if needed)">
-    If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host.
-  </Step>
-</Steps>
+OpenClaw does not create Gemini CLI OAuth or Antigravity OAuth profiles. Connect
+Google through an AI Studio API key or Vertex AI. If you explicitly choose the
+Gemini CLI runtime, it can use the selected Google API-key profile. Existing
+valid Gemini CLI OAuth profiles remain runtime-compatible, but they are not a
+setup or recovery route.

 Gemini CLI uses `stream-json` by default. OpenClaw reads assistant stream
 messages and normalizes `stats.cached` into `cacheRead`; legacy
--- a/docs/concepts/usage-tracking.md
+++ b/docs/concepts/usage-tracking.md
@@ -315,7 +315,7 @@ provider-neutral for CLI, app, and Control UI consumers.
 - **DeepSeek**: API key via env/config/auth store (`DEEPSEEK_API_KEY`).
  Shows each provider-reported currency balance.
 - **GitHub Copilot**: OAuth tokens in auth profiles.
- **Gemini CLI**: OAuth tokens in auth profiles.
+- **Gemini CLI**: existing OAuth profiles or supported Google API-key profiles.
 - **MiniMax**: API key or MiniMax OAuth auth profile. OpenClaw treats
  `minimax`, `minimax-cn`, and `minimax-portal` as the same MiniMax quota
  surface, prefers stored MiniMax OAuth when present, and otherwise falls back
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -2795,7 +2795,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
  - H3: Other subscription-style hosted options
  - H3: OpenCode
  - H3: Google Gemini (API key)
-  - H3: Google Vertex and Gemini CLI
+  - H3: Google Vertex and Gemini CLI runtime
  - H3: Z.AI (GLM)
  - H3: Vercel AI Gateway
  - H3: Other bundled provider plugins
--- a/docs/gateway/cli-backends.md
+++ b/docs/gateway/cli-backends.md
@@ -231,7 +231,11 @@ The bundled Google plugin registers for `google-gemini-cli`:
 | `sessionMode`             | `existing`                                                                             |
 | `sessionIdFields`         | `["session_id", "sessionId"]`                                                          |

-Prerequisite: the local Gemini CLI must be installed and on `PATH` as `gemini` (`brew install gemini-cli` or `npm install -g @google/gemini-cli`).
+Prerequisites: the local Gemini CLI must be installed and on `PATH` as `gemini`
+(`brew install gemini-cli` or `npm install -g @google/gemini-cli`), and the
+selected model must have a supported Google AI Studio API-key profile. Existing
+valid legacy Gemini CLI OAuth profiles remain runtime-compatible, but OpenClaw
+does not create or repair them.

 Gemini CLI output notes:

--- a/docs/help/faq-first-run.md
+++ b/docs/help/faq-first-run.md
@@ -606,18 +606,16 @@ and troubleshooting see the main [FAQ](/help/faq).

  </Accordion>

-  <Accordion title="How do I set up Gemini CLI OAuth?">
-    Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.
+  <Accordion title="Can I use Gemini CLI or Antigravity OAuth?">
+    OpenClaw does not offer new Gemini CLI OAuth or Antigravity OAuth setup.
+    Connect Google with an AI Studio API key or Vertex AI instead.

-    1. Install Gemini CLI locally so `gemini` is on `PATH`:
-       - Homebrew: `brew install gemini-cli`
-       - npm: `npm install -g @google/gemini-cli`
-    2. Enable the plugin: `openclaw plugins enable google`
-    3. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
-    4. Default model after login: `google/gemini-3.1-pro-preview` (runtime `google-gemini-cli`)
-    5. Requests failing after login? Set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and retry.
+    The optional `google-gemini-cli` runtime remains available for advanced
+    setups using a supported Google API-key profile. Existing valid legacy
+    Gemini CLI OAuth profiles remain executable for compatibility, but OpenClaw
+    cannot create or repair them.

-    OAuth tokens are stored in auth profiles on the gateway host. Details: [Google](/providers/google), [Model providers](/concepts/model-providers).
+    Details: [Google](/providers/google), [Model providers](/concepts/model-providers).

  </Accordion>

--- a/docs/nodes/audio.md
+++ b/docs/nodes/audio.md
@@ -37,7 +37,8 @@ If you have not configured models and `tools.media.audio.enabled` is not `false`
 Install/link provenance is capability evidence, not execution evidence. It never moves a candidate ahead of CPU sherpa by itself. OpenClaw does not load a model during setup or status checks just to probe a backend.
 Auto-detected whisper.cpp keeps its normal model-run logs enabled so OpenClaw can record the upstream `using … backend` line. Explicit CLI entries keep their configured output flags.

-Gemini CLI auto-detect for media understanding was replaced by a sandboxed Antigravity CLI (`agy`) fallback for image/video; audio does not use a CLI fallback beyond the local binaries above.
+Gemini CLI and Antigravity are not auto-detected for media understanding. Audio
+does not use a CLI fallback beyond the local binaries above.

 To disable auto-detection, set `tools.media.audio.enabled: false`. To customize, add capability-tagged entries to `tools.media.models`.

--- a/docs/nodes/media-understanding.md
+++ b/docs/nodes/media-understanding.md
@@ -174,9 +174,6 @@ When `tools.media.<capability>.enabled` is not `false` and no models are configu
    - Video: Google &rarr; Qwen &rarr; Moonshot

  </Step>
-  <Step title="Antigravity CLI (image/video only)">
-    First installed `agy` or `antigravity` binary (override with `OPENCLAW_ANTIGRAVITY_CLI`), sandboxed against the media's directory.
-  </Step>
 </Steps>

 To disable auto-detection for a capability:
--- a/docs/providers/google.md
+++ b/docs/providers/google.md
@@ -1,9 +1,9 @@
 ---
-summary: "Google Gemini setup (API key + OAuth, image generation, media understanding, TTS, web search)"
+summary: "Google Gemini setup (AI Studio API key, Vertex AI, optional CLI runtime, and multimodal tools)"
 title: "Google (Gemini)"
 read_when:
  - You want to use Google Gemini models with OpenClaw
-  - You need the API key or OAuth auth flow
+  - You need Google AI Studio, Vertex AI, or Gemini CLI runtime guidance
 ---

 The Google plugin provides access to Gemini models through Google AI Studio, plus image generation, media understanding (image/audio/video), text-to-speech, and web search via Gemini Grounding.
@@ -11,15 +11,17 @@ The Google plugin provides access to Gemini models through Google AI Studio, plu
 - Provider: `google`
 - Auth: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
 - API: Google Gemini API
- Runtime option: `agentRuntime.id: "google-gemini-cli"` reuses Gemini CLI OAuth while keeping model refs canonical as `google/*`.
+- Managed-cloud provider: `google-vertex` with Google Cloud Application Default Credentials
+- Optional runtime: `agentRuntime.id: "google-gemini-cli"` runs an explicitly configured model through the local Gemini CLI

 ## Getting started

-Choose your preferred auth method and follow the setup steps.
+For most installations, use a Google AI Studio API key. Use `google-vertex` when
+the Gateway already runs inside a managed Google Cloud environment.

 <Tabs>
-  <Tab title="API key">
-    **Best for:** standard Gemini API access through Google AI Studio.
+  <Tab title="AI Studio API key">
+    **Recommended for:** standard Gemini API access.

    <Steps>
      <Step title="Get an API key">
@@ -70,16 +72,23 @@ Choose your preferred auth method and follow the setup steps.

  </Tab>

-  <Tab title="Gemini CLI (OAuth)">
-    **Best for:** signing in with your Google account through Gemini CLI OAuth instead of using a separate API key.
+  <Tab title="Gemini CLI runtime">
+    **Advanced use only:** run a canonical `google/*` model through an installed
+    Gemini CLI while keeping authentication on the supported AI Studio API-key
+    path.

-    <Warning>
-    The `google-gemini-cli` provider is an unofficial integration. Some users
-    report account restrictions when using OAuth this way. Use at your own risk.
-    </Warning>
+    OpenClaw does not offer new Gemini CLI OAuth or Antigravity OAuth setup.
+    [Google ended consumer Gemini CLI Login with Google access on June 18, 2026](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals),
+    and the [Antigravity terms](https://antigravity.google/terms) prohibit
+    third-party tools from accessing the service through Antigravity OAuth. Use
+    an AI Studio API key or Vertex AI instead.

    <Steps>
-      <Step title="Install the Gemini CLI">
+      <Step title="Configure Google AI Studio">
+        Complete the API-key setup in the first tab. OpenClaw must have a usable
+        `google` API-key profile before the CLI runtime can be selected.
+      </Step>
+      <Step title="Install Gemini CLI">
        The local `gemini` command must be available on `PATH`.

        ```bash
@@ -93,46 +102,37 @@ Choose your preferred auth method and follow the setup steps.
        OpenClaw supports both Homebrew installs and global npm installs, including
        common Windows/npm layouts.
      </Step>
-      <Step title="Log in via OAuth">
-        ```bash
-        openclaw models auth login --provider google-gemini-cli --set-default
-        ```
-      </Step>
-      <Step title="Verify the model is available">
-        ```bash
-        openclaw models list --provider google
+      <Step title="Select the CLI runtime">
+        Keep the canonical Google model ref and opt that model into the CLI
+        runtime:
+
+        ```json5
+        {
+          agents: {
+            defaults: {
+              model: { primary: "google/gemini-3.1-pro-preview" },
+              models: {
+                "google/gemini-3.1-pro-preview": {
+                  agentRuntime: { id: "google-gemini-cli" },
+                },
+              },
+            },
+          },
+        }
        ```
      </Step>
    </Steps>

-    - Default model: `google/gemini-3.1-pro-preview`
    - Runtime: `google-gemini-cli`
-    - Alias: `gemini-cli`
+    - Auth: selected Google AI Studio API-key profile
+    - Model refs: canonical `google/*`

-    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.
+    Existing valid Gemini CLI OAuth profiles remain executable for compatibility,
+    but OpenClaw cannot create or repair them. If one breaks, replace it with a
+    Google AI Studio API-key profile.

-    **Environment variables:**
-
-    - `OPENCLAW_GEMINI_OAUTH_CLIENT_ID` / `GEMINI_CLI_OAUTH_CLIENT_ID`
-    - `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET` / `GEMINI_CLI_OAUTH_CLIENT_SECRET`
-
-    <Note>
-    If Gemini CLI OAuth requests fail after login, set `GOOGLE_CLOUD_PROJECT` or
-    `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and retry.
-    </Note>
-
-    <Note>
-    If login fails before the browser flow starts, make sure the local `gemini`
-    command is installed and on `PATH`.
-    </Note>
-
-    Onboarding auto-detection lists an existing Gemini CLI login but never
-    auto-tests it because Gemini CLI has no tool-free probe. Choose Gemini CLI
-    OAuth or a Gemini API key to continue.
-
-    `google-gemini-cli/*` model refs are legacy compatibility aliases. New
-    configs should use `google/*` model refs plus the `google-gemini-cli`
-    runtime when they want local Gemini CLI execution.
+    `google-gemini-cli/*` refs remain legacy compatibility aliases. New configs
+    should use `google/*` model refs plus the explicit runtime selection above.

  </Tab>
 </Tabs>
@@ -466,10 +466,9 @@ verifies a text response and `describe_view` function roundtrip.
  </Accordion>

  <Accordion title="Gemini CLI usage notes">
-    When using the `google-gemini-cli` OAuth provider, OpenClaw uses Gemini
-    CLI `stream-json` output by default and normalizes usage from the final
-    `stats` payload. Legacy `--output-format json` overrides still use the
-    JSON parser.
+    The optional `google-gemini-cli` runtime uses Gemini CLI `stream-json`
+    output by default and normalizes usage from the final `stats` payload.
+    Legacy `--output-format json` overrides still use the JSON parser.

    - Streamed reply text comes from assistant `message` events.
    - For legacy JSON output, reply text comes from the CLI JSON `response` field.
--- a/docs/providers/index.md
+++ b/docs/providers/index.md
@@ -87,7 +87,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi

 ## Shared overview pages

- [Additional provider variants](/providers/models#additional-provider-variants) - Anthropic Vertex, Copilot Proxy, and Gemini CLI OAuth
+- [Additional provider variants](/providers/models#additional-provider-variants) - Anthropic Vertex, Copilot Proxy, and the optional Gemini CLI runtime
 - [Image Generation](/tools/image-generation) - Shared `image_generate` tool, provider selection, and failover
 - [Music Generation](/tools/music-generation) - Shared `music_generate` tool, provider selection, and failover
 - [Video Generation](/tools/video-generation) - Shared `video_generate` tool, provider selection, and failover
--- a/docs/providers/models.md
+++ b/docs/providers/models.md
@@ -57,7 +57,7 @@ For the full provider catalog and advanced configuration, see

 - `anthropic-vertex` - install `@openclaw/anthropic-vertex-provider` for implicit Anthropic on Google Vertex support when Vertex credentials are available; no separate onboarding auth choice
 - `copilot-proxy` - local VS Code Copilot Proxy bridge; use `openclaw onboard --auth-choice copilot-proxy`
- `google-gemini-cli` - unofficial Gemini CLI OAuth flow; requires a local `gemini` install (`brew install gemini-cli` or `npm install -g @google/gemini-cli`); default model `google-gemini-cli/gemini-3-flash-preview`; use `openclaw onboard --auth-choice google-gemini-cli` or `openclaw models auth login --provider google-gemini-cli --set-default`
+- `google-gemini-cli` - optional explicit runtime for canonical `google/*` models; requires a local `gemini` install and a supported Google AI Studio API-key profile; new Gemini CLI or Antigravity OAuth setup is not offered

 ## Related

--- a/docs/start/onboarding-overview.md
+++ b/docs/start/onboarding-overview.md
@@ -93,8 +93,10 @@ offering a verified manual API-key step when nothing is found. Sensitive
 credentials use masked input. Once inference passes, OpenClaw starts and
 helps configure the rest.

-Gemini CLI remains available for normal agents after setup, but it is not
-offered for this inference gate because it cannot enforce the tool-free probe.
+Gemini CLI remains available as an explicitly configured runtime after setup,
+but Gemini CLI and Antigravity are not offered as detected inference routes.
+Use Google AI Studio API-key or Vertex AI for guided setup. The optional Gemini
+CLI runtime specifically requires an AI Studio API-key profile.

 Full reference: [Onboarding (macOS App)](/start/onboarding)

--- a/docs/start/onboarding.md
+++ b/docs/start/onboarding.md
@@ -91,15 +91,16 @@ To use a Claude subscription when the Gateway host has no Claude CLI login, run
 printed token as **Anthropic setup-token** under **Connect with an API key or
 token**.

-Installed Gemini CLI, Antigravity, Pi, and OpenCode CLIs are shown for context
-when they cannot be selected as the reusable guided-setup inference route.
-Gemini and Antigravity cannot enforce the tool-free inference probe. Pi and
-OpenCode are whole-agent harnesses rather than setup inference routes; their
-session integrations require separate runtime and plugin setup.
+Pi and OpenCode installs may be shown for context when they cannot be selected
+as the reusable guided-setup inference route. They are whole-agent harnesses,
+not setup inference routes; their session integrations require separate runtime
+and plugin setup. Gemini CLI and Antigravity are not offered as detected setup
+routes.

 You can also sign in through the provider's own OAuth or device-pairing flow.
-The built-in choices include OpenAI/ChatGPT, OpenRouter, GitHub Copilot, Google
-Gemini CLI, xAI, MiniMax Global and CN, and Chutes. The list comes from the
+The built-in choices include OpenAI/ChatGPT, OpenRouter, GitHub Copilot, xAI,
+MiniMax Global and CN, and Chutes. Google is available through the supported AI
+Studio API-key route. The list comes from the
 Gateway's active text-inference provider plugins rather than a fixed app list,
 so another provider can opt in without adding provider-specific macOS code.

--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -92,10 +92,9 @@ Plain `openclaw onboard` follows this path:
 2. Detect configured models, API-key environment variables, supported local AI
   CLIs, and already installed tool-capable models from reachable Ollama or LM
   Studio servers on the Gateway host. This read-only pass never downloads a
-   model. Gemini CLI, Antigravity, Pi, and OpenCode installs are also reported
-   when they cannot serve as the reusable inference route for guided setup.
-   Gemini and Antigravity cannot enforce the tool-free probe; Pi and OpenCode
-   are whole-agent harnesses rather than setup inference routes.
+   model. Pi and OpenCode installs may also be reported for context when they
+   cannot serve as the reusable inference route. Gemini CLI and Antigravity are
+   not offered as detected setup routes.
 3. Test the first detected candidate with a real completion. On failure, show the
   reason and continue to the next usable candidate.
 4. If detection is exhausted, choose OpenAI, Anthropic, xAI (Grok), Google, or