Codex CLI

Codex CLI puede conectarse a HiAPI mediante la importación con un clic de CC Switch, o puedes configurarlo manualmente (paso 9). Los pasos siguientes usan gpt-6-astra como ejemplo; HiAPI usa el protocolo OpenAI Responses. Este tutorial se verificó en Mac con Codex CLI 0.162.1; los pasos de Mac son la ruta principal y los de Windows se explican aparte. Puedes saltarte la instalación del software que ya tengas.

1. Instala Node.js

Instala LTS 22.19 o posterior como se describe en Instalación de Node.js, y sáltalo si ya lo tienes. Después ejecuta los dos comandos siguientes en una terminal; basta con ver números de versión:

node --version
npm --version

2. Instala Codex CLI

En la terminal que acabas de abrir, ejecuta cada línea:

npm install -g @openai/codex
codex --version

Basta con ver un número de versión de codex-cli; la configuración manual (paso 9) requiere 0.134 o posterior. En Windows PowerShell, usa npm.cmd install -g @openai/codex y codex.cmd --version.

3. Instala y abre CC Switch

Descarga, instala y abre CC Switch como se describe en Instalar CC Switch e importar con un clic; si ya lo tienes, basta con abrirlo.

Si ya tienes proveedores, apunta primero el nombre de la tarjeta marcada como “In use” en la página Codex, y cuando haga falta exporta una copia SQL como se describe en Haz una copia de seguridad de tu configuración actual.

4. Elige una HiAPI API key

Elige o crea una clave como se describe en Obtener una API key y apunta su nombre. Aquí no hace falta copiar la clave; la importación se la lleva.

5. Prepara la importación con un clic en la web

1. Abre la página de conexión de Codex de HiAPI y elige API Key setup → Codex → Command line → gpt-6-astra → macOS. En Windows, elige Windows como sistema.

2. Haz clic en Import to CC Switch, elige el nombre de la clave que apuntaste en el desplegable API Key y comprueba que abajo aparece Responses API · https://api.hiapi.ai/v1.

3. Haz clic en Prepare import y luego en Open CC Switch; permite la apertura cuando el navegador lo pregunte.

Las capturas de cada paso están en Prepara la importación en la página de conexión.

6. Confirma la importación en CC Switch

En la ventana “Confirm provider import”, comprueba los elementos de abajo, deja desactivada la opción Switch to this provider immediately after import y haz clic en Import:

De vuelta en la página Codex de CC Switch, la tarjeta HiAPI - gpt-6-astra significa que la importación ha funcionado (todavía no está activada). Consulta las capturas en Confirma la importación en CC Switch.

7. Activa HiAPI

1. Espera primero a que termine la tarea que esté ejecutando Codex. En la página Codex → Direct de CC Switch, haz clic en el botón Switch / Enable de la tarjeta HiAPI - gpt-6-astra; HiAPI solo está activado cuando la tarjeta está marcada como “In use”. Consulta las capturas en Activa HiAPI.
2. Cierra Codex por completo y vuelve a abrirlo para que la nueva configuración surta efecto. CLI y Desktop pueden compartir la configuración local de Codex; para volver más tarde a tu proveedor original, cambia a su tarjeta aquí y vuelve a abrir el cliente.

8. Abre Codex, elige un modelo y empieza

1. Abre una terminal nueva y ve a la carpeta de proyecto que quieras usar, o crea una vacía primero:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. La primera vez pregunta si quieres confiar en el directorio; confirma que la ruta es la carpeta que acabas de elegir, luego confirma como te indique y mantén los permisos predeterminados. Con la importación de un clic, ejecuta codex directamente; no añadas el --profile hiapi que se usa en la configuración manual.

3. En la caja de entrada de Codex, escribe /model y pulsa Enter. Usa las flechas para elegir GPT-6 Astra / gpt-6-astra y pulsa Enter; si hay un nivel de razonamiento, elige uno y confirma, luego pulsa Esc para volver.

① Usa las flechas para elegir GPT-6-Astra; ② pulsa Enter para confirmar.

4. Envía “Hola, preséntate en una frase.” Una respuesta normal significa que la conexión funciona. Si el Registro de solicitudes de la consola de HiAPI muestra esta solicitud, está pasando por HiAPI. Después, basta con escribir en la caja de entrada lo que quieras hacer.

9. Configuración manual (sin CC Switch)

Salta este paso si usaste la importación con un clic. La configuración manual solo se aplica a Codex CLI, no a Codex Desktop.

1. En un Mac, ejecuta las tres líneas siguientes en una terminal; si ya existe un archivo con el mismo nombre, se hace antes una copia de seguridad automáticamente:

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. Para un archivo nuevo, pega todo el contenido de abajo; si el archivo ya existe, actualiza solo los campos y tablas con los mismos nombres, conserva el resto y no añadas duplicados. Los campos de nivel superior deben ir antes de [model_providers.hiapi]. env_key = "HIAPI_API_KEY" es la forma en que Codex lee una variable de entorno; déjalo como está.

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Pulsa Ctrl+O → Enter → Ctrl+X para guardar y salir. El nombre del archivo debe ser hiapi.config.toml, no .toml.txt. Si has definido CODEX_HOME, guarda el archivo en ese directorio.

4. Vuelve a Consola de HiAPI → API Keys, haz clic en el icono de copiar junto a la clave y copia la HiAPI API key completa. En la misma terminal en la que vayas a iniciar Codex, ejecuta el comando de abajo (sustituye YOUR_HIAPI_API_KEY por tu HiAPI API key y conserva las comillas), luego ve a tu directorio de proyecto e inicia:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. En Windows, usa PowerShell para crear el directorio $env:USERPROFILE\.codex, abre hiapi.config.toml en el Bloc de notas y pega el mismo TOML; haz primero una copia del archivo si ya existe. En Save as, elige “Todos los archivos” y UTF-8, y confirma que no hay sufijo .txt. En la misma ventana de PowerShell y en el directorio del proyecto, ejecuta:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

La variable de entorno solo se aplica a la terminal actual; vuelve a definirla después de cerrar la terminal. Una vez iniciado, elige un modelo como en el paso 8.

Solución de problemas

Aquí solo se recogen los problemas propios de Codex CLI. Para errores comunes como 401, 404 y 429, consulta Errores comunes.