OpenCode

OpenCode 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.

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.

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. 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.

{
  "$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:

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.

{
  "$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