OpenCode setup: custom provider with @ai-sdk/openai-compatible

OpenCode is an open-source coding agent for the terminal. It builds on the AI SDK, which means any OpenAI-compatible service can be plugged in as a custom provider through the @ai-sdk/openai-compatible package. Our gateway is one of those, so a short JSON block gives OpenCode access to every model in our catalogue on one prepaid balance.

What you need

• OpenCode installed and starting normally in your terminal.
• A funded account (top-ups start at $3): sign up.
• An API key from the API keys page, starting with sk-.

Step 1: save your key with /connect

Start opencode, run the /connect command, scroll to Other, and enter a provider ID. Use relaykit, because the config in the next step refers to the same ID. Paste your sk- key when asked.

OpenCode stores the credential in its local auth file (~/.local/share/opencode/auth.json), outside your project, so it never ends up in git.

Prefer environment variables? Skip /connect and reference a variable from the config instead (shown in step 2).

Step 2: describe the provider in opencode.json

OpenCode reads a global config at ~/.config/opencode/opencode.json and an optional opencode.json in your project root. The global file is the right place for a provider you’ll use everywhere:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "relaykit/claude-sonnet-5",
  "provider": {
    "relaykit": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Relaykit",
      "options": {
        "baseURL": "https://api.oneaiapikey.com/v1"
      },
      "models": {
        "claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "claude-opus-5-5": { "name": "Claude Opus 5.5" },
        "gpt-6.1-sol": { "name": "GPT-6.1 Sol" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  }
}

How the pieces fit:

• The key under provider must match the ID you used with /connect.
• npm: "@ai-sdk/openai-compatible" tells OpenCode to talk to the Chat Completions endpoint.
• options.baseURL includes /v1; the SDK adds /chat/completions itself.
• Each key under models is an exact model id from our catalogue. The name is only a display label.
• The top-level model uses the provider/model format and becomes your default.

If you went the environment variable route, add an apiKey reference to options and set the variable in your shell:

"options": {
  "baseURL": "https://api.oneaiapikey.com/v1",
  "apiKey": "{env:RELAYKIT_API_KEY}"
}

Optionally, give each model a limit object with context and output token counts so OpenCode can manage long sessions accurately.

Recommended models

Rates are USD per 1M tokens, pulled from our catalogue:

claude-sonnet-5 is a solid default for agentic work. Add deepseek-v4-flash for cheap, quick tasks and claude-opus-5-5 for the hard ones. Switch between them any time with the /models command. Browse the rest on the models page.

Step 3: verify it works

Run a one-shot prompt from your shell:

opencode run "Reply with the single word: ready"

If the reply comes back, the provider works. Inside the interactive UI, open /models and confirm the gateway’s models are listed under the provider name. Each request also appears in your console’s usage log within a few seconds.

Troubleshooting

401 Unauthorized. OpenCode didn’t send a valid key. Re-run /connect with the same provider ID, or check that the environment variable named in {env:...} is set in the shell that launched OpenCode.

Provider or models missing from /models. Usually a JSON syntax error or a mismatched provider ID. Validate the file (the $schema line enables editor validation) and make sure the ID matches the one in /connect.

404 Not Found. The baseURL is wrong. Use https://api.oneaiapikey.com/v1, no trailing slash, no endpoint path.

“Model not found” or “no available channel”. A key under models doesn’t match a catalogue id. Ids are lowercase and use the exact punctuation shown above.

Long responses time out. OpenCode streams by default, which keeps long generations alive. In your own scripts, send "stream": true for long outputs, since proxies cut idle non-streaming requests at about 100 seconds.

Balance exhausted. Requests fail at zero credit. Top up in the console; no config changes needed.

Next steps

Also using an editor? See the Kilo Code and Zed guides, or the full list of tool guides. The quickstart covers direct API calls, and the pricing page lists every rate.