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

Berechtigungen

Konfiguriere die Berechtigungsprofile von Codex für den Zugriff auf Dateisystem und Netzwerk (Beta)

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-only führt lokale Befehle ohne Schreibzugriff aus.
  • :workspace erlaubt Schreibzugriffe innerhalb der aktiven Workspace-Stammverzeichnisse und in den temporären Verzeichnissen des Systems.
  • :danger-full-access hebt 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-only oder definiere ein eigenes Profil, das Lesezugriffe nur dort erlaubt, wo sie nötig sind.
  • Für Änderungen im Workspace verwende das integrierte Profil :workspace oder definiere ein eigenes Profil, das über :workspace_roots Schreibzugriffe erlaubt. Gib zusätzlich nur die temporären Verzeichnisse oder Cache-Pfade frei, die du für den Ablauf benötigst.
  • Verwende :danger-full-access fü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 oder allow_local_binding = true setzt, ö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_search und bei verwalteten Clients mit allowed_web_search_modes. tools.web_search.allowed_domains filtert 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_servers und 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 elevated verwendet eigene Sandbox-Benutzerkonten mit geringeren Rechten, Zugriffsbeschränkungen im Dateisystem und Firewallregeln. Die ältere Ausweichoption unelevated bietet 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.