Die Installation von Codex ist nicht schwer, das eigentliche Problem ist das Einbinden: Wo soll der API-Schlüssel platziert werden, wie schreibt man config.toml, was sind die Unterschiede zwischen Windows und macOS, warum kann VS Code die Variablen im Terminal nicht lesen, muss das Modell festgelegt werden...

Wenn du nur schnell Codex zum Laufen bringen möchtest, kannst du die Konfiguration auf drei Werte reduzieren:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

Nach Abschluss können das Codex CLI, Desktop und VS Code Erweiterung die Datei ~/.codex/config.toml gemeinsam nutzen, und das Modell wird beim Start direkt ausgewählt, ohne die Verbindung ständig neu konfigurieren zu müssen.

Hier folgt eine Schritt-für-Schritt-Anleitung für die Erstkonfiguration.

Vorbereitung

Vor Beginn bitte sicherstellen:

  • Bei Ace Data Cloud registriert und eingeloggt
  • Eine funktionierende Anwendung erstellt oder vorhanden
  • Node.js und npm auf dem Rechner installiert
  • Terminal oder PowerShell verwenden können
  • Mindestens eine der Optionen: Codex CLI, Codex Desktop oder VS Code Erweiterung

Schritt 1: API-Schlüssel bei Ace Data Cloud holen

Öffne die Liste der Ace Data Cloud Anwendungen, gehe zu deiner Anwendung und kopiere den API-Schlüssel.

Wichtig:

  • Der API-Schlüssel ist ein sensibles Credential, nicht in öffentliche Repositories speichern
  • Keine echten Schlüssel in Tutorialscreenshots verwenden
  • Für verschiedene Umgebungen oder Zwecke separate Credentials erstellen und verwalten
  • Bei Verdacht auf Lecks den Schlüssel umgehend rotieren oder widerrufen

In diesem Leitfaden wird die Umgebungsvariable ACEDATACLOUD_API_KEY verwendet, um den Schlüssel vor der direkten Eingabe in die Konfigurationsdatei zu schützen.

Schritt 2: Codex CLI installieren

Mit npm global installieren:

npm install -g @openai/codex

Nach der Installation prüfen:

codex --version

Wenn die Meldung „Befehl nicht gefunden“ erscheint, sicherstellen, dass der globale npm-Installationsordner im PATH ist, dann Terminal neu starten.

Wenn du hauptsächlich VS Code nutzt, kannst du auch die OpenAI Codex Erweiterung installieren:

code --install-extension openai.chatgpt

CLI und Erweiterung teilen sich die Konfigurationsdatei, daher ist es ratsam, Provider und Umgebungsvariablen zuerst zu konfigurieren und dann den Editor zu starten, um die Funktion zu prüfen.

Schritt 3: API-Schlüssel als Umgebungsvariable setzen

macOS / Linux: Aktuelle Terminal-Sitzung

export ACEDATACLOUD_API_KEY="Dein API-Schlüssel"

Diese Einstellung gilt nur für die aktuelle Shell und deren Kindprozesse. Nach Schließen des Terminals ist die Variable weg.

macOS / Linux: Dauerhaft

Bei Zsh:

echo 'export ACEDATACLOUD_API_KEY="Dein API-Schlüssel"' >> ~/.zshrc
source ~/.zshrc

Bei Bash:

echo 'export ACEDATACLOUD_API_KEY="Dein API-Schlüssel"' >> ~/.bashrc
source ~/.bashrc

Auf gemeinsam genutzten Rechnern keine sensiblen Schlüssel in Shell-Konfigurationen unüberlegt speichern; in Teamumgebungen sollte eine Credential-Management-Lösung mit minimalen Rechten genutzt werden.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "Dein API-Schlüssel"

Nach Ausführung PowerShell schließen und neu öffnen. setx aktualisiert nur die Umgebungsvariablen für neue Prozesse, alte PowerShell- oder VS Code-Instanzen lesen die Variable möglicherweise noch nicht.

Für eine temporäre Einstellung nur in der aktuellen PowerShell-Sitzung:

$env:ACEDATACLOUD_API_KEY="Dein API-Schlüssel"

Schritt 4: config.toml erstellen oder bearbeiten

Gemeinsam genutzte Konfigurationsdateien für CLI, Desktop und VS Code:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

Falls das Verzeichnis noch nicht existiert, vorher erstellen.

macOS / Linux:

mkdir -p ~/.codex

Dann die Datei anlegen oder bearbeiten:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows (PowerShell) nutzt den gleichen Provider und Base URL, die Authentifizierung erfolgt hier mit PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

Wichtig: Die drei Namen müssen exakt übereinstimmen:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Der Base URL muss vollständig inklusive /v1 sein.

Schritt 5: Codex starten und Modell auswählen

Nach Speichern die Konfiguration neu laden, Terminal öffnen und:

codex

Im Codex-Interface den Befehl /model ausführen, um die verfügbaren Modelle zu sehen. Sicherstellen, dass der Provider acedatacloud aktiv ist, und dann das gewünschte Modell auswählen.

Das Modell muss nicht fest in der Konfiguration stehen. Provider und Modellwahl sind getrennt, um bei Modellwechseln den Aufwand zu minimieren. Die verfügbaren Modelle und deren Aktualität sind stets auf /model und in der Plattform-Dokumentation zu prüfen.

Schritt 6: Mit einer einfachen Anfrage testen

Nicht gleich das komplette Projekt umkrempeln lassen. Zunächst eine kurze, schnelle Anfrage schicken, z.B.:

Bitte fasse die Verzeichnisstruktur des aktuellen Projekts zusammen, ohne Dateien zu verändern.

Dann im Ace Data Cloud Usage Dashboard prüfen, ob die Anfrage angekommen ist, und Status sowie Verbrauch kontrollieren.

Wenn die kleine Anfrage funktioniert, kann schrittweise das Lesen von Dateien, das Generieren von Änderungen, das Bearbeiten von Code und das Ausführen von Tests erfolgen.

Wichtige Hinweise für VS Code

Das VS Code Erweiterung liest die gleiche ~/.codex/config.toml, aber ob sie das API-Key sieht, hängt vom Umfeld ab, in dem der Erweiterungsprozess läuft.

Nach Konfiguration den Editor vollständig schließen und neu starten. Unter macOS / Linux kann es helfen, VS Code aus einem Terminal mit gesetztem API-Key zu starten:

code .

In Remote-Umgebungen (z.B. Remote SSH, WSL, Container, Codespaces) muss die Umgebungsvariable in der jeweiligen Umgebung gesetzt sein, da die Erweiterung nur die Umgebung des laufenden Prozesses liest.

Nur im lokalen Shell gesetzte Variablen werden nicht automatisch an Remote-Umgebungen weitergereicht.

Hinweise für die Konfiguration von Desktop

Desktop nutzt die gleiche Konfigurationsdatei, aber die Anwendung liest Umgebungsvariablen nicht automatisch aus der Shell, in der sie gestartet wurde.

Wenn der API-Schlüssel im Desktop nicht erkannt wird:

  1. Environment-Variablen dauerhaft oder systemweit setzen
  2. Desktop vollständig beenden
  3. Anwendung neu starten
  4. Provider und Modell erneut prüfen

Häufige Fehlerbehebung

1. 401, Unauthorized oder falscher API-Schlüssel

Prüfen:

  1. Ist der API-Schlüssel vollständig kopiert?
  2. Ist die Umgebungsvariable ACEDATACLOUD_API_KEY korrekt gesetzt?
  3. Wurde die Variable vor dem Start von Codex/VS Code/Desktop gesetzt?
  4. Entspricht auth.command dem Betriebssystem?
  5. Ist der Schlüssel noch gültig? Geben Sie den vollständigen Schlüssel nicht in Logs oder Chats aus. Sie können stattdessen nur überprüfen, ob die Variable existiert.

macOS / Linux:

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Schlüssel ist gesetzt"; else echo "Schlüssel fehlt"; fi

PowerShell:

if ($env:ACEDATACLOUD_API_KEY) { "Schlüssel ist gesetzt" } else { "Schlüssel fehlt" }

2. Provider wurde nicht zu acedatacloud

Bestätigen Sie den Pfad der Konfigurationsdatei und die TOML-Hierarchie. Häufige Fehler sind:

  • Dateiname lautet config.toml.txt
  • Es wurde eine andere Benutzerverzeichnis bearbeitet
  • Der Tabellenname ist inkonsistent geschrieben
  • Anführungszeichen oder Array-Formate sind fehlerhaft
  • Nach dem Speichern wurde der Client nicht neu gestartet

3. Base URL-Anfrage schlägt fehl

Stellen Sie sicher, dass die Adresse lautet:

https://api.acedata.cloud/v1

Vergessen Sie nicht https:// oder das /v1 am Ende, und verwenden Sie nicht versehentlich die Adresse der Konsole.

4. CLI funktioniert, VS Code nicht

Das liegt meist nicht an der Provider-Konfiguration, sondern daran, dass der VS Code-Prozess die Umgebungsvariablen nicht liest. Starten Sie code . im Terminal, in dem die Variablen gesetzt sind, oder konfigurieren Sie systemweite Variablen und starten Sie VS Code vollständig neu.

5. Key in WSL, SSH oder Containern nicht lesbar

Umgebungsvariablen müssen in der Umgebung gesetzt werden, in der Codex oder die Erweiterung tatsächlich läuft. setx auf Windows schreibt nicht automatisch nach WSL; lokale Variablen werden auch nicht automatisch an Remote-SSH-Hosts oder Container übertragen.

6. Das gewünschte Modell wird nicht gefunden

Geben Sie nicht manuell alte Modell-IDs ein. Führen Sie /model aus, um die aktuellen Optionen in Echtzeit zu sehen, und prüfen Sie die Zugriffsrechte, das Guthaben und den aktuellen Provider.

7. Anfrage kommt an, kann aber komplexe Aufgaben nicht ausführen

Begrenzen Sie die Aufgaben zunächst: Lassen Sie Codex nur lesen und analysieren, planen, und erlauben Sie schrittweise Änderungen und Tests. Der erfolgreiche Zugriff auf das Modell bedeutet nicht, dass alle Repository-Aufgaben sofort erledigt werden; komplexe Änderungen erfordern klare Akzeptanzkriterien, Tests und manuelle Überprüfung.

Empfohlene Checkliste für die Konfiguration

Vor der ersten offiziellen Aufgabe prüfen Sie:

  • Ein gültiger API-Key wurde aus der Anwendungsübersicht erhalten
  • Der Schlüssel ist in ACEDATACLOUD_API_KEY gespeichert
  • Der Schlüssel wurde nicht in ein Git-Repository geschrieben
  • model_provider ist auf acedatacloud gesetzt
  • Base URL ist https://api.acedata.cloud/v1
  • auth.command stimmt mit dem Betriebssystem überein
  • Codex oder VS Code wurde vollständig neu gestartet
  • /model zeigt Provider und Modell an
  • Minimale Testanfrage ist erfolgreich
  • In der Nutzungshistorie sind die entsprechenden Aufrufe sichtbar

Ein Provider, weniger doppelte Konfiguration

Der Fokus dieses Zugangs liegt nicht auf zusätzlichem TOML, sondern auf einer stabilen Grenzlinie:

  • API-Key wird durch Umgebungsvariablen verwaltet
  • Provider-Verbindung wird durch config.toml gesteuert
  • Modelle werden in Codex je nach Aufgabe ausgewählt
  • Aufruf- und Verbrauchsaufzeichnungen sind im Ace Data Cloud-Dashboard zentral sichtbar
  • CLI, Desktop und VS Code teilen sich eine Konfiguration

Wenn Authentifizierung, Provider- und Modellwahl klar getrennt sind, lassen sich viele Probleme wie „Warum funktioniert Codex wieder nicht?“ schnell eingrenzen, ohne sich ständig neu anzumelden, neu zu installieren oder mehrere Konfigurationen zu kopieren.

Öffnen Sie das Codex Konfigurationszentrum für offizielle Anleitungen verschiedener Clients oder gehen Sie zu Anwendungsübersicht, um den API-Key zu erhalten.

Referenzmaterial