La instalación de Codex no es difícil; lo que realmente puede bloquearte es la integración: dónde colocar la API Key, cómo escribir config.toml, cuáles son las diferencias entre Windows y macOS, por qué VS Code no puede leer las variables del terminal, si se debe fijar el modelo…

Si solo quieres poner Codex en marcha cuanto antes, puedes reducir la configuración a tres valores:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

Después de completarlo, Codex CLI, Desktop y la extensión de VS Code pueden compartir ~/.codex/config.toml; el modelo se selecciona directamente después del inicio, sin necesidad de modificar constantemente la configuración de integración para cambiar de modelo.

A continuación, completaremos una configuración desde cero.

Preparativos

Antes de comenzar, confirma:

  • Que te has registrado e iniciado sesión en Ace Data Cloud
  • Que has creado o tienes una aplicación disponible
  • Que Node.js y npm están instalados en tu equipo
  • Que puedes utilizar el terminal o PowerShell
  • Que estás preparado para utilizar al menos uno entre Codex CLI, Codex Desktop o la extensión de VS Code

Primer paso: obtener la API Key de Ace Data Cloud

Abre la lista de aplicaciones de Ace Data Cloud, entra en una aplicación disponible y copia la API Key.

Ten en cuenta:

  • La API Key es una credencial sensible; no la incluyas en repositorios públicos
  • No incluyas Keys reales en capturas de pantalla de tutoriales
  • Se recomienda crear y gestionar las credenciales por separado según el entorno o el propósito
  • Si sospechas que se ha filtrado, debes rotarla o revocarla a tiempo

Este artículo utiliza de forma uniforme la variable de entorno ACEDATACLOUD_API_KEY, para evitar escribir directamente credenciales en texto plano en el archivo de configuración de Codex.

Segundo paso: instalar Codex CLI

Instala Codex globalmente mediante npm:

npm install -g @openai/codex

Verifica después de la instalación:

codex --version

Si se indica que no se encuentra el comando, primero confirma que el directorio global de ejecutables de npm se ha añadido a PATH y luego vuelve a abrir el terminal.

Si utilizas principalmente VS Code, también puedes instalar la extensión Codex publicada por OpenAI:

code --install-extension openai.chatgpt

La CLI y la extensión de VS Code comparten el archivo de configuración; por tanto, se recomienda configurar primero el Provider y las variables de entorno, y después iniciar el editor para verificar.

Tercer paso: configurar la variable de entorno de la API Key

macOS / Linux: sesión actual del terminal

export ACEDATACLOUD_API_KEY="tu API Key"

Este comando solo tiene efecto en el Shell actual y sus procesos secundarios. La variable desaparecerá al cerrar el terminal.

macOS / Linux: efecto permanente

Si utilizas Zsh:

echo 'export ACEDATACLOUD_API_KEY="tu API Key"' >> ~/.zshrc
source ~/.zshrc

Si utilizas Bash:

echo 'export ACEDATACLOUD_API_KEY="tu API Key"' >> ~/.bashrc
source ~/.bashrc

No copies indiscriminadamente configuraciones de Shell que contengan Keys reales en equipos compartidos; los entornos de equipo deben combinar herramientas de gestión de credenciales y políticas de privilegios mínimos.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "tu API Key"

Después de ejecutarlo, cierra y vuelve a abrir PowerShell. setx no actualiza automáticamente los procesos ya abiertos, por lo que el terminal existente y VS Code podrían seguir sin poder leer el nuevo valor.

Si solo necesitas configurarla temporalmente en la sesión actual de PowerShell:

$env:ACEDATACLOUD_API_KEY="tu API Key"

Cuarto paso: crear o editar config.toml

Codex CLI, Desktop y la extensión de VS Code comparten el siguiente archivo de configuración:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

Si el directorio no existe, créalo primero.

macOS / Linux:

mkdir -p ~/.codex

Después escribe:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows utiliza el mismo Provider y Base URL, pero el comando de autenticación se cambia a PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

Los tres nombres de la configuración deben mantenerse estrictamente coherentes:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

La Base URL también debe incluir completamente /v1.

Quinto paso: iniciar Codex y seleccionar un modelo

Después de guardar la configuración, vuelve a abrir el terminal y ejecuta:

codex

Después de entrar en Codex, ejecuta:

/model

Confirma que el Provider actual es acedatacloud y luego selecciona un modelo de la lista disponible.

No es necesario fijar model en la configuración de integración. Separar el Provider de la selección del modelo puede reducir el coste de editar repetidamente el TOML al cambiar de modelo. Los modelos reales y el rango disponible se actualizarán; se debe tomar como referencia /model y el catálogo en tiempo real de la plataforma.

Sexto paso: verificar con una solicitud mínima

No le pidas a Codex que refactorice todo el repositorio desde el principio. Primero envía una solicitud sencilla cuyo resultado pueda evaluarse rápidamente, por ejemplo:

Resume la estructura de directorios del proyecto actual, no modifiques ningún archivo.

Después abre Ace Data Cloud Usage History, confirma que la solicitud ha llegado y revisa el estado y el consumo.

Si la solicitud mínima tiene éxito, prueba gradualmente a leer archivos, generar planes de modificación, editar código y ejecutar pruebas.

Puntos clave de configuración de VS Code

La extensión de VS Code leerá el mismo ~/.codex/config.toml, pero que pueda ver la API Key depende del entorno del proceso en el que se ejecuta la extensión.

Después de la configuración, cierra por completo y vuelve a abrir VS Code. En macOS / Linux, si al iniciarlo desde la interfaz gráfica sigue sin poder leer la variable, puedes ejecutar lo siguiente desde el terminal donde ya se ha configurado la Key:

code .

En los siguientes entornos, debes configurar la variable en el lado donde realmente se ejecuta la extensión:

  • Remote SSH: host remoto
  • WSL: entorno Linux de WSL
  • Dev Container: entorno de contenedor
  • Codespaces o entornos remotos similares: sesión remota correspondiente

Configurar la variable únicamente en el Shell local no garantiza que la extensión remota la obtenga automáticamente.

Puntos clave de configuración de Codex Desktop

Desktop y CLI comparten el archivo de configuración, pero las aplicaciones gráficas no necesariamente heredan el export ejecutado temporalmente en el terminal.

Si Desktop no puede leer la Key:

  1. Configura la variable de entorno como permanente o a nivel del sistema
  2. Cierra completamente Desktop
  3. Reinicia la aplicación
  4. Vuelve a comprobar el Provider y el modelo

Solución de errores comunes

1. 401, Unauthorized o Incorrect API Key

Orden de comprobación:

  1. Si la API Key se copió completamente
  2. Si el nombre de la variable de entorno es ACEDATACLOUD_API_KEY
  3. Si el proceso actual se inició después de configurar la variable
  4. Si auth.command corresponde al sistema operativo actual
  5. Si la credencial sigue siendo válida No imprimas la Key completa en registros o chats. Puedes comprobar la variable solo determinando si “existe”.

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. El Provider no cambia a acedatacloud

Confirma la ruta del archivo de configuración y la jerarquía de TOML. Los errores comunes incluyen:

  • El nombre del archivo se escribió como config.toml.txt
  • Se editó otro directorio de usuario
  • La ortografía del nombre de la tabla no coincide
  • Errores en las comillas o el formato del array
  • No se reinició el cliente después de guardar

3. Error en la solicitud de la Base URL

Confirma que la dirección sea:

https://api.acedata.cloud/v1

No omitas https:// ni el /v1 final, y tampoco uses por error la dirección de la página de la consola.

4. La CLI funciona, pero VS Code no funciona

Por lo general, esto no es un problema de configuración del Provider, sino que el proceso de VS Code no ha leído la variable de entorno. Inicia code . desde un terminal donde la variable ya esté configurada, o reinicia por completo VS Code después de configurar una variable a nivel de sistema.

5. No se puede leer la Key en WSL, SSH o contenedores

La variable de entorno debe configurarse en el entorno donde Codex o la extensión realmente se ejecuta. setx en el host de Windows no se escribe automáticamente en WSL; las variables locales tampoco se transfieren automáticamente a hosts SSH remotos o contenedores.

6. No se encuentra el modelo que se quiere usar

No adivines manualmente ID de modelos antiguos. Ejecuta /model para ver las opciones disponibles en tiempo real y comprueba los permisos de la aplicación, el saldo y el Provider actual.

7. La solicitud llega, pero no puede completar tareas complejas

Primero reduce el alcance de la tarea: permite que Codex solo analice en modo lectura y enumere un plan, y luego permite gradualmente modificaciones y pruebas. Que la integración del modelo sea exitosa no significa que todas las tareas del repositorio deban completarse de una sola vez; los cambios complejos aún requieren criterios de aceptación claros, pruebas y revisión humana.

Lista de verificación de configuración recomendada

Antes de enviar la primera tarea formal, confirma cada elemento:

  • Se ha obtenido una API Key válida de la lista de aplicaciones
  • La Key se guarda en ACEDATACLOUD_API_KEY
  • La Key no se ha escrito en el repositorio Git
  • model_provider es acedatacloud
  • La Base URL es https://api.acedata.cloud/v1
  • auth.command coincide con el sistema operativo
  • Codex o VS Code se ha reiniciado por completo
  • /model puede mostrar el Provider y los modelos
  • La solicitud de prueba mínima se realizó correctamente
  • Se pueden ver los registros de llamadas correspondientes en Usage History

Un Provider, menos configuración duplicada

El punto clave de este método de integración no es escribir un fragmento adicional de TOML, sino establecer límites estables:

  • La API Key se gestiona mediante variables de entorno
  • La conexión del Provider se gestiona mediante config.toml
  • Los modelos se seleccionan en Codex según la tarea
  • Los registros de llamadas y el consumo se consultan de forma unificada en la consola de Ace Data Cloud
  • CLI, Desktop y VS Code comparten una misma configuración

Cuando la autenticación, el Provider y la selección de modelos se separan claramente, muchos problemas de “por qué Codex no funciona otra vez” pueden localizarse rápidamente, sin necesidad de volver a iniciar sesión, reinstalar o copiar múltiples configuraciones repetidamente.

Abre el Centro de configuración de Codex para consultar las guías oficiales para distintos clientes, o ve a la lista de aplicaciones para obtener una API Key.

Materiales de referencia