Configuración del cliente Codex
El cliente Codex es la aplicación de escritorio de OpenAI. Permite iniciar sesión directamente con ChatGPT o usar una API Key para ejecutar el flujo de trabajo local de Codex. Los principiantes suelen confundirse: el inicio de sesión con cuenta oficial, la API Key de OpenAI y la Key de un proveedor no son lo mismo.
Primero, distinga entre los dos métodos de inicio de sesión
Esta página solo cubre las configuraciones en el cliente de escritorio relacionadas con Key, modelo y Provider. La instalación por línea de comandos, los comandos de terminal y el uso más completo de CLI se encuentran en la página de Herramientas CLI.
| Método | Para quién es adecuado | Cómo gestionar la Key |
|---|---|---|
| Inicio de sesión con ChatGPT | Ya tiene una cuenta ChatGPT Plus / Pro / Business / Enterprise y desea usar Codex oficial directamente. | Siga la guía de inicio de sesión del cliente para acceder; por lo general, no es necesario ingresar una API Key manualmente. |
| Inicio de sesión con API Key de OpenAI | Desea usar una cuenta de OpenAI Platform con pago por uso, o sus flujos de trabajo locales requieren una API Key. | Use la Key generada en la consola de OpenAI, no la Key del proveedor. |
| Proveedor / Servicio proxy | El proveedor proporciona su propia dirección de API, Key y nombre de modelo. | No complete arbitrariamente el campo de inicio de sesión de API Key oficial; por lo general, debe configurar un Provider personalizado a través de config.toml. |
Ruta de ejemplo: C: \Users\YourUsername\. codex
Cómo configurar la Key
El directorio de configuración local de Codex se llama . codex. Para clientes de Windows, use %USERPROFILE%\. codex. Para macOS / Linux, normalmente se usa ~/. codex. Si solo inicia sesión con ChatGPT, no escriba la Key manualmente por ahora; si usa un proveedor o la Key de un proveedor externo, se recomienda colocar la Key en una variable de entorno del sistema y luego permitir que config.toml lea esta variable.
| Sistema | Archivo de configuración | Dónde colocar la Key |
|---|---|---|
| Windows | %USERPROFILE%\. codex\config.toml | Variables de entorno de usuario, por ejemplo MZ_PROXY_API_KEY. |
| macOS / Linux | ~/. codex/config.toml | Variables de entorno del terminal actual. Tras confirmar que funciona, guárdela a largo plazo según las costumbres de su sistema. |
| WSL | ~/. codex/config.toml | WSL tiene su propio directorio personal (home) y no leerá automáticamente el %USERPROFILE%\. codex de Windows. |
$env:MZ_PROXY_API_KEY = "YOUR_KEY"MZ_PROXY_API_KEY="YOUR_KEY" codex "Please reply only: Configuration successful"No escriba la Key real en páginas web, capturas de pantalla, historiales de chat o repositorios de proyectos. Use variables de entorno siempre que sea posible en lugar de escribir la Key directamente en config.toml. Para guardarla a largo plazo en Windows, puede añadir una variable de usuario en las "Variables de entorno" del sistema; el método para guardarla a largo plazo en macOS / Linux dependerá del terminal que utilice realmente.
Cómo configurar el modelo
El modelo predeterminado se define en la parte superior de config.toml. La documentación oficial actualmente recomienda comenzar desde gpt-5.5. Si utiliza un proveedor, complete la cadena que aparece en la lista de modelos del panel del proveedor utilizada para llamadas a la API. Puede llamarse "ID de modelo", "Nombre del modelo" o similar en el panel. Cópielo exactamente como está. No modifique mayúsculas/minúsculas, guiones ni puntos por su cuenta.
model = "gpt-5.5"model = "MODEL_ID_FROM_PROVIDER_DASHBOARD" model_provider = "mz_proxy"| Parámetro | Cómo completarlo | Errores comunes |
|---|---|---|
| model | ID de modelo / Nombre de modelo, que es el identificador original utilizado para llamadas a la API en la lista de modelos del panel. | No use un nombre descriptivo propio como identificador del modelo, ni cambie mayúsculas/minúsculas, guiones o puntos por su cuenta. |
| model_provider | Seleccione el Provider ID definido más abajo. | Se definió la tabla del Provider, pero no se cambió aquí. |
| openai_base_url | Úselo únicamente cuando desee cambiar la URL de solicitud del Provider integrado de OpenAI. | Mezclarlo con un Provider personalizado hace que las solicitudes se envíen al lugar equivocado. |
| wire_api | Por lo general, use responses. | Puede que no funcione correctamente cuando el proveedor no admite la API Responses. |
Cómo configurar un Provider de proveedor
El núcleo de la configuración de un proveedor consta de tres elementos: Nombre del modelo, Base URL y Variable de entorno de la Key. Si su proveedor ofrece una interfaz compatible con OpenAI, priorice que admita la API Responses; los proveedores que solo admiten el antiguo Chat Completions tendrán una peor compatibilidad futura.
model = "MODEL_ID_FROM_PROVIDER_DASHBOARD" model_provider = "mz_proxy" [model_providers.mz_proxy] name = "Example AI Provider" base_url = "https://YOUR_PROVIDER_API_URL" env_key = "MZ_PROXY_API_KEY" wire_api = "responses"model = "gpt-5.5" model_provider = "openai" openai_base_url = "https://YOUR_OPENAI_PROXY_API_URL"openai_base_url solo para proxies empresariales, residencia de datos o direcciones de reenvío oficial de OpenAI.| Elementos a verificar | Enfoque correcto | Enfoque incorrecto |
|---|---|---|
| Base URL | Copie la dirección de API proporcionada por el panel del proveedor; consulte las instrucciones del proveedor para saber si incluye /v1. | Usar la página de inicio o la página principal de la consola como dirección de API. |
| Key | Use un nombre de variable de entorno, por ejemplo MZ_PROXY_API_KEY. | Escribir la Key directamente en los archivos del proyecto o enviar capturas de pantalla. |
| Provider ID | Cree su propio ID en inglés, por ejemplo mz_proxy. | Usar openai, ollama, lmstudio u otro tipo de ID reservado. |
| Model ID / Model Name | Copie el identificador original utilizado para llamadas a la API desde la lista de modelos del panel. | Usar un nombre descriptivo propio, el nombre del plan o un nombre adivinado de memoria. |
Primero, verifique estos puntos en los ajustes del cliente
Tras abrir los ajustes del cliente Codex, el panel izquierdo estará agrupado en 'Personal, Integration, Coding, Archived'. Los principiantes deben comenzar por General (Regular); confirme principalmente el modo de trabajo, el alcance de los permisos, la ubicación de apertura predeterminada, el terminal y el idioma; la gestión del modelo, la Key y el Provider se realiza en la sección de configuración de config.toml mencionada anteriormente.
| Ajuste | ¿Qué significa en la imagen? | Consejos para principiantes |
|---|---|---|
| Modo de trabajo | Elija cuántos detalles técnicos mostrar al responder con Codex. Adecuado para programación estará más enfocado en código y control; Adecuado para trabajo diario reducirá los detalles técnicos. | Elija 'Adecuado para programación' al configurar código o resolver errores; elija 'Adecuado para trabajo diario' cuando solo redacte textos u organice contenido. |
| Permisos predeterminados | Permite a Codex leer y editar archivos en el espacio de trabajo actual; solicita permisos adicionales solo cuando se necesita acceder a contenido fuera del espacio de trabajo. | Puede mantener la configuración predeterminada. Asegúrese de comprobar a qué desea acceder antes de cada autorización. |
| Revisión automática | Codex puede resolver automáticamente algunas solicitudes de acceso adicionales, pero la página también advierte que la revisión automática puede equivocarse. | Si no está seguro, desactívelo primero y confirme paso a paso usted mismo; una vez familiarizado, actívelo según sea necesario. |
| Acceso total | Permitir que Codex edite cualquier archivo en la computadora y ejecute comandos de red sin aprobación conlleva un riesgo mucho mayor. | No lo active por defecto. Habilítelo temporalmente solo cuando comprenda claramente las consecuencias y la tarea actual realmente lo requiera. |
| Destino de apertura predeterminado | Decide qué aplicación utiliza el cliente por defecto para abrir archivos o carpetas. La captura muestra Antigravity. | Elija el editor o espacio de trabajo que utiliza habitualmente. Si no está seguro, conserve el valor actual. |
| Shell del terminal integrado | Decide qué shell utiliza Codex en el terminal integrado, como PowerShell, CMD o Git Bash. | Los principiantes en Windows deben priorizar el uso de PowerShell, a menos que el tutorial requiera específicamente otro terminal. |
| Idioma | Controla el idioma de la interfaz del cliente. La captura muestra detección automática. | Si desea mantener las instrucciones en un idioma específico, elija su preferencia o detección automática. |
| Panel inferior / Ubicación predeterminada del terminal | Controla si se muestra el panel inferior y si las pestañas del terminal aparecen por defecto en la parte inferior o a la derecha. | Elija según el tamaño de la pantalla: en portátiles suele colocarse abajo, en pantallas panorámicas puede colocarse a la derecha. |
| Revisión de código | Decide al iniciar /review si la revisión se lleva a cabo en la conversación actual o si se divide en una conversación de revisión independiente. | Los principiantes deben usar primero la 'vista integrada' (inline view), donde el contexto está más enfocado. |
| Sugerencias automáticas | Sugiere qué pasos seguir a continuación en función de los archivos del proyecto y las aplicaciones conectadas. | Puede activarlo; si le resulta molesto, desactívelo nuevamente. |
Verificación y resolución de problemas
Tras cambiar la Key, el modelo o el Provider, reinicie el cliente y cree un nuevo hilo de prueba. Por ahora, no permita que modifique archivos; solo pídale que confirme que el proyecto actual y el modelo están funcionando correctamente.
First state which files you can see. Do not modify files or run commands. Reply only with whether the current project is readable and the model ID or model name you are using.| Síntoma | Causa común | Cómo solucionarlo |
|---|---|---|
| El aviso indica que no hay Key o error de autenticación | La variable de entorno no ha surtido efecto o el cliente aún no se ha reiniciado. | Vuelva a abrir el terminal/cliente; en Windows, compruebe las variables de entorno en una nueva ventana. |
| Modelo no disponible | El ID de modelo / nombre de modelo es incorrecto, o el proveedor no ha habilitado este modelo. | Vuelva al panel del proveedor y copie el identificador original de la lista de modelos. |
| 404 / punto de conexión no encontrado | La ruta de Base URL es incorrecta; los problemas comunes suelen ser incluir /v1 de más o de menos. | Confirme la dirección de API según la documentación del proveedor, no la adivine. |
| La solicitud se envía a OpenAI oficial | No se ha cambiado al ID personalizado del proveedor, o se usó openai_base_url cuando no correspondía a este caso. | Verifique si model_provider coincide con su Provider ID. |
| Funciona en WSL, pero no en el cliente de Windows | Windows y WSL utilizan diferentes directorios . codex. | Asegúrese de estar modificando el archivo de configuración que el cliente realmente lee. |
config.toml.Permisos y seguridad
El cliente Codex puede leer archivos de proyecto y también puede modificar archivos, realizar comprobaciones o abrir páginas para visualizarlas según su confirmación. Lo más importante para los principiantes es observar claramente qué quiere hacer antes de permitirle continuar.
| Elemento | En qué fijarse | Consejos para principiantes |
|---|---|---|
| Avisos de aprobación | Si desea modificar archivos, ejecutar comprobaciones o acceder a servicios externos. | Si no lo entiende, rechácelo primero y pídale a Codex que le explique el motivo. |
| Cambios en archivos | Qué archivos se añaden, eliminan o modifican. | Antes de confirmar, revise cada diferencia (diff) una por una; no se quede solo con el resumen. |
| Alcance del proyecto | A qué proyecto de su computadora está conectada esta conversación. | Asegúrese de que no sea un proyecto antiguo o un proyecto de prueba. |
| Destino de los cambios | Compruebe si edita una copia aislada en lugar de modificar su proyecto original. | Cuando los riesgos sean inciertos, priorice el uso de una copia aislada. |
| Vista de página en navegador | Compruebe si la página que se abre es de desarrollo local. | Verifique manualmente cuando involucre cuentas, pagos o permisos de backend. |