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

> Add our gateway to OpenCode as a custom provider in opencode.json with @ai-sdk/openai-compatible, store the key via /connect, pick models and fix errors.

Source: https://oneaiapikey.com/docs/guides/opencode

Base URL: `https://api.oneaiapikey.com/v1`

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](https://oneaiapikey.com/console/sign-up).
- An API key from the [API keys page](https://oneaiapikey.com/console/keys), 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:

~/.config/opencode/opencode.json:

```json
{
  "$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 block with an env reference:

```json
"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:

| Model id | Good for | Input | Output |
| --- | --- | --- | --- |
| `claude-sonnet-5` | Daily coding, Code review, Writing | $2.20 | $11 |
| `claude-opus-5-5` | Agentic coding, Large refactors, Complex reasoning | $4.40 | $22 |
| `gpt-6.1-sol` | Codex CLI, Tool calling, Long context | $2.20 | $11 |
| `deepseek-v4-flash` | Budget coding, Sub-agents, Batch jobs | $0.24 | $0.96 |

`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](https://oneaiapikey.com/models).

## Step 3: verify it works

Run a one-shot prompt from your shell:

Smoke test:

```bash
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](https://oneaiapikey.com/console/billing) in the console; no config changes needed.

## Next steps

Also using an editor? See the [Kilo Code](https://oneaiapikey.com/docs/guides/kilo-code) and [Zed](https://oneaiapikey.com/docs/guides/zed) guides, or the full list of [tool guides](https://oneaiapikey.com/docs/guides). The [quickstart](https://oneaiapikey.com/docs/quickstart) covers direct API calls, and the [pricing page](https://oneaiapikey.com/pricing) lists every rate.

## Other OpenAI format tools

- [Codex CLI CLI](https://oneaiapikey.com/docs/guides/codex-cli)
- [Cursor IDE](https://oneaiapikey.com/docs/guides/cursor)
- [Cline Extension](https://oneaiapikey.com/docs/guides/cline)