Sandbox de Codex y config.toml: permisos, aprobaciones y red

El sandbox de Codex es el límite técnico de los comandos locales: determina qué archivos pueden modificar y si disponen de red. approval_policy responde a otra pregunta: cuándo debe Codex detenerse para pedir permiso antes de cruzar un límite. Cambiar una opción no modifica automáticamente la otra. Según la documentación oficial de Sandbox, los procesos iniciados por Codex —como git, gestores de paquetes y test runners— heredan la misma frontera.

Para trabajo local habitual, workspace-write con on-request ofrece una base útil: Codex continúa dentro del proyecto y puede pedir aprobación al necesitar salir. read-only sirve para inspeccionar. danger-full-access elimina las restricciones de filesystem y network; es una decisión de confianza, no el arreglo genérico para una ruta equivocada o un fallo de instalación. Del mismo modo, approval_policy = "never" significa que no habrá prompts, no que esa clave conceda acceso total.

Después identifica la capa propietaria. Los valores personales viven en ~/.codex/config.toml. Un repositorio de confianza puede añadir .codex/config.toml; los modos reutilizables usan profile y las pruebas puntuales, overrides de CLI. Copiar una configuración completa para arreglar un permiso puede cambiar también model, provider, network y MCP y ocultar la causa original.

Antes de tocar una capa, respalda solo el archivo afectado. Borrar todo ~/.codex para corregir una tabla puede eliminar también credenciales, perfiles, reglas y estado que siguen funcionando.

La precedencia decide qué valor es efectivo

Codex resuelve la configuración ordinaria de mayor a menor prioridad:

1. opciones CLI y --config;
2. archivos .codex/config.toml de un proyecto de confianza, ganando el más cercano al directorio actual;
3. el perfil elegido con --profile;
4. ~/.codex/config.toml;
5. /etc/codex/config.toml en Unix, si existe;
6. valores integrados.

Esta es la secuencia actual de Configuration precedence. Si cambias el archivo personal y no ocurre nada, busca primero un override de CLI, proyecto o perfil.

Hay claves que un proyecto no puede sobrescribir: clases machine-local de provider, autenticación, selección de perfil, notificaciones y telemetría. La lista actual incluye model_provider, model_providers, profile y otel. Consulta el listado completo en Configuration reference y coloca esas claves en el nivel de usuario.

Elige por separado límite y autonomía

Una base de bajo riesgo puede tener solo dos líneas:

toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Cada control tiene una responsabilidad distinta:

Los modos comunes actuales son read-only, workspace-write y danger-full-access; las políticas, untrusted, on-request y never. En CLI, /permissions abre el selector; IDE y desktop app usan el control bajo el composer. Las opciones visibles dependen de versión y política, así que consulta How permissions work en lugar de seguir una captura antigua.

Si solo necesitas escribir en un segundo repositorio, añade una raíz concreta sin abrir todo el host:

toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
writable_roots = ["/absolute/path/to/second-repo"]
network_access = false

No uses el directorio personal ni la raíz del disco como writable root universal. network_access controla la red saliente de los subprocess dentro del sandbox workspace-write. No es el control de web search, apps, MCP o remote browser. Que el navegador obtenga una página no demuestra que npm install o una prueba con API dispongan de internet.

El sistema operativo cambia el primer fallo posible

El objetivo de seguridad es común, pero la aplicación es nativa de cada plataforma. La guía oficial Getting started permite separar estos casos:

Ubuntu/Debian:

bash
sudo apt install bubblewrap

Fedora:

bash
sudo dnf install bubblewrap

Si persiste el aviso de user namespace o AppArmor, sigue el procedimiento de tu distribución en la página oficial antes de desactivar una protección global. Dentro de Docker, el contenedor exterior puede bloquear namespace o seccomp necesarios para bwrap. Confirma primero que ese contenedor aporta el aislamiento previsto; usar un modo más amplio dentro de él no equivale a usar full access directamente sobre el host.

Los perfiles actuales son archivos independientes

Un modo de revisión conservador puede vivir en:

toml
# ~/.codex/revision.config.toml
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"

Se activa así:

bash
codex --profile revision

El perfil solo necesita las diferencias respecto a la base. El formato puede cambiar entre versiones del cliente, por lo que conviene consultar Advanced Config: Profiles antes de copiar ejemplos antiguos con [profiles.name].

El provider es una ruta específica, no parte del mínimo universal

Bedrock, Azure y un provider personalizado tienen contratos diferentes. Antes de copiar su bloque, confirma cuatro hechos: qué superficie de Codex vas a usar, qué identificador de modelo o deployment espera esa ruta, qué endpoint es correcto y dónde obtiene la credencial el proceso.

Una tabla de provider puede analizarse bien aunque el endpoint no exista, el modelo no esté desplegado, la clave pertenezca a otra cuenta o la IDE no herede la variable de entorno. Por eso conviene mantener el baseline general separado de la guía del provider concreto.

No pegues una clave real en el TOML de un repositorio ni en un mensaje de soporte. Cuando el campo admita una variable de entorno, guarda el nombre de la variable y verifica por separado que el proceso CLI, IDE, WSL o runner pueda verla.

Un MCP tiene sintaxis, transporte, credencial y tools

Para un servidor STDIO local:

toml
[mcp_servers.docs]
command = "docs-server"
args = ["--read-only"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Para streamable HTTP:

toml
[mcp_servers.tareas]
url = "https://mcp.example.internal/mcp"
bearer_token_env_var = "TAREAS_MCP_TOKEN"
enabled = true

La guía oficial de Model Context Protocol distingue STDIO, streamable HTTP, OAuth, headers desde entorno, timeouts y listas de tools.

Después de editar, usa los comandos que ofrezca tu versión instalada:

bash
codex mcp list
codex mcp --help

Para un servidor OAuth existe codex mcp login <server-name>. Aparecer en la lista prueba que Codex leyó la definición; no prueba que el ejecutable arranque, la URL responda, la autenticación funcione ni que una tool concreta sea correcta.

Diagnostica desde el primer límite sin demostrar

Versiones recientes exponen --strict-config y doctor. Comprueba primero tu instalación:

bash
codex --version
codex --help
codex doctor --help

Si aparecen esas opciones, una pasada de solo lectura es:

bash
codex --strict-config doctor --summary

El modo strict convierte campos no reconocidos en error. doctor revisa instalación, config, auth y runtime. Ninguno sustituye una petición real al provider o una llamada a la tool MCP.

En Business o Enterprise, requirements.toml puede limitar approval, permission profiles, web search, MCP permitidos, plugins y features. Ante un conflicto, el cliente puede volver a un valor compatible y mostrar un aviso. Admin-enforced requirements describe esa frontera. Mover la misma opción prohibida a otro archivo local no la supera.

Haz que cada cambio tenga un único resultado observable. Demuestra primero lectura, luego una escritura dentro del workspace y una prueba propia del proyecto; solo después prueba el directorio o red adicionales que la tarea necesita. Así separas config no cargada, rechazo correcto del sandbox, approval no disponible y fallo del SO al crear el entorno aislado.

Si la decisión real es elegir agente de programación y no configurar Codex, consulta la comparación entre Claude Code y Codex.