Permisos

La configuración administrada allowed_permission_profiles es la excepción: hace que Codex utilice perfiles de permisos. Elimina configuraciones anteriores como sandbox_mode y [sandbox_workspace_write] antes de desplegar una lista de permitidos de perfiles administrada. Para un despliegue empresarial con versiones mixtas, puedes mantener el requisito administrado allowed_sandbox_modes como restricción temporal de compatibilidad hasta que todos los clientes ejecuten Codex 0.138.0 o una versión posterior.

Los perfiles de permisos te permiten aplicar límites de privilegios mínimos 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 llegar los comandos.

Usa perfiles para conceder a Codex acceso suficiente para el chat actual sin otorgarle un acceso amplio a tu equipo o red. Por ejemplo, un perfil de solo lectura puede permitir que Codex inspeccione un proyecto sin editarlo, mientras que un perfil con capacidad 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 Ámbito y aplicación para conocer los detalles y las salvedades específicos de cada plataforma.

Para obtener información sobre 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 local de comandos en modo de solo lectura.
• :workspace permite escrituras dentro de las raíces activas del espacio de trabajo y los directorios temporales del sistema.
• :danger-full-access elimina las restricciones del entorno aislado local y solo debe utilizarse cuando ese acceso amplio sea intencional.

Crea un perfil con nombre en [permissions.<name>] y, a continuación, establece la clave de nivel superior default_permissions en el nombre de ese perfil o en 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 la configuración administrada requirements.toml. Una vez que allowed_permission_profiles está presente, los perfiles omitidos se deniegan, incluidos los perfiles integrados omitidos y los que se añadan en futuras versiones de Codex. Consulta Controlar los perfiles de permisos disponibles para ver la configuración administrada recomendada.

Los perfiles personalizados utilizan dos conceptos relacionados:

• [permissions.<name>.workspace_roots] añade directorios concretos que deben contar como 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 más las raíces definidas anteriormente por el perfil.

Los perfiles también utilizan el modelo normal de capas de configuración. Las capas con mayor precedencia pueden añadir o sustituir entradas con el mismo nombre de perfil sin volver a declarar todo el perfil.

Por ejemplo, una configuración a nivel de organización y otra a nivel de 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 participan en el 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 de tiempo de ejecución que necesitan las herramientas habituales para desarrolladores.
• Aplica las mismas reglas de raíz del espacio de trabajo a la sesión actual y a las raíces definidas por el perfil.
• Mantiene en modo de solo lectura la configuración relacionada con el IDE, como .devcontainer/, en cada raíz.
• Deniega los archivos de entorno coincidentes mediante una regla glob.
• Permite el acceso a la red únicamente mediante la política de dominios configurada.

Dentro de un perfil activo, las reglas de denegación más específicas siguen vigentes incluso cuando una ruta más amplia se puede leer o escribir. Por ejemplo, un perfil puede hacer que las raíces del espacio de trabajo sean escribibles y, al mismo tiempo, establecer una ruta .env coincidente en deny.

Ampliar un perfil

Usa extends cuando un perfil sea casi igual a uno integrado o a otro perfil con nombre. Es preferible ampliar un perfil integrado en lugar de comenzar desde cero para conservar las protecciones de referencia. Por ejemplo, ampliar :workspace mantiene en modo de solo lectura el directorio .codex de la raíz del espacio de trabajo, salvo que lo anules de forma explícita. Establece el perfil principal una vez y, después, añade o anula 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 denegados los archivos que coinciden con .env y permite solicitudes a api.openai.com. Un perfil puede ampliar :read-only, :workspace u otro perfil con nombre. No puede ampliar :danger-full-access; Codex también rechaza perfiles principales desconocidos y ciclos de herencia.

Especificación de configuración

Permisos del sistema de archivos

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

Las entradas más específicas prevalecen sobre las más amplias. Cuando dos entradas apuntan a la misma ruta, deny tiene precedencia sobre write, y write tiene precedencia sobre read.

Esta precedencia permite que un perfil describa primero un área de trabajo amplia y después excluya archivos o directorios que deben permanecer ilegibles:

[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 siendo escribible, .devcontainer/ sigue siendo legible sin volverse escribible, y los archivos de entorno coincidentes permanecen inaccesibles para los comandos del entorno aislado.

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

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

Formas de ruta compatibles:

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

Utiliza :root solo cuando un perfil necesite intencionalmente una cobertura de lectura amplia:

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

Utiliza 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 su raíz del espacio de trabajo. Se rechaza el recorrido al directorio principal, como ../other-repo.

Denegar lecturas con rutas exactas o globs

Utiliza deny para archivos o subárboles que Codex no deba leer, incluso cuando una regla de perfil más amplia conceda acceso en las proximidades. Las rutas exactas funcionan bien para ubicaciones estables como ~/.ssh. Los patrones glob funcionan mejor cuando un perfil necesita abarcar una familia de archivos confidenciales cuyas ubicaciones exactas varían entre repositorios.

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

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

Esta regla deniega las lecturas de los archivos .env coincidentes que se encuentren bajo cada raíz del espacio de trabajo definida por el perfil o en tiempo de ejecución. Úsala cuando quieras conservar las escrituras normales en el espacio de trabajo y, al mismo tiempo, mantener ilegibles los archivos de entorno, secretos generados u otros archivos similares que contengan credenciales.

Los patrones glob deny son compatibles como reglas de denegación de lectura. Los globs read o write son menos portables en los entornos aislados de Linux, WSL y Windows nativo, por lo que, cuando sea posible, es preferible utilizar 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ímites puede necesitar una expansión previa acotada antes de que se inicie el entorno aislado. Establece glob_scan_max_depth cuando utilices 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. Los valores superiores analizan a mayor profundidad antes del inicio del entorno aislado, lo que puede añadir trabajo de inicio en Linux, WSL y Windows nativo. Si prefieres no utilizar una expansión acotada, enumera profundidades explícitas como *.env, */*.env y */*/*.env.

Añade al perfil raíces reutilizables del espacio de trabajo cuando deban aplicarse las mismas reglas a más elementos que 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 :workspace_roots a las raíces del espacio de trabajo en tiempo de ejecución de la sesión actual y a cada raíz del espacio de trabajo habilitada y definida por el perfil.

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

Permisos de red

El acceso a la red y el filtrado de red son configuraciones independientes. Establece permissions.<name>.network.enabled = true para permitir que los comandos accedan a la red y habilita features.network_proxy para aplicar las reglas de dominios 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 dominios del perfil de permisos no se aplican.
• Red activada, proxy activado: los comandos utilizan el proxy, que aplica las reglas de dominios del perfil. Si el proxy activo no tiene dominios permitidos, bloquea los destinos externos.

Añadir [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 del entorno aislado de red se enlaza de forma predeterminada a agentes de escucha 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 estos ajustes de los agentes de escucha en sus valores predeterminados, salvo que estés integrando un entorno de ejecución específico. Las claves de red dangerously_* son vías de escape para entornos especializados y no deben utilizarse para el desarrollo local habitual.

Redes locales y privadas

Cuando el proxy de red está activo, Codex aplica de forma predeterminada una protección de red local/privada como defensa contra la revinculación de DNS y el acceso accidental a servicios locales. Para permitir intencionalmente un destino local literal, incluye en la lista de permitidos el host o literal de IP exacto:

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

Establece allow_local_binding = true solo cuando el perfil deba llegar 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 Unix

El uso de proxy para sockets Unix es una vía de escape local para herramientas como Docker. Utilízalo con moderación:

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

Utiliza deny para rechazar una ruta de socket, incluida una entrada de permiso heredada. Las rutas de socket denegadas se omiten de la lista de permitidos efectiva.

Cuando los sockets Unix estén habilitados, mantén los agentes de escucha del proxy enlazados a direcciones de bucle invertido.

Migrar desde la configuración anterior del entorno aislado

Los perfiles de permisos sustituyen la combinación anterior de sandbox_mode y sandbox_workspace_write cuando quieras que un único perfil reutilizable describa tanto el comportamiento del sistema de archivos como el de la red. Utiliza un sistema u otro en una sesión, pero no ambos.

Puntos de partida recomendados:

• Para un flujo de trabajo de solo lectura, utiliza el perfil integrado :read-only o define un perfil personalizado con acceso de lectura solo donde sea necesario.
• Para editar el espacio de trabajo, utiliza el perfil integrado :workspace o define un perfil personalizado que escriba mediante :workspace_roots y añada únicamente las rutas adicionales temporales o de caché que necesite el flujo de trabajo.
• Para una ejecución local sin restricciones, utiliza :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 aún pueden añadir restricciones que la configuración del usuario no debe ampliar. Consulta Configuración administrada para conocer las restricciones del sistema de archivos y la red aplicadas por los administradores.

Ámbito y aplicación

Los perfiles de permisos definen los límites para la ejecución local de comandos en el entorno aislado. Utilízalos junto con las políticas de aprobación y los controles independientes para búsquedas web, conectores, servidores MCP, el navegador integrado, Computer Use y Codex cloud.

Qué controlan los perfiles

• Ejecución local de comandos: los perfiles de permisos rigen los comandos del entorno aislado que se ejecutan en tu equipo. Los conectores, los servidores MCP, las superficies del navegador o de Computer Use, la configuración de entornos de Codex cloud y los escalamientos aprobados utilizan sus propios controles.
• Escrituras en el sistema de archivos: un perfil con capacidad de escritura puede crear cambios persistentes. Considera confidenciales las escrituras en scripts, pasos de compilación, enlaces del gestor de paquetes, archivos de inicio del shell y directorios compartidos, porque otras herramientas o usuarios pueden ejecutar esos archivos posteriormente fuera del contexto del entorno aislado original.
• Destinos salientes: las reglas de dominios de red limitan los destinos a los que puede dirigirse el tráfico de los comandos en el entorno aislado solo mientras el proxy de red está activo. No determinan si un destino permitido es de confianza, y las reglas de permiso con comodines siguen siendo amplias.
• 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 permitidos, o establecer allow_local_binding = true, abre explícitamente el acceso a servicios locales.

Qué no controla el proxy de red

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

• Búsqueda web: la herramienta de búsqueda alojada utiliza su propia configuración de acceso. Utiliza web_search y, para 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 respaldadas por conectores utilizan sus propias conexiones del lado del servicio, permisos del espacio de trabajo y configuración de la app o herramienta.
• Servidores MCP: los servidores MCP locales y remotos utilizan su propio proceso o transporte. Contrólalos con la configuración mcp_servers y listas de servidores permitidos administradas.
• Navegador y Computer Use: la navegación del navegador y las acciones de Computer Use utilizan sus propios controles de funciones y aprobación.
• Tráfico del servicio de Codex: las solicitudes del modelo, de autenticación y de otros servicios del cliente utilizan la configuración independiente del proxy HTTP y del sistema del cliente.
• Codex cloud: estas tareas utilizan la propia configuración de acceso a Internet de su entorno.

Para limitar estas superficies, configura cada capacidad directamente. Una lista de comandos con acceso a la red no es una política de red global para todas las acciones que Codex puede realizar.

Cómo funciona la aplicación

• En macOS, Codex utiliza perfiles del entorno aislado Seatbelt. Si el entorno aislado de la plataforma no puede aplicar la política seleccionada, Codex se niega a ejecutar el comando en lugar de ejecutarlo sin entorno aislado de forma silenciosa.
• En Linux y WSL, Codex utiliza bubblewrap y seccomp, con Landlock disponible para rutas alternativas de compatibilidad. La ruta de aplicación más sólida depende de los espacios de nombres de usuario y de la compatibilidad del kernel; los hosts de contenedores restringidos pueden forzar rutas de compatibilidad, y las políticas divididas no compatibles se rechazan.
• En Windows nativo, el entorno aislado elevated es el más sólido porque puede utilizar usuarios dedicados del entorno aislado con menos privilegios, límites de permisos del sistema de archivos y reglas del cortafuegos. El entorno aislado unelevated es una alternativa con un aislamiento de red más débil y no puede aplicar todas las exclusiones independientes de lectura/escritura, por lo que las políticas no compatibles se rechazan. Utiliza WSL cuando necesites el modelo de entorno aislado de Linux.

Orientación operativa

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

Perfiles habituales

Solo lectura con lista de redes permitidas

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 hará que Codex pueda escribir en las carpetas de tu espacio de trabajo y, al mismo tiempo, denegará las lecturas del resto del sistema de archivos (con excepciones limitadas, según lo determinado por :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 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"

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