OpenCode supports 75+ LLM providers through its provider directory, but custom providers still matter. They are how you add a gateway, a local runtime, an internal inference endpoint, or a model that has not landed in the directory yet.

The pattern is straightforward: store a credential, add a provider block, restart OpenCode, then pick the model from /models.

When to use a custom provider

Use a custom provider when the model or endpoint is not already available through OpenCode’s built-in provider list.

Good examples:

  • Haimaker - one API key for multiple model families through an OpenAI-compatible gateway.
  • Ollama - local models at http://localhost:11434/v1.
  • LM Studio - local models at http://127.0.0.1:1234/v1.
  • Internal gateways - company-hosted OpenAI-compatible endpoints.
  • New providers - anything that speaks the OpenAI-compatible chat API before OpenCode’s directory catches up.

If the provider already exists in OpenCode, prefer the built-in path first. Custom config is most useful when you need a custom base URL, a gateway, or a model that is missing from the default list.

Step 1: Add the credential

The current OpenCode docs point users to opencode auth login for provider credentials. For a custom OpenAI-compatible provider, choose Other, enter a provider ID, then paste the API key:

opencode auth login

Pick a short provider ID you will also use in config. For example:

haimaker
ollama
mygateway

OpenCode stores credentials in:

~/.local/share/opencode/auth.json

You can edit that file manually when needed, but using opencode auth login avoids key-shape mistakes.

Step 2: Configure the provider

Open or create your OpenCode config. Depending on your setup, this may be opencode.json in the project or a global file under ~/.config/opencode/.

Add a provider block with the same provider ID you used during auth. Here’s the pattern using haimaker.ai as an example:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

What each field does:

  • npm: the SDK adapter. For any OpenAI-compatible API, use @ai-sdk/openai-compatible. OpenCode loads the adapter on demand.
  • name: the display name shown in OpenCode.
  • options.baseURL: the base URL for the provider’s API. Should end at /v1 or whatever version prefix the provider uses.
  • models: the models you want available in OpenCode. The keys must match exactly what the provider’s API accepts in the model field of a completion request.

You can add as many custom providers as you want, each as a separate entry under provider.

Step 3: Restart and verify

OpenCode may not pick up provider changes until it restarts. Quit it completely, start it again, then run:

/models

You should see the provider display name and the configured models. Select one and send a small prompt before using it on real code.

Full example: Haimaker gateway

Use this when you want one OpenAI-compatible endpoint for multiple model families:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Why this setup works well: OpenCode sees one provider, while Haimaker handles access to multiple upstream model families. That keeps your OpenCode config smaller and makes model switching less annoying.

Full example: Ollama local provider

Ollama exposes an OpenAI-compatible local endpoint at http://localhost:11434/v1:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

Pull the models before starting OpenCode:

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

If OpenCode requires auth for the local provider, run opencode auth login, choose Other, use ollama as the provider ID, and enter any non-empty key such as ollama. Ollama does not validate local API keys.

Common errors and fixes

Provider does not appear in /models

Check four things:

  1. The provider ID from opencode auth login matches the provider key in config.
  2. The config file is valid JSON or JSONC.
  3. You restarted OpenCode after editing provider config.
  4. The model is listed under the provider’s models object.

Authentication fails on the first request

The credential is missing or attached to the wrong provider ID. Run:

opencode auth list

Then confirm the provider ID matches your config exactly. Do not include Bearer in the key field.

Model shows up but requests fail

The model ID probably does not match what the upstream API expects. Custom providers pass model IDs through unchanged. If your config says qwen/qwen3-coder, the API must accept exactly qwen/qwen3-coder.

For Haimaker, test the key and endpoint:

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

For Ollama, check local models:

ollama list

Use the exact model name from that output.

Tool calls fail with local models

Local models are more sensitive to context limits and tool-call formatting. Start with a model known to handle agentic coding well, such as Qwen3 Coder, and keep context modest. The OpenCode docs also recommend increasing Ollama num_ctx when tool calls are not working.

Built-in providers stopped working

You probably replaced more config than intended. Keep custom providers under the provider object and avoid deleting existing provider entries. When in doubt, make the smallest possible config change: add one provider ID and one model, restart, test, then add more.

The practical setup

For most OpenCode users, the clean setup is:

  1. Haimaker for cloud models and one-key routing.
  2. Ollama for local private work.
  3. One premium fallback for hard debugging and multi-file refactors.

That gives you local privacy when it matters, low-cost cloud models for routine work, and a stronger model when the coding task is expensive in attention.

USE HAIMAKER WITH OPENCODE

For local setup, see Use Ollama with OpenCode. For broader local-model rankings, see Best Ollama Models for Coding Agents.