OpenCode

The registry gives you the full catalog. To expose a curated subset, rename models in the picker, or override the base URL, add a merge-gateway block to opencode.json in your project root (or ~/.config/opencode/opencode.json):

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "provider": {
4
    "merge-gateway": {
5
      "models": {
6
        "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
7
        "google/gemini-2.5-flash": { "name": "Gemini 2.5 Flash" }
8
      }
9
    }
10
  }
11
}

These two cover a common pair: a high-capability model for hard problems, and a fast, low-cost model for quick edits. Each key under models is a Gateway provider/model name from GET /v1/models. Because the provider comes from the registry, you don’t need the npm or name fields, and your exported MERGE_GATEWAY_API_KEY is picked up automatically. To route through a different host, add an options.baseURL.

Instead of hard-picking a model, add a default_routing entry to the models block in opencode.json (for example "default_routing": { "name": "Merge routing" }) and select it with /models. Gateway hands those requests to your routing policy, which picks the vendor and model per request based on your rules (cost, performance, or prompt complexity). The policy comes from the key’s project (project API key) or the org default.

The export MERGE_GATEWAY_API_KEY=... above lives in your shell, so it applies only to that terminal. To persist it, add the same line to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish). The key you paste through /connect is saved by OpenCode, so it persists on its own. If you add an opencode.json for model overrides, commit it to your project so it persists across sessions too.

OpenCode downloads the Merge Gateway provider package (merge-gateway-ai-sdk-provider) from the npm registry the first time you send a message, then caches it in ~/.cache/opencode/packages. This error means that download failed on your machine, before any request reached Gateway, which is why reconnecting or generating a new API key doesn’t help. Common causes are a corporate proxy or VPN, a private npm registry that hasn’t approved the package, expired registry credentials, or a firewall blocking registry.npmjs.org.

The fastest fix is to seed OpenCode’s package cache from your terminal. OpenCode reuses an existing cache entry and skips its own installer, so this resolves the error whenever your shell has proxy or registry settings that OpenCode doesn’t inherit (common when OpenCode is launched outside the terminal):

$
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 install succeeds, send a message again and you’re done. If it fails, its error output names the real blocker, because it exercises the same download path OpenCode uses. Check npm config list for registry, proxy, or https-proxy overrides you don’t expect. If your organization runs a private registry, it needs to allow both merge-gateway-ai-sdk-provider and its dependencies. After fixing the npm configuration, delete ~/.cache/opencode/packages and send a message again.

If you can’t change the npm setup, use this provider block instead. It runs on OpenCode’s built-in OpenAI-compatible provider against Gateway’s /v1 endpoint, so nothing is downloaded. Chat, tool calls, and image input all work; the trade-off is that Gateway-specific response detail (for example cache token breakdowns) isn’t surfaced, and you list models yourself instead of getting the full catalog:

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "provider": {
4
    "merge-compat": {
5
      "npm": "@ai-sdk/openai-compatible",
6
      "name": "Merge Gateway (compat)",
7
      "options": {
8
        "baseURL": "https://api-gateway.merge.dev/v1",
9
        "apiKey": "{env:MERGE_GATEWAY_API_KEY}"
10
      },
11
      "models": {
12
        "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
13
        "google/gemini-2.5-flash": { "name": "Gemini 2.5 Flash" }
14
      }
15
    }
16
  }
17
}

OpenCode is agentic and relies on tool calls to read and edit files. Tool calling works through Gateway for any model whose capabilities.supports_tool_calling is true on the chosen vendor route. See Tool calling.

Any model Gateway supports. Use GET /v1/models to list them, or open the Gateway dashboard and copy the model identifier.