From d540255ce706fca0bfc4136c91e6e49f7ca95d8a Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 30 Jul 2026 22:56:26 +0800 Subject: [PATCH] docs(google): document supported auth paths --- docs/cli/openclaw.md | 6 +- docs/cli/setup.md | 5 +- docs/concepts/model-providers.md | 51 ++++------------ docs/concepts/usage-tracking.md | 2 +- docs/docs_map.md | 2 +- docs/gateway/cli-backends.md | 6 +- docs/help/faq-first-run.md | 18 +++--- docs/nodes/audio.md | 3 +- docs/nodes/media-understanding.md | 3 - docs/providers/google.md | 99 +++++++++++++++---------------- docs/providers/index.md | 2 +- docs/providers/models.md | 2 +- docs/start/onboarding-overview.md | 6 +- docs/start/onboarding.md | 15 ++--- docs/start/wizard.md | 7 +-- 15 files changed, 100 insertions(+), 127 deletions(-) diff --git a/docs/cli/openclaw.md b/docs/cli/openclaw.md index a7581f970ba9..7b7ec72b4efd 100644 --- 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 diff --git a/docs/cli/setup.md b/docs/cli/setup.md index 67ef90d724a2..4a2961593918 100644 --- 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 diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 8e799ae96c33..23d297866780 100644 --- 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/"].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. - -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. - - -Gemini CLI OAuth is shipped as part of the bundled `google` plugin. - - - - - - ```bash - brew install gemini-cli - ``` - - - ```bash - npm install -g @google/gemini-cli - ``` - - - - - ```bash - openclaw plugins enable google - ``` - - - ```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. - - - - If requests fail after login, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host. - - +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 diff --git a/docs/concepts/usage-tracking.md b/docs/concepts/usage-tracking.md index 6b7d1b898913..3e22f1eb51b9 100644 --- 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 diff --git a/docs/docs_map.md b/docs/docs_map.md index 588babdd0330..c34437b0d5ce 100644 --- 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 diff --git a/docs/gateway/cli-backends.md b/docs/gateway/cli-backends.md index f76e7795841f..2d5ace905d96 100644 --- 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: diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 732456b4b73e..e50ee1947649 100644 --- 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). - - Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`. + + 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). diff --git a/docs/nodes/audio.md b/docs/nodes/audio.md index 21a012a379fd..563f88c85775 100644 --- 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`. diff --git a/docs/nodes/media-understanding.md b/docs/nodes/media-understanding.md index 475b013d52ae..9909497c1a76 100644 --- a/docs/nodes/media-understanding.md +++ b/docs/nodes/media-understanding.md @@ -174,9 +174,6 @@ When `tools.media..enabled` is not `false` and no models are configu - Video: Google → Qwen → Moonshot - - First installed `agy` or `antigravity` binary (override with `OPENCLAW_ANTIGRAVITY_CLI`), sandboxed against the media's directory. - To disable auto-detection for a capability: diff --git a/docs/providers/google.md b/docs/providers/google.md index 6d23566d88b1..7f4eb71e8371 100644 --- 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. - - **Best for:** standard Gemini API access through Google AI Studio. + + **Recommended for:** standard Gemini API access. @@ -70,16 +72,23 @@ Choose your preferred auth method and follow the setup steps. - - **Best for:** signing in with your Google account through Gemini CLI OAuth instead of using a separate API key. + + **Advanced use only:** run a canonical `google/*` model through an installed + Gemini CLI while keeping authentication on the supported AI Studio API-key + path. - - The `google-gemini-cli` provider is an unofficial integration. Some users - report account restrictions when using OAuth this way. Use at your own risk. - + 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. - + + 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. + + 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. - - ```bash - openclaw models auth login --provider google-gemini-cli --set-default - ``` - - - ```bash - openclaw models list --provider google + + 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" }, + }, + }, + }, + }, + } ``` - - 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` - - - If Gemini CLI OAuth requests fail after login, set `GOOGLE_CLOUD_PROJECT` or - `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and retry. - - - - If login fails before the browser flow starts, make sure the local `gemini` - command is installed and on `PATH`. - - - 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. @@ -466,10 +466,9 @@ verifies a text response and `describe_view` function roundtrip. - 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. diff --git a/docs/providers/index.md b/docs/providers/index.md index 28d76cfe4045..11802f05f328 100644 --- 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 diff --git a/docs/providers/models.md b/docs/providers/models.md index 14e07184a0e7..29dced9eea9e 100644 --- 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 diff --git a/docs/start/onboarding-overview.md b/docs/start/onboarding-overview.md index 5c7b39a186fb..55395673d395 100644 --- 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) diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index baa91b1ab5a9..bc7be10af8ee 100644 --- 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. diff --git a/docs/start/wizard.md b/docs/start/wizard.md index 663c87980ee2..cd7c0de4ef1b 100644 --- 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