Berechtigungen

Mit Berechtigungsprofilen können Sie Grenzen nach dem Prinzip der geringsten 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 können, mit Netzwerkregeln kombiniert, die festlegen, welche Ziele Befehle erreichen können.

Verwenden Sie Profile, um Codex ausreichend Zugriff für den aktuellen Chat zu gewähren, ohne einen umfassenden Zugriff auf Ihren Computer oder Ihr Netzwerk einzuräumen. Beispielsweise kann ein schreibgeschütztes Profil Codex ein Projekt untersuchen lassen, ohne es zu bearbeiten, während ein Profil mit Schreibrechten Ä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 Cloud-Netzwerkeinstellungen von Codex finden Sie unter Internetzugriff.

Profil definieren und auswählen

Codex enthält 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 weitreichende Zugriff beabsichtigt ist.

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

Unternehmensadministratoren können Profile definieren und über das verwaltete requirements.toml einschränken, welche Profile Benutzer auswählen dürfen. Sobald allowed_permission_profiles vorhanden ist, werden nicht aufgeführte Profile abgelehnt, einschließlich ausgelassener 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 miteinander verbundene 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 aktuellen Laufzeitsitzung sowie die oben definierten Stammverzeichnisse des Profils.

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"

[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:

• Erlaubt Lesezugriff auf die minimalen Laufzeitpfade, die gängige Entwicklertools benötigen.
• Wendet dieselben Regeln für Workspace-Stammverzeichnisse auf die aktuelle Sitzung und die im Profil definierten Stammverzeichnisse an.
• Beschränkt IDE-nahe Einstellungen wie .devcontainer/ unter jedem Stammverzeichnis auf Lesezugriffe.
• Verweigert den Zugriff auf passende Umgebungsdateien mithilfe einer Glob-Regel.
• Erlaubt Netzwerkzugriff ausschließlich über die konfigurierte Domainrichtlinie.

Innerhalb eines aktiven Profils bleiben spezifischere Verweigerungsregeln wirksam, selbst wenn ein allgemeinerer Pfad lesbar oder beschreibbar ist. Beispielsweise kann ein Profil Schreibzugriffe auf Workspace-Stammverzeichnisse erlauben und gleichzeitig einen passenden .env-Pfad auf deny setzen.

Profil erweitern

Verwenden Sie extends, wenn ein Profil weitgehend einem integrierten oder einem anderen benannten Profil entspricht. Erweitern Sie vorzugsweise ein integriertes Profil, statt 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 dann nur die abweichenden Regeln hinzu oder überschreiben Sie diese.

default_permissions = "project-edit"

[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 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. Es kann nicht :danger-full-access erweitern; Codex weist außerdem unbekannte übergeordnete Profile und Vererbungszyklen zurück.

Konfigurationsspezifikation

Dateisystemberechtigungen

Dateisystemeinträge verwenden read, write oder deny:

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

Mit dieser Rangfolge kann ein Profil zunächst einen umfassenden Arbeitsbereich beschreiben und anschließend Dateien oder Verzeichnisse ausnehmen, die nicht lesbar bleiben sollen:

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

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

In diesem Beispiel bleibt der Stamm des Workspace beschreibbar, .devcontainer/ bleibt lesbar, ohne beschreibbar zu werden, und entsprechende Umgebungsdateien bleiben für Sandbox-Befehle nicht verfügbar.

Ein spezifischerer Pfad kann außerdem einen engeren Unterbaum innerhalb einer umfassenderen Verweigerung wieder freigeben:

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

Unterstützte Pfadformen:

Unter nativem Windows können auf das Home-Verzeichnis bezogene Pfade auch umgekehrte Schrägstriche verwenden, zum Beispiel ~\work.

Verwenden Sie :root nur, wenn ein Profil absichtlich umfassenden Lesezugriff benötigt:

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

Verwenden Sie verschachtelte Einträge unter :workspace_roots, um den Zugriff auf Unterpfade relativ zum Workspace-Stammverzeichnis 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 bleiben. Das Durchlaufen übergeordneter Verzeichnisse wie ../other-repo wird abgelehnt.

Lesezugriffe mit exakten Pfaden oder Globs verweigern

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

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 entsprechende .env-Dateien, die unter jedem zur Laufzeit oder im Profil definierten Workspace-Stammverzeichnis gefunden werden. Verwenden Sie sie, wenn Sie normale Schreibzugriffe im Workspace beibehalten und gleichzeitig Umgebungsdateien, generierte Geheimnisse oder ähnliche Dateien mit Zugangsdaten unlesbar halten möchten.

deny-Glob-Muster werden als Regeln zum Verweigern von Lesezugriffen unterstützt. read- oder write-Globs sind beim Sandboxing unter Linux, WSL und nativem Windows weniger portabel. Bevorzugen Sie daher nach Möglichkeit exakte Pfade oder Unterbaumregeln wie "docs/**" = "read".

Unter Linux, WSL und nativem Windows muss ein unbegrenztes **-Muster zum Verweigern von Lesezugriffen möglicherweise vor dem Start der Sandbox begrenzt vorab expandiert werden. 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 durchsuchen vor dem Start der Sandbox tiefere Ebenen, was unter Linux, WSL und nativem Windows zusätzlichen Startaufwand verursachen kann. Wenn Sie keine begrenzte Expansion 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 :workspace_roots-Regeln auf die Workspace-Stammverzeichnisse der aktuellen Sitzung sowie auf jedes aktivierte, im Profil definierte Workspace-Stammverzeichnis an.

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

Netzwerkberechtigungen

Legen Sie enabled = true fest, um den Netzwerkzugriff für das ausgewählte Profil zuzulassen:

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

Wenn der Netzwerkzugriff aktiviert ist, verwendet Codex standardmäßig vollständige Netzwerkfunktionen. Die meisten Profile sollten außerdem Domänenregeln definieren:

[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

Der Proxy der Netzwerk-Sandbox bindet 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 nicht eine bestimmte Laufzeit integrieren. Die dangerously_*-Netzwerkschlüssel sind Ausweichmöglichkeiten für spezialisierte Umgebungen und sollten nicht für die gewöhnliche lokale Entwicklung verwendet werden.

Lokale und private Netzwerke

Codex wendet standardmäßig eine Schutzmaßnahme für lokale/private Netzwerke an, um DNS-Rebinding und unbeabsichtigten Zugriff auf lokale Dienste abzuwehren. Um ein wörtlich angegebenes lokales Ziel absichtlich zuzulassen, nehmen Sie den exakten Host oder die IP-Adresse 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

Das Proxying von Unix-Sockets ist eine lokale Ausweichmöglichkeit für Tools 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 abzulehnen, einschließlich eines geerbten Zulassungseintrags. Verweigerte Socket-Pfade werden aus der effektiven Zulassungsliste entfernt.

Wenn Unix-Sockets aktiviert sind, müssen Proxy-Listener weiterhin an Loopback-Adressen gebunden bleiben.

Von älteren Sandbox-Einstellungen migrieren

Berechtigungsprofile ersetzen die ältere Kombination aus sandbox_mode und sandbox_workspace_write, wenn Sie mit einem einzigen wiederverwendbaren Profil sowohl das Dateisystem- als auch das Netzwerkverhalten 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 uneingeschränkte lokale Ausführung :danger-full-access nur, wenn Sie absichtlich das umfassendste lokale Zugriffsmodell wünschen.

Profile beschreiben die lokale Standard-Sicherheitskonfiguration einer Sitzung. Von der Organisation verwaltete Anforderungen können weiterhin Einschränkungen hinzufügen, die durch die Benutzerkonfiguration nicht erweitert werden dürfen. Unter Verwaltete Konfiguration finden Sie vom Administrator erzwungene Dateisystem- und Netzwerkbeschränkungen.

Geltungsbereich und Durchsetzung

Berechtigungsprofile legen die Grenzen für die lokale Ausführung von Befehlen in der Sandbox fest. Verwenden Sie sie zusammen mit Genehmigungsrichtlinien und den separaten Steuerungsmöglichkeiten für Konnektoren, MCP-Server, den integrierten Browser, Computer Use und die Codex-Cloud.

Was Profile steuern

• Lokale Befehlsausführung: Berechtigungsprofile steuern Sandbox-Befehle, die auf Ihrem Computer ausgeführt werden. Konnektoren, MCP-Server, Browser- oder Computer-Use-Oberflächen, Umgebungseinstellungen der Codex-Cloud und genehmigte Rechteerweiterungen verwenden eigene Steuerungsmöglichkeiten.
• Schreibzugriffe auf das Dateisystem: Ein schreibfähiges Profil kann dauerhafte Änderungen erzeugen. Behandeln Sie Schreibzugriffe auf Skripte, Build-Schritte, Hooks von Paketmanagern, Shell-Startdateien und gemeinsam genutzte Verzeichnisse als vertraulich, da spätere Tools oder Benutzer diese Dateien außerhalb des ursprünglichen Sandbox-Kontexts ausführen können.
• Ausgehende Ziele: Netzwerk-Domänenregeln beschränken, wohin der Datenverkehr von Sandbox-Befehlen über den Netzwerk-Proxy gesendet werden kann. Sie bestimmen nicht, ob ein zugelassenes Ziel vertrauenswürdig ist, und Platzhalter-Zulassungsregeln bleiben umfassend.
• Lokale Dienste: Lokale und private Netzwerkziele sind standardmäßig blockiert. Wenn Sie localhost, private IP-Adressen oder Unix-Sockets in die Zulassungsliste aufnehmen oder allow_local_binding = true festlegen, öffnen Sie ausdrücklich den Zugriff auf lokale Dienste.

Funktionsweise der Durchsetzung

• Unter macOS verwendet Codex Seatbelt-Sandbox-Profile. Wenn die ausgewählte Richtlinie nicht durch die Plattform-Sandbox durchgesetzt werden kann, verweigert Codex die Ausführung des Befehls, anstatt ihn unbemerkt ohne Sandbox auszuführen.
• Unter Linux und WSL verwendet Codex bubblewrap und seccomp, wobei Landlock für Kompatibilitäts-Fallback-Pfade verfügbar ist. Der stärkste Durchsetzungsmechanismus hängt von Benutzer-Namespaces und der Kernel-Unterstützung ab. Eingeschränkte Container-Hosts können Kompatibilitätsmechanismen erzwingen und nicht unterstützte geteilte Richtlinien werden abgelehnt.
• Unter nativem Windows ist das elevated-Sandboxing am stärksten, da es dedizierte Sandbox-Benutzer mit geringeren Berechtigungen, Dateisystem-Berechtigungsgrenzen und Firewall-Regeln verwenden kann. Das unelevated-Sandboxing ist ein Fallback mit schwächerer Netzwerkisolation und kann nicht jede getrennte Lese-/Schreibausnahme 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 sich die Aufgabe noch abschließen lässt, insbesondere wenn Sie Schreibzugriffe oder ausgehenden Netzwerkzugriff gewähren. Stimmen Sie Genehmigungsrichtlinie, Umgang mit Geheimnissen und Zulassungsregeln auf diese Zugriffsebene ab.

Gängige Profile

Schreibgeschützt mit Netzwerk-Zulassungsliste

default_permissions = "readonly-net"

[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, mit dem Ihre Workspace-Ordner für Codex beschreibbar werden, während Lesezugriffe auf den Rest des Dateisystems verweigert werden (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"

Schreibzugriff auf den Workspace 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

Schreibzugriff auf den Workspace mit öffentlichem Webzugriff

default_permissions = "workspace-net"

[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 umfassende Zulassungsliste einschränken.