feat(gemini_oauth): full Gemini CLI OAuth integration with Cloud Code API

.env.example

@@ -4,7 +4,7 @@ DATABASE_POOL_SIZE=10
 
 # LLM Provider
 # LLM_BACKEND=nearai           # default
-# Possible values: nearai, ollama, openai_compatible, openai, anthropic, github_copilot, tinfoil, openai_codex
+# Possible values: nearai, ollama, openai_compatible, openai, anthropic, github_copilot, tinfoil, openai_codex, gemini_oauth
 # LLM_REQUEST_TIMEOUT_SECS=120  # Increase for local LLMs (Ollama, vLLM, LM Studio)
 
 # === Anthropic Direct ===
@@ -110,6 +110,23 @@ NEARAI_AUTH_URL=https://private.near.ai
 # OPENAI_CODEX_AUTH_URL=https://auth.openai.com  # override (rare)
 # OPENAI_CODEX_API_URL=https://chatgpt.com/backend-api/codex  # override (rare)
 
+# === Google Gemini (OAuth, Gemini CLI compatible) ===
+# LLM_BACKEND=gemini_oauth
+# GEMINI_MODEL=gemini-2.5-flash                  # default
+# GEMINI_CREDENTIALS_PATH=~/.gemini/oauth_creds.json  # default
+# GEMINI_API_KEY=...                             # optional: use API key instead of OAuth
+# GEMINI_API_KEY_AUTH_MECHANISM=query             # "query" (default) or "header"
+# GEMINI_SAFETY_BLOCK_NONE=true                  # disable safety filters (default: false)
+# GEMINI_CLI_CUSTOM_HEADERS=Key:Value,Key2:Value2
+# GEMINI_TOP_P=0.95
+# GEMINI_TOP_K=40
+# GEMINI_SEED=42
+# GEMINI_PRESENCE_PENALTY=0.0
+# GEMINI_FREQUENCY_PENALTY=0.0
+# GEMINI_RESPONSE_MIME_TYPE=application/json
+# GEMINI_RESPONSE_JSON_SCHEMA={"type":"object"}
+# GEMINI_CACHED_CONTENT=cachedContents/abc123
+
 # For full provider setup guide see docs/LLM_PROVIDERS.md
 
 # Channel Configuration

FEATURE_PARITY.md

@@ -3,6 +3,7 @@
 This document tracks feature parity between IronClaw (Rust implementation) and OpenClaw (TypeScript reference implementation). Use this to coordinate work across developers.
 
 **Legend:**
+
 - ✅ Implemented
 - 🚧 Partial (in progress or incomplete)
 - ❌ Not implemented
@@ -204,7 +205,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | Skills (modular capabilities) | ✅ | ✅ | Prompt-based skills with trust gating, attenuation, activation criteria, catalog, selector |
 | Skill routing blocks | ✅ | 🚧 | ActivationCriteria (keywords, patterns, tags) but no "Use when / Don't use when" blocks |
 | Skill path compaction | ✅ | ❌ | ~ prefix to reduce prompt tokens |
-| Thinking modes (off/minimal/low/medium/high/xhigh/adaptive) | ✅ | ❌ | Configurable reasoning depth |
+| Thinking modes (off/minimal/low/medium/high/xhigh/adaptive) | ✅ | 🚧 | thinkingConfig for Gemini models (thinkingBudget/thinkingLevel); no per-level control yet |
 | Per-model thinkingDefault override | ✅ | ❌ | Override thinking level per model; Anthropic Claude 4.6 defaults to adaptive |
 | Block-level streaming | ✅ | ❌ | |
 | Tool-level streaming | ✅ | ❌ | |
@@ -236,9 +237,13 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | NEAR AI | ✅ | ✅ | - | Primary provider |
 | Anthropic (Claude) | ✅ | 🚧 | - | Via NEAR AI proxy; Opus 4.5, Sonnet 4, Sonnet 4.6, adaptive thinking default |
 | OpenAI | ✅ | 🚧 | - | Via NEAR AI proxy; GPT-5.4 + Codex OAuth |
-| AWS Bedrock | ✅ | ❌ | P3 | |
-| Google Gemini | ✅ | ❌ | P3 | |
-| NVIDIA API | ✅ | ❌ | P3 | New provider |
+| AWS Bedrock | ✅ | ✅ | - | Native Converse API via aws-sdk-bedrockruntime (requires `--features bedrock`) |
+| Google Gemini | ✅ | ✅ | - | OAuth (PKCE + S256), function calling, thinkingConfig, generationConfig |
+| io.net | ✅ | ✅ | P3 | Via `ionet` adapter |
+| Mistral | ✅ | ✅ | P3 | Via `mistral` adapter |
+| Yandex AI Studio | ✅ | ✅ | P3 | Via `yandex` adapter |
+| Cloudflare Workers AI | ✅ | ✅ | P3 | Via `cloudflare` adapter |
+| NVIDIA API | ✅ | ✅ | P3 | Via `nvidia` adapter and `providers.json` |
 | OpenRouter | ✅ | ✅ | - | Via OpenAI-compatible provider (RigAdapter) |
 | Tinfoil | ❌ | ✅ | - | Private inference provider (IronClaw-only) |
 | OpenAI-compatible | ❌ | ✅ | - | Generic OpenAI-compatible endpoint (RigAdapter) |
@@ -466,7 +471,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | Device pairing | ✅ | ❌ | |
 | Tailscale identity | ✅ | ❌ | |
 | Trusted-proxy auth | ✅ | ❌ | Header-based reverse proxy auth |
-| OAuth flows | ✅ | 🚧 | NEAR AI OAuth plus hosted extension/MCP OAuth broker; external auth-proxy rollout still pending |
+| OAuth flows | ✅ | 🚧 | NEAR AI OAuth + Gemini OAuth (PKCE, S256) + hosted extension/MCP OAuth broker; external auth-proxy rollout still pending |
 | DM pairing verification | ✅ | ✅ | ironclaw pairing approve, host APIs |
 | Allowlist/blocklist | ✅ | 🚧 | allow_from + pairing store |
 | Per-group tool policies | ✅ | ❌ | |
@@ -523,6 +528,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 ## Implementation Priorities
 
 ### P0 - Core (Already Done)
+
 - ✅ TUI channel with approval overlays
 - ✅ HTTP webhook channel
 - ✅ DM pairing (ironclaw pairing list/approve, host APIs)
@@ -550,13 +556,15 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 - ✅ OpenAI-compatible / OpenRouter provider support
 
 ### P1 - High Priority
+
 - ❌ Slack channel (real implementation)
 - ✅ Telegram channel (WASM, DM pairing, caption, /start)
 - ❌ WhatsApp channel
 - ✅ Multi-provider failover (`FailoverProvider` with retryable error classification)
 - ✅ Hooks system (core lifecycle hooks + bundled/plugin/workspace hooks + outbound webhooks)
 
 ### P2 - Medium Priority
+
 - ❌ Media handling (images, PDFs)
 - ✅ Ollama/local model support (via rig::providers::ollama)
 - ❌ Configuration hot-reload
@@ -565,6 +573,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 - ❌ Partial output preservation on abort
 
 ### P3 - Lower Priority
+
 - ❌ Discord channel
 - ❌ Matrix channel
 - ❌ Other messaging platforms

docs/LLM_PROVIDERS.md

@@ -1,8 +1,8 @@
 # LLM Provider Configuration
 
 IronClaw defaults to NEAR AI for model access, but supports any OpenAI-compatible
-endpoint as well as Anthropic and Ollama directly. This guide covers the most common
-configurations.
+endpoint as well as Anthropic, Ollama, and Google Gemini directly. This guide covers
+the most common configurations.
 
 ## Provider Overview
 
@@ -11,7 +11,7 @@ configurations.
 | NEAR AI | `nearai` | OAuth (browser) | Default; multi-model |
 | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | Claude models |
 | OpenAI | `openai` | `OPENAI_API_KEY` | GPT models |
-| Google Gemini | `gemini` | `GEMINI_API_KEY` | Gemini models |
+| Google Gemini | `gemini_oauth` | OAuth (browser) | Gemini models; function calling |
 | io.net | `ionet` | `IONET_API_KEY` | Intelligence API |
 | Mistral | `mistral` | `MISTRAL_API_KEY` | Mistral models |
 | Yandex AI Studio | `yandex` | `YANDEX_API_KEY` | YandexGPT models |
@@ -62,6 +62,51 @@ Popular models: `gpt-4o`, `gpt-4o-mini`, `o3-mini`
 
 ---
 
+## Google Gemini (OAuth)
+
+Uses Google OAuth with PKCE (S256) for authentication — no API key required.
+On first run, a browser opens for Google account login. Credentials (including
+refresh token) are saved to `~/.gemini/oauth_creds.json` with `0600` permissions.
+
+```env
+LLM_BACKEND=gemini_oauth
+GEMINI_MODEL=gemini-2.5-flash
+```
+
+### Supported features
+
+| Feature | Status | Notes |
+|---|---|---|
+| Function calling | ✅ | `functionDeclarations` / `functionCall` / `functionResponse` |
+| `generationConfig` | ✅ | `temperature`, `maxOutputTokens` passed from request |
+| `thinkingConfig` | ✅ | `thinkingBudget`/`thinkingLevel` for thinking-capable models (does NOT set `includeThoughts`) |
+| `toolConfig` | ✅ | `functionCallingConfig.mode`: `AUTO`/`ANY`/`NONE` |
+| SSE streaming | ✅ | Cloud Code API with `streamGenerateContent?alt=sse` |
+| Token refresh | ✅ | Automatic via refresh token |
+
+### Popular models
+
+| Model | ID | Notes |
+|---|---|---|
+| Gemini 3.1 Pro | `gemini-3.1-pro-preview` | Latest, strongest reasoning |
+| Gemini 3.1 Pro Custom Tools | `gemini-3.1-pro-preview-customtools` | Enhanced tool use |
+| Gemini 3 Pro | `gemini-3-pro-preview` | Preview |
+| Gemini 3 Flash | `gemini-3-flash-preview` | Fast preview with thinking |
+| Gemini 3.1 Flash Lite | `gemini-3.1-flash-lite-preview` | Preview, lightweight |
+| Gemini 2.5 Pro | `gemini-2.5-pro` | Stable, strong reasoning |
+| Gemini 2.5 Flash | `gemini-2.5-flash` | Fast, good quality |
+| Gemini 2.5 Flash Lite | `gemini-2.5-flash-lite` | Fastest, lightweight |
+
+### Cloud Code API vs standard API
+
+Models containing `-preview` (with hyphen) or `gemini-3` in the name, as well
+as any `gemini-` model with major version >= 2, route through the Cloud Code
+API (`cloudcode-pa.googleapis.com`) which supports SSE streaming
+and project-scoped access. Other models use the standard Generative Language
+API (`generativelanguage.googleapis.com`).
+
+---
+
 ## GitHub Copilot
 
 GitHub Copilot exposes chat endpoint at

src/app.rs

@@ -729,13 +729,13 @@ impl AppBuilder {
         self.init_database().await?;
         self.init_secrets().await?;
 
-        // Post-init validation: if a non-nearai backend was selected but
-        // credentials were never resolved (deferred resolution found no keys),
-        // fail early with a clear error instead of a confusing runtime failure.
-        if self.config.llm.backend != "nearai"
-            && self.config.llm.backend != "bedrock"
-            && self.config.llm.backend != "openai_codex"
-            && self.config.llm.provider.is_none()
+        // Post-init validation: backends with dedicated config (nearai, gemini_oauth,
+        // bedrock, openai_codex) handle their own credential resolution. For registry-based
+        // backends, fail early if no provider config was resolved.
+        if !matches!(
+            self.config.llm.backend.as_str(),
+            "nearai" | "gemini_oauth" | "bedrock" | "openai_codex"
+        ) && self.config.llm.provider.is_none()
         {
             let backend = &self.config.llm.backend;
             anyhow::bail!(

src/config/llm.rs

@@ -9,6 +9,7 @@ use crate::llm::config::*;
 use crate::llm::registry::{ProviderProtocol, ProviderRegistry};
 use crate::llm::session::SessionConfig;
 use crate::settings::Settings;
+
 impl LlmConfig {
     /// Create a test-friendly config without reading env vars.
     #[cfg(feature = "libsql")]
@@ -37,6 +38,7 @@ impl LlmConfig {
             },
             provider: None,
             bedrock: None,
+            gemini_oauth: None,
             openai_codex: None,
             request_timeout_secs: 120,
             cheap_model: None,
@@ -73,11 +75,16 @@ impl LlmConfig {
             backend_lower == "nearai" || backend_lower == "near_ai" || backend_lower == "near";
         let is_bedrock =
             backend_lower == "bedrock" || backend_lower == "aws_bedrock" || backend_lower == "aws";
+        let is_gemini_oauth = backend_lower == "gemini_oauth" || backend_lower == "gemini-oauth";
         let is_openai_codex = backend_lower == "openai_codex"
             || backend_lower == "openai-codex"
             || backend_lower == "codex";
 
-        if !is_nearai && !is_bedrock && !is_openai_codex && registry.find(&backend_lower).is_none()
+        if !is_nearai
+            && !is_bedrock
+            && !is_gemini_oauth
+            && !is_openai_codex
+            && registry.find(&backend_lower).is_none()
         {
             tracing::warn!(
                 "Unknown LLM backend '{}'. Will attempt as openai_compatible fallback.",
@@ -131,8 +138,8 @@ impl LlmConfig {
             smart_routing_cascade: parse_optional_env("SMART_ROUTING_CASCADE", true)?,
         };
 
-        // Resolve registry provider config (for non-NearAI, non-Bedrock, non-Codex backends)
-        let provider = if is_nearai || is_bedrock || is_openai_codex {
+        // Resolve registry provider config (for non-NearAI, non-Bedrock, non-Gemini, non-Codex backends)
+        let provider = if is_nearai || is_bedrock || is_gemini_oauth || is_openai_codex {
             None
         } else {
             Some(Self::resolve_registry_provider(
@@ -213,6 +220,19 @@ impl LlmConfig {
 
         let request_timeout_secs = parse_optional_env("LLM_REQUEST_TIMEOUT_SECS", 120)?;
 
+        let gemini_oauth = if backend_lower == "gemini_oauth" || backend_lower == "gemini-oauth" {
+            let model = Self::resolve_model("GEMINI_MODEL", settings, "gemini-2.5-flash")?;
+            let credentials_path = optional_env("GEMINI_CREDENTIALS_PATH")?
+                .map(PathBuf::from)
+                .unwrap_or_else(GeminiOauthConfig::default_credentials_path);
+            Some(GeminiOauthConfig {
+                model,
+                credentials_path,
+            })
+        } else {
+            None
+        };
+
         // Generic cheap model (works with any backend).
         // Falls back to NearAI-specific cheap_model in provider chain logic.
         let cheap_model = optional_env("LLM_CHEAP_MODEL")?;
@@ -226,6 +246,8 @@ impl LlmConfig {
                 "nearai".to_string()
             } else if is_bedrock {
                 "bedrock".to_string()
+            } else if is_gemini_oauth {
+                "gemini_oauth".to_string()
             } else if is_openai_codex {
                 "openai_codex".to_string()
             } else if let Some(ref p) = provider {
@@ -237,6 +259,7 @@ impl LlmConfig {
             nearai,
             provider,
             bedrock,
+            gemini_oauth,
             openai_codex,
             request_timeout_secs,
             cheap_model,

src/config/mod.rs

@@ -56,8 +56,8 @@ pub use self::tunnel::TunnelConfig;
 pub use self::wasm::WasmConfig;
 pub use self::workspace::WorkspaceConfig;
 pub use crate::llm::config::{
-    BedrockConfig, CacheRetention, LlmConfig, NearAiConfig, OAUTH_PLACEHOLDER, OpenAiCodexConfig,
-    RegistryProviderConfig,
+    BedrockConfig, CacheRetention, GeminiOauthConfig, LlmConfig, NearAiConfig, OAUTH_PLACEHOLDER,
+    OpenAiCodexConfig, RegistryProviderConfig,
 };
 pub use crate::llm::session::SessionConfig;
 

src/llm/config.rs

@@ -165,6 +165,8 @@ pub struct LlmConfig {
     pub provider: Option<RegistryProviderConfig>,
     /// AWS Bedrock config (populated when backend=bedrock, requires --features bedrock).
     pub bedrock: Option<BedrockConfig>,
+    /// Gemini OAuth config (populated when backend=gemini_oauth).
+    pub gemini_oauth: Option<GeminiOauthConfig>,
     /// OpenAI Codex config (populated when backend=openai_codex).
     pub openai_codex: Option<OpenAiCodexConfig>,
     /// HTTP request timeout in seconds for LLM API calls.
@@ -267,3 +269,34 @@ impl NearAiConfig {
         }
     }
 }
+
+/// Configuration for Gemini OAuth integration.
+///
+/// Extended generation config parameters (topP, topK, seed, etc.) are read from
+/// environment variables at request time:
+/// - `GEMINI_TOP_P` — nucleus sampling (0.0–1.0)
+/// - `GEMINI_TOP_K` — top-k sampling (integer)
+/// - `GEMINI_SEED` — deterministic generation seed
+/// - `GEMINI_PRESENCE_PENALTY` — presence penalty (-2.0–2.0)
+/// - `GEMINI_FREQUENCY_PENALTY` — frequency penalty (-2.0–2.0)
+/// - `GEMINI_RESPONSE_MIME_TYPE` — e.g. "application/json"
+/// - `GEMINI_RESPONSE_JSON_SCHEMA` — JSON schema string for structured output
+/// - `GEMINI_CACHED_CONTENT` — cached content resource name
+/// - `GEMINI_CLI_CUSTOM_HEADERS` — custom headers (key:value,key:value)
+/// - `GOOGLE_GENAI_API_VERSION` — API version (default: v1beta)
+/// - `GEMINI_API_KEY` — optional API key for non-OAuth auth mode
+/// - `GEMINI_API_KEY_AUTH_MECHANISM` — "x-goog-api-key" (default) or "bearer"
+#[derive(Debug, Clone)]
+pub struct GeminiOauthConfig {
+    pub model: String,
+    pub credentials_path: PathBuf,
+}
+
+impl GeminiOauthConfig {
+    pub fn default_credentials_path() -> PathBuf {
+        dirs::home_dir()
+            .unwrap_or_else(|| PathBuf::from("."))
+            .join(".gemini")
+            .join("oauth_creds.json")
+    }
+}