Externe Modelle mit Codex verbinden

Dieser Leitfaden behandelt zwei Integrationswege für gehostete Drittanbietermodelle:

Zunächst müssen Sie eine wichtige Einschränkung kennen:

Dieser Leitfaden gilt für lokal ausgeführte Codex-Clients, einschließlich Codex CLI, der Codex IDE-Erweiterung und Desktop-Clients, die dieselbe config.toml lesen. In Codex-Cloud-Chats kann derzeit über diese Konfiguration nicht zu einem benutzerdefinierten Modell gewechselt werden.

Vorbereitungen

Codex CLI installieren oder aktualisieren

npm install -g @openai/codex@latest
codex --version

Führen Sie Codex nach der Erstinstallation mindestens einmal aus:

codex

Dadurch wird das Benutzerkonfigurationsverzeichnis initialisiert.

Speicherorte der Codex-Konfigurationsdatei

macOS und Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Sichern Sie die Datei, bevor Sie Änderungen vornehmen.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Anbieter, MCP und Modell-Gateways sind nicht dasselbe

Diese Konzepte lösen unterschiedliche Probleme:

• model_provider bestimmt, wohin Codex Modellanfragen sendet;
• MCP fügt Werkzeuge und Kontext wie GitHub, Browser oder Datenbanken hinzu;
• ein Modell-Gateway übernimmt zwischen Codex und einem Upstream-Modell die Protokollkonvertierung, Authentifizierung, Weiterleitung, Protokollierung oder Ratenbegrenzung.

Konfigurieren Sie zum Wechseln des zugrunde liegenden Modells einen Anbieter und nicht MCP.

API keys schützen

Übertragen Sie keine echten API keys in ein Git-Repository und legen Sie vollständige Schlüssel nicht in Screenshots, Protokollen oder Support-Tickets offen.

Bevorzugen Sie bei manuell konfigurierten Anbietern Umgebungsvariablen:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch speichert die Anbieterkonfiguration lokal und ändert beim Anbieterwechsel die lokale Codex-Konfiguration. Es handelt sich um ein Open-Source-Werkzeug eines Drittanbieters und nicht um ein OpenAI-Produkt. Installieren Sie es ausschließlich über die offizielle CC Switch-Website oder das GitHub-Repository und schützen Sie seine lokale Datenbank, Konfiguration und Sicherungen.

1. Drittanbietermodelle mit CC Switch verbinden

CC Switch ist für die meisten Drittanbietermodelle die einfachere Option. Es verwaltet Anbieter, API keys, Modelllisten und lokales Routing und kann inkompatible Upstream-Protokolle übersetzen.

1.1 Welche Probleme CC Switch löst

Moderne Codex-Clients senden Anfragen der Responses API, während viele Drittanbieterdienste eine der folgenden Schnittstellen bereitstellen:

• OpenAI Chat Completions;
• Anthropic Messages;
• Modell-IDs, die Codex standardmäßig nicht aufführt;
• anbieterspezifische Reasoning-Parameter oder Formate für Streaming-Ereignisse.

CC Switch kann den Anfragepfad wie folgt übersetzen:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Ein Anbieter mit nativer Responses-Unterstützung benötigt keine Chat-Protokollkonvertierung. Ein Anbieter für Chat Completions oder Anthropic Messages erfordert lokales Routing.

1.2 CC Switch installieren

Verwenden Sie ausschließlich die offiziellen Vertriebskanäle:

• Offizielle CC Switch-Website
• CC Switch-GitHub-Repository
• CC Switch-Releases

Unter macOS wird Homebrew empfohlen:

brew install --cask cc-switch

So führen Sie ein Update durch:

brew upgrade --cask cc-switch

Laden Sie unter Windows das .msi-Installationsprogramm oder das portable Archiv aus den Releases herunter.

Laden Sie unter Linux das .deb-, .rpm- oder AppImage-Paket aus den Releases herunter. Bezeichnungen können sich zwischen Versionen geringfügig ändern. Verwenden Sie daher das neueste stabile Release und betrachten Sie die in der Anwendung angezeigten Optionen als maßgeblich.

1.3 Voraussetzungen

Bereiten Sie Folgendes vor:

1. Codex ist installiert und wurde mindestens einmal gestartet;
2. CC Switch ist installiert und startet ordnungsgemäß;
3. Sie besitzen einen API key für den gewünschten Modelldienst;
4. Sie haben Base URL, Modell-ID und Upstream-Protokoll in der Anbieterdokumentation überprüft;
5. wenn Sie offizielle Codex-Kontofunktionen benötigen, führen Sie zunächst eine offizielle Anmeldung durch.

Prüfen Sie den aktuellen Codex-Anmeldestatus:

codex login status

Melden Sie sich bei Bedarf an:

codex login

Die Anmeldung per Gerätecode ist ebenfalls verfügbar:

codex login --device-auth

1.4 Optional: Offizielle Anmeldung bei Verwendung eines Drittanbieters beibehalten

Dies ist vor allem nützlich, wenn Sie Desktop-Funktionen, offizielle Plugins oder Fernsteuerungsfunktionen beibehalten möchten, während Modellanfragen an einen Drittanbieter gesendet werden. Benutzer, die ausschließlich die CLI verwenden und nicht auf offizielle Kontofunktionen angewiesen sind, können diesen Schritt überspringen.

Empfohlene Reihenfolge:

1. wählen Sie im Codex-Bereich von CC Switch OpenAI Official aus;
2. starten Sie Codex und melden Sie sich mit einem offiziellen Konto an;
3. öffnen Sie in CC Switch Settings → General → Codex App Enhancements;
4. aktivieren Sie Keep official login when switching third-party providers;
5. fügen Sie den Drittanbieter hinzu oder wechseln Sie zu ihm.

Wenn diese Option aktiviert ist, versucht CC Switch, Folgendes beizubehalten:

• ~/.codex/auth.json für den offiziellen Anmeldestatus;
• ~/.codex/config.toml für den aktiven Drittanbieter sowie dessen Modell-, Endpunkt- und Authentifizierungskonfiguration.

auth.json enthält vertrauliche Anmeldedaten. Geben Sie die Datei nicht weiter und übertragen Sie sie nicht in die Versionsverwaltung.

1.5 Einen Drittanbieter hinzufügen

Öffnen Sie CC Switch, wechseln Sie zum übergeordneten Bereich Codex und klicken Sie oben rechts auf die Schaltfläche zum Hinzufügen.

Integrierte Voreinstellung bevorzugen

Wenn eine Voreinstellung vorhanden ist, verwenden Sie diese und geben Sie nur den API key sowie alle erforderlichen kontospezifischen Werte ein. Eine Voreinstellung konfiguriert normalerweise:

• die Base URL;
• das Standardmodell;
• das Upstream-Protokoll;
• ob lokales Routing erforderlich ist;
• Modellzuordnungen;
• ausgewählte Reasoning-Parameter.

Die Liste der Voreinstellungen ändert sich mit der Weiterentwicklung von CC Switch. Langlebige Dokumentation sollte die aktuelle Modell-ID eines Anbieters nicht fest vorgeben. Verwenden Sie die Liste in der Anwendung und die offizielle Dokumentation des Anbieters.

Benutzerdefinierten Anbieter erstellen

Wenn keine Voreinstellung verfügbar ist, wählen Sie eine benutzerdefinierte Konfiguration und geben Sie Folgendes an:

Die wichtigste Einstellung ist Upstream Format:

Wählen Sie Responses nicht allein deshalb aus, weil ein Anbieter mit „OpenAI-Kompatibilität“ wirbt. Viele OpenAI-kompatible APIs implementieren nur Chat Completions.

1.6 Base URL korrekt eingeben

Standardmäßig hängt CC Switch den passenden API-Pfad an die Base URL an. Geben Sie in den meisten Fällen den API-Stammpfad aus der Anbieterdokumentation ein, anstatt /chat/completions oder /responses selbst zu wiederholen.

Wenn der Anbieter beispielsweise Folgendes dokumentiert:

POST https://api.example.com/v1/chat/completions

müssen Sie möglicherweise Folgendes eingeben:

https://api.example.com

oder, abhängig von der Voreinstellung und der Anbieterdokumentation:

https://api.example.com/v1

Ob /v1 zur Base URL gehört, hängt vom Anbieter und von der CC Switch-Voreinstellung ab. Verwenden Sie die integrierte Verbindungsprüfung oder die Routing-Protokolle, um die endgültige Anfrage-URL zu bestätigen.

Verwenden Sie Full URL Mode nur, wenn der Anbieter einen nicht standardmäßigen vollständigen Endpunktpfad erfordert.

1.7 Needs Local Routing und Modellzuordnung konfigurieren

Aktivieren Sie Needs Local Routing, wenn der Anbieter Chat Completions oder Anthropic Messages verwendet oder Modellnamen nutzt, die Codex standardmäßig nicht erkennt.

Chat-orientierte Voreinstellungen aktivieren diese Option normalerweise automatisch. Überprüfen Sie sie bei benutzerdefinierten Anbietern.

Nach der Aktivierung wird eine Tabelle für Modellzuordnungen verfügbar. Zu den üblichen Feldern gehören:

Wichtige Punkte:

• verwenden Sie die genaue Modell-ID aus der Anbieterdokumentation;
• raten Sie nicht die Größe des Kontextfensters;
• starten Sie Codex nach Änderungen an der Modellliste neu;
• CC Switch erzeugt den Codex-Modellkatalog aus diesen Zuordnungen;
• wenn ein Relay die Domain oder den Modellnamen ändert, kann die automatische Erkennung der Reasoning-Fähigkeiten falsch sein und sollte in den erweiterten Einstellungen überprüft werden.

1.8 Lokales Routing und Codex-Übernahme aktivieren

Öffnen Sie in CC Switch:

Settings → Routing → Local Routing

Gehen Sie anschließend wie folgt vor:

1. aktivieren Sie den Hauptschalter für lokales Routing;
2. aktivieren Sie Codex unter Routing Enabled;
3. überprüfen Sie die Einstellung Needs Local Routing des Anbieters;
4. lassen Sie CC Switch geöffnet, solange der Anbieter verwendet wird.

Die standardmäßige lokale Route lautet üblicherweise:

http://127.0.0.1:15721

Nach der Übernahme verweist die aktive Codex-Konfiguration auf die lokale Route von CC Switch. CC Switch leitet Anfragen anschließend an den derzeit ausgewählten Upstream-Anbieter weiter.

Bei einem Chat Completions-Upstream sieht der Ablauf normalerweise so aus:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Anbieter wechseln und Codex neu starten

Kehren Sie zur Liste der Codex-Anbieter in CC Switch zurück, wählen Sie den konfigurierten Anbieter aus und aktivieren Sie ihn.

Starten Sie Codex nach dem Wechsel vollständig neu, denn:

• Codex liest config.toml beim Start;
• das Menü /model lädt seinen Katalog normalerweise beim Start;
• die IDE-Erweiterung oder der Desktop-Client speichert möglicherweise den vorherigen Anbieter zwischen;
• bestehende Sitzungen können alte Modellmetadaten beibehalten.

CLI-Benutzer können einfach einen neuen Prozess starten:

codex

1.10 Integration überprüfen

Führen Sie in Codex Folgendes aus:

/status

Überprüfen Sie das aktive Modell, den Anbieter, die Berechtigungen und die Kontextinformationen.

Öffnen Sie die Modellauswahl:

/model

Überprüfen Sie die Konfigurationsebenen:

/debug-config

Prüfen Sie außerdem:

• den aktiven Codex-Anbieter in CC Switch;
• die Protokolle oder Statistiken des lokalen Routings von CC Switch;
• den Anfrageverlauf und Änderungen des Guthabens im Anbieter-Dashboard;
• ob ~/.codex/config.toml derzeit auf die lokale Route verweist.

Validieren Sie die Einrichtung nicht nur mit einer einfachen Begrüßung. Führen Sie mindestens einen Test der Agentenfähigkeiten durch:

1. bitten Sie Codex, die Dateien im aktuellen Projekt aufzulisten;
2. bitten Sie Codex, eine Datei zu lesen und zusammenzufassen;
3. bitten Sie Codex, eine kleine Datei zu ändern;
4. bitten Sie Codex, die Tests auszuführen;
5. belassen Sie einen einfachen Fehler und prüfen Sie, ob Codex das Testergebnis verwenden kann, um mit der Fehlerbehebung fortzufahren.

Eine erfolgreiche Textgenerierung beweist nicht, dass Werkzeugaufrufe und mehrstufige Agentenabläufe kompatibel sind.

1.11 Zum offiziellen OpenAI-Anbieter zurückwechseln

Wählen Sie in CC Switch OpenAI Official aus und starten Sie Codex neu.

Prüfen Sie den Anmeldestatus:

codex login status

Melden Sie sich bei Bedarf erneut an:

codex login

Wenn Sie sowohl den offiziellen Anmeldestatus als auch Modellanfragen an Drittanbieter benötigen, vergewissern Sie sich, dass Keep official login when switching third-party providers weiterhin aktiviert ist.

1.12 Einschränkungen und betriebliche Aspekte

CC Switch vereinfacht die Konfiguration, beseitigt jedoch keine Einschränkungen des Upstreams:

• CC Switch muss für die Konvertierung von Chat oder Messages weiter ausgeführt werden;
• die Protokollkonvertierung kann nicht jede anbieterspezifische Funktion nachbilden;
• einige Modelle können chatten, führen Werkzeugaufrufe jedoch nicht zuverlässig aus;
• Web Search, Bildeingaben, WebSockets oder Antwortspeicherung sind möglicherweise nicht verfügbar;
• die Ratenbegrenzungen, Abrechnung und Richtlinien zur Datenspeicherung des Upstream-Anbieters gelten weiterhin;
• ein API-Relay kann Anfragen und Antworten erneut verändern;
• Konfigurationen sollten nach Upgrades von CC Switch, Codex oder dem Anbieter erneut getestet werden.

CC Switch eignet sich am besten für die lokale Desktop-Entwicklung. Bevorzugen Sie für Server, CI oder lang laufende Headless-Automatisierung einen nativen Responses-Anbieter oder ein selbst gehostetes Gateway.

2. Eine gehostete API mit einem benutzerdefinierten Modellanbieter verbinden

Konfigurieren Sie einen Anbieter nur dann direkt, wenn der Dienst die von Codex benötigte Responses API nativ unterstützt.

Wenn der Dienst nur /chat/completions oder Anthropic Messages bereitstellt, verwenden Sie den CC Switch-Ablauf aus Abschnitt 1. Versuchen Sie nicht, die Inkompatibilität mit wire_api = "chat" zu beheben.

2.1 Erforderliche API-Fähigkeiten

Ein für die direkte Codex-Integration geeigneter Anbieter sollte mindestens Folgendes unterstützen:

• POST /responses;
• Responses-JSON-Objekte;
• Responses-SSE-Streaming-Ereignisse;
• Funktions- oder Werkzeugaufrufe;
• JSON Schema-Werkzeugparameter;
• Fortsetzung nach der Rückgabe von Werkzeugergebnissen;
• mehrstufige Anfragen oder eine Entsprechung zu previous_response_id;
• ein ausreichendes Kontextfenster und stabile, lang laufende Anfragen;
• dokumentierte Authentifizierung, Ratenbegrenzungen und Fehlerantworten.

Die reine Textgenerierung reicht für einen zuverlässigen Codex-Agenten nicht aus.

2.2 Allgemeine Konfiguration

Bearbeiten Sie die Konfiguration auf Benutzerebene:

~/.codex/config.toml

Fügen Sie Folgendes hinzu:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Verwenden Sie nicht diese reservierten Anbieter-IDs:

openai
ollama
lmstudio

Verwenden Sie stattdessen eine benutzerdefinierte ID wie third_party oder company_gateway.

2.3 Konfigurationsfelder

Ob base_url /v1 enthält, hängt von der Anbieterdokumentation ab. Ein üblicher endgültiger Endpunkt lautet:

https://provider.example.com/v1/responses

2.4 API key festlegen

Aktuelle bash- / zsh-Sitzung:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Aktuelle PowerShell-Sitzung:

$env:THIRD_PARTY_API_KEY = "your API key"

Für den aktuellen Windows-Benutzer dauerhaft speichern:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Starten Sie das Terminal, die IDE oder den Desktop-Client neu, nachdem Sie eine dauerhafte Umgebungsvariable festgelegt haben.

2.5 Zuerst den Responses-Endpunkt testen

Rufen Sie den Anbieter direkt auf, bevor Sie Codex starten:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Überprüfen Sie Folgendes:

• der Endpunkt gibt keinen 404-Fehler zurück;
• die Antwort besitzt eine Responses-Struktur und nicht nur ein Chat Completions-Array choices;
• die Modell-ID wird akzeptiert;
• die Authentifizierung ist korrekt;
• Fehler enthalten nützliche Diagnoseinformationen.

Testen Sie anschließend separat:

• stream: true;
• Werkzeugaufrufe;
• Fortsetzung nach Werkzeugergebnissen;
• mehrere Gesprächsrunden;
• lange Kontexte;
• Parallelität und Ratenbegrenzungen.

2.6 Codex-Konfiguration validieren

Starten Sie im strikten Modus:

codex --strict-config

--strict-config behandelt unbekannte Konfigurationsschlüssel als Fehler. Dadurch lassen sich Felder erkennen, die aus veralteten Leitfäden übernommen wurden.

Führen Sie in Codex Folgendes aus:

/status

Führen Sie zum Überprüfen der Konfigurationsquellen Folgendes aus:

/debug-config

Überschreiben Sie Anbieter und Modell für einen einzelnen Durchlauf, ohne die Standardkonfiguration zu ändern:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Modellkataloge und Unknown model

Ein Codex-Modellkatalog kann Folgendes beschreiben:

• die Größe des Kontextfensters;
• unterstützte Reasoning-Stufen;
• Eingabemodalitäten;
• Fähigkeiten für Werkzeugaufrufe;
• Kürzungsverhalten;
• Mindestversionen des Clients.

Wenn der Anbieter einen Codex-kompatiblen Modellkatalog bereitstellt, speichern Sie ihn lokal und konfigurieren Sie:

model_catalog_json = "~/.codex/provider-models.json"

Wenn kein Katalog vorhanden ist, legen Sie ein Kontextfenster erst fest, nachdem Sie den tatsächlichen Wert bestätigt haben:

model_context_window = 131072

Kopieren Sie keine Metadaten eines nicht verwandten Modells, nur um eine Warnung zu entfernen. Falsche Fähigkeits- oder Kontextmetadaten können zu vorzeitiger Kürzung, Upstream-Limitfehlern oder fehlerhaften Werkzeugaufrufen führen.

2.8 Vollständige Kompatibilitätscheckliste

Testen Sie vor dem Produktionseinsatz:

• nicht streamenden /responses-Text;
• Responses-SSE-Streaming;
• einen Werkzeugaufruf;
• mehrere sequenzielle oder parallele Werkzeugaufrufe;
• JSON Schema-Parameter;
• Fortsetzung nach Werkzeugergebnissen;
• lange Kontexte und automatische Komprimierung;
• Reasoning-Parameter;
• Bilder oder andere Eingabemodalitäten;
• Ratenbegrenzungen und Wiederholungsverhalten;
• ob ein Proxy SSE puffert;
• ob der Anbieter Werkzeugfelder verwirft oder umschreibt;
• Richtlinien zu Datenspeicherung, Protokollierung und Datenschutz.

2.9 Speicherort der Anbieterkonfiguration

Speichern Sie model_provider, model_providers und die Anbieterauthentifizierung in der Datei auf Benutzerebene:

~/.codex/config.toml

Speichern Sie sie nicht in der Datei auf Repository-Ebene:

<project>/.codex/config.toml

Codex ignoriert projektlokale Felder, die Modellanfragen umleiten oder die Anbieterauthentifizierung ändern könnten. Dadurch wird verhindert, dass ein nicht vertrauenswürdiges geklontes Repository Anfragen unbemerkt an einen anderen Server weiterleitet.

3. Mehrere Drittanbieter mit Profilen verwalten

Benutzer von CC Switch können Anbieter normalerweise in der Anwendung wechseln und benötigen keine Codex-Profile.

Profile sind nützlich, wenn Sie mehrere native Responses-Anbieter manuell konfigurieren. Belassen Sie die Anbieterdefinitionen in der Basiskonfiguration und verwenden Sie separate Profildateien, um einen Anbieter und ein Modell auszuwählen.

Basis-~/.codex/config.toml:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Erstellen Sie:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Erstellen Sie ein weiteres Profil:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Wählen Sie beim Start von Codex ein Profil aus:

codex --profile fast
codex --profile quality

Nicht interaktiver Modus:

codex exec --profile quality "Review the current changes"

Profildateien befinden sich unter:

$CODEX_HOME/<profile-name>.config.toml

Der Standardwert für CODEX_HOME ist ~/.codex.

Aktuelle Codex-Versionen verwenden separate Profildateien und lesen veraltete [profiles.<name>]-Tabellen nicht mehr. Migrieren Sie jedes veraltete Profil in eine eigene <name>.config.toml-Datei.

4. Benutzerdefinierte Header und erweiterte Authentifizierung

4.1 Standardmäßige Bearer-Token

Die meisten Drittanbieterdienste funktionieren mit:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex liest den Schlüssel aus der Umgebung und wendet die Bearer-Authentifizierung des Anbieters an.

4.2 Benutzerdefinierte API-key-Header

Einige Dienste erfordern:

x-api-key: <key>

Verwenden Sie env_http_headers:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

Der Wert VENDOR_API_KEY ist der Name einer Umgebungsvariable und nicht das Geheimnis selbst.

export VENDOR_API_KEY="your API key"

4.3 Statische Header und Abfrageparameter

Fügen Sie nicht vertrauliche statische Header hinzu:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Fügen Sie Abfrageparameter hinzu:

query_params = { "api-version" = "2026-08-01" }

Speichern Sie keine echten Geheimnisse in http_headers.

4.4 Befehlsbasierte Authentifizierung

Eine Unternehmensumgebung kann kurzlebige Token aus einem Schlüsselbund, einem Cloud-Anmeldeinformationshelfer oder einem internen Befehl beziehen:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Der Befehl darf nur das Token auf der Standardausgabe ausgeben.

Kombinieren Sie diese Authentifizierungsmethoden nicht:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 OpenAI-Authentifizierung über einen Proxy wiederverwenden

Legen Sie Folgendes nur fest, wenn der Proxy weiterhin auf OpenAI-Modelle zugreift und Codex die offizielle OpenAI-Authentifizierung verwenden soll:

requires_openai_auth = true

Dies ist nicht die richtige Einstellung für einen normalen API key eines Drittanbietermodells. Wenn sie aktiviert ist, ignoriert Codex das env_key des Anbieters.

5. Fehlerbehebung

5.1 CC Switch wechselt den Anbieter, aber Codex verwendet weiterhin das alte Modell

Prüfen Sie jeden Punkt:

1. der gewünschte Codex-Anbieter ist in CC Switch aktiviert;
2. der Hauptschalter für lokales Routing ist eingeschaltet;
3. Codex ist unter Routing Enabled aktiviert;
4. für Chat- oder Messages-Anbieter ist Needs Local Routing aktiviert;
5. CC Switch wird weiterhin ausgeführt;
6. Codex, die IDE oder der Desktop-Client wurde vollständig neu gestartet;
7. /debug-config zeigt die erwartete Konfigurationsquelle.

Starten Sie Codex nach Änderungen an Modellzuordnungen neu, damit das Menü /model seinen Katalog neu laden kann.

5.2 404, 400 oder ein fehlender /responses-Endpunkt

Häufige Ursachen sind:

• ein Chat Completions-Anbieter wird als nativer Responses-Anbieter behandelt;
• /v1 wurde fälschlicherweise hinzugefügt oder entfernt;
• /chat/completions wurde doppelt angehängt;
• Full URL Mode wurde für einen nicht standardmäßigen Endpunkt nicht aktiviert;
• lokales Routing hat Codex nicht übernommen;
• eine unvollständige Responses-Implementierung im Drittanbieter-Gateway.

Benutzer von CC Switch sollten Upstream Format und die Routing-Protokolle prüfen. Benutzer eines direkten Anbieters sollten <base_url>/responses mit curl aufrufen.

5.3 401 Unauthorized oder 403 Forbidden

Prüfen Sie:

• ob der API key gültig ist;
• ob er zur richtigen Region, zum richtigen Projekt oder Tarif gehört;
• ob das Konto über ausreichendes Guthaben und die erforderlichen Berechtigungen verfügt;
• ob der Dienst ein Bearer-Token oder x-api-key erwartet;
• ob der Name der Umgebungsvariable genau mit env_key übereinstimmt;
• ob CC Switch den richtigen Schlüssel gespeichert hat;
• ob ein Proxy den Authentifizierungs-Header entfernt hat.

Geben Sie keinen vollständigen Schlüssel in gemeinsam genutzten Protokollen aus.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 Das Modell fehlt in /model

Prüfen Sie:

• ob CC Switch Model Mapping die genaue Upstream-Modell-ID enthält;
• ob der Anbieter gespeichert und aktiviert wurde;
• ob Codex neu gestartet wurde;
• ob ein manueller Anbieter über ein gültiges model_catalog_json verfügt;
• ob das Katalog-JSON gültig ist;
• ob der Anbieter das Modell umbenannt oder eingestellt hat.

5.5 Text funktioniert, aber Codex kann keine Dateien lesen, keinen Code bearbeiten oder keine Befehle ausführen

Mögliche Ursachen:

• das Modell ist bei Werkzeugaufrufen schwach;
• der Upstream implementiert keine Funktionsaufrufe;
• ein Relay verwirft Werkzeugaufruf-IDs;
• Fragmente von Streaming-Werkzeugaufrufen werden nicht korrekt zusammengesetzt;
• JSON Schema wird umgeschrieben;
• Werkzeugergebnisse werden in der nächsten Runde nicht zurückgegeben;
• der Modellkontext ist zu kurz;
• der Modellkatalog weist fälschlicherweise Fähigkeiten aus.

Testen Sie einen echten Ablauf „lesen → bearbeiten → Tests ausführen → Fehler untersuchen → beheben“ anstelle einer einfachen Chat-Eingabe.

5.6 Streaming-Verbindungen werden häufig getrennt

Benutzer von CC Switch sollten zuerst die Protokolle des lokalen Routings und die Upstream-Antworten prüfen. Häufige Ursachen sind:

• Warteschlangenbildung beim Upstream oder lange Reasoning-Zeit;
• ein Gateway, das SSE nicht zeitnah ausgibt;
• Pufferung durch CDN, Reverse-Proxy oder Unternehmensnetzwerk;
• nicht standardmäßige Upstream-Ereignisse;
• Kompatibilitätsprobleme in einer bestimmten Version von CC Switch oder des Anbieters.

Bei einem direkten Anbieter können Sie Folgendes erhöhen:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Längere Zeitüberschreitungen können Netzwerkprobleme oder langsame Inferenz abmildern, aber keine fehlerhafte Protokollimplementierung reparieren.

5.7 wire_api = "chat" verhindert den Start von Codex

Dieser Wert erscheint in älteren Leitfäden. Die aktuelle Codex-Konfiguration unterstützt nur:

wire_api = "responses"

Verwenden Sie CC Switch, wenn der Upstream nur Chat Completions bereitstellt.

Prüfen Sie mit Folgendem auf weitere veraltete Felder:

codex --strict-config

5.8 Das Bearbeiten der Projektkonfiguration ändert den Anbieter nicht

Anbietereinstellungen gehören in:

~/.codex/config.toml

Ein .codex/config.toml auf Projektebene kann keine Felder überschreiben, die Anfragen umleiten oder die Anbieterauthentifizierung ändern, einschließlich model_provider und model_providers.

5.9 Das Terminal funktioniert, aber die IDE-Erweiterung findet den API key nicht

GUI-Anwendungen erben häufig keine Variablen, die vorübergehend in einem bestehenden Terminal exportiert wurden.

Zu den Optionen gehören:

• starten Sie die IDE aus dem Terminal, in dem die Variable festgelegt ist;
• speichern Sie die Variable dauerhaft in der Benutzerumgebung des Betriebssystems;
• beenden Sie die IDE vollständig und öffnen Sie sie erneut;
• verwenden Sie CC Switch, um die lokale Anbieterkonfiguration zu verwalten.

5.10 Offizielle Anmeldung oder offizielle Funktionen funktionieren nach einem Wechsel nicht mehr

Prüfen Sie:

• ob OpenAI Official erneut ausgewählt wurde;
• ob Keep official login when switching third-party providers aktiviert ist;
• ob ein älterer Ablauf ~/.codex/auth.json überschrieben hat;
• ob codex login status erfolgreich ausgeführt wird.

Melden Sie sich bei Bedarf erneut an:

codex login

Geben Sie keine auth.json-Datei mit Zugriffstoken weiter und bearbeiten Sie sie nicht manuell.

5.11 Web Search, Bilder oder andere erweiterte Funktionen funktionieren nicht

Ein Anbieter, der Text und Werkzeugaufrufe unterstützt, implementiert nicht zwangsläufig jede Codex-Funktion.

Benutzerdefinierte Anbieter weisen standardmäßig keine eigenständige Web Search aus. Legen Sie Folgendes nur fest, wenn Anbieter, Modell und Endpunkt diese Funktion tatsächlich unterstützen:

supports_standalone_web_search = true

Eine fälschliche Aktivierung führt lediglich dazu, dass Codex Anfragen sendet, die der Upstream nicht verarbeiten kann. Validieren Sie Bildeingaben, WebSockets, Antwortspeicherung und andere erweiterte Funktionen separat.

6. Einen Integrationsweg auswählen

Validieren Sie jede Integration auf drei Ebenen:

1. Konnektivität: Sie gibt zuverlässig Text zurück;
2. Werkzeugnutzung: Sie kann Dateien lesen, Befehle ausführen und anhand von Werkzeugergebnissen fortfahren;
3. Aufgabenabschluss: Sie kann einen Bearbeitungs-, Test- und Reparaturablauf abschließen.

Prüfen Sie außerdem:

• die Preise des Drittanbieters;
• Ratenbegrenzungen;
• ob Quellcode und Eingaben protokolliert werden;
• Regionen der Datenspeicherung;
• Compliance-Anforderungen für Teams oder Unternehmen;
• ob Modell-Upgrades Regressionstests erfordern.

Wenn Sie einen API key eines Drittanbieters verwenden, wird die Nutzung von diesem Anbieter oder Relay abgerechnet. Kontingente eines ChatGPT Plus-, Pro- oder Codex-Abonnements werden dadurch nicht automatisch verbraucht oder geteilt.

Referenzen

• Grundlagen der Codex-Konfiguration
• Erweiterte Codex-Konfiguration
• Codex-Konfigurationsreferenz
• Codex-Authentifizierung
• Codex-Entwicklerbefehle
• Codex-Modelle
• CC Switch auf GitHub
• CC Switch-Benutzerhandbuch
• CC Switch: Anbieter hinzufügen
• CC Switch: Offizielle Codex-Anmeldung beibehalten