> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# OpenCode

> Connect OpenCode to Gateway with /connect, optionally curate models in opencode.json, and fix provider download failures.

[OpenCode](https://opencode.ai) lists Merge Gateway in its model registry, so connecting to Gateway's `/v1/ai-sdk` endpoint takes one command and no config file. Shared setup: [Building with coding agents](/merge-gateway/coding-agents/overview).

## Connect OpenCode

Export your key, run `opencode` in your project, then `/connect` and select **Merge Gateway**. Paste the key when prompted, or skip if `MERGE_GATEWAY_API_KEY` is set. Pick a model with `/models` and ask for a small code change. OpenCode's session header groups each session into one thread in Logs.

```bash
export MERGE_GATEWAY_API_KEY="mg_..."
```

## Curate models in opencode.json

The registry's model list is a snapshot that can lag the [model catalog](/merge-gateway/models/catalog). To rename models or add unlisted ones and aliases, add a `merge-gateway` block to `opencode.json` in your project root or `~/.config/opencode/opencode.json`. Skip `npm`, `name`, and the key, which the registry and your export supply.

**`opencode.json`**

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "merge-gateway": {
      "models": {
        "anthropic/claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "google/gemini-3.6-flash": { "name": "Gemini 3.6 Flash" },
        "@alias/support-agent": { "name": "Support agent policy" }
      }
    }
  }
}
```

To override the host, set `options.baseURL` to a URL ending in `/v1/ai-sdk`.

## Fix "Failed to initialize provider: merge-gateway"

On the first message, OpenCode downloads `merge-gateway-ai-sdk-provider` from npm and caches it in `~/.cache/opencode/packages`. This error means the download failed before any request reached Gateway, so a new API key won't help. Usual causes are a proxy or VPN, a private npm registry that hasn't approved the package, or a firewall blocking `registry.npmjs.org`.

Seed the cache from your terminal, which has your proxy and registry settings:

```bash
mkdir -p ~/.cache/opencode/packages/merge-gateway-ai-sdk-provider
cd ~/.cache/opencode/packages/merge-gateway-ai-sdk-provider
npm install merge-gateway-ai-sdk-provider
```

If that fails, its error names the blocker: check `npm config list` for unexpected `registry`, `proxy`, or `https-proxy` values, and make sure a private registry allows the package and its dependencies. Then delete `~/.cache/opencode/packages` and retry.

If you can't change npm, use OpenCode's built-in OpenAI-compatible provider. It downloads nothing, but you list models yourself and lose Gateway-specific response detail such as cache token breakdowns.

**`opencode.json`**

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "merge-compat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Merge Gateway (compat)",
      "options": {
        "baseURL": "https://api-gateway.merge.dev/v1/openai",
        "apiKey": "{env:MERGE_GATEWAY_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-5": { "name": "Claude Sonnet 5" }
      }
    }
  }
}
```

## Next steps

#### [Building with coding agents](/merge-gateway/coding-agents/overview)

Keys, models, aliases, and project scoping

#### [Tracing](/merge-gateway/observability/tracing)

Find an OpenCode session in Logs by thread ID