Permisos

Los perfiles de permisos te permiten aplicar el principio de mínimo privilegio 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 conectarse.

Usa los perfiles para dar a Codex el acceso que necesita para el chat actual sin concederle acceso general a tu computadora o a tu 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 los cambios a determinadas raíces del espacio de trabajo.

Los perfiles de permisos locales son compatibles con macOS, Linux, WSL y Windows nativo. Consulta Alcance y aplicación de las reglas para conocer los detalles y las limitaciones de cada plataforma.

Para conocer la configuración de red actual de Codex Cloud, consulta Conectarse a servicios. Para Codex Cloud (versión anterior), consulta Acceso a internet.

Definir y seleccionar un perfil

Codex incluye tres perfiles de permisos integrados:

• :read-only limita la ejecución de comandos locales a operaciones de solo lectura.
• :workspace permite escribir dentro de las raíces activas del espacio de trabajo y en los directorios temporales del sistema.
• :danger-full-access elimina las restricciones del sandbox local. Úsalo solo si quieres conceder ese nivel de acceso.

Crea un perfil con nombre en [permissions.<name>] y establece la clave de nivel superior default_permissions en el nombre de ese perfil o de 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 de empresas pueden definir perfiles y restringir cuáles pueden seleccionar los usuarios mediante el archivo administrado requirements.toml. Cuando se incluye allowed_permission_profiles, se deniegan todos los perfiles que no figuren en la lista, incluidos los perfiles integrados omitidos y los que se agreguen en futuras versiones 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 específicos que se consideran 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. Esto incluye las raíces que usa la sesión actual en tiempo de ejecución y las que define el perfil en la tabla anterior.

Los perfiles también usan el modelo habitual de configuración por capas. Las capas de mayor prioridad pueden agregar o reemplazar entradas bajo el mismo nombre de perfil sin tener que volver a definir todo el perfil.

Por ejemplo, la configuración de una organización y la de un usuario pueden ampliar 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:

• Permite leer el conjunto mínimo de rutas que necesitan las herramientas de desarrollo habituales en tiempo de ejecución.
• Aplica las mismas reglas a las raíces del espacio de trabajo de la sesión actual y a las que define el perfil.
• Concede acceso de solo lectura a la configuración relacionada con el IDE, como .devcontainer/, dentro de cada raíz.
• Deniega el acceso a los archivos de entorno que coinciden con un patrón glob.
• Permite el acceso a la red únicamente según la política de dominios configurada.

Dentro de un perfil activo, las reglas de denegación más específicas siguen vigentes aunque una ruta más amplia tenga permisos de lectura o escritura. Por ejemplo, un perfil puede permitir la escritura en las raíces del espacio de trabajo y aun así asignar a una ruta .env que coincida con el patrón el valor deny.

Extender un perfil

Usa extends cuando un perfil sea muy similar a uno integrado o a otro perfil con nombre. Es preferible extender un perfil integrado para conservar sus protecciones básicas. Por ejemplo, al extender :workspace, las rutas .git, .agents, .codex y .aws de la raíz del espacio de trabajo siguen siendo de solo lectura, a menos que reemplaces esas reglas de forma explícita. Define el perfil base una sola vez y luego agrega o reemplaza únicamente 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 bloqueado el acceso a los archivos .env que coinciden con el patrón 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 la configuración

Permisos del sistema de archivos

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

Las entradas más específicas tienen prioridad sobre las más generales. Cuando dos entradas se refieren a la misma ruta, deny tiene prioridad sobre write, y write sobre read.

Este orden de prioridad permite definir primero un área de trabajo amplia y luego excluir los archivos o directorios que no deben poder leerse:

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

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

En este ejemplo, se puede seguir escribiendo en la raíz del espacio de trabajo. El directorio .devcontainer/ sigue siendo de solo lectura y los comandos que se ejecutan en el sandbox siguen sin poder acceder a los archivos de entorno que coinciden con el patrón.

Una ruta más específica también puede volver a permitir el acceso a un subárbol dentro de una ruta más amplia cuyo acceso se haya denegado:

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

Formatos de ruta compatibles:

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

Usa :root solo si necesitas dar al perfil acceso de lectura amplio de forma intencional:

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

Usa entradas anidadas en :workspace_roots para definir el acceso a subrutas relativas a cada 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 su raíz del espacio de trabajo. Se rechazan las rutas que ascienden al directorio superior, como ../other-repo.

Denegar la lectura mediante rutas exactas o patrones glob

Usa deny para los archivos o subárboles que Codex no debe leer, incluso cuando una regla más amplia del perfil conceda acceso al área que los contiene. Las rutas exactas funcionan bien para ubicaciones estables, como ~/.ssh. Los patrones glob son más adecuados cuando un perfil debe abarcar un conjunto de archivos sensibles cuya ubicación exacta varía entre repositorios.

Cuando un patrón glob está en :workspace_roots, Codex lo interpreta con respecto a 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 que coincidan con el patrón dentro de cada raíz del espacio de trabajo, tanto las del entorno de ejecución como las definidas por el perfil. Úsala si quieres mantener los permisos de escritura habituales en el espacio de trabajo e impedir que se lean archivos de entorno, secretos generados u otros archivos similares que contengan credenciales.

En Linux, en WSL y en Windows nativo con MXC o elevated, las coincidencias de los patrones glob que deniegan la lectura se enumeran al iniciar cada proceso en el sandbox. Los archivos que coincidan con el patrón y se creen después no se agregan a la lista de denegación de ese proceso. El proceso puede leerlos si sus demás permisos lo permiten. Por ejemplo, un shell, un script, un proceso de monitoreo o un servidor de desarrollo de larga duración puede leer un archivo .env que coincida con el patrón si se crea después de iniciar el proceso.

Esta lista refleja el estado inicial y es válida mientras se ejecuta el proceso en el sandbox, no durante toda la sesión de Codex. Al iniciar un nuevo proceso en el sandbox a través de Codex, se vuelven a enumerar las coincidencias. Si sigues usando un proceso que ya está en ejecución, su lista de denegación no se actualiza. No dependas de un patrón glob para bloquear archivos recién creados en ese proceso. Consulta Compatibilidad de MXC en Windows para conocer las limitaciones específicas de Windows.

Los patrones glob con deny se admiten como reglas de denegación de lectura. Los patrones glob con read o write son menos portables entre los entornos de sandbox de Linux, WSL y Windows nativo. Siempre que sea posible, usa rutas exactas o reglas de subárbol como "docs/**" = "read".

En Linux, WSL y Windows nativo, un patrón ** de denegación de lectura sin límite de profundidad puede necesitar una expansión acotada antes de que se inicie el sandbox. Establece glob_scan_max_depth cuando uses un patrón sin límite como "**/*.env" = "deny":

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

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

El valor de glob_scan_max_depth debe ser de al menos 1. Con valores más altos se exploran más niveles de directorios antes de iniciar el sandbox, lo que puede aumentar el tiempo de inicio en Linux, WSL y Windows nativo. Si prefieres evitar la expansión acotada, enumera las profundidades de forma explícita con patrones como *.env, */*.env y */*/*.env.

Agrega raíces reutilizables del espacio de trabajo al perfil cuando quieras aplicar las mismas reglas a otras raíces además de la 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 que usa la sesión actual en tiempo de ejecución y a cada raíz habilitada que define el perfil.

Windows nativo admite como rutas absolutas tanto las rutas con letra de unidad, como D:\work, como las rutas UNC, como \\server\share.

Permisos de red

El acceso a la red y el filtrado de red se configuran por separado. Establece permissions.<name>.network.enabled = true para que los comandos puedan acceder 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 depende de ambos ajustes:

• Red desactivada: los comandos no pueden acceder a la red, independientemente de que el proxy esté habilitado.
• Red activada y proxy desactivado: los comandos tienen acceso directo a la red sin restricciones. No se aplican las reglas de dominio del perfil de permisos.
• Red y proxy activados: 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 establecer 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 de red del sandbox escucha en direcciones locales de forma predeterminada:

[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

Conserva los valores predeterminados de estos ajustes de escucha, a menos que necesites integrar el proxy con un entorno de ejecución específico. Las claves de red dangerously_* permiten hacer excepciones en entornos especializados y no deben usarse para el desarrollo local habitual.

Redes locales y privadas

Cuando el proxy de red está activo, Codex protege de forma predeterminada las redes locales y privadas frente a los ataques de reasignación de DNS y al acceso accidental a servicios locales. Para permitir de forma intencional el acceso a un destino local indicado como literal, agrega el nombre de host exacto o la dirección IP literal a la lista de destinos permitidos:

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

Establece allow_local_binding = true solo si el perfil necesita conectarse a nombres de host permitidos que se resuelven en direcciones locales o privadas:

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

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

Sockets Unix

El acceso a sockets Unix a través del proxy permite hacer una 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 sockets denegadas se excluyen de la lista efectiva de rutas permitidas.

Cuando habilites los sockets Unix, mantén los servicios de escucha del proxy vinculados a direcciones de loopback.

Migrar desde la configuración anterior del sandbox

Los perfiles de permisos reemplazan la combinación anterior de sandbox_mode y sandbox_workspace_write cuando quieres definir el comportamiento del sistema de archivos y de la red en un mismo perfil reutilizable. Usa un solo sistema por sesión.

Puntos de partida sugeridos:

• Para un flujo de trabajo de solo lectura, usa el perfil integrado :read-only o define un perfil personalizado que conceda acceso de lectura solo donde se necesite.
• Para editar archivos en el espacio de trabajo, usa el perfil integrado :workspace o define un perfil personalizado que permita la escritura 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 si quieres conceder de forma intencional el nivel más amplio de acceso local.

Los perfiles definen los permisos locales predeterminados de una sesión. Los requisitos gestionados por la organización pueden imponer restricciones adicionales, y la configuración del usuario no debe conceder un acceso más amplio que el que permiten esas restricciones. Consulta Configuración administrada para conocer las restricciones del sistema de archivos y de red que aplican los administradores.

Alcance y aplicación de las reglas

Acceso a la computadora local con Work Cloud y políticas de entorno

Revisa la política de cada entorno en el que se use el acceso a la computadora local con Work Cloud:

• Requisitos empresariales: en el modo Work con acceso local y dots, la política Global compatible rige el orquestador compartido en la nube cuando está habilitada la política administrada. Los requisitos de ejecución local aplicables rigen la computadora conectada.
• Ejecución en la nube: los contenedores del modo Work en la nube usan las políticas existentes de Work Cloud.
• Orden de las políticas locales: MDM y los requisitos anteriores para dispositivos administrados tienen prioridad sobre Agent Security. Agent Security tiene prioridad sobre el archivo de requisitos del sistema del dispositivo.
• Prioridad de las políticas: prevalece la política de mayor prioridad, incluso si una política de menor prioridad es más específica. Dentro de una misma política, tienen prioridad los ajustes de entorno específicos de un sistema operativo, seguidos de los ajustes de entorno para todos los sistemas operativos y, por último, de la política Global.

Algunos requisitos tienen reglas de combinación específicas para cada campo. Consulta Configuración administrada y la Referencia de configuración para conocer los campos compatibles y los límites del entorno de ejecución. No des por hecho que Work Cloud admite los perfiles de permisos de Codex que se muestran aquí.

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

Qué controlan los perfiles

• Ejecución de comandos locales: los perfiles de permisos rigen los comandos que se ejecutan en el sandbox de tu computadora. Los conectores, los servidores MCP, las funciones de navegador o de uso de la computadora, la configuración de los entornos de Codex Cloud y las elevaciones de permisos aprobadas tienen sus propios controles.
• Escritura en el sistema de archivos: un perfil con permisos de escritura puede hacer cambios persistentes. Trata como sensibles los cambios en scripts, pasos de compilación, hooks del gestor de paquetes, archivos de inicio del shell y directorios compartidos, ya que otras herramientas o usuarios pueden ejecutar esos archivos más adelante fuera del contexto original del sandbox.
• Destinos del tráfico saliente: las reglas de dominio de red limitan los destinos del tráfico de los comandos que se ejecutan en el sandbox únicamente mientras el proxy de red está activo. Estas reglas no determinan si un destino permitido es confiable. Las reglas de autorización con comodines siguen teniendo un alcance amplio.
• Servicios locales: un proxy de red activo bloquea de forma predeterminada los destinos de redes locales y privadas. Incluir localhost, direcciones IP privadas o sockets Unix en la lista de destinos permitidos, o establecer allow_local_binding = true, habilita de forma explícita el acceso a servicios locales.

Qué queda fuera del control del proxy de red

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

• Búsqueda web: la herramienta de búsqueda alojada usa su propia configuración de acceso. Para controlarla, usa web_search y, en los clientes administrados, allowed_web_search_modes. La opción 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 que usan conectores tienen sus propias conexiones del lado del servicio, permisos del espacio de trabajo y ajustes de la app o herramienta.
• Servidores MCP: los servidores MCP locales y remotos usan su propio proceso o mecanismo de 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 y las acciones de uso de la computadora tienen sus propios controles de funciones y de aprobación.
• Tráfico de servicios de Codex: las solicitudes de modelos, autenticación y otros servicios del cliente usan la configuración independiente de HTTP y del proxy del sistema que tiene el cliente.
• Codex Cloud: estas tareas usan la configuración de red de su propio entorno. Codex Cloud (versión anterior) tiene una configuración de acceso a internet independiente.

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

Cómo se aplican las restricciones

• 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 fuera del sandbox sin avisar.
• En Linux y WSL, Codex usa bubblewrap y seccomp para aplicar las restricciones del sistema de archivos. La opción anterior de Landlock no puede aislar los sockets Unix de app-server y se rechaza para las políticas que restringen el sistema de archivos. Desactiva features.use_legacy_landlock al actualizar. Los hosts que bloquean las operaciones necesarias de bubblewrap no pueden aplicar estas políticas.
• En Windows, MXC usa el aislamiento de procesos para aplicar los permisos del sistema de archivos y de red. Revisa la compatibilidad de MXC antes de habilitarlo. La alternativa anterior elevated usa cuentas de usuario dedicadas al sandbox con privilegios reducidos, límites de permisos del sistema de archivos y reglas de firewall. unelevated es una alternativa anterior con un aislamiento de red más débil que no puede aplicar todas las excepciones que separan los permisos de lectura y escritura. Por eso se rechazan las políticas incompatibles. Usa WSL cuando necesites el modelo de sandbox de Linux.

Recomendaciones de uso

Elige el perfil más restrictivo que permita completar la tarea, especialmente si concedes permisos de escritura o de acceso saliente a la red. Ajusta la política de aprobación, el manejo de secretos y las reglas de autorización a ese nivel de acceso.

Perfiles habituales

Solo lectura con una lista de dominios 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 ejemplo de perfil de permisos permite que Codex escriba en las carpetas de tu espacio de trabajo y le deniega la lectura del resto del sistema de archivos, con las excepciones limitadas que determina :minimal.

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# paths such as .git/, .agents/, .codex/, and .aws/ 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 limitar el alcance de una lista amplia de destinos permitidos.