Codex-Sandbox: npm mit Berechtigungsprofilen gezielt freigeben
Behalte die Schutzregeln des Codex-Arbeitsbereichs bei und erlaube gezielt den Zugriff auf die Paket-Registry. Konfiguriere ein Berechtigungsprofil und den Netzwerkproxy, teste erlaubte und gesperrte Aktionen und prüfe die umfassenden Leserechte, das native Sandboxing sowie die Profilvorgaben deines Unternehmens.
Inhalt

Wenn Codex dein Repository bearbeiten, aber keine npm-Pakete herunterladen kann, prüfe zuerst das Berechtigungsprofil der Sandbox statt der API-Einstellungen. Das integrierte Profil :workspace deaktiviert den Netzwerkzugriff für Befehle und betrifft damit Entwickler, die Abhängigkeiten in lokalen Codex-Sitzungen installieren. Leite ein Profil von :workspace ab, aktiviere den Netzwerkproxy und erlaube den Hostnamen der Registry, statt Vollzugriff zu gewähren.
Stand 2026-11-19 dokumentiert OpenAI Berechtigungsprofile als Beta-Funktion. Diese Anleitung konfiguriert lokal ausgeführte Befehle und verwendet Bash-Beispiele für macOS, Linux oder WSL2.
Was erlaubt das Standardprofil des Arbeitsbereichs?
Wenn ein Git-Repository das Stammverzeichnis des Arbeitsbereichs bildet, dürfen Befehle unter :workspace Quelldateien bearbeiten. Bestimmte Verzeichnisse bleiben geschützt. Unter jedem Stammverzeichnis sind .git, .codex, .agents und .aws weiterhin schreibgeschützt. Das verhindert direkte Änderungen an Repository-Einstellungen wie .codex/config.toml oder an Hooks unter .git/hooks. Dieser Schutz gilt für Pfade unter den Stammverzeichnissen des Arbeitsbereichs, nicht für alle gleichnamigen Verzeichnisse auf dem Rechner.
Lesen ist in einem größeren Bereich erlaubt. Befehle können Dateien außerhalb des Repositorys lesen, soweit deine bestehenden Betriebssystemberechtigungen das zulassen. OpenAI erklärt in der Beschreibung der standardmäßigen Sandbox-Grenzen, warum dadurch Compiler, SDKs, Bibliotheken und Konfigurationen an anderen Speicherorten nutzbar bleiben. Vor den Codex-Befehlen verborgen sind diese Dateien dadurch nicht.
Das Netzwerk ist deaktiviert, weil ein Befehl mit Lesezugriff Daten nicht automatisch auch nach außen senden können soll. Aus demselben Grund benötigen Downloads von Abhängigkeiten zusätzliche Berechtigungen. OpenAI dokumentiert außerdem, dass Kindprozesse die Sandbox-Beschränkungen ihres Elternprozesses erben. Das gilt auch für Nachfolgeprozesse, die nach dem Ende des ursprünglichen Befehls weiterlaufen.
Prüfe bei einem gelegentlichen Download die Anfrage nach Netzwerkzugriff, statt dein Standardprofil zu ändern. Codex kann die Anfrage dir vorlegen oder automatisch prüfen lassen, wie die Beschreibung des Netzwerkproxys erläutert. Für wiederkehrende Downloads von Abhängigkeiten eignet sich ein auf die Registry beschränktes Profil. Lass das Netzwerk bei Aufgaben deaktiviert, die es nicht benötigen.
Ein dev-Profil für die npm-Registry konfigurieren
Deine installierte Codex CLI muss die dokumentierte Schnittstelle codex sandbox --permission-profile unterstützen. Die folgenden Prüfungen benötigen außerdem npm, curl und Bash. Teste die Regeln im Stammverzeichnis einer temporären Git-Arbeitskopie, die du anschließend verwerfen kannst.
Bearbeite deine persönliche Datei ~/.codex/config.toml. Füge die folgenden Einstellungen in bestehende Tabellen ein, statt dieselben Tabellen mehrfach zu definieren. Damit wird dev zum Standard-Berechtigungsprofil.
Kombiniere diese Konfiguration nicht mit den bisherigen Einstellungen sandbox_mode oder [sandbox_workspace_write]. Laut Dokumentation der Berechtigungsprofile musst du eines der beiden Konfigurationssysteme wählen, statt sie zu mischen.
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" übernimmt die integrierten Schutzregeln, einschließlich des Schreibschutzes für .git und .codex. Die zusätzlichen Dateisystemregeln schützen die Einstellungen des Editors und des Entwicklungscontainers vor Änderungen. Sie sperren außerdem die aufgeführten Umgebungsdateien und das Verzeichnis secrets samt Inhalt unter jedem Stammverzeichnis. OpenAI definiert die Werte für Dateisystemberechtigungen so: read erlaubt nur Lesen, write erlaubt Lesen und Schreiben, und deny sperrt den Zugriff.
Die Netzwerkkonfiguration hat zwei getrennte Schalter. permissions.dev.network.enabled = true erlaubt Netzwerkzugriff; network_proxy = true aktiviert die Durchsetzung der Domainregeln. Wie die Dokumentation der Netzwerkberechtigungen erklärt, gewährt ein aktiviertes Netzwerk ohne aktiven Proxy direkten Netzwerkzugriff. Die Domainregeln werden dann nicht durchgesetzt. Lass die Proxyeinstellung deshalb nicht weg.
OpenAIs Sicherheitsleitfaden für Unternehmen verwendet registry.npmjs.org im Beispiel für den Zugriff auf Abhängigkeiten. example.com ist hier ein ausdrücklich gesperrtes Ziel, mit dem du die Einschränkung prüfst. Nach dem dokumentierten Verhalten der Domainregeln haben ausdrückliche Verbote Vorrang vor passenden Freigaben. Anfragen an andere Ziele benötigen eine Genehmigung oder werden blockiert.
Diese Konfiguration erlaubt nicht den unbeschränkten Zugriff auf jeden Host, den eine Paketinstallation möglicherweise kontaktiert. Füge einen weiteren Hostnamen erst hinzu, nachdem du geklärt hast, warum dein Projekt ihn benötigt.
Freigaben und Einschränkungen prüfen
Mit codex sandbox kannst du Befehle direkt unter dem Profil testen. Ergänze --include-managed-config, damit beim Auflösen des Profils auch die administrativ verwalteten Vorgaben berücksichtigt werden. Das ist wichtig, wenn eine Unternehmensrichtlinie deine Auswahl einschränkt.
Prüfe zuerst die Registry in Bash:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
Ein erfolgreicher npm ping meldet PONG. Die Option cache legt den npm-Cache hier innerhalb des Arbeitsbereichs ab. Dadurch brauchst du keine zusätzliche Schreibfreigabe für einen Cache an anderer Stelle. Der Test bestätigt die Verbindung zur Registry, nicht den erfolgreichen Abschluss jeder Abhängigkeit oder jedes Installationsskripts.
Prüfe anschließend Schreibzugriffe im Arbeitsbereich, den Schutz der Git-Metadaten und die gesperrte Domain. Führe die Prüfungen einzeln aus. Der Git-Test setzt voraus, dass .git als Verzeichnis existiert und keine Datei ist, die auf das eigentliche Repository-Verzeichnis verweist.
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
Erwartet wird ein erfolgreicher Schreibzugriff im Arbeitsbereich, ein verweigerter Schreibzugriff auf .git und eine abgelehnte Netzwerkanfrage. Ein Konfigurationsfehler, ein fehlendes Verzeichnis oder ein unabhängiger Verbindungsfehler beweisen nicht, dass die beabsichtigte Einschränkung greift. Wenn eine der gesperrten Operationen gelingt, halte an und prüfe die wirksame Konfiguration, bevor du das Profil regulär nutzt. Dies sind Prüfungen zum Ausführen, keine bereits gemessenen Testergebnisse.
Starte nach den erwarteten Ergebnissen eine neue Codex-Sitzung im Stammverzeichnis des Repositorys. Führe /permissions aus und prüfe den Eintrag dev und seine Beschreibung, wie in OpenAIs Beispiel zur Profilkonfiguration dokumentiert. Wiederhole mit diesem aktiven Profil die ursprüngliche Installation der Abhängigkeiten. Halte den Cache innerhalb des Arbeitsbereichs oder erteile write nur für das konkret benötigte externe Cache-Verzeichnis.
Was prüfen, wenn Downloads weiterhin scheitern?
Wenn das Profil nicht greift, suche zuerst in der geladenen Konfiguration nach bisherigen Sandbox-Einstellungen. Prüfe dann die Rangfolge der Konfiguration: Kommandozeilenoptionen oder Einstellungen eines vertrauenswürdigen Projekts können deine persönlichen Standardwerte überschreiben. Erweitere nicht weiter die Berechtigungen eines Profils, das die Sitzung gar nicht nutzt.
Wenn npm ping funktioniert, die Installation aber scheitert, prüfe das Ziel der fehlgeschlagenen Anfrage und den Dateisystempfad getrennt. Ein anderer Hostname benötigt eine eigene Entscheidung über den Netzwerkzugriff. Schreibzugriffe auf einen Cache außerhalb des Arbeitsbereichs brauchen eine passende Dateisystemregel. Dateisystem- und Netzwerkberechtigungen sind getrennt: Eine Netzwerkfreigabe erlaubt keine zusätzlichen Schreibzugriffe.
Wenn auch ein freigegebenes Ziel nicht erreichbar ist, prüfe, ob der Client die Proxyeinstellungen berücksichtigt. OpenAIs Hinweise zur Implementierung des Netzwerkproxys erklären, dass manche Programme die Proxy-Umgebungsvariablen ignorieren. Untersuche den Client oder seine Konfiguration, statt die Sandbox-Beschränkungen aufzuheben.
Eine fehlgeschlagene Verbindung von Codex zum Modellanbieter ist ein anderes Problem als ein blockierter Paketmanager-Befehl in der Sandbox. Für die Authentifizierung beim Anbieter, die Base URL oder das Protokoll nutze die separate Anleitung zur API-Anbindung von Codex.
Können die umfassenden Leserechte API-Schlüssel offenlegen?
Ja, solche Dateien können lesbar bleiben. Schreibschutz verhindert Änderungen, nicht das Lesen. OpenAI beschreibt diesen Kompromiss ausdrücklich im Artikel zur Codex-Sandbox. Übersetzt lautet die Aussage:
Der Nachteil ist, dass sensible Dateien an anderen Stellen auf dem Rechner ebenfalls lesbar bleiben können, etwa Konfigurationsdateien mit API-Schlüsseln.
Das Standardprofil garantiert also nicht, dass Geheimnisse außerhalb deines Repositorys verborgen sind.
Das Beispiel sperrt nur die relativ zum Stammverzeichnis angegebenen Pfade .env und .env.local sowie secrets samt Inhalt. Es deckt nicht jeden möglichen Dateinamen oder Speicherort für Zugangsdaten ab. Ergänze geeignete deny-Regeln für sensible Pfade in deiner Umgebung, bei Bedarf auch außerhalb des Arbeitsbereichs. Teste mit harmlosen Beispieldateien, statt echte Zugangsdaten auszugeben.
Auch beschreibbare Dateien bleiben ein Risiko. OpenAI beschreibt, wie eine Änderung an einem installierten Paket wie node_modules/prettier einen Formatierer beeinflussen könnte, den dein Editor später außerhalb der Sandbox ausführt. Da Git node_modules häufig ignoriert, erscheint eine solche Änderung möglicherweise nicht in git status. Prüfe neben Änderungen an versionierten Quelldateien auch beschreibbare Werkzeuge und erzeugte Abhängigkeitsdateien.
Teams mit mehreren Coding-Agenten sollten außerdem ihre Claude-Code-Berechtigungen für Geheimnisse und Git prüfen. Nutze die jeweilige Konfiguration des Werkzeugs, statt Codex-Berechtigungsschlüssel in einen anderen Client zu kopieren.
Warum eine native Sandbox statt Docker?
Eine native Sandbox erlaubt Codex, deine vorhandenen Entwicklungswerkzeuge zu nutzen und gestartete Befehle durch das Betriebssystem einzuschränken. OpenAI erklärt das Design seiner nativen Sandbox als Alternative dazu, die gesamte Entwicklungsumgebung in einem Container nachzubauen.
Ein konkretes Beispiel ist die Entwicklung einer iOS-App auf einem Mac. Im von OpenAI beschriebenen Ablauf kann ein Docker-Container weder die native Mac-Build-Toolchain ausführen noch den iPhone-Simulator starten. Werden diese Schritte an den Mac-Host delegiert, laufen sie außerhalb der Sandbox des Containers. Die Operationen auf dem Host benötigen daher eigene Beschränkungen.
Unter macOS nutzt Codex Seatbelt. Für Linux und WSL2 empfiehlt OpenAIs Anleitung zur Sandbox-Einrichtung, bubblewrap über den Paketmanager der Distribution zu installieren. Untersuche einen fehlgeschlagenen Sandbox-Start getrennt von einer verweigerten Anfrage an die Registry.
Der native Betrieb unter Windows muss separat geprüft werden. Die Windows-Sandbox-Dokumentation empfiehlt MXC auf kompatiblen Geräten. Sie warnt außerdem, dass die bisherige Implementierung unelevated keine Lesesperren für Pfade unterstützt. Erfolgreiche Bash-Prüfungen in WSL2 ersetzen keinen Test der Durchsetzung unter nativem Windows.
Ein Container bleibt eine Option, wenn dein gesamter Arbeitsablauf darin stattfindet. Benötigst du Werkzeuge auf dem Host, identifiziere und beschränke die dort ausgeführten Operationen. Gehe nicht davon aus, dass der Container auch an den Host delegierte Aufgaben absichert.
Kann ein Unternehmen die Auswahl von dev verhindern?
Ja. Administratoren können über eine verwaltete requirements.toml einschränken, welche Profile Nutzer auswählen dürfen. Ein lokal definiertes Profil hebt diese Vorgabe nicht auf. OpenAIs Beispiel für verwaltete Vorgaben zeigt diese Richtlinie:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
Wenn allowed_permission_profiles vorhanden ist, bildet die abschließend zusammengeführte Tabelle die vollständige Liste erlaubter Profile. Profile, die darin fehlen oder ausdrücklich auf false gesetzt sind, werden abgelehnt. Entspricht das Beispiel der endgültigen Liste nach dem Zusammenführen aller Vorgaben, ist dein eigenes Profil dev nicht verfügbar, weil es nicht freigegeben ist. Bitte den Administrator um ein geeignetes Build-Profil, statt die Richtlinie zu umgehen.
Die Dokumentation zur verwalteten Konfiguration nennt eine wichtige Versionsgrenze: Listen erlaubter Berechtigungsprofile benötigen Codex 0.138.0 oder neuer. Codex 0.137.0 und ältere Versionen ignorieren allowed_permission_profiles und die verwaltete Einstellung default_permissions. Prüfe jeden verwalteten Client, bevor du dich auf diese Kontrolle verlässt.
Teste vor dem Rollout auf jedem unterstützten Betriebssystem einen erlaubten Build und eine absichtlich gesperrte Aktion. Beschränke die Berechtigungen auf benötigte Registrys, kontrolliere die Auswahl des vorgesehenen Profils und behalte die Sperrtests bei Client-Updates bei.