Codex-Berechtigungsprofile: config.toml-Beispiele für sichere Agentenläufe

Codex-Berechtigungsprofile legen fest, welche Lese-, Schreib- und Zugriffsrechte die Befehle deines Agenten haben. Hier sind getestete config.toml-Beispiele, darunter ein Profil für API-Arbeit, das die Apidog CLI ohne offenen Internetzugang ausführt.

INEZA Felin-Michel

INEZA Felin-Michel

20 November 2026

Codex-Berechtigungsprofile: config.toml-Beispiele für sichere Agentenläufe

Apidog für Unternehmen

On-Premises Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

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:

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:

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.

Diagram of how a Codex permission profile filters filesystem paths and network requests before a command runs

Netzwerkregeln: aus, offen oder per Allowlist

Das Netzwerk kennt drei Zustände, die von zwei Einstellungen gesteuert werden:

  1. Netzwerk aus (enabled = false, der :workspace-Standard): Befehle können das Netzwerk nicht erreichen.
  2. Netzwerk an, Proxy aus: Befehle erhalten direkten, uneingeschränkten Zugriff. Deine Domainregeln werden ignoriert.
  3. 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.

Flow diagram of Codex running Apidog CLI inside the api-work profile, with the network proxy allowing the API host and Apidog and blocking other domains

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:

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.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen