Los perfiles de permisos de Codex son políticas con nombre en config.toml que determinan qué pueden leer, escribir y alcanzar en la red los comandos que Codex ejecuta en tu máquina. Se elige uno con default_permissions, se parte de uno integrado (:read-only, :workspace o :danger-full-access) y luego se añaden rutas read, write y deny, además de una lista de dominios permitidos.
Esta guía reúne ejemplos de config.toml listos para copiar para las configuraciones más habituales, incluida una para trabajo con APIs que permite a tu agente de programación ejecutar pruebas con Apidog CLI contra tus propios hosts de API sin necesidad de abrir todo Internet.
¿Qué son los perfiles de permisos de Codex?
Un perfil de permisos es una política de sandbox reutilizable para Codex. Combina reglas de sistema de archivos (qué rutas pueden leer, escribir o no tocar nunca los comandos) con reglas de red (si los comandos pueden acceder a la red y a qué dominios). Codex las aplica con Seatbelt en macOS, bubblewrap junto con seccomp en Linux y WSL, y MXC en Windows.
OpenAI explicó el diseño en Inside the Codex sandbox, publicado el 18 de noviembre de 2026. En lugar de trasladar tu trabajo a un contenedor, Codex restringe los comandos en tu entorno actual, de modo que las cadenas de herramientas nativas siguen funcionando.
Codex incluye tres perfiles integrados:
| Perfil | Sistema de archivos | Red |
|---|---|---|
:read-only |
Los comandos pueden leer, pero no escribir | Desactivada |
:workspace |
Escritura dentro de las raíces del espacio de trabajo y los directorios temporales; .git, .agents, .codex, .aws permanecen en solo lectura |
Desactivada |
:danger-full-access |
Sin restricciones locales de sandbox | Completa y directa |
La documentación de permisos sigue etiquetando la función como Beta, así que es previsible que las claves cambien entre versiones.
Dónde va la tabla de permisos en config.toml
Tus perfiles se definen en ~/.codex/config.toml (o en una capa de proyecto o de sistema). Hay dos elementos de nivel superior que importan:
-
default_permissionsindica el nombre del perfil que Codex aplica de forma predeterminada. Debe coincidir con un perfil integrado o con uno definido en[permissions]. -
[permissions.<name>]define un perfil. Añádele unadescription; aparecerá en el selector de/permissions.
Hay una regla que suele pillar a la gente. Los perfiles de permisos no se combinan con los ajustes de sandbox antiguos. Si sandbox_mode aparece en algún archivo de configuración cargado, o si pasas --sandbox, Codex usa los ajustes antiguos e ignora default_permissions. Elimina sandbox_mode y [sandbox_workspace_write] antes de cambiar.
Los perfiles siguen el modelo habitual de precedencia de configuración. Las tablas se fusionan de forma recursiva, así que la configuración de un equipo puede añadir un dominio o una ruta al perfil de la organización sin tener que repetir todo.
Reglas del sistema de archivos: read, write y deny
Cada entrada del sistema de archivos asocia una ruta a read, write o deny. Las rutas más específicas prevalecen sobre las más generales y, cuando dos entradas apuntan a la misma ruta, deny prevalece sobre write, que a su vez prevalece sobre read.
Las formas de ruta que más usarás son:
-
:minimal: las rutas de plataforma y de runtime que necesitan las herramientas habituales -
:workspace_roots: las raíces del espacio de trabajo de la sesión más las raíces que añada el perfil -
:root,:tmpdir,:slash_tmp, rutas absolutas y rutas con~/
Usa extends para heredar las protecciones integradas en lugar de reconstruirlas. Aquí tienes un perfil que conserva los valores predeterminados de :workspace y bloquea los secretos:
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"
Las reglas bajo :workspace_roots se aplican a todas las raíces, así que secrets significa la carpeta secrets de cada raíz de proyecto. Un perfil puede extender :read-only, :workspace u otro perfil con nombre. No puede extender :danger-full-access.
En Linux, WSL y Windows nativo, un glob de denegación ** sin límites puede requerir glob_scan_max_depth (como mínimo 1) bajo [permissions.<name>.filesystem] para que Codex pueda expandirlo antes de que arranque el sandbox.
Reglas de red: desactivada, abierta o con lista de permitidos
La red tiene tres estados, y dos ajustes los controlan:
-
Red desactivada (
enabled = false, el valor predeterminado de:workspace): los comandos no pueden acceder a la red. - Red activada, proxy desactivado: los comandos tienen acceso directo y sin restricciones. Tus reglas de dominio se ignoran.
- Red activada, proxy activado: el tráfico pasa por el proxy de red de Codex, que aplica las reglas de dominio del perfil.
El segundo estado es la trampa. Establecer permissions.<name>.network.enabled = true no arranca el proxy. También necesitas esto en el nivel superior:
[features]
network_proxy = true
Los patrones de dominio admiten hosts exactos (api.example.com), *.example.com solo para subdominios, **.example.com para el dominio raíz y sus subdominios, y * como comodín global que solo sirve para permitir. Las entradas de denegación prevalecen sobre las de permiso, y un proxy activo sin entradas allow bloquea todo lo externo.
Cuando el proxy está activo, también bloquea por defecto los destinos de red locales y privados. Para acceder a un servicio local, añade el host literal a la lista de permitidos, por ejemplo "localhost" = "allow" o "127.0.0.1" = "allow".
Un perfil de permisos de Codex para trabajo con APIs
Este es el perfil que probamos para desarrollo de APIs. Edita código en el espacio de trabajo, nunca lee archivos .env ni la carpeta secrets, y solo puede acceder a tu host de API y a 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
Sustituye los dos hosts por los que usen tus pruebas. Apidog CLI envía las solicitudes de prueba desde tu máquina a la API bajo prueba, así que ese host debe estar en la lista de permitidos, no solo el de Apidog. Si pruebas un servidor local, añade "localhost" = "allow".
Instala los paquetes antes de la sesión, no dentro de ella. Ejecutar npm install -g apidog-cli@latest necesita registry.npmjs.org, que este perfil bloquea a propósito.
Un detalle que descubrimos en nuestras pruebas: en un Mac con una aplicación de proxy o una VPN en modo de DNS fake-IP, todos los hosts permitidos se resolvían a una dirección 198.18.x.x. La protección de red local/privada las trataba como privadas y las bloqueaba, y Codex mostraba «local/private network addresses are blocked by the sandbox policy». Añadir allow_local_binding = true bajo [permissions.api-work.network] lo solucionó, pero también abre nombres de host permitidos que se resuelven a direcciones privadas, así que actívalo solo cuando lo necesites.
Prueba el perfil con codex sandbox
No te fíes de un perfil hasta que le hayas visto bloquear algo. El comando codex sandbox ejecuta cualquier comando bajo un perfil con nombre y trata el directorio actual como una raíz del espacio de trabajo:
codex sandbox --permission-profile api-work -- cat README.md .env
Con el perfil anterior, nuestra ejecución imprimió el README y después:
cat: .env: Operation not permitted
Una escritura fuera del espacio de trabajo falló del mismo modo (Operation not permitted), mientras que sí se creó un archivo nuevo dentro del espacio de trabajo. En cuanto a la red, comprueba que el proxy bloquea un host que no hayas incluido:
codex sandbox -P api-work -- curl -sI https://example.org
El proxy respondió 403 Forbidden con x-proxy-error: blocked-by-allowlist, mientras que apidog.com devolvió 200. En macOS, añade --log-denials para imprimir las denegaciones de Seatbelt cuando termine el comando.
También puedes usar codex sandbox para envolver procesos que Codex no ejecuta en sandbox por sí mismo. La publicación de OpenAI señala que los servidores MCP de stdio en config.toml se ejecutan sin sandbox, y muestra un perfil memory-mcp con "~/mcp-data" = "write" y network.enabled = false que envuelve el comando npx del servidor.
Cambia de perfil a mitad de sesión con /permissions
En el CLI de Codex, escribe /permissions para abrir el selector. Cuando existen perfiles con nombre, los muestra junto con sus descripciones. Para seleccionar uno directamente:
/permissions api-work --approval-policy=on-request --reviewer=user
Eso establece el perfil para la sesión actual y te envía a ti las solicitudes de aprobación. Los perfiles y las aprobaciones son controles independientes: el perfil decide a qué puede acceder un comando dentro del sandbox, y la política de aprobación decide cuándo Codex pregunta antes de salirse de él. La referencia de comandos del CLI enumera el resto de comandos de sesión.
Deja que Codex pruebe tu API con Apidog CLI
Con api-work activo, Codex puede ejecutar pruebas de API reales sin abrir todo Internet. Apidog CLI ofrece a tu agente comandos para endpoints, casos de prueba y ejecuciones, con salida JSON que puede leer. Se configura una vez fuera del sandbox:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Después, dale a Codex un único 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 lee el esquema del payload, valida su JSON y ejecuta el caso:
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
En nuestra prueba, apidog auth status y apidog project list se ejecutaron dentro del sandbox api-work con solo **.apidog.com en la lista de permitidos. Tu token permanece en ~/.apidog, que el perfil puede leer pero no modificar. Para ver el proceso completo, consulta cómo usar Apidog CLI en Codex, y cambia -r cli,json por -r junit cuando esa misma ejecución pase a formar parte de una canalización de CI. El plan gratuito de Apidog admite hasta 4 usuarios.
Límites que debes conocer antes de confiar en un perfil
Los perfiles de permisos reducen el radio de impacto. Por sí solos no hacen que un agente sea seguro. La documentación y la publicación de OpenAI enumeran estos límites:
-
Las lecturas amplias siguen activas con
:workspace. Los compiladores necesitan SDKs y configuración fuera del repositorio, así que un archivo de configuración que contenga claves de API puede seguir siendo legible. Deniega explícitamente~/.sshy rutas similares, o usa":root" = "deny"junto con":minimal" = "read". -
Los globs de denegación son una instantánea. En Linux, WSL y Windows, las coincidencias se expanden cuando arranca cada proceso dentro del sandbox. Un
.envcreado después puede ser leído por un shell o un servidor de desarrollo de larga duración. - Los comodines aún pueden filtrar información a través de DNS. El proxy resuelve un nombre de host solo después de que se haya permitido, pero las reglas comodín amplias o el acceso a servicios DNS pueden seguir permitiendo exfiltración mediante DNS.
- El proxy solo cubre los comandos dentro del sandbox. La búsqueda web, los conectores, los servidores MCP, el navegador y el propio tráfico del modelo de Codex usan controles independientes.
-
Las escrituras pueden sobrevivir a la sesión. El ejemplo de OpenAI es un
node_modules/prettiermanipulado que tu editor ejecuta después al guardar, fuera del sandbox.
Si has recurrido a soluciones alternativas para saltarte el sandbox de Codex, un perfil personalizado y restrictivo suele ser una solución más limpia. Los equipos que necesitan aplicar políticas en varias máquinas deberían consultar el recetario de seguridad de Codex y el ajuste gestionado allowed_permission_profiles.
Preguntas frecuentes
¿Cuál es el perfil de permisos predeterminado de Codex?
No hay ninguno en el que debas confiar. La documentación recomienda establecer default_permissions explícitamente para obtener un comportamiento predecible. Para la mayoría de tareas de programación, :workspace es la base sensata: escritura en las raíces del espacio de trabajo y en los directorios temporales, y red desactivada.
¿Por qué se ignoran mis reglas de dominio?
Normalmente porque falta features.network_proxy. Con network.enabled = true y sin proxy, los comandos tienen acceso directo y sin restricciones a la red. Comprueba también que ningún archivo de configuración cargado establezca sandbox_mode, ya que eso desactiva los perfiles por completo.
¿Cómo evito que Codex lea archivos .env?
Añade "**/*.env" = "deny" bajo [permissions.<name>.filesystem.":workspace_roots"]. En Linux, WSL y Windows, define glob_scan_max_depth para los patrones ** sin límites, y recuerda que las nuevas coincidencias no se añaden a los procesos que ya están en ejecución.
¿Puedo permitir localhost en un perfil de permisos de Codex?
Sí. Añade el host literal a la lista de permitidos, por ejemplo "localhost" = "allow" o "127.0.0.1" = "allow". Establece allow_local_binding = true solo cuando un nombre de host permitido se resuelva a una dirección local o privada.
¿Los perfiles de permisos ejecutan los servidores MCP en un sandbox?
No. Los servidores MCP de stdio en config.toml arrancan sin sandbox. Envuelve el comando del servidor en codex sandbox --permission-profile <name> -- con su propio perfil.
¿Puedo usar perfiles con el flag --sandbox?
No. Pasar --sandbox o establecer sandbox_mode hace que Codex use los ajustes de sandbox antiguos en lugar de default_permissions. Elige un solo sistema por sesión.


Top comments (0)