Fresh 2026

OpenCode

How to configure OpenCode's opencode.json to route requests through Gateway via the Merge Gateway AI SDK provider.

OpenCode is an open-source terminal coding agent. Add Merge Gateway as a provider and OpenCode can use every model Gateway supports through a single API key, with routing policies, cost governance, and full request observability in the Gateway dashboard.

Before you start

• Install OpenCode: npm i -g opencode-ai or brew install anomalyco/tap/opencode

• Grab an API key from gateway.merge.dev/settings/api-keys and export it:

  export MERGE_GATEWAY_API_KEY="mg_your_key"

• Decide which models fit your workflow. Gateway model names take the form provider/model, for example anthropic/claude-sonnet-4-6 for heavy coding or google/gemini-2.5-flash for fast, low-cost edits. Browse the full catalog with GET /v1/models or in the dashboard.

Configure OpenCode

Create an opencode.json in your project root (or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "merge-gateway": {
      "npm": "merge-gateway-ai-sdk-provider",
      "name": "Merge Gateway",
      "options": {
        "baseURL": "https://api-gateway.merge.dev/v1/ai-sdk",
        "apiKey": "{env:MERGE_GATEWAY_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "google/gemini-2.5-flash": { "name": "Gemini 2.5 Flash" }
      }
    }
  }
}

These two cover a common pair: a high-capability model for hard problems, and a fast, low-cost model for quick edits. Add whichever models fit your use case. Each key is a Gateway provider/model name from GET /v1/models.

Run opencode in your project, then /models and select one of your Merge Gateway models.

Ask OpenCode to make a small code change. Streaming, tool calls, and file edits all work, and the request shows up in your Gateway dashboard within a few seconds.

Caveats

Until Merge Gateway is listed in OpenCode's model registry, declare the models you want under the models key above. Once Gateway is in the registry, you can run /connect, select Merge Gateway, paste your key, and skip the models block.

Instead of hard-picking a model, point at a routing policy and let Gateway select the vendor and model per request based on your rules (cost, performance, or prompt complexity). Useful when you want cheap models for simple edits and stronger models for hard problems without switching by hand.

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 opencode.json itself is committed to your project, so it persists across sessions automatically.

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.

Next steps

Let Gateway pick the best vendor for each OpenCode request

Use a project-scoped key so OpenCode usage is tracked separately

Cap spend and restrict which models OpenCode can hit