Español

Aprobaciones y seguridad del agente

Cómo operar Codex de forma segura con aislamiento, aprobaciones y controles de red

Codex ayuda a proteger su código y sus datos, y reduce el riesgo de uso indebido.

De forma predeterminada, el agente se ejecuta con el acceso a la red desactivado. Localmente, Codex utiliza un entorno aislado aplicado por el sistema operativo que limita los recursos a los que puede acceder (por lo general, al espacio de trabajo actual), además de una política de aprobación que controla cuándo debe detenerse y pedirle permiso antes de actuar.

Para obtener una explicación general de cómo funciona el aislamiento en la aplicación de escritorio de ChatGPT, Codex CLI y la extensión para IDE, consulte aislamiento. Para obtener una descripción general más amplia de la seguridad empresarial, consulte el informe técnico de seguridad de Codex.

Entorno aislado y aprobaciones

Los controles de seguridad de Codex se componen de dos capas que funcionan conjuntamente:

  • Modo de entorno aislado: Lo que Codex puede hacer técnicamente (por ejemplo, dónde puede escribir y si puede acceder a la red) cuando ejecuta comandos generados por el modelo.
  • Política de aprobación: Cuándo Codex debe pedirle permiso antes de ejecutar una acción (por ejemplo, salir del entorno aislado, usar la red o ejecutar comandos fuera de un conjunto de confianza).

Codex utiliza distintos modos de entorno aislado según dónde se ejecute:

  • Codex cloud: Se ejecuta en contenedores aislados administrados por OpenAI, lo que impide el acceso al sistema anfitrión o a datos no relacionados. Utiliza un modelo de ejecución de dos fases: la configuración se ejecuta antes de la fase del agente y puede acceder a la red para instalar las dependencias especificadas; luego, la fase del agente se ejecuta sin conexión de forma predeterminada, a menos que habilite el acceso a Internet para ese entorno. Los secretos configurados para entornos en la nube solo están disponibles durante la configuración y se eliminan antes de que comience la fase del agente.
  • Codex CLI / extensión para IDE: Los mecanismos del sistema operativo aplican las políticas del entorno aislado. La configuración predeterminada incluye la ausencia de acceso a la red y permisos de escritura limitados al espacio de trabajo activo. Puede configurar el entorno aislado, la política de aprobación y los ajustes de red según su tolerancia al riesgo.

En el preajuste Auto (por ejemplo, --sandbox workspace-write --ask-for-approval on-request), Codex puede leer archivos, realizar modificaciones y ejecutar comandos automáticamente en el directorio de trabajo.

Codex solicita aprobación para editar archivos fuera del espacio de trabajo o ejecutar comandos que requieren acceso a la red. Si quiere conversar o planificar sin realizar cambios, cambie al modo read-only con el comando /permissions.

Codex también puede solicitar aprobación para llamadas a herramientas de aplicaciones (conectores) que indiquen que tienen efectos secundarios, incluso cuando la acción no sea un comando del shell ni un cambio de archivo. Las llamadas destructivas a herramientas de aplicaciones/MCP siempre requieren aprobación cuando la herramienta incluye una anotación de acción destructiva, aunque también incluya otras indicaciones (por ejemplo, indicaciones de solo lectura).

Acceso a la red

Para Codex cloud, consulte acceso del agente a Internet para habilitar el acceso completo a Internet o una lista de dominios permitidos.

En la aplicación de escritorio de ChatGPT, Codex CLI o la extensión para IDE, el modo de entorno aislado workspace-write predeterminado mantiene desactivado el acceso a la red, a menos que lo habilite en su configuración:

[sandbox_workspace_write]
network_access = true

Aislamiento de red

El acceso a la red se controla mediante reglas de destino que se aplican a los scripts, programas y subprocesos generados por los comandos. Cuando el acceso de los comandos a la red ya está habilitado, active la función network_proxy para restringir ese tráfico a la política de red que configure.

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

Para una sesión puntual de CLI, utilice la forma abreviada booleana cuando solo necesite el interruptor, y la forma de tabla cuando también establezca opciones de política:

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

La función cambia la manera en que se aplica el acceso a la red habilitado; no concede acceso a la red por sí sola. Utilice la configuración sandbox_workspace_write.network_access con workspace-write para decidir si los comandos tienen acceso a la red:

  • Red desactivada + network_proxy activado: la red permanece desactivada y la función no tiene ningún efecto.
  • Red activada + network_proxy desactivado: la red permanece activada con acceso saliente directo sin restricciones.
  • Red activada + network_proxy activado: la red permanece activada y el tráfico saliente queda restringido por la política de red configurada.

Los requisitos experimental_network administrados por el administrador son independientes del interruptor de la función del usuario. Pueden configurar e iniciar la red aislada sin features.network_proxy, pero no activan el acceso a la red cuando el entorno aislado activo lo mantiene desactivado. Consulte Configuración administrada para conocer la estructura requirements.toml del lado del administrador.

Política de red

Las reglas de dominio priorizan la lista de permitidos:

  • Los hosts exactos solo coinciden consigo mismos.
  • *.example.com coincide con subdominios como api.example.com, pero no con example.com.
  • **.example.com coincide tanto con el dominio raíz como con los subdominios.
  • Una regla de permiso global * coincide con cualquier host público que no esté denegado. Considere * como acceso amplio a la red y prefiera reglas específicas siempre que sea posible.
  • deny siempre prevalece sobre allow, y el comodín global * solo es válido para reglas de permiso.

Destinos locales y privados

De forma predeterminada, allow_local_binding = false bloquea los destinos de bucle invertido, de vínculo local y privados:

  • Excepciones específicas: añada una dirección IP local literal exacta o una regla de permiso localhost cuando un comando necesite un destino local.
  • Acceso más amplio: establezca allow_local_binding = true únicamente cuando quiera permitir de forma intencional un acceso local/privado más amplio.
  • Comodines: las reglas con comodines no cuentan como excepciones locales explícitas.
  • Direcciones resueltas: los nombres de host que se resuelvan en direcciones IP locales/privadas permanecen bloqueados, aunque coincidan con la lista de permitidos.

Protecciones contra la revinculación de DNS

Antes de permitir un nombre de host, Codex realiza una comprobación de mejor esfuerzo de DNS y de clasificación de IP:

  • Las consultas que fallan o agotan el tiempo de espera se bloquean.
  • Los nombres de host que se resuelven en direcciones no públicas se bloquean.
  • La comprobación reduce el riesgo de revinculación de DNS, pero no lo elimina. Para impedir por completo la revinculación, sería necesario fijar las direcciones IP resueltas en toda la capa de transporte.

Si el DNS hostil forma parte del modelo de amenazas, aplique también controles de salida en una capa inferior.

Ajustes peligrosos

Dos ajustes amplían deliberadamente el límite de confianza:

  • dangerously_allow_non_loopback_proxy = true puede exponer escuchas de proxy más allá de la interfaz de bucle invertido.
  • dangerously_allow_all_unix_sockets = true omite la lista de permitidos de sockets Unix.

Utilícelos únicamente en entornos estrictamente controlados. Cuando el proxy de sockets Unix está habilitado, las escuchas permanecen limitadas al bucle invertido aunque se haya solicitado vincularlas fuera de él, por lo que la red aislada no se convierte en un puente remoto hacia los daemons locales.

network_proxy está desactivado de forma predeterminada. Cuando lo habilita:

Ajuste Valor predeterminado Comportamiento
enabled false Inicia la red aislada solo cuando el acceso de los comandos a la red ya está activado.
domains sin establecer Utiliza el comportamiento de lista de permitidos, por lo que no se permite ningún destino externo hasta que añada reglas allow. Admite hosts exactos, comodines específicos y reglas de permiso globales *; deny siempre prevalece.
unix_sockets sin establecer No se permite ningún destino de socket Unix hasta que añada reglas allow explícitas.
allow_local_binding false Bloquea destinos de redes locales y privadas, a menos que añada una dirección IP local literal exacta o una regla de permiso localhost, o habilite explícitamente un acceso local/privado más amplio.
enable_socks5 true Expone la compatibilidad con SOCKS5 cuando la política lo permite.
enable_socks5_udp true Permite UDP sobre SOCKS5 cuando SOCKS5 está disponible.
allow_upstream_proxy true Permite que la red aislada respete un proxy ascendente del entorno.
dangerously_allow_non_loopback_proxy false Mantiene los extremos de escucha en la interfaz de bucle invertido, a menos que los exponga deliberadamente más allá de localhost.
dangerously_allow_all_unix_sockets false Mantiene el acceso a sockets Unix basado en una lista de permitidos, a menos que omita deliberadamente esa protección.

También puede controlar la herramienta de búsqueda web sin conceder acceso completo a la red a los comandos generados. De forma predeterminada, Codex utiliza una caché de búsqueda web para acceder a los resultados. La caché es un índice de resultados web mantenido por OpenAI, por lo que el modo de caché devuelve resultados indexados previamente en lugar de obtener páginas en vivo. Esto reduce la exposición a la inyección de instrucciones desde contenido arbitrario en vivo, pero aun así debe tratar los resultados web como contenido no confiable. Si utiliza --yolo u otro ajuste de entorno aislado con acceso completo, la búsqueda web utiliza de forma predeterminada resultados en vivo. Utilice --search o establezca web_search = "live" para permitir la navegación en vivo, o establézcalo en "disabled" para desactivar la herramienta:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

Establezca web_search = "indexed" cuando el acceso web externo deba estar restringido por el índice de búsqueda. Tenga cuidado al habilitar el acceso a la red o la búsqueda web en Codex. La inyección de instrucciones puede hacer que el agente obtenga y siga instrucciones no confiables.

Valores predeterminados y recomendaciones

  • Al iniciarse, Codex detecta si la carpeta está bajo control de versiones y recomienda:
    • Carpetas bajo control de versiones: Auto (escritura en el espacio de trabajo + aprobaciones previa solicitud)
    • Carpetas sin control de versiones: read-only
  • Según su configuración, Codex también puede iniciarse en read-only hasta que confíe explícitamente en el directorio de trabajo (por ejemplo, mediante una solicitud de incorporación o /permissions).
  • El espacio de trabajo incluye el directorio actual y directorios temporales como /tmp. Utilice el comando /status para ver qué directorios forman parte del espacio de trabajo.
  • Para aceptar los valores predeterminados, ejecute codex.
  • Puede establecerlos explícitamente:
    • codex --sandbox workspace-write --ask-for-approval on-request
    • codex --sandbox read-only --ask-for-approval on-request

Rutas protegidas en raíces con permiso de escritura

En la política predeterminada del entorno aislado workspace-write, las raíces con permiso de escritura siguen incluyendo rutas protegidas:

  • <writable_root>/.git está protegido como de solo lectura, tanto si aparece como directorio como si aparece como archivo.
  • Si <writable_root>/.git es un archivo de puntero (gitdir: ...), la ruta resuelta del directorio de Git también está protegida como de solo lectura.
  • <writable_root>/.agents está protegido como de solo lectura cuando existe como directorio.
  • <writable_root>/.codex está protegido como de solo lectura cuando existe como directorio.
  • La protección es recursiva, por lo que todo lo que se encuentra bajo esas rutas es de solo lectura.

Ejecutar sin solicitudes de aprobación

Puedes desactivar las solicitudes de aprobación con --ask-for-approval never o -a never (forma abreviada).

Esta opción funciona con todos los modos de --sandbox, por lo que sigues controlando el nivel de autonomía de Codex. Codex hace todo lo posible dentro de las restricciones que establezcas.

Si necesitas que Codex lea archivos, realice modificaciones y ejecute comandos con acceso a la red sin solicitudes de aprobación, usa --sandbox danger-full-access (o la opción --dangerously-bypass-approvals-and-sandbox). Hazlo con precaución.

Como solución intermedia, approval_policy = { granular = { ... } } permite mantener interactivas determinadas categorías de solicitudes de aprobación mientras rechaza automáticamente las demás. La política granular abarca las aprobaciones del entorno aislado, las solicitudes de reglas de execpolicy, las solicitudes de MCP, las solicitudes de request_permissions y las aprobaciones de scripts de habilidades.

Revisiones automáticas de aprobaciones

De forma predeterminada, las solicitudes de aprobación se te envían a ti:

approvals_reviewer = "user"

Las revisiones automáticas de aprobaciones se aplican cuando las aprobaciones son interactivas, como approval_policy = "on-request" o una política de aprobación granular. Establece approvals_reviewer = "auto_review" para dirigir las solicitudes de aprobación aptas a un agente revisor antes de que Codex ejecute la solicitud:

approval_policy = "on-request"
approvals_reviewer = "auto_review"

Para consultar el ciclo de vida completo del revisor, las condiciones de activación, la precedencia de la configuración y el comportamiento ante fallos, consulta Revisión automática.

El revisor evalúa únicamente las acciones que ya requieren aprobación, como las elevaciones del entorno aislado, las solicitudes de red bloqueadas, las solicitudes de request_permissions o las llamadas a herramientas de aplicaciones y MCP que producen efectos secundarios. Las acciones que permanecen dentro del entorno aislado continúan sin un paso de revisión adicional.

La política del revisor comprueba la exfiltración de datos, la búsqueda de credenciales, el debilitamiento persistente de la seguridad y las acciones destructivas. Las acciones de riesgo bajo y medio pueden continuar cuando la política lo permite. La política rechaza las acciones de riesgo crítico. Las acciones de alto riesgo requieren suficiente autorización del usuario y que no coincidan con ninguna regla de denegación. Los fallos al crear la solicitud, en la sesión de revisión o durante el análisis se cierran de forma segura. Los tiempos de espera agotados se muestran por separado, pero la acción tampoco se ejecuta.

La política predeterminada del revisor se encuentra en el repositorio de código abierto de Codex. Las empresas pueden reemplazar su sección específica del inquilino con guardian_policy_config en los requisitos administrados. También se admite el texto local de [auto_review].policy, pero los requisitos administrados tienen prioridad. Para obtener información sobre la configuración, consulta Configuración administrada.

En la aplicación de escritorio de ChatGPT, estas revisiones aparecen como elementos de revisión automática con un estado como En revisión, Aprobada, Denegada, Cancelada o Tiempo de espera agotado. También pueden incluir un nivel de riesgo y una evaluación de la autorización del usuario para la solicitud revisada.

La revisión automática utiliza llamadas adicionales al modelo, por lo que puede aumentar el uso de Codex. Los administradores pueden limitarla con allowed_approvals_reviewers.

Combinaciones habituales de entorno aislado y aprobación

Objetivo Opciones/configuración Efecto
Automático (preajuste) no se necesitan opciones o --sandbox workspace-write --ask-for-approval on-request Codex puede leer archivos, realizar modificaciones y ejecutar comandos en el espacio de trabajo. Codex requiere aprobación para editar fuera del espacio de trabajo o acceder a la red.
Exploración segura de solo lectura --sandbox read-only --ask-for-approval on-request Codex puede leer archivos y responder preguntas. Codex requiere aprobación para realizar modificaciones, ejecutar comandos o acceder a la red.
Solo lectura no interactiva (CI) --sandbox read-only --ask-for-approval never Codex solo puede leer archivos; nunca solicita aprobación.
Editar automáticamente, pero solicitar aprobación para ejecutar comandos que no sean de confianza --sandbox workspace-write --ask-for-approval untrusted Codex puede leer y editar archivos, pero solicita aprobación antes de ejecutar comandos que no sean de confianza.
Modo de revisión automática --sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review o approvals_reviewer = "auto_review" El mismo límite del entorno aislado que en el modo estándar bajo demanda, pero las solicitudes de aprobación aptas las revisa la Revisión automática en lugar de mostrarse al usuario.
Acceso completo peligroso --dangerously-bypass-approvals-and-sandbox (alias: --yolo) Sin entorno aislado ni aprobaciones (no recomendado)

Para ejecuciones no interactivas, usa codex exec --sandbox workspace-write; Codex mantiene las invocaciones anteriores de codex exec --full-auto como una vía de compatibilidad obsoleta y muestra una advertencia.

Con --ask-for-approval untrusted, Codex solo ejecuta automáticamente operaciones de lectura que se sabe que son seguras. Los comandos que pueden modificar el estado o activar rutas de ejecución externas (por ejemplo, operaciones destructivas de Git u opciones de salida o de anulación de configuración de Git) requieren aprobación.

Configuración en config.toml

Para consultar el flujo de trabajo de configuración general, consulta Conceptos básicos de configuración, Configuración avanzada y la Referencia de configuración.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

También puedes guardar preajustes como archivos de perfil y seleccionarlos después con codex --profile profile-name:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"
# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

Probar el entorno aislado localmente

Para ver qué sucede cuando se ejecuta un comando en el entorno aislado de Codex, usa estos comandos de Codex CLI:

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

El comando sandbox también está disponible como codex debug, y los asistentes de plataforma tienen alias (por ejemplo, codex sandbox seatbelt y codex sandbox landlock).

Entorno aislado a nivel del sistema operativo

Codex aplica el entorno aislado de manera diferente según tu sistema operativo:

  • macOS usa políticas de Seatbelt y ejecuta comandos mediante sandbox-exec con un perfil (-p) que corresponde al modo de --sandbox que seleccionaste. Cuando el acceso de lectura restringido habilita los valores predeterminados de la plataforma, Codex añade una política de plataforma de macOS seleccionada cuidadosamente (en lugar de permitir /System de forma general) para conservar la compatibilidad con herramientas comunes.
  • Linux usa bwrap junto con seccomp de forma predeterminada.
  • Windows usa la implementación del entorno aislado de Linux cuando se ejecuta en Subsistema de Windows para Linux 2 (WSL2). WSL1 se admitía hasta Codex 0.114; a partir de 0.115, el entorno aislado de Linux migró a bwrap, por lo que WSL1 dejó de ser compatible. Cuando se ejecuta de forma nativa en Windows, Codex usa una implementación de entorno aislado de Windows.

Si usas la extensión de Codex IDE en Windows, esta admite WSL2 directamente. Establece lo siguiente en la configuración de VS Code para mantener al agente dentro de WSL2 siempre que esté disponible:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

Esto garantiza que la extensión de IDE herede la semántica del entorno aislado de Linux para los comandos, las aprobaciones y el acceso al sistema de archivos, incluso cuando el sistema operativo anfitrión sea Windows. Obtén más información en la guía de WSL.

Cuando ejecutes Codex de forma nativa en Windows, configura el modo de entorno aislado nativo en config.toml:

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

Consulta la guía de configuración de Windows para obtener más información.

Cuando ejecutas Linux en un entorno en contenedores como Docker, es posible que el entorno aislado no funcione si la configuración del anfitrión o del contenedor bloquea el espacio de nombres, las operaciones de bwrap con setuid o las operaciones de seccomp que Codex necesita.

En ese caso, configura el contenedor de Docker para proporcionar el aislamiento que necesitas y, después, ejecuta codex con --sandbox danger-full-access (o la opción --dangerously-bypass-approvals-and-sandbox) dentro del contenedor.

Ejecutar Codex en Dev Containers

Si tu anfitrión no puede ejecutar directamente el entorno aislado de Linux, o si tu organización ya estandariza el desarrollo en contenedores, ejecuta Codex con Dev Containers y permite que Docker proporcione el límite de aislamiento externo. Esto funciona con Visual Studio Code Dev Containers y herramientas compatibles.

Usa el ejemplo de devcontainer seguro de Codex como implementación de referencia. El ejemplo instala Codex, herramientas de desarrollo comunes, bubblewrap y controles de salida basados en firewall.

La implementación de referencia incluye:

  • una imagen base de Ubuntu 24.04 con Codex y herramientas de desarrollo comunes instaladas;
  • un perfil de firewall basado en una lista de permitidos para el acceso saliente;
  • ajustes de VS Code y recomendaciones de extensiones para volver a abrir el espacio de trabajo en un contenedor;
  • montajes persistentes para el historial de comandos y la configuración de Codex;
  • bubblewrap, para que Codex pueda seguir usando su entorno aislado de Linux cuando el contenedor conceda las capacidades necesarias.

Para probarlo:

  1. Instala Visual Studio Code y la extensión Dev Containers.
  2. Copia en tu repositorio la configuración .devcontainer de ejemplo de Codex, o comienza directamente desde el repositorio de Codex.
  3. En VS Code, ejecuta Dev Containers: Open Folder in Container... y selecciona .devcontainer/devcontainer.secure.json.
  4. Después de que se inicie el contenedor, abre una terminal y ejecuta codex.

También puedes iniciar el contenedor desde la CLI:

devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

El ejemplo consta de tres partes principales:

  • .devcontainer/devcontainer.secure.json controla los ajustes, las capacidades, los montajes, las variables de entorno y las extensiones de VS Code del contenedor.
  • .devcontainer/Dockerfile.secure define la imagen basada en Ubuntu y las herramientas instaladas.
  • .devcontainer/init-firewall.sh aplica la política de red saliente.

El firewall de referencia está diseñado deliberadamente como punto de partida. Si dependes de listas de dominios permitidos para el aislamiento, implementa protecciones contra la revinculación de DNS y la actualización de DNS que se adapten a tu entorno, como actualizaciones que tengan en cuenta el TTL o un firewall compatible con DNS.

Dentro del contenedor, elige uno de estos modos:

  • Mantén habilitado el entorno aislado de Linux de Codex si el perfil de Dev Container concede las capacidades necesarias para que bwrap cree el entorno aislado interno.
  • Si el contenedor es el límite de seguridad previsto, ejecuta Codex con --sandbox danger-full-access dentro del contenedor para que Codex no intente crear una segunda capa de aislamiento.

Control de versiones

Codex funciona mejor con un flujo de trabajo de control de versiones:

  • Trabaja en una rama de funcionalidad y mantén git status limpio antes de delegar. Esto facilita aislar y revertir los parches de Codex.
  • Prefiere los flujos de trabajo basados en parches (por ejemplo, git diff/git apply) en lugar de editar directamente los archivos bajo seguimiento. Haz commits con frecuencia para poder revertir los cambios en incrementos pequeños.
  • Trata las sugerencias de Codex como cualquier otro PR: ejecuta verificaciones específicas, revisa las diferencias y documenta las decisiones en los mensajes de commit para facilitar las auditorías.

Supervisión y telemetría

Codex admite la supervisión opcional mediante OpenTelemetry (OTel) para ayudar a los equipos a auditar el uso, investigar problemas y cumplir los requisitos normativos sin debilitar los valores predeterminados de seguridad local. La telemetría está desactivada de forma predeterminada; habilítala explícitamente en tu configuración.

Descripción general

  • Codex desactiva de forma predeterminada la exportación de OTel para mantener autocontenidas las ejecuciones locales.
  • Cuando está habilitado, Codex emite eventos de registro estructurados que abarcan chats, solicitudes de API, actividad de flujos SSE/WebSocket, prompts de usuario (censurados de forma predeterminada), decisiones de aprobación de herramientas y resultados de herramientas.
  • Codex etiqueta los eventos exportados con service.name (originador), la versión de la CLI y una etiqueta de entorno para separar el tráfico de desarrollo, preproducción y producción.

Habilitar OTel (opcional)

Añade un bloque [otel] a tu configuración de Codex (normalmente ~/.codex/config.toml) y elige un exportador y si deseas registrar el texto de los prompts.

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows
  • exporter = "none" mantiene activa la instrumentación, pero no envía datos a ningún destino.
  • Para enviar eventos a tu propio recopilador, elige una de estas opciones:
[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex agrupa los eventos y los envía al cerrarse. Codex exporta únicamente la telemetría generada por su módulo OTel.

Categorías de eventos

Entre los tipos de eventos representativos se incluyen:

  • codex.conversation_starts (modelo, ajustes de razonamiento y política de aislamiento/aprobación)
  • codex.api_request (intento, estado/éxito, duración y detalles del error)
  • codex.sse_event (tipo de evento de flujo, éxito/error, duración y recuentos de tokens en response.completed)
  • codex.websocket_request y codex.websocket_event (duración de la solicitud, además del tipo/éxito/error de cada mensaje)
  • codex.user_prompt (longitud; contenido censurado salvo que se habilite explícitamente)
  • codex.tool_decision (aprobado/denegado, origen: configuración o usuario)
  • codex.tool_result (duración, éxito y fragmento de salida)

Las métricas de OTel asociadas (pares de contador e histograma de duración) incluyen codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event y codex.tool.call (con los instrumentos .duration_ms correspondientes).

Para consultar el catálogo completo de eventos y la referencia de configuración, consulta la documentación de configuración de Codex en GitHub.

Directrices de seguridad y privacidad

  • Mantén log_user_prompt = false salvo que la política permita explícitamente almacenar el contenido de los prompts. Los prompts pueden incluir código fuente y datos confidenciales.
  • Envía la telemetría únicamente a recopiladores bajo tu control; aplica límites de retención y controles de acceso acordes con tus requisitos normativos.
  • Trata los argumentos y las salidas de las herramientas como datos confidenciales. Siempre que sea posible, aplica la censura en el recopilador o SIEM.
  • Revisa los ajustes locales de retención de datos (por ejemplo, history.persistence / history.max_bytes) si no quieres que Codex guarde las transcripciones de las sesiones en CODEX_HOME. Consulta Configuración avanzada y Referencia de configuración.
  • Si ejecutas la CLI con el acceso a la red desactivado, la exportación de OTel no podrá conectarse con tu recopilador. Para exportar, permite el acceso a la red en el modo workspace-write para el punto de conexión de OTel, o exporta desde Codex cloud con el dominio del recopilador en tu lista de permitidos.
  • Revisa periódicamente los eventos para detectar cambios en las aprobaciones o el aislamiento y ejecuciones inesperadas de herramientas.

OTel es opcional y está diseñado para complementar, no sustituir, las protecciones de aislamiento y aprobación descritas anteriormente.

Configuración administrada

Los administradores empresariales pueden configurar los ajustes de seguridad de Codex para su espacio de trabajo en Configuración administrada. Consulta esa página para obtener información sobre la configuración y las políticas.