diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md
index 34e85813f20..279a7ed4736 100644
--- a/docs/concepts/model-providers.md
+++ b/docs/concepts/model-providers.md
@@ -282,6 +282,9 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Auth: Vertex uses gcloud ADC; Gemini CLI uses its OAuth flow
 - Caution: 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.
+  - Install Gemini CLI first:
+    - `brew install gemini-cli`
+    - or `npm install -g @google/gemini-cli`
   - Enable: `openclaw plugins enable google`
   - Login: `openclaw models auth login --provider google-gemini-cli --set-default`
   - Default model: `google-gemini-cli/gemini-3.1-pro-preview`
diff --git a/docs/gateway/cli-backends.md b/docs/gateway/cli-backends.md
index a40d7264bfe..94453000186 100644
--- a/docs/gateway/cli-backends.md
+++ b/docs/gateway/cli-backends.md
@@ -233,6 +233,10 @@ The bundled Google plugin also registers a default for `google-gemini-cli`:
 - `sessionMode: "existing"`
 - `sessionIdFields: ["session_id", "sessionId"]`
 
+Prerequisite: the local Gemini CLI must be installed and available as
+`gemini` on `PATH` (`brew install gemini-cli` or
+`npm install -g @google/gemini-cli`).
+
 Gemini CLI JSON notes:
 
 - Reply text is read from the JSON `response` field.
diff --git a/docs/help/faq.md b/docs/help/faq.md
index 311a1e2b3d8..696856193af 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -651,10 +651,13 @@ for usage/billing and raise limits as needed.
 
     Steps:
 
-    1. Enable the plugin: `openclaw plugins enable google`
-    2. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
-    3. Default model after login: `google-gemini-cli/gemini-3.1-pro-preview`
-    4. If requests fail, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host
+    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-cli/gemini-3.1-pro-preview`
+    5. If requests fail, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host
 
     This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
 
diff --git a/docs/providers/google.md b/docs/providers/google.md
index 598813e6bdb..a06c9e84faf 100644
--- a/docs/providers/google.md
+++ b/docs/providers/google.md
@@ -54,6 +54,9 @@ restrictions. Use at your own risk.
 
 - Default model: `google-gemini-cli/gemini-3.1-pro-preview`
 - Alias: `gemini-cli`
+- Install prerequisite: local Gemini CLI available as `gemini`
+  - Homebrew: `brew install gemini-cli`
+  - npm: `npm install -g @google/gemini-cli`
 - Login:
 
 ```bash
@@ -71,6 +74,10 @@ 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`. OpenClaw supports both Homebrew installs
+and global npm installs, including common Windows/npm layouts.
+
 Gemini CLI JSON usage notes:
 
 - Reply text comes from the CLI JSON `response` field.
diff --git a/docs/providers/models.md b/docs/providers/models.md
index 5c74b0f0f77..683a5be20b3 100644
--- a/docs/providers/models.md
+++ b/docs/providers/models.md
@@ -49,7 +49,7 @@ model as `provider/model`.
 
 - `anthropic-vertex` - 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; default model `google-gemini-cli/gemini-3.1-pro-preview`; use `openclaw onboard --auth-choice google-gemini-cli` or `openclaw models auth login --provider google-gemini-cli --set-default`
+- `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.1-pro-preview`; use `openclaw onboard --auth-choice google-gemini-cli` or `openclaw models auth login --provider google-gemini-cli --set-default`
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
 see [Model providers](/concepts/model-providers).