Autorisations

La configuration gérée allowed_permission_profiles constitue l’exception : elle oblige Codex à utiliser les profils d’autorisation. Supprimez les anciens paramètres tels que sandbox_mode et [sandbox_workspace_write] avant de déployer une liste d’autorisation de profils gérée. Pour un déploiement en entreprise combinant plusieurs versions, vous pouvez conserver l’exigence gérée allowed_sandbox_modes comme contrainte de compatibilité temporaire jusqu’à ce que tous les clients utilisent Codex 0.138.0 ou une version ultérieure.

Les profils d’autorisation vous permettent d’appliquer des limites fondées sur le moindre privilège aux commandes locales que Codex exécute pour votre compte. Un profil est une politique nommée qui associe des règles de système de fichiers, lesquelles déterminent ce que les commandes peuvent lire ou écrire, à des règles réseau, lesquelles déterminent les destinations que les commandes peuvent atteindre.

Utilisez les profils pour accorder à Codex un accès suffisant pour la conversation en cours sans lui donner un accès étendu à votre machine ou à votre réseau. Par exemple, un profil en lecture seule peut permettre à Codex d’inspecter un projet sans le modifier, tandis qu’un profil autorisant l’écriture peut limiter les modifications aux racines d’espace de travail sélectionnées.

Les profils d’autorisation locaux sont pris en charge sur macOS, Linux, WSL et Windows natif. Consultez Portée et application pour connaître les détails et réserves propres à chaque plateforme.

Pour les paramètres réseau de Codex cloud, consultez Accès à Internet.

Définir et sélectionner un profil

Codex comprend trois profils d’autorisation intégrés :

• :read-only maintient l’exécution des commandes locales en lecture seule.
• :workspace autorise les écritures dans les racines d’espace de travail actives et les répertoires temporaires du système.
• :danger-full-access supprime les restrictions de la sandbox locale et ne doit être utilisé que lorsque cet accès étendu est intentionnel.

Créez un profil nommé sous [permissions.<name>], puis définissez la clé de niveau supérieur default_permissions sur le nom de ce profil ou sur l’un des profils intégrés ci-dessus. Dans cet exemple, project-edit est un nom de profil défini par l’utilisateur, et non une valeur intégrée.

Les administrateurs d’entreprise peuvent définir des profils et restreindre ceux que les utilisateurs peuvent sélectionner au moyen de la configuration gérée requirements.toml. Dès que allowed_permission_profiles est présent, les profils omis sont refusés, y compris les profils intégrés omis et les profils ajoutés dans de futures versions de Codex. Consultez Contrôler les profils d’autorisation disponibles pour connaître la configuration gérée recommandée.

Les profils personnalisés utilisent deux concepts associés :

• [permissions.<name>.workspace_roots] ajoute des répertoires concrets qui doivent être considérés comme des racines d’espace de travail pour ce profil.
• [permissions.<name>.filesystem.":workspace_roots"] définit les règles de système de fichiers que Codex applique dans chaque racine d’espace de travail effective : les racines d’espace de travail d’exécution de la session en cours ainsi que les racines définies ci-dessus dans le profil.

Les profils utilisent également le modèle normal de couches de configuration. Les couches de priorité supérieure peuvent ajouter ou remplacer des entrées sous le même nom de profil sans avoir à reformuler l’intégralité du profil.

Par exemple, une configuration au niveau de l’organisation et une configuration au niveau de l’utilisateur peuvent étendre indépendamment le même profil :

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

Lorsque server est actif, les deux racines d’espace de travail font partie du profil effectif.

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"

Ce profil :

• Lit les chemins d’exécution minimaux nécessaires aux outils de développement courants.
• Applique les mêmes règles de racine d’espace de travail à la session en cours et aux racines définies dans le profil.
• Maintient en lecture seule, sous chaque racine, les paramètres associés à l’IDE tels que .devcontainer/.
• Refuse les fichiers d’environnement correspondants au moyen d’une règle glob.
• Autorise l’accès réseau uniquement par l’intermédiaire de la politique de domaine configurée.

Dans un profil actif, les règles de refus plus précises restent applicables même lorsqu’un chemin plus général est lisible ou inscriptible. Par exemple, un profil peut rendre les racines d’espace de travail inscriptibles tout en définissant un chemin .env correspondant sur deny.

Étendre un profil

Utilisez extends lorsqu’un profil est en grande partie identique à un profil intégré ou à un autre profil nommé. Préférez étendre un profil intégré plutôt que de partir de zéro afin de conserver les protections de base. Par exemple, l’extension de :workspace maintient le répertoire .codex de la racine d’espace de travail en lecture seule, sauf si vous le remplacez explicitement. Définissez le parent une seule fois, puis ajoutez ou remplacez uniquement les règles qui diffèrent.

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"

Ce profil part de :workspace, maintient le refus des fichiers .env correspondants et autorise les requêtes vers api.openai.com. Un profil peut étendre :read-only, :workspace ou un autre profil nommé. Il ne peut pas étendre :danger-full-access ; Codex refuse également les parents inconnus et les cycles d’héritage.

Spécification de la configuration

Autorisations du système de fichiers

Les entrées du système de fichiers utilisent read, write ou deny :

Les entrées plus précises remplacent les entrées plus générales. Lorsque deux entrées ciblent le même chemin, deny prévaut sur write, et write prévaut sur read.

Cette priorité permet à un profil de décrire d’abord une vaste zone de travail, puis d’en exclure les fichiers ou répertoires qui doivent rester illisibles :

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

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

Dans cet exemple, la racine d’espace de travail reste inscriptible, .devcontainer/ reste lisible sans devenir inscriptible, et les fichiers d’environnement correspondants restent inaccessibles aux commandes exécutées dans la sandbox.

Un chemin plus précis peut également rouvrir une sous-arborescence plus étroite au sein d’un refus plus général :

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

Formes de chemin prises en charge :

Sur Windows natif, les chemins relatifs au répertoire personnel peuvent également utiliser des barres obliques inverses, comme ~\work.

Utilisez :root uniquement lorsqu’un profil nécessite intentionnellement une large couverture en lecture :

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

Utilisez des entrées imbriquées sous :workspace_roots pour limiter l’accès aux sous-chemins relatifs à la racine d’espace de travail :

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

Les sous-chemins imbriqués doivent rester dans leur racine d’espace de travail. Les remontées vers le parent telles que ../other-repo sont refusées.

Refuser les lectures au moyen de chemins exacts ou de globs

Utilisez deny pour les fichiers ou sous-arborescences que Codex ne doit pas lire, même lorsqu’une règle de profil plus générale accorde un accès à proximité. Les chemins exacts conviennent aux emplacements stables tels que ~/.ssh. Les motifs glob sont mieux adaptés lorsqu’un profil doit couvrir une famille de fichiers sensibles dont l’emplacement exact varie selon les dépôts.

Lorsqu’un glob se trouve sous :workspace_roots, Codex l’interprète par rapport à chaque racine d’espace de travail effective. Par exemple :

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

Cette règle refuse la lecture des fichiers .env correspondants trouvés sous chaque racine d’espace de travail d’exécution ou définie dans le profil. Utilisez-la si vous souhaitez conserver les écritures normales dans l’espace de travail tout en maintenant illisibles les fichiers d’environnement, les secrets générés ou des fichiers similaires contenant des identifiants.

Les motifs glob deny sont pris en charge comme règles de refus de lecture. Les globs read ou write sont moins portables avec la sandbox de Linux, WSL et Windows natif ; préférez donc, lorsque cela est possible, des chemins exacts ou des règles de sous-arborescence telles que "docs/**" = "read".

Sur Linux, WSL et Windows natif, un motif de refus de lecture ** non borné peut nécessiter une pré-expansion bornée avant le démarrage de la sandbox. Définissez glob_scan_max_depth lorsque vous utilisez un motif non borné tel que "**/*.env" = "deny" :

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

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

glob_scan_max_depth doit être au moins égal à 1. Des valeurs plus élevées analysent plus profondément avant le démarrage de la sandbox, ce qui peut ajouter du travail au démarrage sur Linux, WSL et Windows natif. Si vous préférez ne pas utiliser l’expansion bornée, énumérez des profondeurs explicites telles que *.env, */*.env et */*/*.env.

Ajoutez des racines d’espace de travail réutilisables au profil lorsque les mêmes règles doivent s’appliquer à d’autres racines que celle de la session en cours :

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

Lorsque ce profil est actif, Codex applique les règles :workspace_roots aux racines d’espace de travail d’exécution de la session en cours et à chaque racine d’espace de travail activée définie dans le profil.

Sur Windows natif, les chemins avec lettre de lecteur tels que D:\work et les chemins UNC tels que \\server\share sont pris en charge comme chemins absolus.

Autorisations réseau

L’accès réseau et le filtrage réseau sont des paramètres distincts. Définissez permissions.<name>.network.enabled = true pour permettre aux commandes d’accéder au réseau, et activez features.network_proxy pour appliquer les règles de domaine du profil :

[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

Le comportement qui en résulte dépend des deux paramètres :

• Réseau désactivé : les commandes ne peuvent pas accéder au réseau, quelle que soit la fonctionnalité de proxy.
• Réseau activé, proxy désactivé : les commandes disposent d’un accès réseau direct et sans restriction. Les règles de domaine du profil d’autorisation ne sont pas appliquées.
• Réseau activé, proxy activé : les commandes utilisent le proxy, qui applique les règles de domaine du profil. Si le proxy actif ne comporte aucun domaine autorisé, il bloque les destinations externes.

L’ajout de [permissions.<name>.network.domains] ou la définition de permissions.<name>.network.enabled = true n’active pas features.network_proxy. Les administrateurs peuvent également activer le proxy avec [experimental_network] dans requirements.toml. Consultez Configuration gérée.

Lorsqu’il est actif, le proxy de la sandbox réseau se lie par défaut à des points d’écoute locaux :

[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

Conservez les valeurs par défaut de ces paramètres de point d’écoute, sauf si vous effectuez une intégration avec un environnement d’exécution particulier. Les clés réseau dangerously_* sont des échappatoires destinées aux environnements spécialisés et ne doivent pas être utilisées pour le développement local ordinaire.

Réseaux locaux et privés

Lorsque le proxy réseau est actif, Codex applique par défaut une protection du réseau local/privé afin de se prémunir contre la reliaison DNS et l’accès accidentel aux services locaux. Pour autoriser intentionnellement une cible locale littérale, ajoutez l’hôte exact ou le littéral d’adresse IP à la liste d’autorisation :

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

Définissez allow_local_binding = true uniquement lorsque le profil doit atteindre des noms d’hôte figurant sur la liste d’autorisation qui sont résolus en adresses locales ou privées :

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

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

Sockets Unix

Le proxy des sockets Unix constitue une échappatoire locale pour les outils tels que Docker. Utilisez-le avec parcimonie :

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

Utilisez deny pour refuser un chemin de socket, y compris une entrée d’autorisation héritée. Les chemins de socket refusés sont omis de la liste d’autorisation effective.

Lorsque les sockets Unix sont activés, maintenez les points d’écoute du proxy liés aux adresses de bouclage.

Migrer depuis les anciens paramètres de sandbox

Les profils d’autorisation remplacent l’ancienne combinaison de sandbox_mode et sandbox_workspace_write lorsque vous souhaitez qu’un profil réutilisable décrive à la fois le comportement du système de fichiers et celui du réseau. Utilisez un seul de ces systèmes par session, et non les deux.

Points de départ suggérés :

• Pour un flux de travail en lecture seule, utilisez le profil intégré :read-only ou définissez un profil personnalisé qui accorde un accès en lecture uniquement là où cela est nécessaire.
• Pour modifier l’espace de travail, utilisez le profil intégré :workspace ou définissez un profil personnalisé qui écrit par l’intermédiaire de :workspace_roots et ajoute uniquement les chemins temporaires ou de cache supplémentaires nécessaires au flux de travail.
• Pour une exécution locale sans restriction, utilisez :danger-full-access uniquement lorsque vous souhaitez intentionnellement le modèle d’accès local le plus étendu.

Les profils décrivent la posture locale par défaut d’une session. Les exigences gérées par l’organisation peuvent toujours ajouter des restrictions que la configuration utilisateur ne doit pas assouplir. Consultez Configuration gérée pour connaître les contraintes de système de fichiers et de réseau appliquées par les administrateurs.

Portée et application

Les profils d’autorisation définissent les limites de l’exécution locale des commandes dans la sandbox. Utilisez-les avec les politiques d’approbation et les contrôles distincts pour la recherche web, les connecteurs, les serveurs MCP, le navigateur intégré, Computer Use et Codex cloud.

Ce que contrôlent les profils

• Exécution des commandes locales : les profils d’autorisation régissent les commandes exécutées dans la sandbox sur votre machine. Les connecteurs, les serveurs MCP, les interfaces de navigateur ou de computer-use, les paramètres d’environnement de Codex cloud et les élévations approuvées utilisent leurs propres contrôles.
• Écritures dans le système de fichiers : un profil autorisant l’écriture peut créer des modifications persistantes. Considérez comme sensibles les écritures dans les scripts, les étapes de compilation, les hooks de gestionnaires de paquets, les fichiers de démarrage du shell et les répertoires partagés, car d’autres outils ou utilisateurs peuvent ensuite exécuter ces fichiers en dehors du contexte de la sandbox d’origine.
• Destinations sortantes : les règles de domaine réseau limitent les destinations du trafic des commandes exécutées dans la sandbox uniquement lorsque le proxy réseau est actif. Elles ne déterminent pas si une destination autorisée est digne de confiance, et les règles d’autorisation génériques restent étendues.
• Services locaux : un proxy réseau actif bloque par défaut les cibles des réseaux locaux et privés. L’ajout de localhost, d’adresses IP privées ou de sockets Unix à la liste d’autorisation, ou la définition de allow_local_binding = true ouvre explicitement l’accès aux services locaux.

Ce que le proxy réseau ne contrôle pas

Le proxy réseau filtre uniquement le trafic provenant de commandes locales exécutées dans la sandbox. Il n’applique pas la liste d’autorisation de domaines du profil aux éléments suivants :

• Recherche web : l’outil de recherche hébergé utilise ses propres paramètres d’accès. Utilisez web_search et, pour les clients gérés, allowed_web_search_modes afin de le contrôler. tools.web_search.allowed_domains filtre les résultats de recherche, et non l’accès réseau des commandes.
• Apps et connecteurs : les outils reposant sur des connecteurs utilisent leurs propres connexions côté service, autorisations d’espace de travail et paramètres d’app ou d’outil.
• Serveurs MCP : les serveurs MCP locaux et distants utilisent leur propre processus ou transport. Contrôlez-les au moyen de la configuration mcp_servers et de listes d’autorisation de serveurs gérées.
• Navigateur et Computer Use : la navigation dans le navigateur et les actions de computer-use utilisent leurs propres contrôles de fonctionnalité et d’approbation.
• Trafic du service Codex : les requêtes de modèle, d’authentification et les autres requêtes du service client utilisent les paramètres HTTP et de proxy système distincts du client.
• Codex cloud : ces tâches utilisent les paramètres d’accès à Internet de leur propre environnement.

Pour limiter ces interfaces, configurez directement chaque fonctionnalité. Une liste d’autorisation réseau des commandes ne constitue pas une politique réseau globale pour toutes les actions que Codex peut effectuer.

Fonctionnement de l’application

• Sur macOS, Codex utilise les profils de sandbox Seatbelt. Si la politique sélectionnée ne peut pas être appliquée par la sandbox de la plateforme, Codex refuse d’exécuter la commande au lieu de l’exécuter silencieusement sans sandbox.
• Sur Linux et WSL, Codex utilise bubblewrap et seccomp, Landlock étant disponible pour les chemins de repli de compatibilité. Le chemin d’application le plus robuste dépend des espaces de noms utilisateur et de la prise en charge du noyau ; les hôtes de conteneurs restreints peuvent imposer des chemins de compatibilité, et les politiques fractionnées non prises en charge sont refusées.
• Sur Windows natif, la sandbox elevated est la plus robuste, car elle peut utiliser des utilisateurs dédiés à privilèges réduits pour la sandbox, des limites d’autorisation du système de fichiers et des règles de pare-feu. La sandbox unelevated constitue une solution de repli offrant une isolation réseau plus faible et ne peut pas appliquer toutes les exclusions distinctes en lecture/écriture ; les politiques non prises en charge sont donc refusées. Utilisez WSL lorsque vous avez besoin du modèle de sandbox Linux.

Conseils opérationnels

Choisissez le profil le plus restrictif qui permette tout de même d’accomplir la tâche, en particulier lorsque vous accordez des droits d’écriture ou un accès réseau sortant. Veillez à ce que la politique d’approbation, la gestion des secrets et les règles d’autorisation correspondent à ce niveau d’accès.

Profils courants

Lecture seule avec liste d’autorisation réseau

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"

Accès aux fichiers limité à l’espace de travail

Voici un exemple de profil d’autorisation qui rendra vos dossiers d’espace de travail inscriptibles par Codex tout en refusant la lecture du reste du système de fichiers (avec des exceptions limitées, déterminées par :minimal).

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"

Écriture dans l’espace de travail sans réseau

default_permissions = "project-edit"

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

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

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

Écriture dans l’espace de travail avec accès au web public

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"

Utilisez la règle d’autorisation globale "*" uniquement lorsque vous souhaitez autoriser l’accès au réseau public. Les règles de refus peuvent restreindre une liste d’autorisation étendue.