OpenCode unterstützt über sein integriertes Provider-Verzeichnis mehr als 75 LLM-Provider, aber eigene Provider sind weiterhin wichtig. Mit ihnen bindest du ein Gateway, eine lokale Laufzeitumgebung, einen internen Inferenz-Endpunkt oder ein Modell ein, das noch nicht im Verzeichnis enthalten ist.
Das Vorgehen ist einfach: Zugangsdaten speichern, Provider-Block hinzufügen, OpenCode neu starten und dann das Modell über /models auswählen.
Du willst gezielt Haimaker anbinden? Überspringe die manuellen Schritte — führe
npx -y @haimaker/connect --opencodeaus. Die CLI schreibt den Provider-Block und speichert deine Zugangsdaten automatisch (füge--projectfür eine projektspezifische Konfiguration hinzu). Die folgende Anleitung beschreibt die allgemeine Methode für jeden OpenAI-kompatiblen Provider — Ollama, LM Studio, ein internes Gateway oder alles, was noch nicht im Verzeichnis ist. Siehe den Connect-Leitfaden für die Einrichtung mit einem einzigen Befehl.
Wann ein eigener Provider sinnvoll ist
Verwende einen eigenen Provider, wenn das Modell oder der Endpunkt noch nicht in der integrierten OpenCode-Providerliste verfügbar ist.
Typische Anwendungsfälle:
- Haimaker – ein API-Schlüssel für mehrere Modellfamilien über ein OpenAI-kompatibles Gateway.
- Ollama – lokale Modelle unter
http://localhost:11434/v1. - LM Studio – lokale Modelle unter
http://127.0.0.1:1234/v1. - Interne Gateways – im Unternehmen gehostete OpenAI-kompatible Endpunkte.
- Neue Provider – alles, was die OpenAI-kompatible Chat-API unterstützt, bevor das OpenCode-Verzeichnis nachzieht.
Wenn der Provider in OpenCode bereits vorhanden ist, greife bevorzugt auf den integrierten Weg zurück. Eine eigene Konfiguration ist vor allem dann sinnvoll, wenn du eine eigene Base-URL, ein Gateway oder ein Modell benötigst, das in der Standardliste fehlt.
Schritt 1: Zugangsdaten hinzufügen
Die aktuelle OpenCode-Dokumentation verweist Nutzer für Provider-Zugangsdaten auf opencode auth login. Für einen eigenen OpenAI-kompatiblen Provider wähle Other, gib eine Provider-ID ein und füge dann den API-Schlüssel ein:
opencode auth login
Wähle eine kurze Provider-ID, die du auch in der Konfiguration verwendest. Zum Beispiel:
haimaker
ollama
mygateway
OpenCode speichert Zugangsdaten in:
~/.local/share/opencode/auth.json
Du kannst diese Datei bei Bedarf manuell bearbeiten, aber mit opencode auth login vermeidest du Fehler durch ungültige Schlüsselformate.
Schritt 2: Provider konfigurieren
Öffne oder erstelle deine OpenCode-Konfiguration. Je nach Setup ist das opencode.json im Projekt oder eine globale Datei unter ~/.config/opencode/.
Füge einen provider-Block mit derselben Provider-ID hinzu, die du bei der Authentifizierung verwendet hast. So sieht die Konfiguration aus, am Beispiel von haimaker.ai:
{
"$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"
}
}
}
}
}
Was die einzelnen Felder bewirken:
npm: der SDK-Adapter. Verwende für jede OpenAI-kompatible API@ai-sdk/openai-compatible. OpenCode lädt den Adapter bei Bedarf.name: der Anzeigename, der in OpenCode erscheint.options.baseURL: die Basis-URL für die API des Providers. Sie sollte auf/v1oder das jeweilige Versionspräfix des Providers enden.models: die Modelle, die du in OpenCode verfügbar haben möchtest. Die Schlüssel müssen exakt dem entsprechen, was die API des Providers immodel-Feld einer Completion-Anfrage akzeptiert.
Du kannst beliebig viele eigene Provider hinzufügen, jeweils als separater Eintrag unter provider.
Schritt 3: Neustart und Überprüfung
OpenCode übernimmt Änderungen an Providern möglicherweise erst nach einem Neustart. Beende OpenCode vollständig, starte es erneut und führe dann aus:
/models
Du solltest den Anzeigenamen des Providers und die konfigurierten Modelle sehen. Wähle ein Modell aus und sende einen kurzen Prompt, bevor du es an echtem Code verwendest.
Vollständiges Beispiel: Haimaker-Gateway
Verwende dieses Setup, wenn du einen einzigen OpenAI-kompatiblen Endpunkt für mehrere Modellfamilien möchtest:
{
"$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"
}
}
}
}
}
Warum dieses Setup gut funktioniert: OpenCode sieht nur einen Provider, während Haimaker den Zugriff auf mehrere Upstream-Modellfamilien verwaltet. Das hält deine OpenCode-Konfiguration schlank und macht den Modellwechsel weniger umständlich.
Vollständiges Beispiel: Ollama als lokaler Provider
Ollama stellt unter http://localhost:11434/v1 einen OpenAI-kompatiblen lokalen Endpunkt bereit:
{
"$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"
}
}
}
}
}
Lade die Modelle herunter, bevor du OpenCode startest:
ollama pull qwen3-coder:30b
ollama pull gemma4:e4b
Falls OpenCode für den lokalen Provider eine Authentifizierung verlangt, führe opencode auth login aus, wähle Other, verwende ollama als Provider-ID und gib einen beliebigen nicht leeren Schlüssel wie ollama ein. Ollama validiert lokale API-Schlüssel nicht.
Häufige Fehler und Lösungen
Provider erscheint nicht in /models
Prüfe vier Dinge:
- Die Provider-ID aus
opencode auth loginstimmt mit dem Provider-Eintrag in der Konfiguration überein. - Die Konfigurationsdatei ist gültiges JSON oder JSONC.
- Du hast OpenCode nach dem Bearbeiten der Provider-Konfiguration neu gestartet.
- Das Modell ist im
models-Objekt des Providers aufgeführt.
Authentifizierung schlägt bei der ersten Anfrage fehl
Die Zugangsdaten fehlen oder sind der falschen Provider-ID zugeordnet. Führe aus:
opencode auth list
Prüfe anschließend, dass die Provider-ID exakt mit deiner Konfiguration übereinstimmt. Gib im Schlüsselfeld kein Bearer ein.
Modell wird angezeigt, aber Anfragen schlagen fehl
Die Modell-ID stimmt wahrscheinlich nicht mit dem überein, was die Upstream-API erwartet. Eigene Provider geben Modell-IDs unverändert weiter. Wenn in deiner Konfiguration qwen/qwen3-coder steht, muss die API exakt qwen/qwen3-coder akzeptieren.
Für Haimaker teste den Schlüssel und den Endpunkt:
curl https://api.haimaker.ai/v1/models \
-H "Authorization: Bearer your-haimaker-api-key"
Für Ollama prüfe die lokalen Modelle:
ollama list
Verwende den exakten Modellnamen aus dieser Ausgabe.
Tool-Aufrufe schlagen bei lokalen Modellen fehl
Lokale Modelle sind empfindlicher gegenüber Kontextlimits und der Formatierung von Tool-Aufrufen. Beginne mit einem Modell, das sich für agentisches Coding eignet, etwa Qwen3 Coder, und halte den Kontext überschaubar. Die OpenCode-Dokumentation empfiehlt außerdem, Ollama num_ctx zu erhöhen, wenn Tool-Aufrufe nicht funktionieren.
Integrierte Provider funktionieren nicht mehr
Du hast wahrscheinlich mehr Konfiguration ersetzt als beabsichtigt. Behalte eigene Provider im provider-Objekt und vermeide es, bestehende Provider-Einträge zu löschen. Nimm im Zweifel die kleinstmögliche Änderung vor: Füge eine Provider-ID und ein Modell hinzu, starte neu, teste und füge danach weitere hinzu.
Das praxistaugliche Setup
Für die meisten OpenCode-Nutzer ist dieses Setup die sauberste Lösung:
- Haimaker für Cloud-Modelle und das Routing über einen Schlüssel.
- Ollama für lokale, private Arbeit.
- Ein Premium-Fallback für schwieriges Debugging und Refactorings über mehrere Dateien.
So erhältst du lokale Privatsphäre, wenn es darauf ankommt, kostengünstige Cloud-Modelle für Routineaufgaben und ein stärkeres Modell, wenn die Coding-Aufgabe besonders anspruchsvoll ist.
Zur lokalen Einrichtung siehe Ollama mit OpenCode verwenden. Für einen breiteren Vergleich lokaler Modelle siehe Beste Ollama-Modelle für Coding-Agenten.