Connect OpenCode to an OpenAI-compatible API.

OpenCode supports custom OpenAI-compatible providers. The configuration has to match the documentation generation your installed OpenCode uses: the standard docs use provider, npm and options; the versioned v2 docs use providers, package and settings. Pick one schema and keep it intact.

Choose the matching config shape

Standard OpenCode provider docs

This shape uses the OpenAI-compatible package for Chat Completions. Replace the example endpoint, environment variable and model ID with values documented by your provider.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://api.example.com/v1",
        "apiKey": "{env:MY_PROVIDER_API_KEY}"
      },
      "models": {
        "MODEL_ID_FROM_PROVIDER": {
          "name": "My model"
        }
      }
    }
  }
}

OpenCode standard provider documentation

OpenCode v2 provider docs

The v2 shape uses a package path and a separate model alias. In this example, myprovider/my-model is OpenCode’s selectable ID; MODEL_ID_FROM_PROVIDER is the upstream model ID sent with the request.

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "myprovider": {
      "name": "My Provider",
      "env": ["MY_PROVIDER_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "my-model": {
          "name": "My model",
          "modelID": "MODEL_ID_FROM_PROVIDER"
        }
      }
    }
  }
}

OpenCode v2 provider documentation

Do not combine fields from these examples. Use the documentation matching the OpenCode version you have installed; this page does not infer compatibility from a version number.

Keep the credential out of the config file

1. In the TUI, run /connect, choose Other, and enter a stable provider ID. The ID must match the key under provider or providers.
2. Use the credential flow for that provider, or configure the documented environment-variable form. Do not paste a real key into a checked-in project config or browser code.
3. When using the standard docs, opencode auth list helps confirm that the credential exists for the provider ID.

The standard docs say credentials added through /connect are stored in OpenCode’s local auth file. Treat that file as secret. If OpenCode runs as a server or service, make the environment variable available to that process, not only to a different terminal.

Match the endpoint and model identifier

• Base URL: use the API root expected by the selected provider package, commonly a URL ending in /v1. Do not append /chat/completions unless the provider’s OpenCode instructions explicitly ask for a full route.
• Request format: the standard OpenAI-compatible package targets Chat Completions. For an endpoint that implements Responses, use the Responses-compatible package documented for that same OpenCode config generation.
• Model ID: copy the exact upstream ID from the provider. In v2, the model key is OpenCode’s alias and modelID can carry the provider’s actual ID.
• Selection: run /models and select the provider/model entry. A listed model confirms that the client can select it; it does not prove that a chat request succeeds.

Resolve the common setup errors

If the endpoint returns a response but the answer is cut off or malformed, capture the original body before retrying. The incomplete JSON guide and local response checker can inspect a saved response without making another model call.

Official references

OpenCode: Providers and custom OpenAI-compatible providers
OpenCode v2: Providers, packages and model IDs
OpenCode: Configuration locations and precedence

Official documentation checked 20 October 2026. This guide contains examples only; no provider key or model request was used.

Free API access and limits

Check the site free API access and limits before trying to obtain a site key. Read the current status and request limits before using a site key. It is not a source of official provider keys.

ChinaGenAI is not affiliated with the providers named here. This release contains setup guidance and explicitly labeled fictional examples, not claimed live model benchmarks.