Setup guide - From Gemini and OpenCode docs
Use Gemini in OpenCode
OpenCode's documented Custom provider recipe (a providers entry with env, package @opencode/ai/providers/openai-compatible, settings.baseURL and models) filled in with Google's documented Gemini OpenAI-compatible base URL and a current Gemini model id.
Last verified 4 steps4 official sources
Steps
- Step 1.
Get a Gemini API key from Google AI Studio (https://aistudio.google.com/apikey).
- Step 2.
Make the key available as GEMINI_API_KEY in the environment OpenCode runs in. The Custom provider's env field lists the environment variable names that can provide the credential.
Terminalexport GEMINI_API_KEY=your-key - Step 3.
Add the provider to opencode.jsonc (or opencode.json). This is OpenCode's Custom provider example with Google's documented OpenAI-compatible base URL and model id substituted in. The key under providers ('gemini-openai' here is an arbitrary example) becomes the provider ID in model references.
JSON{ "$schema": "https://opencode.ai/config.json", "providers": { "gemini-openai": { "name": "Google Gemini", "env": ["GEMINI_API_KEY"], "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/", }, "models": { "gemini-3.8-flash": { "name": "Gemini 3.8 Flash", }, }, }, }, } - Step 4.
Run /models and pick the Gemini model; the selection applies to the current session. To make it the default for new work, set model to provider/model.
JSON{ "$schema": "https://opencode.ai/config.json", "model": "gemini-openai/gemini-3.8-flash", }
Caveats
- Combined path: OpenCode documents the Custom provider mechanism; Google documents the base URL and model ids. Neither page shows this exact combination.
- OpenCode's catalog comes from models.dev and its package list includes a native @opencode/ai/providers/google runtime, so Google may also be offered under /connect. The providers page has no Google Gemini API section with steps (its Vertex section covers Google Vertex with ADC, not AI Studio keys), so the built-in route is not given here.
- For a model that is not already in the catalog, OpenCode assumes tool support, text and image input, a 200,000-token context limit and a 32,000-token output limit. Set capabilities and limit on the model entry if you need accurate values.
- Google states 'Support for the OpenAI libraries is still in beta while we extend feature support.'
- OpenCode lists @opencode/ai/providers/openai-compatible and a separate .../openai-compatible/responses package. Google's compatibility page documents chat completions, so the base compatible package is used here.
More setup guides
Same tool, other providers
Related reading
- Headless AI Coding Agents in CI: Claude Code, Codex CLI, Gemini CLI, and opencode ComparedHeadless AI coding agents in CI compared: Claude Code, Codex CLI, Gemini CLI, and opencode on invocation flags, sandboxing, auth, and output formats.
- Gemini Trains on Your Chats Unless Keep Activity Is OffA Tell HN says paying for Gemini does not stop chat training. What Google documents about Keep Activity, human review and 3-year retention, and what developers should do before pasting code.
- Gemini 4 Carbon: Benchmarks, Pricing, and AccessGemini 4 Carbon is Google's new frontier model: 59 on the AA Intelligence Index, $2/$10 intro pricing, but cyber-defender access only. What builders do now.
- AI API 429, 529 and 503 Errors: Retry Rules That Match the DocsWhich 429, 529 and 503 errors to retry across OpenAI, Claude, Gemini and Bedrock, how to read Retry-After, and a typed wrapper that skips quota errors.
- AI Model Shutdown Dates 2026-2027: Calendar and Migration PlanEvery scheduled AI model API shutdown through mid 2027 by month: GPT-4o on Jan 14, whisper-1 on Feb 26, Claude Sonnet 4.5 on Nov 30, plus how to migrate.
- Gemini Live and TTS Preview Models Retire November 17: Moving to Gemini 3.8 Live and 3.8 Flash TTSThe Gemini API shuts down two Live API preview models and three TTS preview models on November 17, 2026. Replacement ids, what changes in the session config and TTS request, prices before and after, and the code change.
FAQ
How do I use Gemini in OpenCode?
OpenCode's documented Custom provider recipe (a providers entry with env, package @opencode/ai/providers/openai-compatible, settings.baseURL and models) filled in with Google's documented Gemini OpenAI-compatible base URL and a current Gemini model id.
Which Gemini model ids work in OpenCode?
The official docs read for this guide list gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite and gemini-3.1-pro-preview. Requests go to https://generativelanguage.googleapis.com/v1beta/openai/.
Is this an official Gemini and OpenCode setup?
The steps draw on both Gemini's and OpenCode's docs. It was last checked against 4 official pages on November 8, 2026.
Sources
Last verified against 4 official pages.
- opencode.aihttps://opencode.ai/docs/providers/
- opencode.aihttps://opencode.ai/docs/models/
- ai.google.devhttps://ai.google.dev/gemini-api/docs/openai
- ai.google.devhttps://ai.google.dev/gemini-api/docs/models
Newsletter
New models, set up the day they ship
One email per week. New model releases, the coding tools that support them and how to wire them up.