So verwenden Sie Codex mit jedem Open-Source-Modell (OSS-Modus)

Codex wird standardmäßig mit OpenAI-Modellen ausgeliefert, bindet Sie aber nicht an diese. Die CLI verfügt über einen integrierten OSS-Modus für lokale Laufzeitumgebungen wie Ollama und LM Studio, sowie ein benutzerdefiniertes Anbietersystem, das den Agenten auf jeden kompatiblen Endpunkt verweist, den Sie in einer TOML-Datei definieren. Das bedeutet, Sie können gpt-oss auf Ihrem Laptop ausführen, Codex mit einer gehosteten DeepSeek- oder Qwen-API steuern oder projektbezogen zwischen Anbietern wechseln.

Dieser Leitfaden führt Sie durch die gesamte Einrichtung: Was der OSS-Modus leistet, die genauen Konfigurationsschlüssel, Rezepte pro Modell und die Kompromisse, die Sie eingehen, wenn Sie die OpenAI-Modelle austauschen. Alles hier stammt aus den offiziellen erweiterten Konfigurationsdokumenten von Codex. Wo die Dokumentation unklar ist, weise ich darauf hin, anstatt zu spekulieren.

Eine Anmerkung, bevor wir beginnen. Sobald Ihr Modell in Codex läuft, ist das Modell nur die Hälfte des Workflows. Die andere Hälfte ist die Überprüfung der APIs, die Ihr Agent erstellt und aufruft. Hier kommt Apidog ins Spiel, und wir werden die Kopplung gegen Ende behandeln.

TL;DR

Der Codex OSS-Modus ist eine CLI-Funktion. Führen Sie codex --oss aus, und Codex kommuniziert mit einem lokalen Ollama- oder LM Studio-Server anstelle von OpenAI. Setzen Sie oss_provider = "ollama" in ~/.codex/config.toml, um dies als Standard festzulegen, und übergeben Sie -m <model>, um auszuwählen, welches lokale Modell ausgeführt werden soll. Für gehostete Open-Source-Modelle (DeepSeek, Qwen, GLM über deren APIs) definieren Sie einen [model_providers.<id>]-Block mit einer base_url und einem env_key und wählen diesen dann mit model_provider aus. Der Haken: Die aktuelle Konfigurationsreferenz listet responses als den einzigen unterstützten wire_api-Wert auf, daher muss Ihr Endpunkt das Responses API-Protokoll sprechen.

Was der OSS-Modus ist

Der OSS-Modus ist die Abkürzung von Codex, um lokale Open-Source-Modellserver zu nutzen. Die Dokumentation beschreibt zwei unterstützte lokale Anbieter:

• Ollama, die beliebte lokale Modell-Laufzeitumgebung
• LM Studio, die Desktop-Anwendung mit einem integrierten lokalen Server

Sie aktivieren ihn mit dem Flag --oss. Aus der Codex-Entwicklerbefehlsreferenz:

--oss: Verwendet einen lokalen Open-Source-Modell-Anbieter. Codex verwendet --local-provider, Ihren konfigurierten oss_provider, oder fordert Sie auf, zwischen LM Studio und Ollama zu wählen.

Es gibt ein Begleit-Flag, --local-provider, das lmstudio oder ollama akzeptiert und Ihre Standardeinstellung für einen einzelnen Lauf überschreibt. Wenn Sie weder ein Flag noch eine Konfigurationsstandardeinstellung festlegen, fordert die interaktive CLI Sie zur Auswahl auf. Das nicht-interaktive codex exec fordert nicht auf; es beendet sich mit einem Fehler. Für Skripte und CI sollten Sie den Anbieter daher immer explizit festlegen.

Ein ehrlicher Hinweis zu Oberflächen: Die Dokumentation behandelt den OSS-Modus und benutzerdefinierte Anbieter im Rahmen des config.toml-Systems der CLI. Die IDE-Erweiterung und die Codex-Cloud werden in den Konfigurationsdokumenten nirgends als Unterstützung für lokale Anbieter erwähnt. [ÜBERPRÜFEN: ob die Codex IDE-Erweiterung model_providers aus config.toml auf dieselbe Weise liest wie die CLI; die Dokumentation macht dazu keine Angaben.] Betrachten Sie dies als einen CLI-Workflow, bis OpenAI etwas anderes dokumentiert.

Warum ein Open-Source-Modell in Codex ausführen

Berechtigte Frage, da Codex OpenAIs eigener Agent ist. Einige echte Gründe:

• Kostenkontrolle. Lokale Inferenz über Ollama kostet nichts pro Token. Wenn Sie bei langen Agenten-Sitzungen Ihre Nutzungslimits ausschöpfen, erledigt ein lokales Modell die mühsame Arbeit, während Sie die gehosteten Aufrufe für schwierige Probleme aufsparen.
• Datenschutz und Air-Gapped-Arbeit. Manche Codebasen dürfen die Maschine nicht verlassen. Ein lokales Kimi-, GLM- oder gpt-oss-Modell behält jedes Token auf Ihrer Hardware. Unser Leitfaden zum lokalen Ausführen von Kimi K3 behandelt, was das in der Praxis bedeutet.
• Modellpräferenz. Open-Weight-Modelle haben die meisten Lücken beim Codieren geschlossen. Die gehosteten APIs von DeepSeek und Qwen unterbieten die OpenAI-Preise, während sie bei Coding-Benchmarks im Bereich liegen, und es kann sein, dass Ihnen einfach gefällt, wie ein bestimmtes Modell Code schreibt.
• Ein Agenten-Gerüst, viele Modelle. Die Terminal-UX, Sandboxing und der Genehmigungsablauf von Codex sind gut. Die Anbieterkonfiguration ermöglicht es Ihnen, dieses Gerüst beizubehalten und das "Gehirn" auszutauschen.

Wo die Konfiguration liegt

Codex speichert den Zustand unter CODEX_HOME, was standardmäßig ~/.codex ist. Ihre benutzerbezogene Konfiguration ist ~/.codex/config.toml, und ein Repository kann projektbezogene Überschreibungen in .codex/config.toml enthalten. Alles Folgende gehört in eine dieser beiden Dateien.

Schnellstart: Codex mit Ollama

Der schnellste Weg zu einem Open-Source-Modell in Codex ist Ollama.

1. Installieren Sie Ollama von ollama.com und starten Sie es. Es stellt eine OpenAI-kompatible API auf Port 11434 bereit.
2. Ziehen Sie ein Modell. OpenAIs eigene Open-Weight-Veröffentlichung ist eine naheliegende erste Wahl; die gpt-oss-Bibliotheksseite enthält die 20b- und 120b-Varianten. Wir haben die eigenständige Einrichtung in wie man gpt-oss mit Ollama ausführt behandelt.

ollama pull gpt-oss:20b

3. Führen Sie Codex im OSS-Modus aus und benennen Sie das Modell:

codex --oss -m gpt-oss:20b

Das Flag -m/--model überschreibt das konfigurierte Modell, und in Kombination mit --oss wählt es aus, welches lokale Modell ausgeführt wird. Für die nicht-interaktive Nutzung:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

4. Machen Sie es zur Standardeinstellung, damit Sie die Flags weglassen können. In ~/.codex/config.toml:

# Standard-lokaler Anbieter, der mit `--oss` verwendet wird
oss_provider = "ollama" # oder "lmstudio"

Das ist die gesamte Funktion für lokale Modelle. Kein API-Schlüssel, kein benutzerdefinierter Anbieterblock. LM Studio funktioniert auf die gleiche Weise: Laden Sie ein Modell in der App, starten Sie seinen lokalen Server und führen Sie codex --oss --local-provider lmstudio aus. Weitere Informationen zur Servereinrichtung finden Sie unter lmstudio.ai.

Benutzerdefinierte Anbieter: Codex auf jeden kompatiblen Endpunkt verweisen

Der OSS-Modus deckt Ollama und LM Studio ab. Für alles andere – gehostete DeepSeek- oder Qwen-APIs, einen Proxy, einen vLLM-Server in Ihrem LAN – bietet Codex benutzerdefinierte Modell-Anbieter. Die Dokumentation definiert einen Anbieter als „wie Codex sich mit einem Modell verbindet (Basis-URL, Wire-API, Authentifizierung und optionale HTTP-Header).“

Das Muster aus der offiziellen Dokumentation:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Die wichtigen Schlüssel:

Auch eine netzwerkweite Feinabstimmung pro Anbieter ist verfügbar: request_max_retries (Standard 4), stream_max_retries (Standard 5) und stream_idle_timeout_ms (Standard 300000). Langsame lokale Hardware profitiert von einem längeren Idle-Timeout, da ein 120b-Modell auf einem Laptop zwischen den Tokens eine Weile still sein kann.

Zwei Regeln, die die Dokumentation direkt hervorhebt. Erstens sind die IDs openai, ollama und lmstudio reserviert; Sie können eingebaute Anbieter nicht überschreiben. Um die Basis-URL des integrierten OpenAI-Anbieters zu ändern, setzen Sie openai_base_url anstatt [model_providers.openai] zu erstellen. Zweitens, und dies prägt alles: Die Konfigurationsreferenz besagt, dass für wire_api „responses der einzige unterstützte Wert ist und der Standardwert, wenn er weggelassen wird.“

Das ist eine echte Einschränkung. Frühere Codex-Versionen akzeptierten wire_api = "chat" für Chat Completions-Endpunkte, und die Modellübersichtsseite besagt immer noch, dass Sie Codex auf Anbieter verweisen können, die „entweder die Chat Completions- oder Responses-APIs“ unterstützen. Die Referenz und die Übersicht stimmen nicht überein. [ÜBERPRÜFEN: ob wire_api = "chat" in der aktuellen CLI-Version noch funktioniert; die Konfigurationsreferenz sagt nur Responses, die Modelle-Seite impliziert, dass Chat noch funktioniert. Vor der Veröffentlichung gegen einen reinen Chat-Endpunkt testen.] Wenn nur Responses gilt, benötigt Ihr Anbieter einen Responses API-Endpunkt, den die meisten OpenAI-kompatiblen Server jetzt bereitstellen, einige gehostete APIs jedoch noch nicht.

Modell-für-Modell-Rezepte

Jedes der folgenden Rezepte besteht aus einem Konfigurationsblock und dem auszuführenden Befehl. Legen Sie die Umgebungsvariable für den API-Schlüssel vor dem Start fest.

DeepSeek (gehostete API)

DeepSeek hat die Responses API-Unterstützung zusammen mit seiner V4 Flash Beta hinzugefügt, was genau dem Wire-Protokoll von Codex entspricht. Wir haben diese Einführung in DeepSeek V4 Flash, die Responses API und Codex behandelt.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

Überprüfen Sie die DeepSeek API-Dokumentation für die aktuellen Modell-IDs. [ÜBERPRÜFEN: genauen base_url-Pfad, den DeepSeek für den Responses-Protokollzugriff dokumentiert; der /v1 Chat-Pfad kann vom Responses-Pfad abweichen.]

Qwen (gehostet über Model Studio)

Alibabas Model Studio (DashScope) stellt einen OpenAI-kompatiblen Modus für die Qwen 3.8-Familie bereit. Der Compatible-Mode-Endpunkt war historisch gesehen auf Chat Completions zugeschnitten. [ÜBERPRÜFEN: ob der Compatible-Modus von DashScope jetzt das Responses-Protokoll bedient; falls nicht, hängt dieses Rezept von der obigen Frage zu wire_api = "chat" ab.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Unser Qwen 3.8 API-Leitfaden behandelt Schlüssel, Modell-IDs und Preise für den gehosteten Weg.

Kimi, GLM und andere Open-Weight-Modelle (lokal über Ollama)

Alles, was Sie in Ollama ziehen können, funktioniert über den einfachen OSS-Modus, kein Anbieterblock erforderlich:

ollama pull <model>
codex --oss -m <model>

Das deckt GLM- und Qwen-Open-Weights ab, plus Kimi K3, wenn Ihre Hardware es übersteht (die K3-Gewichte betragen 594 GB bei MXFP4, daher sollten die meisten Leute Kimi K3 lokal ausführen lesen, bevor sie es versuchen). Für mittelgroße Maschinen ist gpt-oss:20b oder ein quantisiertes Qwen-Coder-Build die praktische Wahl.

Selbstgehostetes vLLM oder ein LAN-Server

Ein vLLM oder ähnlicher OpenAI-kompatibler Server auf einer anderen Maschine ist ein benutzerdefinierter Anbieter, kein OSS-Modus:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM on the workstation"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

Profile: Gehirne pro Aufgabe wechseln

Sie müssen sich nicht für eine Einrichtung entscheiden. Codex-Profile sind separate TOML-Dateien unter ~/.codex/<profile-name>.config.toml, die über Ihre Basiskonfiguration gelegt werden, wenn Sie --profile übergeben. Ein lokales Modellprofil sieht so aus:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

Behalten Sie Ihre Standardkonfiguration für OpenAI-Modelle für schwierige Refactorings bei und starten Sie --profile oss-local für Lint-Korrekturen, Test-Scaffolding und Dokumentationsdurchläufe. Einmalige Überschreibungen funktionieren auch ohne Profil: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

Kompromisse im Vergleich zu OpenAI-Modellen

Seien Sie ehrlich zu sich selbst, was Sie eintauschen:

• Leistungsfähigkeit. gpt-oss:20b ist nicht gpt-5.6-terra. Lokale Modelle scheitern häufiger bei langen Multi-Datei-Bearbeitungen, und Agenten-Schleifen verstärken die Modellschwäche, da jeder Schritt auf dem vorherigen aufbaut.
• Geschwindigkeit. Gehostete APIs streamen schnell. Ein großes lokales Modell auf Consumer-Hardware kann so langsam sein, dass es Ihre Arbeitsweise verändert.
• Tooling-Genauigkeit. Die Prompts und Tool-Aufrufe von Codex sind auf OpenAI-Modelle abgestimmt. Open-Source-Modelle variieren in der Zuverlässigkeit, mit der sie Tool-Aufrufe ausgeben, und das reine Responses-Wire-Protokoll schränkt ein, welche Endpunkte überhaupt in Frage kommen.
• Support-Umfang. Der OSS-Modus ist ein dokumentierter CLI-Pfad, aber Drittanbieter liegen in Ihrer Verantwortung: Modell-IDs, Ratenbegrenzungen und Protokoll-Eigenheiten sind Sache zwischen Ihnen und dem Anbieter.

Die pragmatische Aufteilung: lokale oder günstige gehostete Modelle für hochvolumige Aufgaben mit geringem Risiko, Frontier-Modelle für Aufgaben, bei denen ein fehlgeschlagener Lauf Sie einen Nachmittag kostet.

Überprüfen Sie die APIs, die Ihr Agent berührt

Welches Modell auch immer in Codex läuft, die Ausgabe ist normalerweise Code, der APIs aufruft oder definiert, und Open-Source-Modelle halluzinieren Endpunkte und Schemas häufiger als Frontier-Modelle. Fangen Sie das auf der API-Ebene ab, anstatt in der Produktion.

Apidog deckt diese Seite des Workflows ab. Richten Sie den Apidog MCP-Server auf Ihr Projekt und Ihr Codex-Agent kann die echte API-Spezifikation lesen, während er Code schreibt, anstatt Feldnamen zu erfinden. Verwenden Sie dann die Apidog CLI in Codex, damit der Agent Ihre Testszenarien nach jeder Änderung vom Terminal aus ausführt: Er bearbeitet, er testet, Sie überprüfen einen erfolgreichen Diff. Diese Schleife ist wichtiger, nicht weniger wichtig, wenn ein kleineres Modell den Code schreibt. Laden Sie Apidog herunter, um es einzurichten; die CLI und der MCP-Server funktionieren mit jedem von Ihnen konfigurierten Modell.

Fehlerbehebung

• codex exec meldet im OSS-Modus sofort Fehler. Sie haben keinen Anbieter festgelegt. Nicht-interaktive Läufe fragen nie nach, übergeben Sie also --local-provider ollama oder setzen Sie oss_provider in der Konfiguration.
• Verbindung auf Port 11434 verweigert. Ollama läuft nicht, oder es ist an eine andere Adresse gebunden. Starten Sie die Anwendung oder ollama serve und bestätigen Sie dies mit curl http://localhost:11434/v1/models.
• 404- oder Protokollfehler von einem gehosteten Anbieter. Falsches base_url-Format, oder der Endpunkt spricht nicht das Responses-Protokoll. Überprüfen Sie, ob der Anbieter einen Responses-kompatiblen Pfad dokumentiert.
• Authentifizierungsfehler. env_key benennt eine Umgebungsvariable; Codex liest den Schlüssel beim Start aus Ihrer Shell-Umgebung. Exportieren Sie ihn in derselben Shell, und denken Sie daran, dass launchd- oder CI-Shells Ihre Dotfiles möglicherweise nicht laden.
• Streams sterben mitten in der Generierung bei einem langsamen lokalen Modell. Erhöhen Sie stream_idle_timeout_ms und stream_max_retries im Anbieterblock.
• Konfigurationsänderungen ignoriert. Überprüfen Sie, ob eine projektbezogene .codex/config.toml Ihre Benutzerkonfiguration überschreibt, und denken Sie daran, dass Profile über beidem liegen.

FAQ

Funktioniert der Codex OSS-Modus in der IDE-Erweiterung oder der Codex-Cloud?

Die Dokumentation beschreibt den OSS-Modus und benutzerdefinierte Anbieter als Teil des Konfigurationssystems der CLI. IDE- oder Cloud-Unterstützung für lokale Anbieter ist nicht dokumentiert, behandeln Sie dies also als CLI-Funktion. [ÜBERPRÜFEN Sie dies, bevor Sie sich auf IDE-Unterstützung verlassen.]

Welche Modelle funktionieren am besten mit Codex im OSS-Modus?

Was immer Ollama oder LM Studio auf Ihrer Hardware bereitstellen kann. gpt-oss:20b ist die standardmäßige reibungsarme Option. Starke Open-Weight-Coding-Optionen umfassen die Qwen 3.8-Familie und GLM; für die riesigen Modelle wie Kimi K3, überprüfen Sie zuerst die Hardware-Berechnungen in unserem Leitfaden für lokales Kimi K3.

Kann ich OpenRouter oder einen anderen Aggregator mit Codex verwenden?

Jeder Aggregator, der einen kompatiblen Endpunkt bereitstellt, passt zum Muster [model_providers.<id>]: Setzen Sie base_url und env_key und wählen Sie ihn dann mit model_provider aus. Die offene Frage ist das Protokoll: Die Konfigurationsreferenz listet responses als den einzigen unterstützten wire_api auf, bestätigen Sie also, dass Ihr Aggregator die Responses API bedient.

Benötige ich einen OpenAI API-Schlüssel, um Codex mit einem Open-Source-Modell auszuführen?

Für den OSS-Modus mit einem lokalen Ollama- oder LM Studio-Server wird kein Schlüssel benötigt. Benutzerdefinierte gehostete Anbieter verwenden ihren eigenen Schlüssel über env_key. Sie melden sich weiterhin wie gewohnt bei Codex selbst an für alles, was die Dienste von OpenAI betrifft.

Verwenden Sie die Einrichtung, die zur Aufgabe passt. Ein lokales gpt-oss für die günstigen Schleifen, DeepSeek oder Qwen, wenn Sie gehostete Geschwindigkeit zu geringeren Kosten wünschen, und OpenAIs Frontier-Modelle, wenn das Problem schwierig ist. Die Codex-Konfiguration macht alle drei mit einem Flag unterscheidbar, und da Apidog die Überprüfung auf der API-Seite übernimmt, wird das Modell zu einem austauschbaren Teil statt einer festen Verpflichtung.