---
title: OpenCode Integration
description: Connect OpenCode to 200+ models through LLM Gateway's built-in provider. No config files needed — just select, authenticate, and code.
icon: OpenCode
---

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

[OpenCode](https://opencode.ai) is an open-source AI coding agent for your terminal, IDE, or desktop. LLM Gateway is a built-in provider in OpenCode, so setup takes under a minute — no config files or npm adapters required. You get access to 200+ models from 40+ providers, all tracked in one dashboard.

<Callout type="info">
	**Using DevPass?** This integration also works with a
	[DevPass](https://devpass.llmgateway.io) plan key. Use root model IDs without
	a provider prefix (`claude-sonnet-4-5`, not `anthropic/claude-sonnet-4-5`) —
	provider-pinned routing is not available on coding plans; the gateway picks
	the provider for you.
</Callout>

## Prerequisites

- OpenCode installed — visit the [OpenCode download page](https://opencode.ai/download) for your platform
- An LLM Gateway API key

## Setup

<Steps>
<Step>
### Launch OpenCode

Start OpenCode from your terminal:

```bash
opencode
```

**In VS Code/Cursor:**

1. Install the OpenCode extension from the marketplace
2. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
3. Type "OpenCode" and select "Open opencode"

</Step>

<Step>
### Open the Provider List

Once OpenCode launches, run the `/providers` or `/connect` command to open the provider selection screen.

</Step>

<Step>
### Select LLM Gateway

LLM Gateway is listed as a built-in provider. Select "LLM Gateway" from the provider list.

</Step>

<Step>
### Enter Your API Key

OpenCode will prompt you for your API key. Enter your LLM Gateway API key and press Enter. OpenCode will automatically save your credentials securely.

[Sign up for LLM Gateway](https://llmgateway.io/signup) and create an API key from your dashboard.

</Step>

<Step>
### Start Using OpenCode

You're all set! OpenCode is now connected to LLM Gateway. You can start asking questions and building with AI.

</Step>
</Steps>

## Why Use LLM Gateway with OpenCode

- **200+ models** — GPT-5, Claude, Gemini, Llama, and more from 40+ providers
- **One API key** — Stop juggling credentials for every provider
- **Cost tracking** — See what each coding agent costs in your dashboard
- **Response caching** — Repeated requests hit cache automatically
- **Volume discounts** — The more you use, the more you save

## Adding Custom Models

The built-in provider gives you access to all standard LLM Gateway models. If you want to add custom model aliases or configure models not yet listed in the built-in provider, you can create a `config.json` in your OpenCode configuration directory:

**macOS/Linux:** `~/.config/opencode/config.json`

**Windows:** `C:\Users\YourUsername\.config\opencode\config.json`

```json
{
	"provider": {
		"llmgateway": {
			"models": {
				"deepseek-v3": {
					"name": "DeepSeek V3"
				}
			}
		}
	}
}
```

Since LLM Gateway is a built-in provider, you only need to specify what you're adding — OpenCode merges your config with the built-in provider definition, so `npm`, `name`, and `baseURL` don't need to be repeated.

After updating `config.json`, restart OpenCode to see the new models.

## Pinning a Model to a Specific Provider

OpenCode's built-in model list only shows root model IDs (e.g. `claude-sonnet-5`), which LLM Gateway routes to the best available provider automatically. If you want a model to always run on one specific provider — for example to guarantee a fixed price, a compliance boundary, or consistent behavior — use LLM Gateway's [`provider/model` syntax](/features/routing#provider-specific-routing) as the model ID.

Instead of writing these entries by hand, you can generate the full catalog — every coding model, pinned per upstream provider, with display names, context limits, and pricing — with the [LLM Gateway CLI](https://docs.llmgateway.io/developers/cli#configure):

```bash
npx @llmgateway/cli configure opencode
```

Or add the pinned variants you want manually as custom models, and they show up in OpenCode's model picker alongside the built-in list:

```json
{
	"provider": {
		"llmgateway": {
			"models": {
				"anthropic/claude-sonnet-5": {
					"name": "Claude Sonnet 5 (Anthropic direct)"
				},
				"aws-bedrock/claude-sonnet-5": {
					"name": "Claude Sonnet 5 (AWS Bedrock)"
				}
			}
		}
	}
}
```

You can also pin one as your default model, or per-agent:

```json
{
	"model": "llmgateway/anthropic/claude-sonnet-5"
}
```

For providers with multiple regions, append a region suffix to pin both provider and region, e.g. `aws-bedrock/claude-sonnet-5:us`. See the [routing docs](/features/routing#provider-specific-routing) for the full syntax, and each model's available providers on the [models page](https://llmgateway.io/models).

### Disabling Fallback

By default, LLM Gateway automatically fails over to alternative providers if your chosen provider is experiencing downtime — even for provider-pinned model IDs. To make the pin strict, pass the `X-No-Fallback` header. Requests will then be sent only to the provider you specified, with no automatic fallback.

```json
{
	"provider": {
		"llmgateway": {
			"options": {
				"headers": {
					"X-No-Fallback": "true"
				}
			}
		}
	}
}
```

<Callout type="warn">
	Disabling fallback means requests will fail if the chosen provider is down.
	See the [routing
	docs](/features/routing#disabling-fallback-with-x-no-fallback-header) for
	details.
</Callout>

## Switching Models

Select a different model directly in the OpenCode interface, or update the `model` field in your configuration:

```json
{
	"model": "llmgateway/gpt-5-mini"
}
```

<Callout type="info">
	View all available models on the [models page](https://llmgateway.io/models).
</Callout>

## Troubleshooting

### Connection timeout

Check that you have an active internet connection and that your API key is valid from the [dashboard](https://llmgateway.io/dashboard).

### Custom models not showing up

After editing `config.json`, restart OpenCode completely for changes to take effect.

### 404 Not Found errors with custom config

If you are using a custom `config.json`, verify your `baseURL` is set to `https://api.llmgateway.io/v1` (note the `/v1` at the end).

## Configuration Tips

- **Global configuration**: Use `~/.config/opencode/config.json` to apply settings across all projects
- **Project-specific**: Place `opencode.json` in your project root to override global settings for that project
- **Model selection**: You can specify different models for different types of tasks using OpenCode's agent configuration

<Callout type="info">
	Need help? Join our [Discord community](https://llmgateway.io/discord) for
	support and troubleshooting assistance.
</Callout>
