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-onlybeschränkt die lokale Befehlsausführung auf Lesezugriffe.:workspaceerlaubt Schreibzugriffe innerhalb der aktiven Workspace-Stammverzeichnisse und temporären Systemverzeichnisse.:danger-full-accesshebt 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" = trueWenn 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 directoryVerschachtelte 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" = trueWenn 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 allowDas 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 = trueBelassen 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-onlyoder definieren Sie ein benutzerdefiniertes Profil mit Lesezugriff nur dort, wo er benötigt wird. - Verwenden Sie zum Bearbeiten des Workspace das integrierte Profil
:workspaceoder definieren Sie ein benutzerdefiniertes Profil, das über:workspace_rootsschreibt 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-accessnur, 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 vonallow_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_searchund bei verwalteten Clientsallowed_web_search_modes, um es zu steuern.tools.web_search.allowed_domainsfiltert 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_serversund 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
elevatedam stärksten, da sie dedizierte Sandbox-Benutzer mit niedrigeren Berechtigungen, Dateisystem-Berechtigungsgrenzen und Firewall-Regeln verwenden kann. Die Sandbox-Ausführung mitunelevatedist 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 = falseWorkspace-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.