Beta. Die Berechtigungsprofile werden derzeit weiterentwickelt und können sich ändern.
Berechtigungsprofile lassen sich nicht mit den älteren Sandbox-Einstellungen kombinieren. Konfiguriere entweder default_permissions und [permissions] oder sandbox_mode / sandbox_workspace_write. Wenn sandbox_mode in einer geladenen Konfigurationsdatei steht, du --sandbox übergibst oder das ausgewählte Konfigurationsprofil sandbox_mode setzt, verwendet Codex die älteren Sandbox-Einstellungen anstelle von default_permissions.
Eine Ausnahme ist die verwaltete Vorgabe allowed_permission_profiles. Sie bewirkt, dass Codex Berechtigungsprofile verwendet. Entferne ältere Einstellungen wie sandbox_mode und [sandbox_workspace_write], bevor du eine verwaltete Liste zulässiger Profile bereitstellst. Wenn du Codex in einem Unternehmen mit unterschiedlichen Clientversionen einführst, kannst du die verwaltete Vorgabe allowed_sandbox_modes vorübergehend aus Kompatibilitätsgründen beibehalten, bis alle Clients Codex 0.138.0 oder neuer verwenden.
Mit Berechtigungsprofilen gibst du lokalen Befehlen, die Codex für dich ausführt, nur die Rechte, die sie benötigen. Ein Profil ist eine benannte Richtlinie. Seine Dateisystemregeln legen fest, was Befehle lesen oder schreiben dürfen. Seine Netzwerkregeln bestimmen, welche Ziele die Befehle erreichen dürfen.
Mit network.enabled = true erlaubst du Befehlen im Profil den Netzwerkzugriff. Dadurch startet der Netzwerkproxy noch nicht. Damit die Domainregeln des Profils greifen, setze zusätzlich features.network_proxy = true in config.toml oder verwende aktivierte, zentral verwaltete Vorgaben unter [experimental_network]. Ohne aktiven Proxy schränken die Domainregeln den direkten Netzwerkzugriff nicht ein.
Gib Codex mit einem Profil den Zugriff, den es für den aktuellen Chat braucht, ohne deinen gesamten Computer oder dein Netzwerk freizugeben. Mit einem Profil ohne Schreibzugriff kann Codex beispielsweise ein Projekt untersuchen, ohne es zu bearbeiten. Ein Profil mit Schreibzugriff kann Änderungen auf ausgewählte Workspace-Stammverzeichnisse beschränken.
Lokale Berechtigungsprofile werden unter macOS, Linux, WSL und nativ unter Windows unterstützt. Plattformspezifische Details und Einschränkungen findest du im Abschnitt Geltungsbereich und Durchsetzung.
Die aktuellen Netzwerkeinstellungen für Codex Cloud findest du im Abschnitt Verbindung mit Diensten herstellen. Für Codex Cloud (Legacy) siehe Internetzugriff.
Ein Profil definieren und auswählen
Codex enthält drei integrierte Berechtigungsprofile:
:read-onlyführt lokale Befehle ohne Schreibzugriff aus.:workspaceerlaubt Schreibzugriffe innerhalb der aktiven Workspace-Stammverzeichnisse und in den temporären Verzeichnissen des Systems.:danger-full-accesshebt die lokalen Sandbox-Beschränkungen auf. Verwende dieses Profil nur, wenn du diesen weitreichenden Zugriff ausdrücklich möchtest.
Erstelle unter [permissions.<name>] ein benanntes Profil. Setze anschließend den Schlüssel default_permissions auf der obersten Ebene auf den Namen dieses Profils oder eines der oben genannten integrierten Profile. In diesem Beispiel ist project-edit ein selbst gewählter Profilname und kein integrierter Wert.
In Unternehmen kann die IT-Administration über eine verwaltete requirements.toml Profile definieren und festlegen, welche davon zur Auswahl stehen. Sobald allowed_permission_profiles vorhanden ist, sind alle nicht aufgeführten Profile gesperrt. Das gilt auch für nicht aufgeführte integrierte Profile und für Profile, die in späteren Codex-Versionen hinzukommen. Die empfohlene verwaltete Konfiguration findest du im Abschnitt Verfügbare Berechtigungsprofile steuern.
Für eigene Profile sind zwei Einstellungen wichtig:
- Unter
[permissions.<name>.workspace_roots]fügst du konkrete Verzeichnisse hinzu, die für dieses Profil als Workspace-Stammverzeichnisse gelten sollen. - Unter
[permissions.<name>.filesystem.":workspace_roots"]legst du die Dateisystemregeln fest, die Codex in allen wirksamen Workspace-Stammverzeichnissen anwendet. Dazu gehören die zur Laufzeit festgelegten Stammverzeichnisse der aktuellen Sitzung und die oben im Profil definierten Stammverzeichnisse.
Für Profile gelten die üblichen Konfigurationsebenen. Ebenen mit höherem Vorrang können unter demselben Profilnamen Einträge hinzufügen oder ersetzen, ohne das gesamte Profil erneut zu definieren.
Beispielsweise können die Konfiguration deiner Organisation und deine persönliche Konfiguration dasselbe Profil unabhängig voneinander erweitern:
# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true
# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true
Wenn server aktiv ist, gehören beide Workspace-Stammverzeichnisse zum wirksamen Profil.
default_permissions = "project-edit"
[features]
network_proxy = true
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"
Dieses Profil hat folgende Wirkung:
- Es erlaubt das Lesen der Laufzeitpfade, die gängige Entwicklungstools mindestens benötigen.
- Es wendet dieselben Regeln auf die Workspace-Stammverzeichnisse der aktuellen Sitzung und die im Profil definierten Stammverzeichnisse an.
- Es erlaubt für IDE-bezogene Einstellungen wie
.devcontainer/in jedem Stammverzeichnis nur Lesezugriff. - Es sperrt mit einer Glob-Regel den Zugriff auf Umgebungsdateien, die dem Muster entsprechen.
- Es erlaubt Netzwerkzugriff nur im Rahmen der konfigurierten Domainrichtlinie.
Innerhalb eines aktiven Profils bleiben spezifischere Verbote wirksam, auch wenn ein übergeordneter Pfad lesbar oder beschreibbar ist. So kann ein Profil Schreibzugriffe in Workspace-Stammverzeichnissen erlauben und dennoch für einen passenden .env-Pfad deny festlegen.
Ein Profil erweitern
Verwende extends, wenn ein Profil weitgehend einem integrierten oder einem anderen benannten Profil entspricht. Erweitere möglichst ein integriertes Profil, damit dessen grundlegende Schutzregeln erhalten bleiben. Wenn du beispielsweise :workspace erweiterst, bleiben die Pfade .git, .agents, .codex und .aws im Workspace-Stammverzeichnis ohne Schreibzugriff, sofern du die Regeln nicht ausdrücklich überschreibst. Lege das übergeordnete Profil einmal fest. Ergänze oder überschreibe dann nur die Regeln, die davon abweichen.
default_permissions = "project-edit"
[features]
network_proxy = true
[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
Dieses Profil baut auf :workspace auf, sperrt weiterhin den Zugriff auf passende .env-Dateien und erlaubt Anfragen an api.openai.com. Ein Profil kann :read-only, :workspace oder ein anderes benanntes Profil erweitern. :danger-full-access lässt sich nicht erweitern. Codex lehnt auch unbekannte übergeordnete Profile und zyklische Vererbung ab.
Konfigurationsspezifikation
| Eintrag | Typ / Werte | Standardwert | Details |
|---|---|---|---|
default_permissions |
Profilname als Zeichenfolge | Keiner | Legt fest, welches Berechtigungsprofil Codex standardmäßig anwendet. Der Name muss einem Profil unter [permissions] oder einem integrierten Profil wie :workspace entsprechen. Setze den Wert ausdrücklich, damit das Verhalten vorhersehbar ist. In verwalteten Vorgaben darf er nur fehlen, wenn sowohl :workspace als auch :read-only ausdrücklich erlaubt sind. Codex verwendet die älteren Sandbox-Einstellungen, sofern die verwaltete Vorgabe allowed_permission_profiles in dieser Konfiguration nicht die Verwendung von Berechtigungsprofilen vorschreibt. |
[permissions.<name>] |
Tabelle | Keiner | Definiert ein benanntes Profil. Mit default_permissions wählst du ein Profil als Standard aus. Auch andere Einstellungen für Berechtigungsprofile verwenden den Profilnamen. |
permissions.<name>.description |
Zeichenfolge | Keiner | Enthält eine verständliche Beschreibung des Profils. Über extends erbt ein Profil die Beschreibung des übergeordneten Profils nicht. |
permissions.<name>.extends |
Profilname als Zeichenfolge | Keiner | Verwendet ein anderes benanntes Profil oder das integrierte Profil :read-only oder :workspace als Grundlage. Codex lehnt :danger-full-access, unbekannte übergeordnete Profile und zyklische Vererbung ab. |
[permissions.<name>.workspace_roots] |
Tabelle | Keiner | Fügt im Profil definierte Workspace-Stammverzeichnisse hinzu. Für sie gelten dieselben Dateisystemregeln unter :workspace_roots wie für die zur Laufzeit festgelegten Workspace-Stammverzeichnisse der aktuellen Sitzung. |
permissions.<name>.workspace_roots."<path>" |
Boolescher Wert | false |
Fügt den Pfad bei true zu den Workspace-Stammverzeichnissen des Profils hinzu. Einträge mit dem Wert false bleiben inaktiv. |
[permissions.<name>.filesystem] |
Tabelle | Keiner | Ordnet Dateisystempfaden Zugriffsrechte oder Regeln für untergeordnete Pfade zu. Fehlt die Dateisystemtabelle oder ist sie leer, bleibt der Dateisystemzugriff eingeschränkt und Codex gibt beim Start eine Warnung aus. |
permissions.<name>.filesystem.glob_scan_max_depth |
Zahl | Keiner | Begrenzt unter Linux, WSL und nativ unter Windows die Suchtiefe für Glob-Muster, die Lesezugriffe verbieten, wenn Codex die Treffer vor dem Start der Sandbox erfasst. Größere Werte können die Suche beim Start aufwendiger machen. Verwende mindestens 1, wenn die Suche für ein unbegrenztes **-Muster vorab auf eine bestimmte Tiefe beschränkt werden muss. |
[permissions.<name>.filesystem]."<path>" |
read, write oder deny |
Keiner | Regelt den direkten Zugriff auf einen unterstützten Pfad. deny verweigert den Zugriff und hat Vorrang vor gleich spezifischen Einträgen mit write oder read. Codex lehnt direkte Schreibregeln ab, die die aktive Laufzeitumgebung nicht durchsetzen kann. |
[permissions.<name>.filesystem."<path>"]."<subpath>" |
read, write oder deny |
Keiner | Regelt den Zugriff auf einen Pfad unterhalb von <path>. Verwende . für den Basispfad selbst. Alle anderen Unterpfade müssen relativ sein, unterhalb des Basispfads liegen und dürfen weder . noch .. als Pfadbestandteile enthalten. |
[permissions.<name>.network] |
Tabelle | Keiner | Konfiguriert den Netzwerkzugriff für Befehle und die Richtlinie, die ein aktiver Netzwerkproxy durchsetzt. Aktiviere features.network_proxy, sofern der Proxy nicht über zentral verwaltete Netzwerkvorgaben gestartet wird. |
permissions.<name>.network.enabled |
Boolescher Wert | false |
Erlaubt Befehlen im Profil den Netzwerkzugriff. Dadurch startet der Netzwerkproxy nicht. Ohne aktiven Proxy können Befehle direkte Verbindungen ohne Domainbeschränkungen herstellen. |
[permissions.<name>.network.domains] |
Tabelle | Keiner | Ordnet Hostmustern allow oder deny zu. Die Regeln greifen nur bei aktivem Netzwerkproxy. Ohne allow-Einträge blockiert der aktive Proxy Anfragen an Domains. Verbote haben Vorrang vor Freigaben. |
permissions.<name>.network.domains."<pattern>" |
allow oder deny |
Keiner | Unterstützt exakte Hostnamen, *.example.com für Subdomains, **.example.com für die Stammdomain einschließlich ihrer Subdomains und * als globalen Platzhalter ausschließlich für Freigaben. Bei der Normalisierung der Hostmuster entfernt Codex Leerraum am Anfang und Ende, wandelt Buchstaben in Kleinbuchstaben um und entfernt einen abschließenden Punkt sowie Portnummern oder eckige Klammern. |
[permissions.<name>.network.unix_sockets] |
Tabelle | Keiner | Legt Ausnahmen für die Freigabeliste der Unix-Sockets fest. Verwende sie nur für lokale Integrationen wie Docker. |
permissions.<name>.network.unix_sockets."<path>" |
allow oder deny |
Keiner | Nimmt einen absoluten Unix-Socket-Pfad mit allow in die wirksame Freigabeliste auf oder sperrt ihn mit deny. Gesperrte Einträge erscheinen nicht in der wirksamen Freigabeliste. |
permissions.<name>.network.proxy_url |
URL als Zeichenfolge | http://127.0.0.1:3128 |
Adresse des HTTP-Proxy-Listeners für HTTP_PROXY, HTTPS_PROXY, WebSocket-Proxyvariablen und entsprechende Proxy-Umgebungsvariablen von Tools. |
permissions.<name>.network.enable_socks5 |
Boolescher Wert | true |
Aktiviert den SOCKS5-Listener für ALL_PROXY und FTP-Proxyvariablen. |
permissions.<name>.network.socks_url |
URL als Zeichenfolge | http://127.0.0.1:8081 |
Adresse des SOCKS5-Listeners. |
permissions.<name>.network.enable_socks5_udp |
Boolescher Wert | true |
Aktiviert die UDP-Unterstützung für SOCKS5, wenn der SOCKS5-Listener aktiviert ist. |
permissions.<name>.network.allow_upstream_proxy |
Boolescher Wert | true |
Erlaubt dem Netzwerkproxy der Sandbox, bei ausgehenden Anfragen die Einstellungen HTTP(S)_PROXY und ALL_PROXY für vorgeschaltete Proxys zu berücksichtigen. |
permissions.<name>.network.allow_local_binding |
Boolescher Wert | false |
Deaktiviert bei true den Schutz vor Zugriffen auf lokale und private Netzwerke. Bei false müssen lokale Ziele wie localhost oder 127.0.0.1 ausdrücklich mit ihrem exakten Namen oder ihrer IP-Adresse freigegeben werden. Hostnamen, die auf lokale oder private IP-Adressen aufgelöst werden, bleiben gesperrt. |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
Boolescher Wert | false |
Erlaubt Proxy-Listenern, sich an Adressen außerhalb des Loopback-Bereichs zu binden. Lass diese Einstellung für die normale lokale Entwicklung ungesetzt. |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
Boolescher Wert | false |
Umgeht die Freigabeliste für Unix-Sockets, wenn die Weiterleitung von Unix-Socket-Verbindungen über den Proxy unterstützt wird. Diese Ausnahme ermöglicht weitreichenden lokalen Zugriff. |
Dateisystemberechtigungen
Dateisystemeinträge verwenden read, write oder deny:
| Zugriff | Bedeutung |
|---|---|
read |
Befehle dürfen Dateien unterhalb des Pfads lesen und Verzeichnisinhalte auflisten. Sie können dort keine Dateien erstellen, ändern, umbenennen oder löschen. |
write |
Befehle dürfen Dateien unterhalb des Pfads lesen und ändern. Sie dürfen Dateien auch erstellen, umbenennen und löschen, wenn das Betriebssystem dies erlaubt. |
deny |
Sperrt Lese- und Schreibzugriffe unterhalb des Pfads. Damit kannst du einen Unterpfad von einer umfassenderen Freigabe mit read oder write ausnehmen. |
Spezifischere Einträge haben Vorrang vor allgemeineren Einträgen. Beziehen sich zwei Einträge auf denselben Pfad, hat deny Vorrang vor write und write Vorrang vor read.
So kannst du in einem Profil zunächst einen größeren Arbeitsbereich freigeben und dann Dateien oder Verzeichnisse ausnehmen, die nicht lesbar sein sollen:
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"
In diesem Beispiel bleibt das Workspace-Stammverzeichnis beschreibbar. Für .devcontainer/ ist nur Lesezugriff erlaubt. Auf Umgebungsdateien, die dem Muster entsprechen, können Befehle in der Sandbox nicht zugreifen.
Mit einem spezifischeren Pfad kannst du auch einen Teil eines ansonsten gesperrten Verzeichnisbaums wieder freigeben:
[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"
Unterstützte Pfadangaben:
| Pfad | Bedeutung | Regeln für Unterpfade |
|---|---|---|
:root |
Stammverzeichnis des Dateisystems | Nur . |
:minimal |
Plattform- und Laufzeitpfade, die gängige Tools benötigen | Nur . |
:workspace_roots |
Workspace-Stammverzeichnisse der aktuellen Sitzung sowie alle aktivierten, im Profil definierten Workspace-Stammverzeichnisse | Ja |
:tmpdir |
Das durch $TMPDIR angegebene Verzeichnis, sofern verfügbar |
Nur . |
:slash_tmp |
Das Verzeichnis /tmp, sofern es existiert |
Nur . |
/absolute/path |
Ein absoluter Pfad der jeweiligen Plattform, etwa /path unter macOS, Linux oder WSL oder C:\path nativ unter Windows |
Ja |
~/path |
Ein Pfad im Home-Verzeichnis des aktuellen Benutzerkontos | Ja |
Nativ unter Windows können Pfade relativ zum Home-Verzeichnis auch umgekehrte Schrägstriche enthalten, etwa ~\work.
Verwende :root nur, wenn ein Profil ausdrücklich weitreichenden Lesezugriff benötigt:
[permissions.audit.filesystem]
":root" = "read"
Mit verschachtelten Einträgen unter :workspace_roots regelst du den Zugriff auf Unterpfade relativ zum jeweiligen Workspace-Stammverzeichnis:
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write" # each workspace root
"docs" = "read" # each workspace-root docs directory
"generated" = "deny" # each workspace-root generated directory
Verschachtelte Unterpfade müssen innerhalb ihres Workspace-Stammverzeichnisses bleiben. Codex lehnt Pfade ab, die über das übergeordnete Verzeichnis führen, etwa ../other-repo.
Lesezugriffe mit exakten Pfaden oder Glob-Mustern sperren
Verwende deny für Dateien oder Verzeichnisbäume, die Codex auch dann nicht lesen soll, wenn eine allgemeinere Profilregel den umgebenden Bereich freigibt. Exakte Pfade eignen sich für feste Speicherorte wie ~/.ssh. Glob-Muster eignen sich besser für Gruppen sensibler Dateien, deren genaue Speicherorte sich von Repository zu Repository unterscheiden.
Steht ein Glob-Muster unter :workspace_roots, wertet Codex es relativ zu jedem wirksamen Workspace-Stammverzeichnis aus. Zum Beispiel:
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
Diese Regel sperrt Lesezugriffe auf passende .env-Dateien in jedem Workspace-Stammverzeichnis, das zur Laufzeit oder im Profil festgelegt wurde. Verwende sie, wenn normale Schreibzugriffe im Workspace möglich bleiben sollen, Befehle aber keine Umgebungsdateien, generierten Geheimnisse oder ähnlichen Dateien mit Zugangsdaten lesen dürfen.
Unter Linux, WSL und nativ unter Windows mit MXC oder elevated werden die Treffer für Glob-Muster, die Lesezugriffe sperren, beim Start jedes Prozesses in der Sandbox erfasst. Passende Dateien, die danach entstehen, werden nicht in die Sperrliste dieses Prozesses aufgenommen. Sie bleiben lesbar, sofern die übrigen Berechtigungen den Zugriff erlauben. So kann eine länger laufende Shell, ein Skript, ein Datei-Watcher oder ein Entwicklungsserver eine passende .env-Datei lesen, die erst nach dem Start erstellt wurde.
Die erfasste Liste gilt für die Laufzeit des jeweiligen Sandbox-Prozesses, nicht für die gesamte Codex-Sitzung. Wenn du über Codex einen neuen Prozess in der Sandbox startest, werden die Treffer erneut erfasst. Bei einem bereits laufenden Prozess wird die Sperrliste nicht aktualisiert. Verlass dich bei diesem Prozess daher nicht darauf, dass ein Glob-Muster neu erstellte Dateien sperrt. Windows-spezifische Einschränkungen findest du im Abschnitt MXC-Kompatibilität unter Windows.
Glob-Muster mit deny werden als Regeln zum Sperren von Lesezugriffen unterstützt. Glob-Muster mit read oder write sind beim Sandboxing unter Linux, WSL und nativ unter Windows weniger portabel. Verwende daher nach Möglichkeit exakte Pfade oder Regeln für Verzeichnisbäume wie "docs/**" = "read".
Unter Linux, WSL und nativ unter Windows kann es bei einem unbegrenzten **-Muster zum Sperren von Lesezugriffen nötig sein, die Treffer vor dem Start der Sandbox bis zu einer festgelegten Tiefe zu ermitteln. Setze glob_scan_max_depth, wenn du ein unbegrenztes Muster wie "**/*.env" = "deny" verwendest:
[permissions.project-edit.filesystem]
glob_scan_max_depth = 3
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
glob_scan_max_depth muss mindestens 1 sein. Bei höheren Werten durchsucht Codex vor dem Start der Sandbox mehr Verzeichnisebenen. Das kann den Start unter Linux, WSL und nativ unter Windows aufwendiger machen. Wenn du auf diese Suche mit begrenzter Tiefe verzichten möchtest, gib die Ebenen einzeln an, etwa mit *.env, */*.env und */*/*.env.
Füge dem Profil wiederverwendbare Workspace-Stammverzeichnisse hinzu, wenn dieselben Regeln über das Stammverzeichnis der aktuellen Sitzung hinaus gelten sollen:
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true
Wenn dieses Profil aktiv ist, wendet Codex die Regeln unter :workspace_roots auf die zur Laufzeit festgelegten Workspace-Stammverzeichnisse der aktuellen Sitzung und auf jedes aktivierte, im Profil definierte Workspace-Stammverzeichnis an.
Nativ unter Windows werden Pfade mit Laufwerkbuchstaben wie D:\work und UNC-Pfade wie \\server\share als absolute Pfade unterstützt.
Netzwerkberechtigungen
Netzwerkzugriff und Netzwerkfilterung werden getrennt konfiguriert. Setze permissions.<name>.network.enabled = true, damit Befehle auf das Netzwerk zugreifen dürfen. Aktiviere features.network_proxy, damit die Domainregeln des Profils greifen:
[features]
network_proxy = true
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"example.com" = "allow" # exact host
"*.example.com" = "allow" # subdomains only
"**.example.com" = "allow" # apex and subdomains
"ads.example.com" = "deny" # deny wins over allow
Das Verhalten hängt von beiden Einstellungen ab:
- Netzwerk aus: Befehle können unabhängig von der Proxy-Einstellung nicht auf das Netzwerk zugreifen.
- Netzwerk an, Proxy aus: Befehle haben direkten, uneingeschränkten Netzwerkzugriff. Die Domainregeln des Berechtigungsprofils greifen nicht.
- Netzwerk an, Proxy an: Befehle verwenden den Proxy, der die Domainregeln des Profils durchsetzt. Sind für den aktiven Proxy keine Domains freigegeben, blockiert er externe Ziele.
Weder ein Eintrag unter [permissions.<name>.network.domains] noch die Einstellung permissions.<name>.network.enabled = true aktiviert features.network_proxy. Alternativ kann die IT-Administration den Proxy über [experimental_network] in requirements.toml aktivieren. Siehe Verwaltete Konfiguration.
Der aktive Netzwerkproxy der Sandbox lauscht standardmäßig an lokalen Adressen:
[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true
Behalte die Standardwerte für diese Listener bei, sofern du keine bestimmte Laufzeitumgebung anbinden musst. Die Netzwerkschlüssel dangerously_* ermöglichen Ausnahmen für spezielle Umgebungen. Verwende sie nicht für die normale lokale Entwicklung.
Lokale und private Netzwerke
Bei aktivem Netzwerkproxy blockiert Codex standardmäßig den Zugriff auf lokale und private Netzwerkziele. Das schützt vor DNS-Rebinding und unbeabsichtigten Zugriffen auf lokale Dienste. Wenn du ein direkt angegebenes lokales Ziel gezielt freigeben möchtest, trage den exakten Hostnamen oder die IP-Adresse in die Freigabeliste ein:
[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"
Setze allow_local_binding = true nur, wenn das Profil freigegebene Hosts erreichen muss, deren Namen auf lokale oder private Adressen aufgelöst werden:
[permissions.project-edit.network]
enabled = true
allow_local_binding = true
[permissions.project-edit.network.domains]
"localhost" = "allow"
Unix-Sockets
Die Weiterleitung von Unix-Socket-Verbindungen über den Proxy ermöglicht lokalen Tools wie Docker eine Ausnahme von den Zugriffsbeschränkungen. Nutze sie sparsam:
[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"
Mit deny sperrst du einen Socket-Pfad auch dann, wenn eine geerbte Regel ihn freigibt. Gesperrte Socket-Pfade erscheinen nicht in der wirksamen Freigabeliste.
Wenn Unix-Sockets aktiviert sind, binde die Proxy-Listener weiterhin an Loopback-Adressen.
Von älteren Sandbox-Einstellungen migrieren
Berechtigungsprofile ersetzen die ältere Kombination aus sandbox_mode und sandbox_workspace_write, wenn du den Zugriff auf Dateisystem und Netzwerk in einem einzigen wiederverwendbaren Profil festlegen möchtest. Verwende pro Sitzung nur eines der beiden Systeme.
Geeignete Ausgangspunkte:
- Für einen Ablauf ohne Schreibzugriff verwende das integrierte Profil
:read-onlyoder definiere ein eigenes Profil, das Lesezugriffe nur dort erlaubt, wo sie nötig sind. - Für Änderungen im Workspace verwende das integrierte Profil
:workspaceoder definiere ein eigenes Profil, das über:workspace_rootsSchreibzugriffe erlaubt. Gib zusätzlich nur die temporären Verzeichnisse oder Cache-Pfade frei, die du für den Ablauf benötigst. - Verwende
:danger-full-accessfür die uneingeschränkte lokale Ausführung nur, wenn du ausdrücklich den größtmöglichen lokalen Zugriff gewähren möchtest.
Profile legen die standardmäßigen lokalen Zugriffsrechte für eine Sitzung fest. Zentral verwaltete Vorgaben deiner Organisation können den Zugriff weiter einschränken. Die persönliche Konfiguration sollte diese Grenzen nicht erweitern. Weitere Informationen zu zentral durchgesetzten Dateisystem- und Netzwerkbeschränkungen findest du im Abschnitt Verwaltete Konfiguration.
Geltungsbereich und Durchsetzung
Zugriff auf den lokalen Computer mit Work Cloud und Richtlinien für Umgebungen
Prüfe die Richtlinie für jede Umgebung, in der Work Cloud auf den lokalen Computer zugreift:
- Unternehmensvorgaben: Bei Work mit lokalem Zugriff und bei dots gelten für den gemeinsam genutzten Cloud-Orchestrator die unterstützten globalen Richtlinienvorgaben, sofern die verwaltete Richtlinie aktiviert ist. Für den verbundenen Computer gelten die jeweils anwendbaren Vorgaben zur lokalen Ausführung.
- Ausführung in der Cloud: Cloud-Container von Work verwenden die bestehenden Richtlinien von Work Cloud.
- Rangfolge lokaler Richtlinien: MDM-Vorgaben und ältere Vorgaben für verwaltete Geräte haben Vorrang vor Agent Security. Agent Security hat wiederum Vorrang vor der Datei mit den Systemvorgaben des Geräts.
- Vorrang von Richtlinien: Eine höherrangige Richtlinie hat auch dann Vorrang, wenn eine nachrangige Richtlinie spezifischer ist. Innerhalb einer Richtlinie haben umgebungsspezifische Ausnahmen für ein bestimmtes Betriebssystem Vorrang vor solchen für alle Betriebssysteme. Danach gelten die globalen Vorgaben.
Für einige Vorgaben gelten je nach Feld unterschiedliche Regeln für die Zusammenführung. Informationen zu unterstützten Feldern und Einschränkungen der Laufzeitumgebung findest du im Abschnitt Verwaltete Konfiguration und in der Konfigurationsreferenz. Setze nicht voraus, dass Work Cloud die hier gezeigten Codex-Berechtigungsprofile unterstützt.
Berechtigungsprofile begrenzen, was lokal in der Sandbox ausgeführte Befehle tun dürfen. Verwende sie zusammen mit Genehmigungsrichtlinien und den separaten Einstellungen für Websuche, Konnektoren, MCP-Server, den integrierten Browser, Computernutzung und Codex Cloud.
Was Profile steuern
- Lokale Befehlsausführung: Berechtigungsprofile gelten für Befehle, die in der Sandbox auf deinem Computer laufen. Für Konnektoren, MCP-Server, Browserfunktionen und Computernutzung, die Umgebungseinstellungen von Codex Cloud und genehmigte Rechteerweiterungen gelten jeweils eigene Einstellungen.
- Schreibzugriffe auf das Dateisystem: Ein Profil mit Schreibzugriff ermöglicht dauerhafte Änderungen. Behandle Schreibzugriffe auf Skripte, Build-Schritte, Hooks von Paketmanagern, Startdateien der Shell und gemeinsam genutzte Verzeichnisse als sensibel. Andere Tools oder Personen können die betroffenen Dateien später außerhalb der ursprünglichen Sandbox ausführen.
- Ziele ausgehender Verbindungen: Domainregeln begrenzen die Netzwerkziele von Befehlen in der Sandbox nur bei aktivem Netzwerkproxy. Eine Freigabe sagt nichts darüber aus, ob ein Ziel vertrauenswürdig ist. Freigaben mit Platzhaltern gelten für entsprechend viele Ziele.
- Lokale Dienste: Ein aktiver Netzwerkproxy blockiert standardmäßig lokale und private Netzwerkziele. Wenn du
localhost, private IP-Adressen oder Unix-Sockets freigibst oderallow_local_binding = truesetzt, öffnest du ausdrücklich den Zugriff auf lokale Dienste.
Was der Netzwerkproxy nicht steuert
Der Netzwerkproxy filtert nur den Datenverkehr lokaler Befehle, die innerhalb der Sandbox laufen. Für die folgenden Funktionen gilt die Domainfreigabeliste des Profils nicht:
- Websuche: Das gehostete Suchtool verwendet eigene Zugriffseinstellungen. Du steuerst es mit
web_searchund bei verwalteten Clients mitallowed_web_search_modes.tools.web_search.allowed_domainsfiltert die Suchergebnisse und hat keinen Einfluss auf den Netzwerkzugriff von Befehlen. - Apps und Konnektoren: Tools, die Konnektoren verwenden, nutzen eigene dienstseitige Verbindungen, Workspace-Berechtigungen und Einstellungen für die jeweilige App oder das jeweilige Tool.
- MCP-Server: Lokale und entfernte MCP-Server verwenden eigene Prozesse oder Transportverbindungen. Du steuerst sie über die Konfiguration
mcp_serversund verwaltete Freigabelisten für Server. - Browser und Computernutzung: Für die Browsernavigation und Aktionen der Computernutzung gelten eigene Funktions- und Genehmigungseinstellungen.
- Datenverkehr mit Codex-Diensten: Für Modell- und Authentifizierungsanfragen sowie Anfragen an andere Dienste verwendet der Client seine separaten HTTP- und Systemproxy-Einstellungen.
- Codex Cloud: Für diese Aufgaben gelten die Netzwerkeinstellungen der jeweiligen Umgebung. Codex Cloud (Legacy) hat eigene Einstellungen für den Internetzugriff.
Wenn du diese Funktionen einschränken möchtest, konfiguriere jede einzeln. Eine Netzwerkfreigabeliste für Befehle ist keine globale Netzwerkrichtlinie für alle Aktionen, die Codex ausführen kann.
So werden die Regeln durchgesetzt
- Unter macOS verwendet Codex Sandbox-Profile von Seatbelt. Kann die Sandbox der Plattform die ausgewählte Richtlinie nicht durchsetzen, verweigert Codex die Ausführung des Befehls. Der Befehl wird nicht stillschweigend außerhalb der Sandbox ausgeführt.
- Unter Linux und WSL setzt Codex Dateisystembeschränkungen mit bubblewrap und seccomp durch. Die ältere Landlock-Option kann die Unix-Sockets des App Server nicht isolieren. Codex lehnt sie deshalb für Richtlinien mit eingeschränktem Dateisystemzugriff ab. Deaktiviere beim Upgrade
features.use_legacy_landlock. Auf Hosts, die die erforderlichen bubblewrap-Operationen blockieren, lassen sich diese Richtlinien nicht anwenden. - Unter Windows setzt MXC Dateisystem- und Netzwerkberechtigungen durch Prozessisolierung um. Prüfe vor der Aktivierung die MXC-Kompatibilität. Die ältere Ausweichoption
elevatedverwendet eigene Sandbox-Benutzerkonten mit geringeren Rechten, Zugriffsbeschränkungen im Dateisystem und Firewallregeln. Die ältere Ausweichoptionunelevatedbietet eine schwächere Netzwerkisolierung und kann nicht jede Ausnahme mit getrennten Lese- und Schreibrechten durchsetzen. Codex lehnt nicht unterstützte Richtlinien daher ab. Verwende WSL, wenn du das Sandbox-Modell von Linux benötigst.
Hinweise für den Betrieb
Wähle das Profil mit den geringsten Rechten, mit denen sich die Aufgabe noch erledigen lässt. Das ist besonders wichtig, wenn du Schreibzugriff oder ausgehende Netzwerkverbindungen erlaubst. Stimme die Genehmigungsrichtlinie, den Umgang mit Geheimnissen und die Freigaberegeln auf diese Zugriffsrechte ab.
Häufig verwendete Profile
Ohne Schreibzugriff, mit Netzwerkfreigabeliste
default_permissions = "readonly-net"
[features]
network_proxy = true
[permissions.readonly-net.filesystem]
":minimal" = "read"
[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"
[permissions.readonly-net.network]
enabled = true
[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"
Dateizugriff auf den Workspace beschränken
Mit diesem Berechtigungsprofil kann Codex in deine Workspace-Verzeichnisse schreiben. Lesezugriffe auf das übrige Dateisystem sind bis auf die wenigen durch :minimal festgelegten Ausnahmen gesperrt.
default_permissions = "workspace-only"
[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# paths such as .git/, .agents/, .codex/, and .aws/ within a workspace root
# are read-only while the rest of the folder is writable.
extends = ":workspace"
[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"
# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"
# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"
Schreibzugriff im Workspace ohne Netzwerkzugriff
default_permissions = "project-edit"
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
[permissions.project-edit.network]
enabled = false
Schreibzugriff im Workspace mit Zugriff auf das öffentliche Web
default_permissions = "workspace-net"
[features]
network_proxy = true
[permissions.workspace-net.filesystem]
":minimal" = "read"
[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"
[permissions.workspace-net.network]
enabled = true
[permissions.workspace-net.network.domains]
"*" = "allow"
Verwende die globale Freigaberegel "*" nur, wenn du den Zugriff auf öffentliche Netzwerke ausdrücklich erlauben möchtest. Mit Sperrregeln kannst du eine weitreichende Freigabe einschränken.