Perfiles de permisos de Codex: ejemplos de config.toml para ejecuciones seguras de agentes

Los perfiles de permisos de Codex determinan qué pueden leer, escribir y a qué pueden acceder los comandos de tu agente. Aquí tienes ejemplos probados de config.toml, incluido un perfil para trabajo con API que ejecuta Apidog CLI sin acceso abierto a internet.

INEZA Felin-Michel

INEZA Felin-Michel

20 November 2026

Perfiles de permisos de Codex: ejemplos de config.toml para ejecuciones seguras de agentes

Apidog para empresas

Despliegue local

SSO & RBAC

Conforme con SOC 2

Explorar Apidog Enterprise

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:

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:

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.

Diagrama de cómo un perfil de permisos de Codex filtra las rutas del sistema de archivos y las solicitudes de red antes de que se ejecute un comando

Reglas de red: desactivada, abierta o con lista de permitidos

La red tiene tres estados, y dos ajustes los controlan:

  1. Red desactivada (enabled = false, el valor predeterminado de :workspace): los comandos no pueden acceder a la red.
  2. Red activada, proxy desactivado: los comandos tienen acceso directo y sin restricciones. Tus reglas de dominio se ignoran.
  3. 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.

Diagrama de flujo de Codex ejecutando Apidog CLI dentro del perfil api-work, con el proxy de red permitiendo el host de la API y Apidog y bloqueando el resto de dominios

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:

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.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs