OpenCode OpenAI Compatible Provider: Setting the Base URL in opencode.json

You ran /connect inside OpenCode, scrolled to Other, typed a provider ID, pasted your API key, and hit enter. OpenCode said it saved. You started a task. Nothing changed — the model list still shows the built-ins, and if you try to reference your model you get model not found. There was no base URL field anywhere in that flow, and that absence is the reason why.

That is the expected outcome, and it is documented. OpenCode's provider docs state the requirement as two numbered steps:

To add a provider you need to: 1. Add the API keys for the provider using the /connect command. 2. Configure the provider in your OpenCode config.

Step 1 is what you did. Step 2 is a file you write. /connect stores the key in ~/.local/share/opencode/auth.json and stops there — nothing in that flow writes a provider block for you.

So an opencode openai compatible provider is a block you write into opencode.json, not a form you fill in. Below: the shortest block that loads, the version difference that silently voids it, and the one command that makes your models appear.

The shortest opencode.json that works

OpenCode reads opencode.json from the project root. There are two config shapes in circulation, and they are not interchangeable.

v2 — note providers, plural:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "aicomp": {
      "env": ["AICOMP_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://aicomp.ai/v1"
      },
      "models": {
        "claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  }
}

v1 — provider, singular, and the package is different:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aicomp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "aicomp",
      "options": {
        "baseURL": "https://aicomp.ai/v1",
        "apiKey": "{env:AICOMP_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": { "name": "Claude Sonnet 5" }
      }
    }
  }
}

In OpenCode the provider block is keyed provider (singular) on v1 and providers (plural) on v2. Using the v1 key on a v2 build makes the entire block parse as an unknown key and get silently ignored — no error, no warning. The field names move too:

Three things to get right before you save:

1. The key never goes in the file. v2 lists the variable name in env; v1 interpolates it with {env:VAR}. Export it in the shell you launch OpenCode from — export AICOMP_API_KEY=sk-... — so it never lands in a committed file.
2. The base URL stops at /v1. https://aicomp.ai/v1 and nothing after it. The provider package appends the resource path.
3. The package string differs between versions. v1 is @ai-sdk/openai-compatible. v2 is @opencode/ai/providers/openai-compatible. A v1 package name in a v2 block, or the reverse, produces a provider that loads and then does nothing useful.

Verify the credential from outside OpenCode first. If this fails, nothing you do in the config matters:

export AICOMP_API_KEY=sk-your-gateway-key

curl -s https://aicomp.ai/v1/models \
  -H "Authorization: Bearer $AICOMP_API_KEY" \
  | jq -r '.data[].id' | head -40

Then start OpenCode in that directory and run the /models command. Your provider and its models appear in the picker only after that. Skipping /models is why a correct config looks broken: the values are loaded, the list just has not been refreshed.

The OpenCode-specific parts of an OpenAI-compatible provider

/connect stores a credential, not a provider

The interactive flow is: /connect → scroll to the bottom → Other → enter a unique provider ID → enter the API key. Per the docs above, that is step 1 of 2. The key lands in ~/.local/share/opencode/auth.json.

So the sequence that works is both steps, in order:

# 1. register the credential interactively
opencode            # then /connect -> Other -> "aicomp" -> paste key

# 2. write the provider block into ./opencode.json (the two blocks above)

# 3. refresh the picker inside the TUI
#    /models

If you did step 1 and stopped, you have a key in a store and no provider that uses it.

Model references are providerID/modelID

The providers object is indexed by provider ID, and that same ID is the prefix in every model reference. With the config above, the provider ID is aicomp, so the models are aicomp/claude-sonnet-5 and aicomp/deepseek-v4-flash. Anywhere OpenCode asks for a model — the picker, a --model flag, a per-agent override — the string carries the prefix.

This is where it gets sharp: a small number of catalogue IDs already contain a slash (

). They are rare but they are real — OpenCode's own docs use "google/gemma-3n-e4b" as a model key in their LM Studio example, so a slash inside the model half is expected rather than an error. A gateway model named vendor/model produces a reference like aicomp/vendor/model, and it is genuinely ambiguous on sight which slash separates provider from model and which is part of the model name. The rule is that the first slash is always the separator — the prefix is the provider ID you wrote, and everything after it is the model ID verbatim, including any slashes it carries.

Per-model limits belong in the same block. OpenCode accepts a limit object with context and output, which is where you stop a long response being cut short:

"models": {
  "claude-sonnet-5": {
    "name": "Claude Sonnet 5",
    "limit": { "context": 200000, "output": 16384 }
  }
}

settings.baseURL only exists if the package supports it

The base URL is not a top-level OpenCode field in v2 — it lives under settings as settings.baseURL, and it is package-specific. It applies only when the package you named actually reads it. Set @opencode/ai/providers/openai-compatible and the setting is honoured. Name a package that does not implement it and the field is inert: no error, no warning, requests just go to the package's default endpoint.

That is why a config can look perfect and still bill the wrong place. Confirm the request in your gateway usage log rather than trusting a successful task.

headers and body work at two levels

Both v1 (options.headers) and v2 accept custom headers, and v2 adds body. The useful part is scope: you can set them at the provider level, where they apply to every model, or at the model or variant level, where they override for one entry. A provider that needs a specific header on one model only does not force you to duplicate the provider block.

{
  "providers": {
    "aicomp": {
      "env": ["AICOMP_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "https://aicomp.ai/v1" },
      "headers": { "HTTP-Referer": "https://your-app.example" },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "headers": { "X-One-Model-Only": "true" }
        }
      }
    }
  }
}

env is an ordered list, not a single name

v2's env takes an array of environment variable names and checks them in order. That is a fallback chain: if the first is unset, OpenCode tries the next. It is also a quiet failure source — if you renamed your variable and left the old name first, OpenCode finds nothing and you get an auth error with a key that is definitely exported under some name.

Failure modes

What a coding session costs here

OpenCode re-reads whatever is in scope on every turn, so a twenty-turn session pays for the same files twenty times on the input side. The output side is smaller per turn but repeats: every proposed edit is a full response, and every failed command buys another one. A realistic day lands near 180k input tokens and 55k output tokens. Over 20 working days, 3.6M input and 1.1M output.

One day = 180k input + 55k output on this page's workload. 20 days = 3.6M input and 1.1M output. Rates checked 2026-09-26 — gateway rates move with upstream promotions, so verify the current number in your dashboard before committing to a budget.

Because the reference format is providerID/modelID, switching models is a one-token edit — same endpoint, same key, same config block. That makes the most effective lever here a per-phase split rather than a per-model one: declare a strong model and an inexpensive one under the same provider, then pick per task instead of paying the strong rate for mechanical edits.

FAQ

FAQ

Related

• Base URL not working — the doubled-path, wrong-vendor and inert-setting failures
• OpenAI-compatible error codes — what each status tells you, in the order they fire
• LiteLLM model name mapping — the same prefix problem in a different tool
• OpenAI SDK with a custom endpoint — the raw-client version of this setup
• Context length exceeded — when the real error is context, not config
• All tools with one endpoint — the same override across editors and CLIs
• Cost calculator — put your own token volumes against the rates above

Get API access

Get API access