Deutsch

Berechtigungen

Berechtigungen

Konfigurieren Sie Beta-Berechtigungsprofile von Codex für den Dateisystem- und Netzwerkzugriff

Verwaltetes allowed_permission_profiles ist die Ausnahme: Dadurch verwendet Codex Berechtigungsprofile. Entfernen Sie ältere Einstellungen wie sandbox_mode und [sandbox_workspace_write], bevor Sie eine verwaltete Profil-Zulassungsliste bereitstellen. Für eine unternehmensweite Einführung mit gemischten Versionen können Sie die verwaltete Anforderung allowed_sandbox_modes vorübergehend als Kompatibilitätsbeschränkung beibehalten, bis auf jedem Client Codex 0.138.0 oder höher ausgeführt wird.

Mit Berechtigungsprofilen können Sie Grenzen nach dem Prinzip der minimalen Rechte auf lokale Befehle anwenden, die Codex in Ihrem Auftrag ausführt. Ein Profil ist eine benannte Richtlinie, die Dateisystemregeln, die festlegen, was Befehle lesen oder schreiben dürfen, mit Netzwerkregeln kombiniert, die festlegen, welche Ziele Befehle erreichen dürfen.

Verwenden Sie Profile, um Codex ausreichend Zugriff für den aktuellen Chat zu gewähren, ohne umfassenden Zugriff auf Ihren Computer oder Ihr Netzwerk einzuräumen. Ein schreibgeschütztes Profil kann Codex beispielsweise erlauben, ein Projekt zu untersuchen, ohne es zu bearbeiten, während ein schreibfähiges Profil Änderungen auf ausgewählte Workspace-Stammverzeichnisse beschränken kann.

Lokale Berechtigungsprofile werden unter macOS, Linux, WSL und nativem Windows unterstützt. Plattformspezifische Details und Einschränkungen finden Sie unter Geltungsbereich und Durchsetzung.

Informationen zu den Netzwerkeinstellungen von Codex cloud finden Sie unter Internetzugriff.

Profil definieren und auswählen

Codex umfasst drei integrierte Berechtigungsprofile:

  • :read-only beschränkt die lokale Befehlsausführung auf Lesezugriffe.
  • :workspace erlaubt Schreibzugriffe innerhalb der aktiven Workspace-Stammverzeichnisse und temporären Systemverzeichnisse.
  • :danger-full-access hebt lokale Sandbox-Beschränkungen auf und sollte nur verwendet werden, wenn dieser umfassende Zugriff beabsichtigt ist.

Erstellen Sie unter [permissions.<name>] ein benanntes Profil und legen Sie anschließend den Schlüssel default_permissions auf oberster Ebene auf diesen Profilnamen oder eines der oben genannten integrierten Profile fest. In diesem Beispiel ist project-edit ein benutzerdefinierter Profilname und kein integrierter Wert.

Unternehmensadministratoren können Profile definieren und über verwaltetes requirements.toml einschränken, welche Profile Benutzer auswählen dürfen. Sobald allowed_permission_profiles vorhanden ist, werden nicht aufgeführte Profile verweigert – einschließlich nicht aufgeführter integrierter Profile und Profile, die in zukünftigen Codex-Versionen hinzugefügt werden. Die empfohlene verwaltete Konfiguration finden Sie unter Verfügbare Berechtigungsprofile steuern.

Benutzerdefinierte Profile verwenden zwei zusammengehörige Konzepte:

  • [permissions.<name>.workspace_roots] fügt konkrete Verzeichnisse hinzu, die für dieses Profil als Workspace-Stammverzeichnisse gelten sollen.
  • [permissions.<name>.filesystem.":workspace_roots"] definiert die Dateisystemregeln, die Codex innerhalb jedes effektiven Workspace-Stammverzeichnisses anwendet: die Workspace-Stammverzeichnisse der Laufzeit der aktuellen Sitzung sowie die oben definierten Profil-Stammverzeichnisse.

Profile verwenden außerdem das normale Modell der Konfigurationsebenen. Ebenen mit höherer Priorität können Einträge unter demselben Profilnamen hinzufügen oder ersetzen, ohne das gesamte Profil erneut anzugeben.

Beispielsweise können eine Konfiguration auf Organisationsebene und eine Konfiguration auf Benutzerebene 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, sind beide Workspace-Stammverzeichnisse Bestandteil des effektiven Profils.

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:

  • Liest die minimalen Laufzeitpfade, die gängige Entwicklerwerkzeuge benötigen.
  • Wendet dieselben Regeln für Workspace-Stammverzeichnisse auf die aktuelle Sitzung und die vom Profil definierten Stammverzeichnisse an.
  • Beschränkt IDE-nahe Einstellungen wie .devcontainer/ unter jedem Stammverzeichnis auf Lesezugriffe.
  • Verweigert übereinstimmende Umgebungsdateien mit einer Glob-Regel.
  • Erlaubt Netzwerkzugriff ausschließlich über die konfigurierte Domänenrichtlinie.

Innerhalb eines aktiven Profils bleiben enger gefasste Verweigerungsregeln wirksam, selbst wenn ein weiter gefasster Pfad les- oder schreibbar ist. Ein Profil kann beispielsweise Workspace-Stammverzeichnisse schreibbar machen und zugleich einen übereinstimmenden .env-Pfad auf deny setzen.

Profil erweitern

Verwenden Sie extends, wenn ein Profil weitgehend einem integrierten oder anderen benannten Profil entspricht. Erweitern Sie vorzugsweise ein integriertes Profil, anstatt von Grund auf neu zu beginnen, damit die grundlegenden Schutzmaßnahmen übernommen werden. Wenn Sie beispielsweise :workspace erweitern, bleibt das Verzeichnis .codex des Workspace-Stammverzeichnisses schreibgeschützt, sofern Sie dies nicht ausdrücklich überschreiben. Legen Sie das übergeordnete Profil einmal fest und fügen Sie anschließend nur die abweichenden Regeln hinzu oder überschreiben Sie diese.

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 basiert auf :workspace, verweigert weiterhin übereinstimmende .env-Dateien und erlaubt Anfragen an api.openai.com. Ein Profil kann :read-only, :workspace oder ein anderes benanntes Profil erweitern. Es kann :danger-full-access nicht erweitern; Codex weist außerdem unbekannte übergeordnete Profile und Vererbungszyklen zurück.

Konfigurationsspezifikation

Eintrag Typ / Werte Standard Details
default_permissions Profilname als Zeichenfolge Keiner Benennt das Berechtigungsprofil, das Codex standardmäßig anwendet. Es muss einem Profil unter [permissions] oder einem integrierten Profil wie :workspace entsprechen. Legen Sie es für vorhersehbares Verhalten ausdrücklich fest; verwaltete Anforderungen dürfen es nur auslassen, wenn sowohl :workspace als auch :read-only ausdrücklich erlaubt sind. Codex verwendet ältere Sandbox-Einstellungen, sofern verwaltetes allowed_permission_profiles Codex in dieser Konfiguration nicht zur Verwendung von Berechtigungsprofilen anweist.
[permissions.<name>] Tabelle Keine Definiert ein benanntes Profil. default_permissions wählt ein Profil als Standard aus; andere Einstellungen für Berechtigungsprofile verwenden ebenfalls den Profilnamen.
permissions.<name>.description Zeichenfolge Keine Stellt eine menschenlesbare Beschreibung des Profils bereit. Ein Profil erbt die Beschreibung seines übergeordneten Profils nicht über extends.
permissions.<name>.extends Profilname als Zeichenfolge Keiner Erstellt dieses Profil ausgehend von einem anderen benannten Profil oder dem integrierten Profil :read-only bzw. :workspace. Codex weist :danger-full-access, unbekannte übergeordnete Profile und Vererbungszyklen zurück.
[permissions.<name>.workspace_roots] Tabelle Keine Fügt vom Profil definierte Workspace-Stammverzeichnisse hinzu, die zusätzlich zu den Workspace-Stammverzeichnissen der Laufzeit der aktuellen Sitzung die Dateisystemregeln aus :workspace_roots erhalten.
permissions.<name>.workspace_roots."<path>" Boolescher Wert false Fügt den Pfad zum Satz der Workspace-Stammverzeichnisse des Profils hinzu, wenn true gilt. Auf false gesetzte Einträge bleiben inaktiv.
[permissions.<name>.filesystem] Tabelle Keine Ordnet Dateisystempfade Zugriffswerten oder bereichsbezogenen Unterpfadzuordnungen zu. Fehlende oder leere Dateisystemtabellen halten den Dateisystemzugriff eingeschränkt und geben beim Start eine Warnung aus.
permissions.<name>.filesystem.glob_scan_max_depth Zahl Keine Begrenzt unter Linux, WSL und nativem Windows die Erweiterung von Glob-Mustern zur Leseverweigerung, wenn Codex vor dem Sandbox-Start eine Momentaufnahme der Treffer erstellt. Größere Werte können den Scanaufwand beim Start erhöhen. Verwenden Sie mindestens den Wert 1, wenn ein unbegrenztes **-Muster eine begrenzte Vorab-Erweiterung benötigt.
[permissions.<name>.filesystem]."<path>" read, write oder deny Keiner Gewährt direkten Zugriff auf einen unterstützten Pfad. deny verweigert den Zugriff und hat Vorrang vor ebenso spezifischen write- oder read-Einträgen. Codex weist direkte Schreibregeln zurück, die von der aktiven Laufzeit nicht durchgesetzt werden können.
[permissions.<name>.filesystem."<path>"]."<subpath>" read, write oder deny Keiner Gewährt Zugriff auf einen Nachfahren von <path>. Verwenden Sie . für den Basispfad. Andere Unterpfade müssen relative Nachfahren sein und dürfen keine .- oder ..-Komponenten enthalten.
[permissions.<name>.network] Tabelle Keine Konfiguriert den Netzwerkzugriff von Befehlen und die Richtlinie, die ein aktiver Netzwerk-Proxy durchsetzt. Aktivieren Sie features.network_proxy, sofern nicht von Administratoren verwaltete Netzwerkanforderungen den Proxy starten.
permissions.<name>.network.enabled Boolescher Wert false Aktiviert den Netzwerkzugriff für Befehle im Profil. Dies startet den Netzwerk-Proxy nicht; ohne aktiven Proxy können Befehle ohne Domänenbeschränkungen direkte Verbindungen herstellen.
[permissions.<name>.network.domains] Tabelle Keine Ordnet Hostmuster allow oder deny zu. Regeln gelten nur, wenn der Netzwerk-Proxy aktiv ist. Der aktive Proxy blockiert Domänenanfragen, wenn keine allow-Einträge vorhanden sind, und Verweigerungseinträge setzen sich gegenüber Zulassungseinträgen durch.
permissions.<name>.network.domains."<pattern>" allow oder deny Keiner Unterstützt exakte Hosts, *.example.com für Subdomänen, **.example.com für die Apex-Domäne und Subdomänen sowie * als globales Platzhalterzeichen ausschließlich für Zulassungen. Hostmuster werden normalisiert, indem Leerraum entfernt, Kleinschreibung angewendet, ein abschließender Punkt entfernt und einfache Ports oder Klammern entfernt werden.
[permissions.<name>.network.unix_sockets] Tabelle Keine Ordnet Überschreibungen der Zulassungsliste für Unix-Sockets zu. Verwenden Sie dies nur für lokale Integrationen wie Docker.
permissions.<name>.network.unix_sockets."<path>" allow oder deny Keiner Fügt mit allow einen absoluten Unix-Socket-Pfad zur effektiven Zulassungsliste hinzu oder weist ihn mit deny zurück. Verweigerte Einträge werden aus der effektiven Zulassungsliste ausgelassen.
permissions.<name>.network.proxy_url URL-Zeichenfolge http://127.0.0.1:3128 HTTP-Proxy-Listener, der für HTTP_PROXY, HTTPS_PROXY, WebSocket-Proxy-Variablen und zugehörige Proxy-Umgebungsvariablen von Werkzeugen verwendet wird.
permissions.<name>.network.enable_socks5 Boolescher Wert true Aktiviert den für ALL_PROXY und FTP-Proxy-Variablen verwendeten SOCKS5-Listener.
permissions.<name>.network.socks_url URL-Zeichenfolge http://127.0.0.1:8081 Adresse des SOCKS5-Listeners.
permissions.<name>.network.enable_socks5_udp Boolescher Wert true Aktiviert SOCKS5-UDP-Unterstützung, wenn der SOCKS5-Listener aktiviert ist.
permissions.<name>.network.allow_upstream_proxy Boolescher Wert true Ermöglicht dem Netzwerk-Sandbox-Proxy, vorgelagerte Einstellungen für HTTP(S)_PROXY und ALL_PROXY bei ausgehenden Anfragen zu berücksichtigen.
permissions.<name>.network.allow_local_binding Boolescher Wert false Deaktiviert den Schutz für lokale/private Netzwerke, wenn true gilt. Wenn false gilt, müssen exakte lokale Literale wie localhost oder 127.0.0.1 ausdrücklich zugelassen werden; Hostnamen, die in lokale oder private IPs aufgelöst werden, bleiben blockiert.
permissions.<name>.network.dangerously_allow_non_loopback_proxy Boolescher Wert false Ermöglicht Proxy-Listenern die Bindung an Nicht-Loopback-Adressen. Lassen Sie dies für die gewöhnliche lokale Entwicklung ungesetzt.
permissions.<name>.network.dangerously_allow_all_unix_sockets Boolescher Wert false Umgeht die Zulassungsliste für Unix-Sockets, sofern Unix-Socket-Proxying unterstützt wird. Dies ist ein weitreichendes lokales Schlupfloch.

Dateisystemberechtigungen

Dateisystemeinträge verwenden read, write oder deny:

Zugriff Bedeutung
read Erlaubt Befehlen, Dateien zu lesen und Verzeichnisse unter dem Pfad aufzulisten. Befehle können dort keine Dateien erstellen, ändern, umbenennen oder löschen.
write Erlaubt Befehlen, Dateien unter dem Pfad zu lesen und zu ändern, einschließlich des Erstellens, Umbenennens und Löschens von Dateien, sofern das Betriebssystem dies zulässt.
deny Verweigert sowohl Lese- als auch Schreibzugriffe unter dem Pfad. Verwenden Sie dies, um einen verweigerten Unterpfad aus einer weiter gefassten read- oder write-Berechtigung auszunehmen.

Spezifischere Einträge überschreiben weiter gefasste Einträge. Wenn zwei Einträge auf denselben Pfad abzielen, hat deny Vorrang vor write und write hat Vorrang vor read.

Dank dieser Rangfolge kann ein Profil zunächst einen weit gefassten Arbeitsbereich beschreiben und anschließend Dateien oder Verzeichnisse ausnehmen, die unlesbar bleiben 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 schreibbar, .devcontainer/ bleibt lesbar, ohne schreibbar zu werden, und übereinstimmende Umgebungsdateien bleiben für Sandbox-Befehle unzugänglich.

Ein spezifischerer Pfad kann außerdem einen engeren Teilbaum innerhalb einer weiter gefassten Verweigerung wieder öffnen:

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Unterstützte Pfadformen:

Pfad Bedeutung Bereichsbezogene Unterpfade
:root Das Dateisystem-Stammverzeichnis Nur .
:minimal Plattform- und Laufzeitpfade, die von gängigen Werkzeugen benötigt werden Nur .
:workspace_roots Die Workspace-Stammverzeichnisse der aktuellen Sitzung sowie alle aktivierten, vom Profil definierten Workspace-Stammverzeichnisse Ja
:tmpdir Der Speicherort $TMPDIR, sofern verfügbar Nur .
:slash_tmp Der Ordner /tmp, sofern vorhanden Nur .
/absolute/path Ein absoluter Plattformpfad, etwa /path unter macOS/Linux/WSL oder C:\path unter nativem Windows Ja
~/path Ein Pfad unter dem Home-Verzeichnis des aktuellen Benutzers Ja

Unter nativem Windows können Home-relative Pfade auch umgekehrte Schrägstriche verwenden, beispielsweise ~\work.

Verwenden Sie :root nur, wenn ein Profil bewusst eine umfassende Leseabdeckung benötigt:

[permissions.audit.filesystem]
":root" = "read"

Verwenden Sie verschachtelte Einträge unter :workspace_roots, um den Zugriff auf relative Unterpfade des Workspace-Stammverzeichnisses zu begrenzen:

[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 verbleiben. Übergeordnete Traversierung wie ../other-repo wird zurückgewiesen.

Lesezugriffe mit exakten Pfaden oder Globs verweigern

Verwenden Sie deny für Dateien oder Teilbäume, die Codex nicht lesen soll, selbst wenn eine weiter gefasste Profilregel den Zugriff in der Nähe gewährt. Exakte Pfade eignen sich gut für stabile Speicherorte wie ~/.ssh. Glob-Muster eignen sich besser, wenn ein Profil eine Gruppe vertraulicher Dateien abdecken muss, deren genaue Speicherorte sich je nach Repository unterscheiden.

Wenn sich ein Glob unter :workspace_roots befindet, interpretiert Codex ihn relativ zu jedem effektiven Workspace-Stammverzeichnis. Beispiel:

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Diese Regel verweigert Lesezugriffe auf übereinstimmende .env-Dateien, die unter jedem Laufzeit- oder vom Profil definierten Workspace-Stammverzeichnis gefunden werden. Verwenden Sie sie, wenn Sie normale Workspace-Schreibzugriffe beibehalten und zugleich Umgebungsdateien, generierte Geheimnisse oder ähnliche Dateien mit Zugangsdaten unlesbar halten möchten.

deny-Glob-Muster werden als Regeln zur Leseverweigerung unterstützt. read- oder write-Globs sind bei der Sandbox-Ausführung unter Linux, WSL und nativem Windows weniger portabel. Bevorzugen Sie daher nach Möglichkeit exakte Pfade oder Teilbaumregeln wie "docs/**" = "read".

Unter Linux, WSL und nativem Windows kann ein unbegrenztes **-Muster zur Leseverweigerung vor dem Sandbox-Start eine begrenzte Vorab-Erweiterung benötigen. Legen Sie glob_scan_max_depth fest, wenn Sie ein unbegrenztes Muster wie "**/*.env" = "deny" verwenden:

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth muss mindestens 1 betragen. Höhere Werte scannen vor dem Sandbox-Start tiefer, was unter Linux, WSL und nativem Windows zusätzlichen Startaufwand verursachen kann. Wenn Sie keine begrenzte Erweiterung verwenden möchten, geben Sie explizite Tiefen wie *.env, */*.env und */*/*.env an.

Fügen Sie dem Profil wiederverwendbare Workspace-Stammverzeichnisse hinzu, wenn dieselben Regeln für mehr als das Stammverzeichnis der aktuellen Sitzung gelten sollen:

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

Wenn dieses Profil aktiv ist, wendet Codex die Regeln aus :workspace_roots auf die Workspace-Stammverzeichnisse der Laufzeit der aktuellen Sitzung sowie auf jedes aktivierte, vom Profil definierte Workspace-Stammverzeichnis an.

Unter nativem Windows werden Laufwerkbuchstabenpfade wie D:\work und UNC-Pfade wie \\server\share als absolute Pfade unterstützt.

Netzwerkberechtigungen

Netzwerkzugriff und Netzwerkfilterung sind separate Einstellungen. Legen Sie permissions.<name>.network.enabled = true fest, um Befehlen den Netzwerkzugriff zu ermöglichen, und aktivieren Sie features.network_proxy, um die Domänenregeln des Profils durchzusetzen:

[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 resultierende Verhalten hängt von beiden Einstellungen ab:

  • Netzwerk aus: Befehle können unabhängig von der Proxy-Funktion nicht auf das Netzwerk zugreifen.
  • Netzwerk ein, Proxy aus: Befehle haben direkten, uneingeschränkten Netzwerkzugriff. Domänenregeln im Berechtigungsprofil werden nicht durchgesetzt.
  • Netzwerk ein, Proxy ein: Befehle verwenden den Proxy, der die Domänenregeln des Profils durchsetzt. Wenn der aktive Proxy keine zulässigen Domänen enthält, blockiert er externe Ziele.

Das Hinzufügen von [permissions.<name>.network.domains] oder das Festlegen von permissions.<name>.network.enabled = true aktiviert features.network_proxy nicht. Alternativ können Administratoren den Proxy mit [experimental_network] in requirements.toml aktivieren. Siehe Verwaltete Konfiguration.

Wenn der Netzwerk-Sandbox-Proxy aktiv ist, bindet er sich standardmäßig an lokale Listener:

[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

Belassen Sie diese Listener-Einstellungen auf ihren Standardwerten, sofern Sie keine Integration mit einer bestimmten Laufzeit vornehmen. Die Netzwerkschlüssel unter dangerously_* sind Schlupflöcher für spezialisierte Umgebungen und sollten nicht für die gewöhnliche lokale Entwicklung verwendet werden.

Lokale und private Netzwerke

Wenn der Netzwerk-Proxy aktiv ist, wendet Codex standardmäßig einen Schutz für lokale/private Netzwerke an, um DNS-Rebinding und versehentliche Zugriffe auf lokale Dienste abzuwehren. Um ein lokales Literalziel bewusst zuzulassen, nehmen Sie den exakten Host oder das exakte IP-Literal in die Zulassungsliste auf:

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

Legen Sie allow_local_binding = true nur fest, wenn das Profil auf zugelassene Hostnamen zugreifen muss, die in 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

Unix-Socket-Proxying ist ein lokales Schlupfloch für Werkzeuge wie Docker. Verwenden Sie es sparsam:

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Verwenden Sie deny, um einen Socket-Pfad einschließlich eines geerbten Zulassungseintrags zurückzuweisen. Verweigerte Socket-Pfade werden aus der effektiven Zulassungsliste ausgelassen.

Wenn Unix-Sockets aktiviert sind, binden Sie Proxy-Listener weiterhin an Loopback-Adressen.

Von älteren Sandbox-Einstellungen migrieren

Berechtigungsprofile ersetzen die ältere Kombination aus sandbox_mode und sandbox_workspace_write, wenn Sie Dateisystem- und Netzwerkverhalten in einem wiederverwendbaren Profil beschreiben möchten. Verwenden Sie für eine Sitzung entweder das eine oder das andere System, nicht beide.

Empfohlene Ausgangspunkte:

  • Verwenden Sie für einen schreibgeschützten Workflow das integrierte Profil :read-only oder definieren Sie ein benutzerdefiniertes Profil mit Lesezugriff nur dort, wo er benötigt wird.
  • Verwenden Sie zum Bearbeiten des Workspace das integrierte Profil :workspace oder definieren Sie ein benutzerdefiniertes Profil, das über :workspace_roots schreibt und nur die zusätzlichen temporären oder Cache-Pfade hinzufügt, die der Workflow benötigt.
  • Verwenden Sie für die uneingeschränkte lokale Ausführung :danger-full-access nur, wenn Sie bewusst das umfassendste lokale Zugriffsmodell wünschen.

Profile beschreiben die lokale Standardhaltung einer Sitzung. Von der Organisation verwaltete Anforderungen können weiterhin Einschränkungen hinzufügen, die durch die Benutzerkonfiguration nicht gelockert werden dürfen. Informationen zu durch Administratoren erzwungenen Dateisystem- und Netzwerkbeschränkungen finden Sie unter Verwaltete Konfiguration.

Geltungsbereich und Durchsetzung

Berechtigungsprofile definieren die Grenzen für die lokale Befehlsausführung in der Sandbox. Verwenden Sie sie zusammen mit Genehmigungsrichtlinien und den separaten Steuerelementen für Websuche, Connectors, MCP-Server, den integrierten Browser, Computer Use und Codex cloud.

Was Profile steuern

  • Lokale Befehlsausführung: Berechtigungsprofile steuern Sandbox-Befehle, die auf Ihrem Computer ausgeführt werden. Connectors, MCP-Server, Browser- oder Computer-Use-Oberflächen, Umgebungseinstellungen von Codex cloud und genehmigte Rechteausweitungen verwenden eigene Steuerelemente.
  • Dateisystem-Schreibzugriffe: Ein schreibfähiges Profil kann dauerhafte Änderungen erstellen. Behandeln Sie Schreibzugriffe auf Skripte, Build-Schritte, Paketmanager-Hooks, Shell-Startdateien und gemeinsam genutzte Verzeichnisse als vertraulich, da spätere Werkzeuge oder Benutzer diese Dateien außerhalb des ursprünglichen Sandbox-Kontexts ausführen können.
  • Ausgehende Ziele: Netzwerk-Domänenregeln begrenzen nur bei aktivem Netzwerk-Proxy, wohin der Befehlsverkehr aus der Sandbox gesendet werden kann. Sie bestimmen nicht, ob ein zulässiges Ziel vertrauenswürdig ist, und Platzhalter-Zulassungsregeln bleiben weit gefasst.
  • Lokale Dienste: Ein aktiver Netzwerk-Proxy blockiert standardmäßig Ziele in lokalen und privaten Netzwerken. Die Zulassung von localhost, privaten IPs oder Unix-Sockets bzw. das Festlegen von allow_local_binding = true öffnet ausdrücklich den Zugriff auf lokale Dienste.

Was der Netzwerk-Proxy nicht steuert

Der Netzwerk-Proxy filtert nur Datenverkehr von lokalen Befehlen, die innerhalb der Sandbox ausgeführt werden. Er wendet die Domänen-Zulassungsliste des Profils nicht auf Folgendes an:

  • Websuche: Das gehostete Suchwerkzeug verwendet eigene Zugriffseinstellungen. Verwenden Sie web_search und bei verwalteten Clients allowed_web_search_modes, um es zu steuern. tools.web_search.allowed_domains filtert Suchergebnisse, nicht den Netzwerkzugriff von Befehlen.
  • Apps und Connectors: Connector-gestützte Werkzeuge verwenden eigene serverseitige Verbindungen, Workspace-Berechtigungen sowie App- oder Werkzeugeinstellungen.
  • MCP-Server: Lokale und entfernte MCP-Server verwenden eigene Prozesse oder Transportmechanismen. Steuern Sie sie mit der Konfiguration mcp_servers und verwalteten Server- Zulassungslisten.
  • Browser und Computer Use: Browsernavigation und Computer-Use-Aktionen verwenden eigene Funktions- und Genehmigungssteuerelemente.
  • Codex-Dienstdatenverkehr: Modell-, Authentifizierungs- und andere Client-Dienstanfragen verwenden die separaten HTTP- und System-Proxy-Einstellungen des Clients.
  • Codex cloud: Diese Aufgaben verwenden die eigenen Internetzugriffseinstellungen ihrer Umgebung.

Um diese Oberflächen einzuschränken, konfigurieren Sie jede Funktion direkt. Eine Netzwerk- Zulassungsliste für Befehle ist keine globale Netzwerkrichtlinie für jede Aktion, die Codex ausführen kann.

Funktionsweise der Durchsetzung

  • Unter macOS verwendet Codex Seatbelt-Sandbox-Profile. Wenn die ausgewählte Richtlinie von der Plattform-Sandbox nicht durchgesetzt werden kann, verweigert Codex die Ausführung des Befehls, anstatt ihn stillschweigend ohne Sandbox auszuführen.
  • Unter Linux und WSL verwendet Codex bubblewrap und seccomp, wobei Landlock für Kompatibilitäts-Fallbackpfade verfügbar ist. Der stärkste Durchsetzungspfad hängt von Benutzer-Namespaces und der Kernel-Unterstützung ab; eingeschränkte Container-Hosts können Kompatibilitätspfade erzwingen, und nicht unterstützte geteilte Richtlinien werden abgelehnt.
  • Unter nativem Windows ist die Sandbox-Ausführung mit elevated am stärksten, da sie dedizierte Sandbox-Benutzer mit niedrigeren Berechtigungen, Dateisystem-Berechtigungsgrenzen und Firewall-Regeln verwenden kann. Die Sandbox-Ausführung mit unelevated ist ein Fallback mit schwächerer Netzwerkisolation und kann nicht jede Aufteilung von Lese-/Schreibzugriffen durchsetzen; daher werden nicht unterstützte Richtlinien abgelehnt. Verwenden Sie WSL, wenn Sie das Linux-Sandbox-Modell benötigen.

Betriebshinweise

Wählen Sie das engste Profil, mit dem die Aufgabe noch abgeschlossen werden kann, insbesondere wenn Sie Schreibzugriffe oder ausgehenden Netzwerkzugriff gewähren. Stimmen Sie Genehmigungsrichtlinie, Umgang mit Geheimnissen und Zulassungsregeln auf diese Zugriffsebene ab.

Häufig verwendete Profile

Schreibgeschützt mit Netzwerk-Zulassungsliste

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änkt

Hier sehen Sie ein Beispiel für ein Berechtigungsprofil, das Ihre Workspace-Ordner für Codex schreibbar macht und zugleich Lesezugriffe auf den Rest des Dateisystems verweigert (mit begrenzten Ausnahmen, die durch :minimal bestimmt werden).

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ 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"

Workspace-Schreibzugriff ohne Netzwerk

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

Workspace-Schreibzugriff 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"

Verwenden Sie die globale Zulassungsregel "*" nur, wenn Sie öffentlichen Netzwerkzugriff zulassen möchten. Verweigerungsregeln können eine weit gefasste Zulassungsliste einschränken.