Autorisations

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 stratégie nommée qui combine des règles de système de fichiers, lesquelles définissent ce que les commandes peuvent lire ou écrire, et des règles de réseau, qui définissent les destinations que les commandes peuvent atteindre.

Utilisez les profils pour accorder à Codex les accès nécessaires à 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 l’écriture dans les racines d’espace de travail actives et les répertoires temporaires du système.
• :danger-full-access supprime les restrictions du sandbox local 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 premier niveau 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 limiter ceux que les utilisateurs peuvent sélectionner au moyen du paramètre géré 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 ceux 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 les 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 du 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 actuelle 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 devoir redéfinir 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"

[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 actuelle 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 au réseau uniquement par l’intermédiaire de la stratégie de domaine configurée.

Dans un profil actif, les règles de refus plus restreintes restent en vigueur même lorsqu’un chemin plus large 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 essentiellement identique à un profil intégré ou à un autre profil nommé. Préférez étendre un profil intégré plutôt que partir de zéro afin de conserver les protections de base. Étendre :workspace, par exemple, 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"

[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 correspondant à .env 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 rejette é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 spécifiques 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 de l’espace de travail reste accessible en écriture, .devcontainer/ reste accessible en lecture sans devenir accessible en écriture, et les fichiers d’environnement correspondants restent inaccessibles aux commandes exécutées dans le bac à sable.

Un chemin plus spécifique peut également rouvrir une sous-arborescence plus étroite au sein d’un refus plus large :

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

Formes de chemins prises en charge :

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

N’utilisez :root que 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 de l’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 répertoire parent, telles que ../other-repo, sont rejetées.

Refuser les lectures à l’aide de chemins exacts ou de motifs glob

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 autorise l’accès à proximité. Les chemins exacts conviennent aux emplacements stables tels que ~/.ssh. Les motifs glob sont plus adaptés lorsqu’un profil doit couvrir une famille de fichiers sensibles dont l’emplacement exact varie selon les dépôts.

Lorsqu’un motif glob se trouve sous :workspace_roots, Codex l’interprète relativement à 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 par le profil. Utilisez-la pour conserver les autorisations d’écriture normales dans l’espace de travail, tout en empêchant la lecture des fichiers d’environnement, des secrets générés ou de fichiers similaires contenant des identifiants.

Les motifs glob deny sont pris en charge comme règles de refus de lecture. Les motifs glob read ou write sont moins portables dans les bacs à sable Linux, WSL et Windows natif ; privilégiez donc, lorsque cela est possible, les chemins exacts ou les règles de sous-arborescence telles que "docs/**" = "read".

Sous Linux, WSL et Windows natif, un motif de refus de lecture ** sans limite peut nécessiter une pré-expansion bornée avant le démarrage du bac à sable. Définissez glob_scan_max_depth lorsque vous utilisez un motif sans limite 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. Les valeurs supérieures analysent plus profondément avant le démarrage du bac à sable, ce qui peut augmenter le travail de démarrage sous 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 emplacements que la racine de la session actuelle :

[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 actuelle et à chaque racine d’espace de travail activée définie par le profil.

Sous 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

Définissez enabled = true pour autoriser l’accès réseau du profil sélectionné :

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

Lorsque l’accès réseau est activé, Codex utilise par défaut un comportement réseau complet. La plupart des profils doivent également définir des règles de domaine :

[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 proxy du bac à sable réseau se lie par défaut à des écouteurs 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 d’écoute, sauf si vous effectuez une intégration avec un environnement d’exécution spécifique. Les clés réseau dangerously_* constituent des solutions de dernier recours pour les environnements spécialisés et ne doivent pas être utilisées pour le développement local ordinaire.

Réseaux locaux et privés

Codex applique par défaut une protection des réseaux locaux et privés afin de prévenir la redirection DNS et les accès accidentels aux services locaux. Pour autoriser intentionnellement une cible locale littérale, ajoutez l’hôte exact ou l’adresse IP littérale à la liste d’autorisation :

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

Ne définissez allow_local_binding = true que lorsque le profil doit atteindre des noms d’hôtes autorisés qui correspondent à des adresses locales ou privées :

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

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

Sockets Unix

L’utilisation d’un proxy pour les sockets Unix est une solution de dernier recours locale destinée à des outils tels que Docker. Utilisez-la 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 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, conservez la liaison des écouteurs du proxy aux adresses de bouclage.

Migrer depuis les anciens paramètres du bac à sable

Les profils d’autorisation remplacent l’ancienne combinaison de sandbox_mode et sandbox_workspace_write lorsqu’un même profil réutilisable doit décrire à la fois le comportement du système de fichiers et celui du réseau. Utilisez l’un ou l’autre système pour une session, mais pas 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é avec un accès en lecture limité aux seuls emplacements nécessaires.
• Pour modifier l’espace de travail, utilisez le profil intégré :workspace ou définissez un profil personnalisé qui autorise les écritures via :workspace_roots et ajoute uniquement les chemins temporaires ou de cache supplémentaires requis par le flux de travail.
• Pour une exécution locale sans restriction, utilisez :danger-full-access uniquement lorsque vous souhaitez intentionnellement adopter le modèle d’accès local le plus large.

Les profils décrivent le niveau d’accès local 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 élargir. Consultez la section Configuration gérée pour connaître les contraintes de système de fichiers et de réseau imposées par les administrateurs.

Portée et application

Les profils d’autorisation définissent les limites de l’exécution locale des commandes dans le bac à sable. Utilisez-les avec les politiques d’approbation et les contrôles distincts applicables aux connecteurs, aux serveurs MCP, au navigateur intégré, à Computer Use et à Codex cloud.

Ce que contrôlent les profils

• Exécution locale des commandes : les profils d’autorisation régissent les commandes exécutées dans le bac à sable 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 les écritures dans les scripts, les étapes de compilation, les hooks des gestionnaires de paquets, les fichiers de démarrage du shell et les répertoires partagés comme sensibles, car d’autres outils ou utilisateurs peuvent exécuter ces fichiers ultérieurement hors du contexte du bac à sable d’origine.
• Destinations sortantes : les règles de domaine réseau limitent les destinations accessibles au trafic des commandes exécutées dans le bac à sable via le proxy réseau. Elles ne déterminent pas si une destination autorisée est digne de confiance, et les règles d’autorisation avec caractères génériques restent larges.
• Services locaux : les cibles des réseaux locaux et privés sont bloquées par défaut. L’ajout de localhost, d’adresses IP privées ou de sockets Unix à la liste d’autorisation, ou la définition explicite de allow_local_binding = true, ouvre l’accès aux services locaux.

Fonctionnement de l’application

• Sous macOS, Codex utilise des profils de bac à sable Seatbelt. Si la politique sélectionnée ne peut pas être appliquée par le bac à sable de la plateforme, Codex refuse d’exécuter la commande au lieu de l’exécuter silencieusement hors du bac à sable.
• Sous Linux et WSL, Codex utilise bubblewrap et seccomp, Landlock étant disponible comme solution de repli pour les chemins de compatibilité. Le niveau d’application le plus strict 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 de séparation non prises en charge sont refusées.
• Sous Windows natif, la mise en bac à sable elevated est la plus robuste, car elle peut utiliser des utilisateurs de bac à sable dédiés disposant de privilèges inférieurs, des limites d’autorisation du système de fichiers et des règles de pare-feu. La mise en bac à sable unelevated est une solution de repli offrant une isolation réseau plus faible et ne peut pas appliquer toutes les exclusions distinctes en lecture et en écriture ; les politiques non prises en charge sont donc refusées. Utilisez WSL lorsque vous avez besoin du modèle de bac à sable Linux.

Recommandations opérationnelles

Choisissez le profil le plus restrictif qui permette néanmoins d’accomplir la tâche, en particulier lorsque vous accordez des autorisations 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"

[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 permettra à Codex d’écrire dans les dossiers de votre espace de travail tout en refusant la lecture du reste du système de fichiers (avec quelques 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"

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

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