Codex-Berechtigungsprofile sind benannte Richtlinien in config.toml, die festlegen, welche Befehle, die Codex auf deiner Maschine ausführt, lesen, schreiben und im Netzwerk erreichen dürfen. Du wählst eines mit default_permissions aus, beginnst mit einem integrierten Profil (:read-only, :workspace oder :danger-full-access) und ergänzt dann Pfade für read, write und deny sowie eine Domain-Allowlist.
Dieser Leitfaden bietet direkt kopierbare config.toml-Beispiele für die gängigsten Setups, darunter eines für API-Arbeit, mit dem dein Coding-Agent Apidog-CLI-Tests gegen deine eigenen API-Hosts ausführen kann, ohne offenes Internet.
Was sind Codex-Berechtigungsprofile?
Ein Berechtigungsprofil ist eine wiederverwendbare Sandbox-Richtlinie für Codex. Es kombiniert Dateisystemregeln (welche Pfade Befehle lesen, schreiben oder niemals berühren dürfen) mit Netzwerkregeln (ob Befehle das Netzwerk erreichen dürfen und welche Domains). Codex setzt sie mit Seatbelt unter macOS, bubblewrap plus seccomp unter Linux und WSL sowie MXC unter Windows durch.
OpenAI hat das Design in Inside the Codex-Sandbox erklärt, veröffentlicht am 18. November 2026. Statt deine Arbeit in einen Container zu verlagern, beschränkt Codex Befehle in deiner bestehenden Umgebung, sodass native Toolchains weiterhin laufen.
Codex bringt drei integrierte Profile mit:
| Profil | Dateisystem | Netzwerk |
|---|---|---|
:read-only |
Befehle können lesen, aber nicht schreiben | Aus |
:workspace |
Schreibzugriff in Workspace-Wurzeln und temporären Verzeichnissen; .git, .agents, .codex, .aws bleiben schreibgeschützt |
Aus |
:danger-full-access |
Keine lokalen Sandbox-Beschränkungen | Vollständig, direkt |
Die Berechtigungsdokumentation stuft das Feature weiterhin als Beta ein, daher können sich Schlüssel zwischen Releases ändern.
Wohin die Berechtigungstabelle in config.toml gehört
Deine Profile liegen in ~/.codex/config.toml (oder in einer Projekt- oder Systemebene). Zwei Elemente auf oberster Ebene sind entscheidend:
default_permissionsbenennt das Profil, das Codex standardmäßig anwendet. Es muss einem integrierten Profil oder einem Profil unter[permissions]entsprechen.[permissions.<name>]definiert ein Profil. Gib ihm einedescription; sie erscheint in der/permissions-Auswahl.
Eine Regel bringt viele ins Stolpern. Berechtigungsprofile lassen sich nicht mit den älteren Sandbox-Einstellungen kombinieren. Wenn sandbox_mode in einer geladenen Konfigurationsdatei vorkommt oder du --sandbox übergibst, verwendet Codex die alten Einstellungen und ignoriert default_permissions. Entferne sandbox_mode und [sandbox_workspace_write], bevor du wechselst.
Profile folgen dem normalen Konfigurationsrangfolge-Modell. Tabellen werden rekursiv zusammengeführt, sodass eine Team-Konfiguration eine Domain oder einen Pfad zum Profil einer Organisation hinzufügen kann, ohne alles erneut anzugeben.
Dateisystemregeln: read, write und deny
Jeder Dateisystemeintrag ordnet einen Pfad read, write oder deny zu. Spezifischere Pfade haben Vorrang vor allgemeineren, und wenn zwei Einträge denselben Pfad betreffen, schlägt deny write und dieses wiederum read.
Die Pfadformen, die du am häufigsten verwenden wirst:
:minimal: die Plattform- und Runtime-Pfade, die gängige Tools benötigen:workspace_roots: die Workspace-Wurzeln der Sitzung plus alle Wurzeln, die das Profil hinzufügt:root,:tmpdir,:slash_tmp, absolute Pfade und~/-Pfade
Verwende extends, damit du die integrierten Schutzmechanismen erbst, anstatt sie neu aufzubauen. Hier ist ein Profil, das die :workspace-Standardwerte beibehält und Secrets abschottet:
default_permissions = "dev"
[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
Regeln unter :workspace_roots gelten für jede Wurzel, daher meint secrets den Ordner secrets in jedem Projektstamm. Ein Profil kann :read-only, :workspace oder ein anderes benanntes Profil erweitern. Es kann :danger-full-access nicht erweitern.
Unter Linux, WSL und nativem Windows benötigt ein unbegrenzter **-Deny-Glob möglicherweise glob_scan_max_depth (mindestens 1) unter [permissions.<name>.filesystem], damit Codex ihn vor dem Start der Sandbox erweitern kann.

Netzwerkregeln: aus, offen oder per Allowlist
Das Netzwerk kennt drei Zustände, die von zwei Einstellungen gesteuert werden:
- Netzwerk aus (
enabled = false, der:workspace-Standard): Befehle können das Netzwerk nicht erreichen. - Netzwerk an, Proxy aus: Befehle erhalten direkten, uneingeschränkten Zugriff. Deine Domainregeln werden ignoriert.
- Netzwerk an, Proxy an: Der Datenverkehr läuft über den Codex-Netzwerkproxy, der die Domainregeln des Profils durchsetzt.
Der zweite Zustand ist die Falle. Wenn du permissions.<name>.network.enabled = true setzt, wird der Proxy nicht gestartet. Du benötigst außerdem Folgendes auf oberster Ebene:
[features]
network_proxy = true
Domainmuster unterstützen exakte Hosts (api.example.com), *.example.com nur für Subdomains, **.example.com für die Apex-Domain plus Subdomains und * als globalen Wildcard, der nur zum Erlauben dient. Deny-Einträge überschreiben Allow-Einträge, und ein aktiver Proxy ohne allow-Einträge blockiert alles Externe.
Wenn der Proxy aktiv ist, blockiert er standardmäßig außerdem lokale und private Netzwerkziele. Um einen lokalen Dienst zu erreichen, setze den wörtlichen Host auf die Allowlist, zum Beispiel "localhost" = "allow" oder "127.0.0.1" = "allow".
Ein Codex-Berechtigungsprofil für API-Arbeit
Hier ist das Profil, das wir für die API-Entwicklung getestet haben. Es bearbeitet Code im Workspace, liest niemals .env-Dateien oder einen secrets-Ordner und kann nur deinen API-Host und Apidog erreichen:
default_permissions = "api-work"
[features]
network_proxy = true
[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"
[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"
[permissions.api-work.network]
enabled = true
[permissions.api-work.network.domains]
"api.your-company.com" = "allow" # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow" # Apidog CLI and its API
Ersetze die beiden Hosts durch die, die deine Tests ansprechen. Apidog CLI sendet Testanfragen von deiner Maschine an die zu testende API, daher muss dieser Host auf der Allowlist stehen, nicht nur Apidogs Host. Wenn du einen lokalen Server testest, füge "localhost" = "allow" hinzu.
Installiere Pakete vor der Sitzung, nicht währenddessen. Das Ausführen von npm install -g apidog-cli@latest benötigt registry.npmjs.org, was dieses Profil absichtlich blockiert.
Ein Stolperstein aus unserem Testlauf: Auf einem Mac, auf dem eine Proxy-App oder ein VPN im Fake-IP-DNS-Modus lief, wurde jeder erlaubte Host zu einer 198.18.x.x-Adresse aufgelöst. Die Local/Private-Prüfung behandelte diese als privat und blockierte sie, und Codex meldete „local/private network addresses are blocked by the sandbox policy“. Das Hinzufügen von allow_local_binding = true unter [permissions.api-work.network] behob das Problem, öffnet aber auch Hostnamen auf der Allowlist, die zu privaten Adressen auflösen – setze es also nur, wenn du es brauchst.
Teste das Profil mit codex sandbox
Vertraue einem Profil erst, wenn du gesehen hast, dass es etwas blockiert. Der Befehl codex sandbox führt jeden Befehl unter einem benannten Profil aus und behandelt das aktuelle Verzeichnis als Workspace-Wurzel:
codex sandbox --permission-profile api-work -- cat README.md .env
Mit dem obigen Profil gab unser Lauf die README aus und dann:
cat: .env: Operation not permitted
Ein Schreibvorgang außerhalb des Workspace schlug auf dieselbe Weise fehl (Operation not permitted), während eine neue Datei innerhalb des Workspace erstellt wurde. Prüfe für das Netzwerk, dass der Proxy einen Host blockiert, den du nicht aufgeführt hast:
codex sandbox -P api-work -- curl -sI https://example.org
Der Proxy antwortete mit 403 Forbidden und x-proxy-error: blocked-by-allowlist, während apidog.com 200 zurückgab. Unter macOS fügst du --log-denials hinzu, um die Seatbelt-Ablehnungen nach dem Beenden des Befehls auszugeben.
Du kannst codex sandbox auch verwenden, um Prozesse zu umschließen, die Codex nicht von sich aus in eine Sandbox packt. OpenAI weist in seinem Beitrag darauf hin, dass stdio-MCP-Server in config.toml ohne Sandbox laufen, und zeigt ein memory-mcp-Profil mit "~/mcp-data" = "write" und network.enabled = false, das den npx-Befehl des Servers umschließt.
Profile mitten in der Sitzung mit /permissions wechseln
Tippe in der Codex-CLI /permissions ein, um die Auswahl zu öffnen. Wenn benannte Profile vorhanden sind, werden sie mit ihren Beschreibungen aufgelistet. Um direkt eines auszuwählen:
/permissions api-work --approval-policy=on-request --reviewer=user
Damit wird das Profil für die aktuelle Sitzung festgelegt und Genehmigungsanfragen werden an dich gesendet. Profile und Genehmigungen sind getrennte Steuerungsmechanismen: Das Profil entscheidet, worauf ein in der Sandbox ausgeführter Befehl zugreifen darf, und die Genehmigungsrichtlinie entscheidet, wann Codex fragt, bevor es die Sandbox verlässt. Die CLI-Befehlsreferenz listet die anderen Sitzungsbefehle auf.
Lass Codex deine API mit Apidog CLI testen
Wenn api-work aktiv ist, kann Codex echte API-Tests ohne offenes Internet ausführen. Apidog CLI stellt deinem Agenten Befehle für Endpunkte, Testfälle und Testläufe mit JSON-Ausgabe bereit, die er lesen kann. Du richtest es einmal außerhalb der Sandbox ein:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Gib Codex dann einen Prompt:
Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
Codex liest das Payload-Schema, validiert sein JSON und führt den Testfall aus:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
In unserem Test liefen sowohl apidog auth status als auch apidog project list in der api-work-Sandbox, wobei nur **.apidog.com auf der Allowlist stand. Dein Token bleibt in ~/.apidog, das das Profil lesen, aber nicht ändern kann. Eine vollständige Schritt-für-Schritt-Anleitung findest du unter wie du die Apidog CLI in Codex verwendest; ersetze -r cli,json durch -r junit, wenn derselbe Lauf in eine CI-Pipeline wandert. Der Free-Plan von Apidog deckt bis zu 4 Benutzer ab.

Grenzen, die du kennen solltest, bevor du einem Profil vertraust
Berechtigungsprofile verkleinern den Schadensradius. Sie machen einen Agenten nicht von allein sicher. Die Dokumentation und OpenAIs Beitrag nennen diese Grenzen:
- Weitreichende Lesezugriffe bleiben bei
:workspaceaktiv. Compiler benötigen SDKs und Konfiguration außerhalb des Repos, daher kann eine Konfigurationsdatei an anderer Stelle mit API-Schlüsseln weiterhin lesbar bleiben. Sperre~/.sshund ähnliche Pfade explizit oder verwende":root" = "deny"plus":minimal" = "read". - Deny-Globs sind eine Momentaufnahme. Unter Linux, WSL und Windows werden Übereinstimmungen beim Start jedes in der Sandbox ausgeführten Prozesses erweitert. Eine später erstellte
.envist für eine lang laufende Shell oder einen Dev-Server lesbar. - Wildcards können weiterhin DNS-basierte Datenabflüsse zulassen. Der Proxy löst einen Hostnamen erst auf, nachdem er erlaubt wurde, aber breite Wildcard-Regeln oder Zugriff auf DNS-Dienste können eine DNS-basierte Exfiltration weiterhin ermöglichen.
- Der Proxy deckt nur in der Sandbox ausgeführte Befehle ab. Websuche, Konnektoren, MCP-Server, der Browser und der eigene Modellverkehr von Codex verwenden separate Steuerungen.
- Schreibvorgänge können die Sitzung überdauern. OpenAIs Beispiel ist ein manipuliertes
node_modules/prettier, das dein Editor später beim Speichern außerhalb der Sandbox ausführt.
Wenn du Workarounds zum Umgehen der Codex-Sandbox verwendest, ist ein eng gefasstes benutzerdefiniertes Profil normalerweise die sauberere Lösung. Teams, die Richtlinien maschinenübergreifend benötigen, sollten das Codex-Sicherheits-Cookbook und verwaltete allowed_permission_profiles lesen.
FAQ
Was ist das Standard-Berechtigungsprofil von Codex?
Es gibt kein Standardprofil, auf das du dich verlassen solltest. Die Doku empfiehlt, default_permissions für vorhersehbares Verhalten explizit festzulegen. Für die meisten Coding-Arbeiten ist :workspace die sinnvolle Basis: Schreibzugriff in Workspace-Wurzeln und temporären Verzeichnissen, Netzwerk aus.
Warum werden meine Domainregeln ignoriert?
Normalerweise fehlt features.network_proxy. Mit network.enabled = true und ohne Proxy erhalten Befehle direkten, uneingeschränkten Netzwerkzugriff. Prüfe außerdem, dass keine geladene Konfiguration sandbox_mode setzt, da dies Profile vollständig deaktiviert.
Wie verhindere ich, dass Codex .env-Dateien liest?
Füge "**/*.env" = "deny" unter [permissions.<name>.filesystem.":workspace_roots"] hinzu. Setze unter Linux, WSL und Windows glob_scan_max_depth für unbegrenzte **-Muster und beachte, dass neue Übereinstimmungen nicht für bereits laufende Prozesse ergänzt werden.
Kann ich localhost in einem Codex-Berechtigungsprofil erlauben?
Ja. Setze den wörtlichen Host auf die Allowlist, zum Beispiel "localhost" = "allow" oder "127.0.0.1" = "allow". Setze allow_local_binding = true nur, wenn ein auf der Allowlist stehender Hostname zu einer lokalen oder privaten Adresse auflöst.
Packen Berechtigungsprofile MCP-Server in eine Sandbox?
Nein. Stdio-MCP-Server in config.toml starten ohne Sandbox. Umschließe den Serverbefehl mit codex sandbox --permission-profile <name> -- und einem eigenen Profil.
Kann ich Profile mit dem --sandbox-Flag verwenden?
Nein. Wenn du --sandbox übergibst oder sandbox_mode setzt, verwendet Codex die älteren Sandbox-Einstellungen anstelle von default_permissions. Wähle pro Sitzung ein System.
