Permisos

Los perfiles de permisos te permiten aplicar límites basados en el principio de privilegio mínimo a los comandos locales que Codex ejecuta en tu nombre. Un perfil es una política con nombre que combina reglas del sistema de archivos, que definen qué pueden leer o escribir los comandos, con reglas de red, que definen a qué destinos pueden acceder los comandos.

Usa perfiles para dar a Codex acceso suficiente para el chat actual sin otorgarle un acceso amplio a tu computadora o red. Por ejemplo, un perfil de solo lectura puede permitir que Codex inspeccione un proyecto sin editarlo, mientras que un perfil con permisos de escritura puede limitar las ediciones a las raíces seleccionadas del espacio de trabajo.

Los perfiles de permisos locales son compatibles con macOS, Linux, WSL y Windows nativo. Consulta Alcance y aplicación para obtener detalles y salvedades específicos de cada plataforma.

Para la configuración de red de Codex Cloud, consulta Acceso a Internet.

Definir y seleccionar un perfil

Codex incluye tres perfiles de permisos integrados:

• :read-only mantiene la ejecución de comandos locales en modo de solo lectura.
• :workspace permite escribir dentro de las raíces activas del espacio de trabajo y los directorios temporales del sistema.
• :danger-full-access elimina las restricciones locales del sandbox y debe usarse solo cuando ese acceso amplio sea intencional.

Crea un perfil con nombre en [permissions.<name>] y luego asigna a la clave de nivel superior default_permissions el nombre de ese perfil o uno de los perfiles integrados anteriores. En este ejemplo, project-edit es un nombre de perfil definido por el usuario, no un valor integrado.

Los administradores empresariales pueden definir perfiles y restringir cuáles pueden seleccionar los usuarios mediante el archivo requirements.toml administrado. Una vez que allowed_permission_profiles está presente, se deniegan los perfiles omitidos, incluidos los perfiles integrados omitidos y los que se agreguen en versiones futuras de Codex. Consulta Controlar los perfiles de permisos disponibles para conocer la configuración administrada recomendada.

Los perfiles personalizados usan dos conceptos relacionados:

• [permissions.<name>.workspace_roots] agrega directorios concretos que deben considerarse raíces del espacio de trabajo para ese perfil.
• [permissions.<name>.filesystem.":workspace_roots"] define las reglas del sistema de archivos que Codex aplica dentro de cada raíz efectiva del espacio de trabajo: las raíces del espacio de trabajo en tiempo de ejecución de la sesión actual, junto con las raíces definidas anteriormente en el perfil.

Los perfiles también usan el modelo estándar de capas de configuración. Las capas con mayor precedencia pueden agregar o reemplazar entradas con el mismo nombre de perfil sin tener que volver a declarar todo el perfil.

Por ejemplo, una configuración a nivel de la organización y otra a nivel del usuario pueden extender el mismo perfil de forma independiente:

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

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

Cuando server está activo, ambas raíces del espacio de trabajo forman parte del perfil efectivo.

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"

Este perfil:

• Lee las rutas mínimas en tiempo de ejecución que necesitan las herramientas de desarrollo comunes.
• Aplica las mismas reglas a las raíces del espacio de trabajo de la sesión actual y a las raíces definidas en el perfil.
• Mantiene en modo de solo lectura la configuración relacionada con el IDE, como .devcontainer/, bajo cada raíz.
• Deniega el acceso a los archivos de entorno que coinciden con una regla glob.
• Permite el acceso a la red solo mediante la política de dominios configurada.

En un perfil activo, las reglas de denegación más específicas siguen vigentes aunque una ruta más general sea legible o modificable. Por ejemplo, un perfil puede permitir escribir en las raíces del espacio de trabajo y, aun así, configurar una ruta que coincida con .env como deny.

Extender un perfil

Usa extends cuando un perfil sea prácticamente igual a uno integrado o a otro perfil con nombre. Es preferible extender un perfil integrado en lugar de empezar desde cero para que se conserven las protecciones básicas. Por ejemplo, extender :workspace mantiene el directorio .codex de la raíz del espacio de trabajo en modo de solo lectura, a menos que sobrescribas explícitamente esa regla. Define el perfil base una sola vez y luego agrega o sobrescribe solo las reglas que sean diferentes.

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"

Este perfil parte de :workspace, mantiene denegado el acceso a los archivos que coinciden con .env y permite solicitudes a api.openai.com. Un perfil puede extender :read-only, :workspace u otro perfil con nombre. No puede extender :danger-full-access; Codex también rechaza los perfiles base desconocidos y los ciclos de herencia.

Especificación de configuración

Permisos del sistema de archivos

Las entradas del sistema de archivos usan read, write o deny:

Las entradas más específicas prevalecen sobre las más generales. Cuando dos entradas se aplican a la misma ruta, deny prevalece sobre write, y write prevalece sobre read.

Esta precedencia permite que un perfil describa primero un área de trabajo amplia y luego excluya los archivos o directorios que deben permanecer inaccesibles para la lectura:

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

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

En este ejemplo, la raíz del espacio de trabajo sigue permitiendo la escritura, .devcontainer/ sigue permitiendo la lectura, pero no la escritura, y los archivos de entorno coincidentes siguen sin estar disponibles para los comandos ejecutados en el sandbox.

Una ruta más específica también puede volver a permitir el acceso a un subárbol más acotado dentro de una denegación más amplia:

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

Formatos de ruta compatibles:

En Windows nativo, las rutas relativas al directorio de inicio también pueden usar barras invertidas, como ~\work.

Usa :root solo cuando un perfil requiera intencionalmente acceso de lectura amplio:

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

Usa entradas anidadas en :workspace_roots para limitar el acceso a subrutas relativas a la raíz del espacio de trabajo:

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

Las subrutas anidadas deben permanecer dentro de la raíz de su espacio de trabajo. Se rechazan las referencias a directorios superiores, como ../other-repo.

Denegar la lectura con rutas exactas o patrones glob

Usa deny para archivos o subárboles que Codex no deba leer, incluso cuando una regla más amplia del perfil permita el acceso a ubicaciones cercanas. Las rutas exactas son adecuadas para ubicaciones estables, como ~/.ssh. Los patrones glob son más adecuados cuando un perfil debe abarcar una familia de archivos sensibles cuyas ubicaciones exactas varían entre repositorios.

Cuando un patrón glob se encuentra en :workspace_roots, Codex lo interpreta en relación con cada raíz efectiva del espacio de trabajo. Por ejemplo:

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

Esta regla deniega la lectura de los archivos .env coincidentes ubicados bajo cada raíz del espacio de trabajo del entorno de ejecución o definida por el perfil. Úsala cuando quieras conservar las operaciones normales de escritura en el espacio de trabajo e impedir la lectura de archivos de entorno, secretos generados u otros archivos similares que contengan credenciales.

Los patrones glob deny se admiten como reglas de denegación de lectura. Los patrones glob read o write son menos portables en el sandbox de Linux, WSL y Windows nativo, por lo que conviene usar rutas exactas o reglas de subárbol como "docs/**" = "read", siempre que sea posible.

En Linux, WSL y Windows nativo, un patrón ** sin límites para denegar lecturas puede requerir una expansión previa limitada antes de que se inicie el sandbox. Configura glob_scan_max_depth cuando uses un patrón sin límites como "**/*.env" = "deny":

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

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

glob_scan_max_depth debe ser al menos 1. Con valores más altos, la exploración es más profunda antes de iniciar el sandbox, lo que puede aumentar el trabajo de inicio en Linux, WSL y Windows nativo. Si prefieres no usar una expansión limitada, enumera profundidades explícitas como *.env, */*.env y */*/*.env.

Agrega al perfil raíces reutilizables del espacio de trabajo cuando las mismas reglas deban aplicarse a otras raíces además de la raíz de la sesión actual:

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

Cuando este perfil está activo, Codex aplica las reglas de :workspace_roots a las raíces del espacio de trabajo del entorno de ejecución de la sesión actual y a cada raíz del espacio de trabajo definida en el perfil que esté habilitada.

En Windows nativo, las rutas con letra de unidad, como D:\work, y las rutas UNC, como \\server\share, se admiten como rutas absolutas.

Permisos de red

El acceso a la red y el filtrado de red se configuran por separado. Configura permissions.<name>.network.enabled = true para permitir que los comandos accedan a la red y habilita features.network_proxy para aplicar las reglas de dominio del perfil:

[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

El comportamiento resultante depende de ambas configuraciones:

• Red desactivada: los comandos no pueden acceder a la red, independientemente de la función de proxy.
• Red activada, proxy desactivado: los comandos tienen acceso directo y sin restricciones a la red. Las reglas de dominio del perfil de permisos no se aplican.
• Red activada, proxy activado: los comandos usan el proxy, que aplica las reglas de dominio del perfil. Si el proxy activo no tiene dominios permitidos, bloquea los destinos externos.

Agregar [permissions.<name>.network.domains] o configurar permissions.<name>.network.enabled = true no habilita features.network_proxy. Como alternativa, los administradores pueden habilitar el proxy con [experimental_network] en requirements.toml. Consulta Configuración administrada.

Cuando está activo, el proxy del sandbox de red se vincula de forma predeterminada a listeners locales:

[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

Mantén la configuración predeterminada de estos listeners, salvo que necesites integrarlos con un entorno de ejecución específico. Las claves de red dangerously_* son mecanismos de excepción para entornos especializados y no deben usarse para el desarrollo local habitual.

Redes locales y privadas

Cuando el proxy de red está activo, Codex aplica de forma predeterminada una protección para redes locales y privadas frente al DNS rebinding y al acceso accidental a servicios locales. Para permitir intencionalmente un destino local literal, agrega a la lista de permitidos el host exacto o la dirección IP literal exacta:

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

Configura allow_local_binding = true solo cuando el perfil deba acceder a nombres de host incluidos en la lista de permitidos que se resuelvan en direcciones locales o privadas:

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

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

Sockets de Unix

El uso de proxy para sockets de Unix es un mecanismo de excepción local para herramientas como Docker. Úsalo con moderación:

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

Usa deny para rechazar una ruta de socket, incluso si una entrada heredada la permite. Las rutas de socket rechazadas se excluyen de la lista efectiva de permitidos.

Cuando los sockets de Unix estén habilitados, mantén los listeners del proxy vinculados a direcciones de loopback.

Migrar desde la configuración anterior del sandbox

Los perfiles de permisos sustituyen la combinación anterior de sandbox_mode y sandbox_workspace_write cuando quieres que un solo perfil reutilizable describa el comportamiento del sistema de archivos y de la red. Usa uno u otro sistema en una sesión, no ambos.

Puntos de partida sugeridos:

• Para un flujo de trabajo de solo lectura, usa el perfil integrado :read-only o define un perfil personalizado con acceso de lectura únicamente donde sea necesario.
• Para editar el espacio de trabajo, usa el perfil integrado :workspace o define un perfil personalizado que escriba mediante :workspace_roots y agregue solo las rutas temporales o de caché adicionales que necesite el flujo de trabajo.
• Para la ejecución local sin restricciones, usa :danger-full-access solo cuando quieras intencionalmente el modelo de acceso local más amplio.

Los perfiles describen la postura local predeterminada de una sesión. Los requisitos administrados por la organización pueden imponer restricciones adicionales que la configuración del usuario no debería flexibilizar. Consulta Configuración administrada para conocer las restricciones del sistema de archivos y de la red impuestas por los administradores.

Alcance y aplicación

Los perfiles de permisos establecen los límites para la ejecución local de comandos dentro de un sandbox. Úsalos junto con las políticas de aprobación y los controles independientes de la búsqueda web, los conectores, los servidores MCP, el navegador integrado, el Uso de la computadora y Codex Cloud.

Qué controlan los perfiles

• Ejecución local de comandos: los perfiles de permisos regulan los comandos ejecutados dentro del sandbox de tu equipo. Los conectores, los servidores MCP, las interfaces del navegador o del Uso de la computadora, la configuración de los entornos de Codex Cloud y las escalaciones aprobadas cuentan con sus propios controles.
• Escrituras en el sistema de archivos: un perfil con permisos de escritura puede crear cambios persistentes. Considera sensibles las escrituras en scripts, pasos de compilación, hooks del gestor de paquetes, archivos de inicio del shell y directorios compartidos, porque posteriormente otras herramientas o usuarios pueden ejecutar esos archivos fuera del contexto original del sandbox.
• Destinos de salida: las reglas de dominio de red limitan los destinos del tráfico de los comandos ejecutados en el sandbox solo mientras el proxy de red está activo. No determinan si un destino permitido es confiable y las reglas de permiso con comodines mantienen un alcance amplio.
• Servicios locales: un proxy de red activo bloquea de forma predeterminada los destinos de redes locales y privadas. Agregar localhost, direcciones IP privadas o sockets de Unix a la lista de permitidos, o configurar allow_local_binding = true, habilita explícitamente el acceso a servicios locales.

Qué no controla el proxy de red

El proxy de red solo filtra el tráfico de los comandos locales que se ejecutan dentro del sandbox. No aplica la lista de dominios permitidos del perfil a:

• Búsqueda web: la herramienta de búsqueda alojada usa su propia configuración de acceso. Usa web_search y, en el caso de los clientes administrados, allowed_web_search_modes para controlarla. tools.web_search.allowed_domains filtra los resultados de búsqueda, no el acceso de los comandos a la red.
• Apps y conectores: las herramientas basadas en conectores usan sus propias conexiones del lado del servicio, los permisos del espacio de trabajo y la configuración de la app o la herramienta.
• Servidores MCP: los servidores MCP locales y remotos usan su propio proceso o transporte. Contrólalos mediante la configuración de mcp_servers y las listas administradas de servidores permitidos.
• Navegador y Uso de la computadora: la navegación en el navegador y las acciones de uso de la computadora usan sus propios controles de funciones y aprobación.
• Tráfico de los servicios de Codex: las solicitudes del modelo, de autenticación y de otros servicios del cliente usan la configuración independiente de HTTP y del proxy del sistema del cliente.
• Codex Cloud: estas tareas usan la propia configuración de acceso a Internet de su entorno.

Para limitar estas funciones, configura cada capacidad directamente. Una lista de destinos de red permitidos para comandos no constituye una política de red global para todas las acciones que Codex puede realizar.

Cómo se aplican las políticas

• En macOS, Codex usa perfiles de sandbox de Seatbelt. Si el sandbox de la plataforma no puede aplicar la política seleccionada, Codex se niega a ejecutar el comando en lugar de ejecutarlo sin avisar fuera del sandbox.
• En Linux y WSL, Codex usa bubblewrap y seccomp, mientras que Landlock está disponible para rutas alternativas de compatibilidad. El mecanismo de aplicación más sólido depende de los espacios de nombres de usuario y de la compatibilidad del kernel; los hosts de contenedores con restricciones pueden obligar a usar rutas de compatibilidad, y las políticas divididas no compatibles se rechazan.
• En Windows nativo, el sandbox elevated es la opción más sólida porque puede usar usuarios dedicados del sandbox con menos privilegios, límites de permisos del sistema de archivos y reglas de firewall. El sandbox unelevated es una alternativa con un aislamiento de red más débil y no puede aplicar todas las excepciones que separan los permisos de lectura y escritura, por lo que se rechazan las políticas no compatibles. Usa WSL cuando necesites el modelo de sandbox de Linux.

Recomendaciones operativas

Elige el perfil más restrictivo que permita completar la tarea, especialmente cuando concedas permisos de escritura o acceso saliente a la red. Mantén la política de aprobación, la gestión de secretos y las reglas de permiso en consonancia con ese nivel de acceso.

Perfiles comunes

Solo lectura con lista de destinos de red permitidos

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"

Acceso a archivos limitado al espacio de trabajo

Este es un ejemplo de un perfil de permisos que permite a Codex escribir en las carpetas de tu espacio de trabajo y le deniega la lectura del resto del sistema de archivos (con excepciones limitadas, según lo determine :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"

Escritura en el espacio de trabajo sin acceso a la red

default_permissions = "project-edit"

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

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

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

Escritura en el espacio de trabajo con acceso a la web pública

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"

Usa la regla global de autorización "*" solo cuando quieras permitir el acceso a la red pública. Las reglas de denegación pueden restringir una lista de permitidos amplia.