Profils de permissions Codex : exemples de config.toml pour exécuter des agents en toute sécurité

Les profils d’autorisation Codex déterminent les droits de lecture, d’écriture et d’accès réseau des commandes de votre agent. Voici des exemples testés de config.toml, dont un profil dédié au travail sur API qui exécute Apidog CLI sans accès à l’internet ouvert.

INEZA Felin-Michel

INEZA Felin-Michel

20 November 2026

Profils de permissions Codex : exemples de config.toml pour exécuter des agents en toute sécurité

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Découvrir Apidog Enterprise

Les profils d'autorisations Codex sont des politiques nommées dans config.toml qui déterminent ce que les commandes exécutées par Codex sur votre machine peuvent lire, écrire et atteindre sur le réseau. On en choisit un avec default_permissions, on part d'un profil intégré (:read-only, :workspace ou :danger-full-access), puis on ajoute des chemins read, write et deny ainsi qu'une liste de domaines autorisés.

Ce guide fournit des exemples de config.toml prêts à copier pour les configurations les plus courantes, dont un dédié au travail d'API qui permet à votre agent de codage d'exécuter les tests Apidog CLI contre vos propres hôtes d'API sans accès à Internet ouvert.

Que sont les profils d'autorisations Codex ?

Un profil d'autorisations est une politique de bac à sable réutilisable pour Codex. Il combine des règles de système de fichiers (quels chemins les commandes peuvent lire, écrire ou ne jamais toucher) et des règles réseau (si les commandes peuvent accéder au réseau, et quels domaines). Codex l'applique avec Seatbelt sur macOS, bubblewrap plus seccomp sur Linux et WSL, et MXC sur Windows.

OpenAI a expliqué cette conception dans Inside the Codex sandbox, publié le 18 novembre 2026. Plutôt que de déplacer votre travail dans un conteneur, Codex encadre les commandes dans votre environnement existant, afin que les chaînes d'outils natives fonctionnent toujours.

Codex fournit trois profils intégrés :

Profil Système de fichiers Réseau
:read-only Les commandes peuvent lire, pas écrire Désactivé
:workspace Écritures dans les racines de l'espace de travail et les répertoires temporaires ; .git, .agents, .codex, .aws restent en lecture seule Désactivé
:danger-full-access Aucune restriction de bac à sable local Complet, direct

La documentation sur les autorisations classe encore la fonctionnalité en Beta, attendez-vous donc à ce que les clés changent d'une version à l'autre.

Où placer la table des autorisations dans config.toml

Vos profils résident dans ~/.codex/config.toml (ou dans une couche projet ou système). Deux éléments de premier niveau comptent :

Une règle en piège plus d'un. Les profils d'autorisations ne se combinent pas avec les anciens paramètres de bac à sable. Si sandbox_mode figure dans un fichier de configuration chargé, ou si vous passez --sandbox, Codex utilise les anciens paramètres et ignore default_permissions. Supprimez sandbox_mode et [sandbox_workspace_write] avant de basculer.

Les profils suivent le modèle habituel de priorité de configuration. Les tables fusionnent de façon récursive, ainsi une configuration d'équipe peut ajouter un domaine ou un chemin au profil d'une organisation sans devoir tout redéclarer.

Règles de système de fichiers : read, write et deny

Chaque entrée de système de fichiers associe un chemin à read, write ou deny. Les chemins plus spécifiques priment sur les plus généraux, et lorsque deux entrées ciblent le même chemin, deny l'emporte sur write, qui l'emporte sur read.

Les formes de chemins que vous utiliserez le plus :

Utilisez extends pour hériter des protections intégrées au lieu de les reconstruire. Voici un profil qui conserve les valeurs par défaut de :workspace et verrouille les secrets :

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"

Les règles sous :workspace_roots s'appliquent à chaque racine, donc secrets désigne le dossier secrets de chaque racine de projet. Un profil peut étendre :read-only, :workspace ou un autre profil nommé. Il ne peut pas étendre :danger-full-access.

Sur Linux, WSL et Windows natif, un motif d'exclusion ** non borné peut nécessiter glob_scan_max_depth (au moins 1) sous [permissions.<name>.filesystem] afin que Codex puisse l'étendre avant le démarrage du bac à sable.

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

Règles réseau : désactivé, ouvert ou liste d'autorisation

Le réseau a trois états, et deux paramètres les contrôlent :

  1. Réseau désactivé (enabled = false, la valeur par défaut de :workspace) : les commandes ne peuvent pas atteindre le réseau.
  2. Réseau activé, proxy désactivé : les commandes obtiennent un accès direct et illimité. Vos règles de domaine sont ignorées.
  3. Réseau activé, proxy activé : le trafic passe par le proxy réseau Codex, qui applique les règles de domaine du profil.

Le deuxième état est le piège. Définir permissions.<name>.network.enabled = true ne démarre pas le proxy. Il faut aussi ceci au niveau supérieur :

[features]
network_proxy = true

Les motifs de domaine prennent en charge les hôtes exacts (api.example.com), *.example.com pour les sous-domaines uniquement, **.example.com pour le domaine apex et les sous-domaines, et * comme joker global d'autorisation uniquement. Les entrées de refus l'emportent sur les entrées d'autorisation, et un proxy actif sans entrées allow bloque tout accès externe.

Lorsque le proxy est actif, il bloque aussi par défaut les cibles locales et privées. Pour atteindre un service local, ajoutez à la liste d'autorisation l'hôte littéral, comme "localhost" = "allow" ou "127.0.0.1" = "allow".

Un profil d'autorisations Codex pour le travail d'API

Voici le profil que nous avons testé pour le développement d'API. Il modifie le code dans l'espace de travail, ne lit jamais les fichiers .env ni le dossier secrets, et ne peut atteindre que votre hôte d'API et Apidog :

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

Remplacez les deux hôtes par ceux que vos tests ciblent. Apidog CLI envoie des requêtes de test depuis votre machine vers l'API testée, donc cet hôte doit figurer dans la liste d'autorisation, pas seulement celui d'Apidog. Si vous testez un serveur local, ajoutez "localhost" = "allow".

Installez les paquets avant la session, pas pendant. L'exécution de npm install -g apidog-cli@latest nécessite registry.npmjs.org, que ce profil bloque volontairement.

Un piège rencontré lors de notre test : sur un Mac exécutant une application proxy ou un VPN en mode DNS fake-IP, chaque hôte autorisé se résolvait en une adresse 198.18.x.x. La protection local/privé les traitait comme privées et les bloquait, et Codex signalait « local/private network addresses are blocked by the sandbox policy ». L'ajout de allow_local_binding = true sous [permissions.api-work.network] a résolu le problème, mais cela ouvre aussi des noms d'hôtes autorisés qui se résolvent en adresses privées ; ne l'activez donc que si nécessaire.

Testez le profil avec codex sandbox

Ne faites pas confiance à un profil avant de l'avoir vu bloquer quelque chose. La commande codex sandbox exécute n'importe quelle commande sous un profil nommé et traite le répertoire courant comme racine d'espace de travail :

codex sandbox --permission-profile api-work -- cat README.md .env

Avec le profil ci-dessus, notre exécution a affiché le README puis :

cat: .env: Operation not permitted

Une écriture hors de l'espace de travail a échoué de la même façon (Operation not permitted), tandis qu'un nouveau fichier dans l'espace de travail a bien été créé. Pour le réseau, vérifiez que le proxy bloque un hôte que vous n'avez pas listé :

codex sandbox -P api-work -- curl -sI https://example.org

Le proxy a répondu 403 Forbidden avec x-proxy-error: blocked-by-allowlist, tandis qu'apidog.com a renvoyé 200. Sur macOS, ajoutez --log-denials pour afficher les refus Seatbelt après la sortie de la commande.

Vous pouvez aussi utiliser codex sandbox pour encadrer des processus que Codex ne sandboxe pas de lui-même. L'article d'OpenAI indique que les serveurs MCP stdio dans config.toml s'exécutent sans bac à sable, et montre un profil memory-mcp avec "~/mcp-data" = "write" et network.enabled = false enveloppant la commande npx du serveur.

Changez de profil en cours de session avec /permissions

Dans le CLI Codex, tapez /permissions pour ouvrir le sélecteur. Lorsque des profils nommés existent, il les liste avec leurs descriptions. Pour en sélectionner un directement :

/permissions api-work --approval-policy=on-request --reviewer=user

Cela définit le profil pour la session en cours et vous envoie les demandes d'approbation. Profils et approbations sont des contrôles distincts : le profil décide de ce qu'une commande sandboxée peut toucher, et la politique d'approbation décide quand Codex demande une validation avant d'en sortir. La référence des commandes CLI liste les autres commandes de session.

Laissez Codex tester votre API avec Apidog CLI

Avec api-work actif, Codex peut exécuter de vrais tests d'API sans accès à Internet ouvert. Apidog CLI fournit à votre agent des commandes pour les endpoints, les cas de test et les exécutions, avec une sortie JSON qu'il peut lire. Configurez-le une fois en dehors du bac à sable :

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Ensuite, donnez une seule instruction à Codex :

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 lit le schéma de charge utile, valide son JSON et exécute le cas :

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

Lors de notre test, apidog auth status et apidog project list se sont tous deux exécutés dans le bac à sable api-work avec seulement **.apidog.com autorisé. Votre jeton reste dans ~/.apidog, que le profil peut lire mais pas modifier. Pour un tutoriel complet, consultez comment utiliser l'Apidog CLI dans Codex, et remplacez -r cli,json par -r junit lorsque la même exécution passe dans un pipeline CI. Le plan gratuit d'Apidog couvre jusqu'à 4 utilisateurs.

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

Les limites à connaître avant de faire confiance à un profil

Les profils d'autorisations réduisent le rayon d'impact. Ils ne rendent pas un agent sûr à eux seuls. La documentation et l'article d'OpenAI listent ces limites :

Si vous avez utilisé des contournements pour échapper au bac à sable Codex, un profil personnalisé étroit est généralement la solution la plus propre. Les équipes qui ont besoin d'une politique sur plusieurs machines devraient consulter le cookbook de sécurité Codex et les allowed_permission_profiles gérés.

FAQ

Quel est le profil d'autorisations Codex par défaut ?

Il n'y en a pas sur lequel vous devriez compter. La documentation indique de définir default_permissions explicitement pour un comportement prévisible. Pour la plupart des travaux de codage, :workspace est une base raisonnable : écritures dans les racines de l'espace de travail et les répertoires temporaires, réseau désactivé.

Pourquoi mes règles de domaine sont-elles ignorées ?

Généralement, features.network_proxy est absent. Avec network.enabled = true et sans proxy, les commandes obtiennent un accès réseau direct et illimité. Vérifiez aussi qu'aucune configuration chargée ne définit sandbox_mode, ce qui désactive entièrement les profils.

Comment empêcher Codex de lire les fichiers .env ?

Ajoutez "**/*.env" = "deny" sous [permissions.<name>.filesystem.":workspace_roots"]. Sur Linux, WSL et Windows, définissez glob_scan_max_depth pour les motifs ** non bornés, et rappelez-vous que les nouvelles correspondances ne sont pas ajoutées aux processus déjà en cours d'exécution.

Puis-je autoriser localhost dans un profil d'autorisations Codex ?

Oui. Ajoutez à la liste d'autorisation l'hôte littéral, comme "localhost" = "allow" ou "127.0.0.1" = "allow". Ne définissez allow_local_binding = true que lorsqu'un nom d'hôte autorisé se résout en adresse locale ou privée.

Les profils d'autorisations sandboxent-ils les serveurs MCP ?

Non. Les serveurs MCP stdio dans config.toml démarrent sans bac à sable. Enveloppez la commande du serveur dans codex sandbox --permission-profile <name> -- avec son propre profil.

Puis-je utiliser les profils avec l'option --sandbox ?

Non. Passer --sandbox ou définir sandbox_mode fait que Codex utilise les anciens paramètres de bac à sable au lieu de default_permissions. Choisissez un système par session.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API