Codex CLI — Configuración · Agentes de IA para programar

Codex se configura con archivos TOML. La configuración principal de usuario vive en ~/.codex/config.toml (con CODEX_HOME puedes usar un directorio distinto de ~/.codex).

Dónde viven los archivos y en qué orden mandan

Orden de resolución, de mayor a menor prioridad:

Flags del CLI y sobrescrituras con -c/--config
Archivos .codex/config.toml del proyecto (desde la raíz hasta el directorio actual; gana el más cercano; sólo en proyectos de confianza)
El archivo de perfil seleccionado con --profile nombre (~/.codex/nombre.config.toml)
La configuración de usuario ~/.codex/config.toml
La configuración del sistema /etc/codex/config.toml (Unix)
Los valores por defecto

Los administradores pueden además imponer restricciones con un requirements.toml gestionado (incluido allow_managed_hooks_only = true).

Configuración del proyecto y confianza

La configuración de proyecto vive en .codex/config.toml y sólo se aplica en proyectos de confianza:

# ~/.codex/config.toml
[projects."/Users/tu-usuario/code/mi-repo"]
trust_level = "trusted"   # o "untrusted"

Algunas claves se ignoran en la configuración de proyecto (con un aviso al arrancar): openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url y otel.

Campos clave

Un ~/.codex/config.toml representativo:

model = "gpt-5.6"
model_reasoning_effort = "medium"        # minimal | low | medium | high | xhigh (xhigh depende del modelo)
model_reasoning_summary = "auto"         # auto | concise | detailed | none
model_verbosity = "medium"               # low | medium | high

approval_policy = "on-request"           # untrusted | on-request | never | { granular = {...} }
sandbox_mode = "workspace-write"         # read-only | workspace-write | danger-full-access

web_search = "cached"                    # disabled | cached | indexed | live
file_opener = "vscode"                   # vscode | vscode-insiders | windsurf | cursor | none
review_model = "gpt-5.6"                 # modelo específico para /review

[sandbox_workspace_write]
network_access = false                   # activa la red en workspace-write
writable_roots = ["../shared-lib"]

[history]
persistence = "save-all"                 # save-all | none

[tui]
notifications = true
notification_method = "auto"             # auto | osc9 | bel
alternate_screen = true

Otras claves destacadas:

Clave	Para qué sirve
`approvals_reviewer`	`user` o `auto_review` — enruta las peticiones de aprobación que apliquen a un subagente revisor
`default_permissions` + `[permissions.<nombre>]`	Perfiles de permisos con nombre; los integrados son `:read-only`, `:workspace` y `:danger-full-access`; los perfiles admiten `extends`, reglas de `filesystem` y reglas de `network`
`[mcp_servers.<id>]`	Definiciones de servidores MCP — ver MCP
`[agents]`	Ajustes de los subagentes — ver Subagentes
`[[skills.config]]`	Activa o desactiva skills por ruta — ver Skills
`[features]`	Feature flags (ver más abajo)
`plan_mode_reasoning_effort`	Esfuerzo de razonamiento específico del modo plan
`hooks` / `[hooks.<Evento>]`	Hooks de ciclo de vida en línea (`PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, etc.); los hooks también se cargan desde `~/.codex/hooks.json` y `<repo>/.codex/hooks.json`
`notify`	Comando (como array) que recibe un payload JSON (por ahora sólo eventos `agent-turn-complete`)
`project_doc_max_bytes`	Tope del tamaño combinado de los AGENTS.md (32 KiB por defecto); ver también `project_doc_fallback_filenames` y `project_root_markers` (por defecto `[".git"]`)
`cli_auth_credentials_store`	`file`, `keyring` o `auto`
`[shell_environment_policy]`	`inherit` (`all`/`core`/`none`), `set`, `filters` (patrón → `include`/`exclude`) e `ignore_default_excludes` (true por defecto: no filtra automáticamente los nombres tipo KEY/SECRET/TOKEN)
`[otel]`	Exportación opcional de logs, métricas y trazas por OpenTelemetry
`[analytics] enabled = false`	Desactiva las métricas de uso anónimas
`[windows] sandbox`	Modo del sandbox nativo de Windows: `"elevated"` o `"unelevated"`
`model_providers.<id>`	Proveedores de modelos propios (`base_url`, `env_key`, `wire_api = "responses"` únicamente, cabeceras, autenticación por comando); IDs reservados: `openai`, `ollama`, `lmstudio`; incluye `amazon-bedrock`; `openai_base_url` para proxies sencillos
`oss_provider`	`lmstudio` u `ollama`
`forced_login_method`, `forced_chatgpt_workspace_id`	Restricciones de autenticación impuestas por el administrador
`check_for_update_on_startup`, `hide_agent_reasoning`, `show_raw_agent_reasoning`, `compact_prompt`, `model_auto_compact_token_limit`, `model_context_window`, `tool_output_token_limit`, `sqlite_home`, `log_dir`	Ajustes varios de comportamiento

Perfiles

--profile nombre carga ~/.codex/config.toml y luego superpone ~/.codex/nombre.config.toml. Los archivos de perfil usan claves de primer nivel — no las anides bajo una tabla [profiles.nombre].

Cambio incompatible en Codex 0.134.0: --profile ya no lee [profiles.<nombre>] de config.toml, y se eliminó el selector profile = "nombre" de primer nivel. Migra a archivos separados por perfil (~/.codex/<nombre>.config.toml).

# ~/.codex/work.config.toml
model = "gpt-5.6"
approval_policy = "untrusted"

codex --profile work

Feature flags

Los feature flags viven en la tabla [features] y también se activan o desactivan con codex --enable <nombre> / --disable <nombre> o con codex features enable|disable <nombre>.

Funcionalidad	Por defecto	Notas
`apps`	true
`goals`	true	Objetivos persistentes (`/goal`)
`hooks`	true	Hooks de ciclo de vida
`fast_mode`	true
`memories`	false	Experimental
`multi_agent`	true	Subagentes
`personality`	true
`remote_plugin`	true
`shell_snapshot`	true
`shell_tool`	true
`unified_exec`	true (salvo en Windows)	Terminales en segundo plano, `/ps`
`network_proxy`	false	Proxy experimental con lista blanca de dominios
`context_management.experimental_mode`	false	Requiere iniciar sesión con ChatGPT Plus/Pro/Pro Lite
`code_mode`	false	En desarrollo
`rollout_budget`	false
`prevent_idle_sleep`	false
`skill_mcp_dependency_install`	true
`enable_request_compression`	true

Los antiguos interruptores web_search / web_search_cached / web_search_request están obsoletos — usa la clave web_search de primer nivel.

Última verificación: 2026-09-07

Fuentes oficiales:

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.