> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Uso de GccAi en Codex CLI

> Una guía detallada sobre cómo configurar y usar los servicios de API de GccAi en Codex CLI, permitiéndole acceder a múltiples modelos de IA para programación asistida con una configuración sencilla.

## Introducción

Codex CLI es el agente de programación de terminal de código abierto de OpenAI, capaz de leer y escribir archivos, ejecutar comandos, corregir errores y completar tareas de programación completas directamente en la línea de comandos.
Al conectarse a través de GccAi, puede usar libremente múltiples modelos —incluyendo GPT y Claude— en Codex CLI, con precios más flexibles y competitivos.

## Requisitos previos

Antes de comenzar, asegúrese de tener:

1. **Node.js instalado**
   Descargue e instale desde el [sitio web de Node.js](https://nodejs.org/) (se recomienda la última LTS, v20 o más reciente) para instalar Codex CLI mediante npm

2. **Una clave de API de GccAi**
   Acceda a la [Consola de GccAi](https://gccai.heqingsong.uk/keys) para obtener su clave de API (comienza con `sk-`)

> [!NOTE]
>
> **Consejo:** Si aún no tiene una cuenta en GccAi, regístrese primero en [GccAi](https://gccai.heqingsong.uk) y obtenga su clave de API.

## Paso 1: Instalar Codex CLI

Elija cualquiera de los siguientes métodos para instalar:

**npm (Recomendado)**

Instalación global con npm: funciona en todos los sistemas operativos:

```bash theme={null}
npm install -g @openai/codex
```

> [!NOTE]
>
> Si tiene problemas de permisos, anteponga `sudo` (macOS / Linux).

**Homebrew (macOS)**

Los usuarios de macOS también pueden instalar con Homebrew:

```bash theme={null}
brew install codex
```

### Verificar la instalación

Tras instalar, ejecute el siguiente comando para confirmar:

```bash theme={null}
codex --version
```

Si se imprime un número de versión, la instalación fue correcta.

## Paso 2: Configurar la API de GccAi

Codex CLI gestiona los proveedores de modelos mediante archivos de configuración bajo el directorio `~/.codex/`. Todo lo que necesitamos hacer es añadir un proveedor personalizado que apunte a GccAi.

### 2.1 Localizar el directorio de configuración

* **macOS / Linux:** `~/.codex/`
* **Windows:** `C:\Users\<username>\.codex\`

> [!NOTE]
>
> Si el directorio no existe, ejecute `codex` una vez en su terminal y luego pulse `Ctrl + C` para salir; se creará automáticamente.

### 2.2 Configurar la clave de API

En el directorio de configuración, cree o edite el archivo `auth.json` e introduzca su clave de GccAi:

```json theme={null}
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}
```

| Campo | Descripción |
| - | - |
| `OPENAI_API_KEY` | Su clave de API de GccAi (comienza con `sk-`) |

### 2.3 Configurar el proveedor de modelos

En el directorio de configuración, cree o edite el archivo `config.toml` y añada el proveedor GccAi:

```toml theme={null}
# Default model
model = "gpt-5.5"
# Default provider — matches [model_providers.gccai] below
model_provider = "gccai"

# GccAi provider configuration
[model_providers.gccai]
name = "GccAi"
base_url = "https://gccai.heqingsong.uk/v1"
wire_api = "responses"
requires_openai_auth = true
```

| Campo | Descripción |
| - | - |
| `model` | ID del modelo predeterminado: elija uno de la lista de modelos a continuación |
| `model_provider` | Proveedor predeterminado: debe coincidir con el ID dentro de `[model_providers.xxx]` |
| `name` | Nombre para mostrar del proveedor: se puede personalizar |
| `base_url` | URL compatible con OpenAI de GccAi: fija como `https://gccai.heqingsong.uk/v1` |
| `wire_api` | Protocolo de comunicación: las versiones recientes de Codex requieren `responses` (Responses API) |
| `requires_openai_auth` | Establezca en `true` para autenticarse usando la clave de `auth.json` |

Tras guardar ambos archivos, reinicie Codex CLI para que los cambios surtan efecto.

> [!WARNING]
>
> Asegúrese de que `auth.json` sea JSON válido y `config.toml` sea TOML válido. No use comillas tipográficas o de ancho completo, de lo contrario la configuración no se aplicará.

## Paso 3: Comenzar

### Verificar la configuración

En cualquier directorio de proyecto, ejecute el siguiente comando para confirmar que todo está conectado:

```bash theme={null}
codex "Introduce yourself in one sentence"
```

Si obtiene una respuesta de IA, la configuración está funcionando. Si ve una pantalla de inicio de sesión o errores `401` / `403`, consulte la sección de preguntas frecuentes a continuación.

### Modo interactivo

Ejecute `codex` directamente para entrar en la interfaz interactiva: ideal para tareas de programación completas:

```bash theme={null}
codex
```

Una vez dentro, describa lo que necesita en lenguaje natural, p. ej.:

```
Create an Express.js server with a JSON-returning health check endpoint
```

Codex analizará su proyecto, generará código, ejecutará comandos y solicitará confirmación antes de realizar operaciones sensibles.

### Modos de aprobación

En la primera ejecución, Codex le pedirá que elija un nivel de aprobación:

| Modo | Descripción |
| - | - |
| **Read Only** | Solo se permiten lecturas de archivos: cualquier modificación o comando requiere confirmación |
| **Auto** | Puede leer/escribir archivos y ejecutar comandos dentro del directorio de trabajo (recomendado) |
| **Full Access** | Realiza cualquier operación sin confirmación: usar con precaución |

Recomendamos comenzar con el modo **Auto**. Escriba `/approvals` en la interfaz interactiva para cambiarlo en cualquier momento.

### Cambiar de modelo

En la interfaz interactiva, escriba `/model` para cambiar rápidamente, o cambie el campo `model` en `config.toml` y reinicie.

## Modelos compatibles

Para Codex CLI, se recomiendan los siguientes modelos de la serie GPT-5:

| ID del modelo | Fortalezas | Casos de uso recomendados |
| - | - | - |
| `gpt-5.5` | Buque insignia más reciente, máxima capacidad de programación | Primera opción para Codex, ingeniería compleja |
| `gpt-5.4` | Buque insignia de generación anterior, muy capaz | Programación compleja, diseño de arquitectura |
| `gpt-5.4-mini` | Ligero, rápido, económico | Programación diaria, iteración rápida |
| `gpt-5.3-codex` | Modelo de programación optimizado para Codex | Tareas de programación agéntica |
| `gpt-5.2` | Estable y equilibrado | Tareas de programación rutinarias |

> [!TIP]
>
> **Consejos para elegir un modelo:** La serie GPT-5 anterior se combina mejor con Codex CLI. Para la mejor experiencia, prefiera `gpt-5.5`; `gpt-5.3-codex` está específicamente optimizado para los escenarios de programación agéntica de Codex.

## Comandos comunes

Comandos y atajos usados con frecuencia en Codex CLI:

| Comando | Descripción |
| - | - |
| `codex` | Entrar en la interfaz interactiva |
| `codex "task"` | Comenzar con una instrucción inicial |
| `codex exec "task"` | Modo no interactivo: ejecutar y salir |
| `codex --model gpt-5.4` | Comenzar con un modelo especificado |
| `codex --version` | Mostrar el número de versión |
| `/model` | Cambiar de modelo dentro de la interfaz interactiva |
| `/approvals` | Ajustar el modo de aprobación dentro de la interfaz |
| `Ctrl + C` | Salir de la interfaz interactiva |

## Preguntas frecuentes

### Q1: ¿Aparece una pantalla de inicio de sesión de ChatGPT después del lanzamiento?

Si ve "Sign in with ChatGPT" o similar después del lanzamiento, la configuración no se aplicó.

**Solución de problemas:**

1. Asegúrese de que tanto `config.toml` como `auth.json` estén dentro de `~/.codex/`
2. Verifique que `model_provider` en `config.toml` esté configurado como `gccai`
3. Verifique que `auth.json` sea JSON válido y que la clave esté completamente introducida

### Q2: ¿Errores 401 / 403?

| Código de estado | Significado | Solución |
| - | - | - |
| `401 Unauthorized` | Clave de API ausente o inválida | Verifique la clave en `auth.json`: debe comenzar con `sk-` |
| `403 Forbidden` | Permisos insuficientes o clave expirada | Vaya a la [Consola](https://gccai.heqingsong.uk/keys) para verificar la clave |

Asegúrese también de que `base_url` esté configurado como `https://gccai.heqingsong.uk/v1`, y no la URL oficial de OpenAI.

### Q3: ¿Conexión fallida?

1. Verifique su conexión de red
2. Asegúrese de que `base_url` en `config.toml` sea correcto
3. Si está detrás de un proxy, asegúrese de que permita el acceso a `gccai.heqingsong.uk`

### Q4: ¿`wire_api = "chat"` ya no es compatible?

Las versiones recientes de Codex CLI (0.84.0 y posteriores) han eliminado el protocolo `chat`. Actualice `wire_api` en `config.toml` a `responses`:

```toml theme={null}
wire_api = "responses"
```

GccAi admite la Responses API: simplemente reinicie Codex después del cambio.

### Q5: ¿Fallan las llamadas a herramientas o las ejecuciones?

Asegúrese de que `wire_api` en `config.toml` esté configurado como `responses`. Si aún tiene problemas de compatibilidad, cambie a un modelo de la serie GPT-5 recomendado (p. ej., `gpt-5.5`, `gpt-5.3-codex`): se combinan de forma más fiable con Codex CLI.

### Q6: ¿Usar variables de entorno en lugar de auth.json?

También puede configurar la clave mediante una variable de entorno. Cambie el bloque del proveedor en `config.toml` a:

```toml theme={null}
[model_providers.gccai]
name = "GccAi"
base_url = "https://gccai.heqingsong.uk/v1"
wire_api = "responses"
env_key = "GCCAI_API_KEY"
```

Luego establezca la variable de entorno `GCCAI_API_KEY` con su clave de GccAi. `auth.json` ya no es necesario en esta configuración.

### Q7: ¿Cómo cambio de modelo?

Dos maneras:

1. **En la interfaz interactiva**: Escriba `/model` para cambiar
2. **Edite la configuración**: Cambie el campo `model` en `config.toml` y reinicie Codex CLI

### Q8: ¿Cómo verificar el uso y la facturación?

Acceda a la [Consola de GccAi](https://gccai.heqingsong.uk/overview) para ver estadísticas de llamadas a la API, detalles de consumo de tokens y tendencias de costos.

## Soporte y ayuda

Si tiene algún problema al usar Codex CLI:

* 📚 [Centro de documentación de GccAi](https://gccai.heqingsong.uk)
* 💬 [Comunidad de Discord](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @GccAi\_](https://x.com/GccAi_)
* 📧 Soporte técnico: [zhihong@gccai.heqingsong.uk](mailto:zhihong@gccai.heqingsong.uk)

***

> **[Comience con GccAi](https://gccai.heqingsong.uk)**
>
> ¡Regístrese en GccAi ahora, obtenga su clave de API y experimente un asistente de programación multimodelo en Codex CLI!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.