Add a Custom Provider to OpenCode

OpenCode includes built-in connections for many providers. Check /connect before writing configuration. A custom provider is useful for an unlisted service, a local server, or an organization gateway.

Store the credential#

Inside OpenCode, run /connect, choose Other, and enter a provider ID. Use a short stable value such as mygateway, then enter the API key. The ID must match the configuration block.

Add the provider configuration#

For a Chat Completions-compatible endpoint, the current OpenCode schema uses this pattern:

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

Replace the provider ID, URL, and model ID. Do not use the example values in a live configuration.

Select and test the model#

Restart OpenCode if the new provider does not appear, then run:

/models

Select the custom model and send a read-only request. Check the provider logs before approving file changes.

Common problems#

• Provider not found: the ID from /connect does not match the configuration key.
• Model not found: the models map contains a display name instead of the API model ID.
• Authentication failure: reconnect the provider and confirm the key belongs to the configured endpoint.
• Format error: the endpoint and selected AI SDK package use different protocols.
• Built-in provider duplicated: remove the custom block and use the standard /connect entry.