---
title: "OpenCode Custom Provider Setup: Add Any OpenAI-Compatible API"
description: "Add Haimaker, Ollama, OpenRouter, or any OpenAI-compatible API to OpenCode. Includes opencode auth login, opencode.json config, local model setup, and common provider errors."
date: 2026-04-12
updatedDate: 2026-06-26
location: San Francisco, CA – Apr 12th, 2026
image: /images/opencode-custom-provider-setup-hero.jpg
keywords: "opencode custom provider, opencode add provider, opencode model provider, opencode openai compatible, opencode haimaker, opencode llm provider, opencode provider setup, opencode local provider"
faq:
  - question: "How do I add a custom LLM provider to OpenCode?"
    answer: "Run 'opencode auth login' and choose Other to store the provider credential, then add a matching provider entry in opencode.json with npm set to '@ai-sdk/openai-compatible', baseURL pointing to your API, and the models you want under 'models'. Restart OpenCode and use /models to select it. For Haimaker specifically, 'npx -y @haimaker/connect --opencode' writes the credential and provider block for you."
  - question: "Why doesn't my custom provider show up in /models?"
    answer: "The usual causes are a provider ID mismatch between credentials and config, invalid JSON in opencode.json, a model ID that does not match the upstream API, or forgetting to restart OpenCode after editing provider config."
  - question: "Can I use the same OpenAI-compatible API for multiple providers in OpenCode?"
    answer: "Yes. Each entry in the 'provider' block is independent, so you can add Haimaker, Ollama, OpenRouter, LM Studio, and internal gateways as separate providers. Use unique provider IDs so /models stays readable."
---

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`.

> **Wiring up Haimaker specifically?** Skip the manual steps — run `npx -y @haimaker/connect --opencode` and the CLI writes the provider block and stores your credential automatically (add `--project` for a project-local config). The walkthrough below is the general method for *any* OpenAI-compatible provider — Ollama, LM Studio, an internal gateway, or anything not yet in the directory. See the [connect guide](/connect) for the one-command path.

## 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:

```bash
opencode auth login
```

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

```text
haimaker
ollama
mygateway
```

OpenCode stores credentials in:

```text
~/.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](https://haimaker.ai) as an example:

```jsonc
{
  "$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:

```text
/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:

```jsonc
{
  "$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`:

```jsonc
{
  "$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:

```bash
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:

```bash
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:

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

For Ollama, check local models:

```bash
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.

<a href="https://app.haimaker.ai/sign-up?utm_source=openclaw_blog&utm_medium=cta&utm_campaign=opencode_custom_provider" class="cta-button">USE HAIMAKER WITH OPENCODE</a>

---

*For local setup, see [Use Ollama with OpenCode](/blog/ollama-opencode-setup/). For broader local-model rankings, see [Best Ollama Models for Coding Agents](/blog/best-ollama-models-for-coding-agents/).*