Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Windows-Sandbox

So konfigurierst du die native Codex-Sandbox unter Windows und behebst Probleme.

Unter Windows kannst du Codex mit der nativen ChatGPT-Desktop-App, der CLI oder der IDE-Erweiterung verwenden.

Die ChatGPT-Desktop-App für Windows unterstützt unter anderem parallele Chats, Worktrees, geplante Aufgaben, Git-Funktionen, den integrierten Browser, Dateivorschauen sowie Skills und Plug-ins.

Die App kann mit einer Windows-Sandbox direkt in PowerShell laufen. Dafür brauchst du weder WSL noch eine virtuelle Maschine. So kannst du mit Codex in deiner gewohnten Windows-Umgebung arbeiten. Die Sandbox begrenzt dabei den Zugriff auf das Dateisystem und das Netzwerk.

Informationen zur Installation im Unternehmen findest du im Leitfaden zur Bereitstellung unter Windows.

Codex unterstützt drei Sandbox-Implementierungen für Windows:

  • mxc: Die empfohlene Sandbox für kompatible Windows-Geräte. Sie nutzt die native Prozessisolierung und benötigt weder eine Administratorgenehmigung für das Setup noch zusätzliche Windows-Konten oder lokale Firewallregeln.
  • elevated: Die bevorzugte ältere Ausweichlösung, wenn MXC nicht verfügbar oder deaktiviert ist. Das Setup erfordert eine Administratorgenehmigung. Befehle in der Sandbox laufen ohne Administratorrechte.
  • unelevated: Eine ältere Ausweichlösung, wenn das Setup mit Administratorgenehmigung nicht möglich ist und die Richtlinien deiner Organisation diese Alternative zulassen. Die Netzwerkisolierung ist schwächer als bei elevated. Der Lesezugriff auf einzelne Pfade lässt sich damit nicht sperren.

Windows-Sandbox konfigurieren

Die Windows-Sandbox setzt die geltenden Dateisystem- und Netzwerkberechtigungen für Befehle und deren untergeordnete Prozesse durch. Das Berechtigungsprofil legt fest, für welche Pfade Lese- oder Schreibzugriff besteht und ob Netzwerkzugriff erlaubt ist. Die Genehmigungsrichtlinie regelt unabhängig davon, wann Codex um Genehmigung bittet, einen Befehl mit erweiterten Berechtigungen auszuführen. Mehr dazu unter Sandbox und Genehmigungen.

MXC aktivieren

Bei Privatkonten bevorzugt die Desktop-App automatisch MXC, sofern das Gerät MXC unterstützt. Für die Bereitstellung im Unternehmen oder die eigenständige Nutzung der CLI kannst du dieses Verhalten mit der folgenden Konfiguration aktivieren.

Trage in config.toml Folgendes ein:

[features]
prefer_mxc = true

Mit prefer_mxc = true verwendet Codex MXC für Windows-Befehle, wenn das Gerät MXC unterstützt und die Richtlinie es zulässt. Andernfalls wählt Codex wie bisher eine der älteren Implementierungen aus und richtet sie ein.

Wenn sich die Geräteunterstützung oder die Richtlinien innerhalb deines Unternehmens unterscheiden, lass windows.sandbox auf die zulässige ältere Implementierung eingestellt. So dient elevated oder unelevated als Ausweichlösung.

Die IT-Administration kann diese Konfiguration als Standard verteilen oder features.prefer_mxc = true über requirements.toml verbindlich vorgeben. In beiden Fällen kann Codex auf eine ältere Implementierung ausweichen. Wie sich Standardwerte und verbindliche Vorgaben unterscheiden, erfährst du in der Dokumentation zur verwalteten Konfiguration.

MXC deaktiviert lassen

Um die Nutzung von MXC in deiner Organisation zu verhindern, ergänze in der zentral verwalteten Datei requirements.toml folgenden Eintrag:

[windows]
allow_mxc = false

Damit blockierst du sowohl die automatische Auswahl von MXC als auch die explizite Auswahl über windows.sandbox = "mxc". Bestehende Einstellungen und Vorgaben für die älteren Sandbox-Implementierungen gelten weiterhin.

MXC-Kompatibilität

Der Host muss bereits über die erforderlichen Funktionen von Microsoft Execution Containers (MXC) verfügen, die Microsoft schrittweise für Windows-11-Geräte bereitstellt. Microsoft hat die MXC-Prozessisolierung mit Windows 11 24H2 (Build 26100.9278) und 25H2 (Build 26200.9278) eingeführt. Mit dem folgenden Befehl prüfst du, ob dein Gerät MXC unterstützt.

Ab Version 0.162.0 der Codex CLI kannst du MXC für einen einzelnen Befehl testen, ohne die gespeicherte Sandbox-Auswahl zu ändern. Führe dazu im Projektverzeichnis Folgendes aus:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
$LASTEXITCODE

Die erwartete Ausgabe lautet MXC_OK, der erwartete Exitcode ist 0. Damit prüfst du, ob der Befehl mit dem Berechtigungsprofil für den Workspace und den zentral verwalteten Vorgaben startet.

Die explizite Auswahl über windows.sandbox = "mxc" schlägt fehl, wenn die erforderlichen nativen Funktionen fehlen oder die Richtlinie MXC blockiert.

Beachte die folgenden Einschränkungen:

  • Bei zentral verwaltetem Netzwerkzugriff muss allow_local_binding = true wirksam sein. MXC erlaubt über die Loopback-Schnittstelle des Hosts Verbindungen zu und von lokalen Diensten. Die Domainregeln des Proxys gelten weiterhin für den Datenverkehr über den Proxy. Die zusätzlichen Prüfungen des Proxys für Ziele in privaten Netzwerken entfallen jedoch.
  • Sobald der Befehl im Vordergrund endet, werden alle noch laufenden untergeordneten Prozesse beendet. Teste daher Arbeitsabläufe, die auf abgekoppelte Entwicklungsserver angewiesen sind.
  • Wie unter Linux und WSL ermittelt die Sandbox beim Start jedes Prozesses in der Sandbox, welche Dateien den Glob-Mustern für Lesesperren entsprechen. Dateien, die erst später erstellt werden und ebenfalls einem solchen Muster entsprechen, kann der laufende Prozess weiterhin lesen, sofern seine übrigen Berechtigungen das zulassen. Für langlebige Shells, Skripte, Watcher und Entwicklungsserver gilt der beim Start ermittelte Stand für die Laufzeit des jeweiligen Prozesses innerhalb der Codex-Sitzung. Mehr dazu unter Wann Glob-Muster für Lesesperren ausgewertet werden.

Eine ältere Implementierung als Ausweichlösung konfigurieren

Lege die Ausweichlösung in config.toml fest:

[windows]
sandbox = "elevated" # or "unelevated"

elevated ist die bevorzugte ältere Ausweichlösung. Sie verwendet eigene Sandbox-Konten mit eingeschränkten Rechten, begrenzt den Zugriff über Dateisystemberechtigungen und nutzt Firewallregeln. Außerdem passt sie lokale Richtlinien an, soweit dies für Befehle in der Sandbox erforderlich ist.

Wie MXC ermittelt elevated beim Start jedes Prozesses in der Sandbox, welche Dateien den Glob-Mustern für Lesesperren entsprechen. Dateien, die erst später erstellt werden und ebenfalls einem solchen Muster entsprechen, kann der laufende Prozess weiterhin lesen, sofern seine übrigen Berechtigungen das zulassen. Was das für langlebige Prozesse bedeutet, erfährst du im Abschnitt Wann Glob-Muster für Lesesperren ausgewertet werden.

unelevated ist eine ältere Ausweichlösung. Sie führt Befehle mit einem eingeschränkten Windows-Token aus, das von deinem aktuellen Benutzerkonto abgeleitet ist. Zugriffssteuerungslisten (ACLs) begrenzen den Dateisystemzugriff. Für den Offlinebetrieb nutzt sie Einschränkungen auf Umgebungsebene anstelle einer eigenen Firewallregel für das Offlinekonto. Die Netzwerkisolierung ist schwächer als bei elevated, und der Lesezugriff auf einzelne Pfade lässt sich damit nicht sperren. Die Implementierung ist dennoch nützlich, wenn lokale oder unternehmensweite Richtlinien das Setup mit Administratorgenehmigung blockieren.

Verwende MXC, wenn dein Gerät es unterstützt und die Richtlinie es zulässt. Andernfalls verwende vorzugsweise elevated. Als zweite Ausweichlösung steht unelevated zur Verfügung.

Die IT-Administration kann über requirements.toml einschränken, welche älteren Sandbox-Implementierungen Codex verwenden darf:

[windows]
allowed_sandbox_implementations = ["elevated"]

Dieses Beispiel erlaubt elevated und verhindert, dass Codex auf unelevated ausweicht. Ist MXC verfügbar, schränkt diese Vorgabe mxc nicht ein. Andere zentral verwaltete Berechtigungs- und Netzwerkvorgaben gelten weiterhin. Um beide älteren Implementierungen zuzulassen, gib beide Werte an. Ist kein Modus ausgewählt, bevorzugt Codex elevated.

Die unterstützten Werte findest du in der Referenz zu requirements.toml. Um auch MXC zu blockieren, verwende die separate Vorgabe windows.allow_mxc.

Standardmäßig verwenden beide älteren Sandbox-Modi zusätzlich einen privaten Desktop, um die Benutzeroberfläche stärker zu isolieren.

Die ältere Sandbox mit Administratorgenehmigung durch die IT bereitstellen

Für Beschäftigte ohne lokale Administratorrechte kann die IT die CLI installieren und die Sandbox im Modus elevated bereitstellen, bevor die jeweilige Person Codex startet. Führe dazu in einem Bereitstellungsprozess mit Administratorrechten folgenden Befehl aus:

codex sandbox setup --elevated --user 'DOMAIN\alice' --codex-home 'C:\Users\alice\.codex'

Ersetze das angegebene Konto und den Pfad durch das Windows-Konto und den Pfad zu CODEX_HOME der jeweiligen Person. Der Befehl liest die Konfiguration dieses Kontos, stellt die Sandbox bereit und speichert windows.sandbox = "elevated". Anschließend führt die Person Codex in einem Terminal ohne Administratorrechte aus.

Sandbox-Berechtigungen

Wenn du Codex mit Vollzugriff ausführst, kann Codex auch außerhalb deines Projektverzeichnisses arbeiten und unbeabsichtigt destruktive Aktionen ausführen, die zu Datenverlust führen können. Für eine sicherere Automatisierung behalte die Sandbox-Beschränkungen bei und verwende Regeln für gezielte Ausnahmen. Alternativ kannst du die Genehmigungsrichtlinie auf „never“ setzen. Codex versucht dann, Probleme im Rahmen deiner Genehmigungs- und Sicherheitseinstellungen zu lösen, ohne erweiterte Berechtigungen anzufordern.

Unterstützte Windows-Versionen

Windows-Version Unterstützung Hinweise
Windows 11 Empfohlen Die beste Grundlage für Codex unter Windows. Verwende Windows 11, wenn du die Bereitstellung im Unternehmen standardisierst.
Neuere, vollständig aktualisierte Version von Windows 10 Nach Möglichkeit Codex kann unter Windows 10 laufen, ist dort aber weniger zuverlässig als unter Windows 11. Codex benötigt unter Windows 10 moderne Konsolenfunktionen, darunter ConPTY. In der Praxis ist Windows 10 ab Version 1809 erforderlich.
Ältere Builds von Windows 10 Nicht empfohlen Bei älteren Builds fehlen häufiger erforderliche Konsolenkomponenten wie ConPTY. Auch die Bereitstellung in Unternehmen schlägt häufiger fehl.

Beachte außerdem folgende Voraussetzungen für deine Umgebung:

  • winget sollte verfügbar sein. Falls es fehlt, aktualisiere Windows oder installiere den Windows Package Manager, bevor du Codex einrichtest.
  • Das Setup der älteren Sandbox-Implementierung elevated erfordert eine Administratorgenehmigung.
  • Manche zentral verwalteten Unternehmensgeräte blockieren die erforderlichen Setup-Schritte auch dann, wenn die Betriebssystemversion ausreicht.
  • MXC benötigt zusätzlich die nativen Funktionen, die im Abschnitt MXC-Kompatibilität beschrieben sind. Aus der Tabelle allein geht daher nicht hervor, ob MXC auf einem bestimmten Gerät verfügbar ist.

Lesezugriff der Sandbox prüfen

Wenn ein Befehl ein Verzeichnis nicht lesen kann, prüfe das aktive Berechtigungsprofil, die zentral verwalteten Vorgaben und die Windows-Dateiberechtigungen. Mit /status und /debug-config kannst du in der CLI die aktive Sitzung und die Konfiguration prüfen. Bitte deine IT-Administration, eine zentral verwaltete Einschränkung zu überprüfen, statt die Sandbox zu deaktivieren.

Verwende standardmäßig die native Windows-Sandbox. Wähle WSL, wenn du native Linux-Werkzeuge brauchst, bereits in WSL2 arbeitest oder die verfügbaren nativen Windows-Implementierungen deine Anforderungen nicht erfüllen.

Fehlerbehebung und häufige Fragen

Wenn du ein Problem auf einem zentral verwalteten Windows-Gerät untersuchst, prüfe zuerst den nativen Sandbox-Modus, die Windows-Version und alle Richtlinienfehler, die Codex anzeigt. Prüfe bei MXC die Kompatibilität und die tatsächlich wirksame Netzwerkrichtlinie. Bei den älteren Sandbox-Implementierungen können Probleme beim Setup, mit den Anmelderechten oder mit den Dateisystemberechtigungen auftreten.