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

# Tutorial de uso del terminal Codex CLI

> Codex 集成指南 - Ace Data Cloud

Codex CLI es un agente de programación local de código abierto lanzado por OpenAI, que se ejecuta en tu terminal. Puede leer código, modificar archivos, ejecutar comandos, interpretar errores y ayudar a completar tareas diarias de desarrollo.

Codex CLI soporta proveedores de modelos personalizados. Puedes usarlo a través del proxy compatible con OpenAI Responses proporcionado por Ace Data Cloud, sin necesidad de suscribirte por separado a una cuenta oficial de OpenAI. Tras la configuración, Codex CLI enviará las solicitudes a `https://api.acedata.cloud/v1`.

## Proceso de solicitud

Para usar Codex CLI, primero puedes obtener tu API Token en la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para tenerlo a mano.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

Si aún no has iniciado sesión o registrado, se redirigirá automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión. Después de iniciar sesión o registrarte, volverás automáticamente a esta página.

Al solicitar por primera vez, recibirás un crédito gratuito para probar el servicio Codex CLI sin costo.

## Instalación de Codex CLI

Codex CLI es compatible con macOS, Linux, Windows y WSL. Puedes instalarlo mediante npm o usar Homebrew (solo macOS).

### Instalación con npm (recomendado)

Si ya tienes Node.js instalado, puedes instalarlo directamente con npm. Este método requiere Node.js 18 o superior.

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

### Instalación con Homebrew (macOS)

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

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

### Verificar la instalación

Después de la instalación, abre un nuevo terminal y verifica si el comando está disponible:

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

Si aparece `command not found`, normalmente significa que el terminal actual no ha cargado la nueva variable PATH. Cierra y vuelve a abrir el terminal, o verifica la configuración PATH indicada en la salida del script de instalación.

## Configuración de Codex CLI

Después de la instalación, Codex CLI intentará conectarse por defecto al servicio oficial de OpenAI. Para usar Ace Data Cloud, debes declarar un `model_provider` personalizado en el archivo de configuración de Codex y colocar el API Token en la variable de entorno correspondiente.

### Paso 1: Configurar la variable de entorno

Se recomienda escribir el API Token en el archivo de configuración de tu shell, por ejemplo `~/.zshrc`, `~/.bashrc` o `~/.bash_profile`:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

Reemplaza `{token}` por el API Token copiado desde la consola de Ace Data Cloud.

Luego, abre un nuevo terminal o ejecuta el comando `source` correspondiente para que la configuración surta efecto inmediatamente:

```bash theme={null}
source ~/.zshrc
```

### Paso 2: Editar el archivo de configuración de Codex

Codex CLI usa `~/.codex/config.toml` como archivo de configuración global. Si no existe, créalo:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

Escribe el siguiente contenido en `~/.codex/config.toml`:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

Descripción de los campos:

| Campo                                     | Descripción                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| `model_provider`                          | Nombre del proveedor predeterminado, corresponde a la clave `[model_providers.<name>]` abajo |
| `model`                                   | ID del modelo predeterminado                                                                 |
| `model_reasoning_effort`                  | Intensidad del razonamiento, valores comunes: `low`, `medium`, `high`                        |
| `[model_providers.acedatacloud].base_url` | URL del proxy OpenAI Responses de Ace Data Cloud                                             |
| `[model_providers.acedatacloud].env_key`  | Nombre de la variable de entorno donde Codex CLI lee el API Token                            |
| `[model_providers.acedatacloud].wire_api` | Tipo de protocolo, para usar OpenAI Responses debe ser `responses`                           |

### Limpiar caché de inicio de sesión OpenAI

Si antes iniciaste sesión con una cuenta oficial de OpenAI en Codex CLI, es posible que tengas un estado de inicio de sesión almacenado localmente (normalmente en `~/.codex/auth.json`). Antes de cambiar al proxy de Ace Data Cloud, se recomienda limpiar ese inicio de sesión antiguo:

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

Si el comando `codex logout` no está disponible, también puedes eliminar manualmente el archivo caché:

```bash theme={null}
rm -f ~/.codex/auth.json
```

Si nunca iniciaste sesión con una cuenta oficial de OpenAI, puedes omitir este paso.

### Iniciar sesión

Entra en el directorio de tu proyecto y luego inicia Codex CLI:

```bash theme={null}
cd /path/to/your/project
codex
```

Cuando veas la interfaz interactiva de Codex, puedes escribir tus solicitudes directamente, por ejemplo:

```text theme={null}
Explica la estructura de directorios de este proyecto
```

### Verificar configuración

Dentro de Codex CLI, puedes ver el modelo y proveedor actuales con:

```text theme={null}
/model
```

Deberías ver que el modelo actual proviene del proveedor `acedatacloud`, por ejemplo:

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

Si el proveedor mostrado no es `acedatacloud`, significa que la configuración no se aplicó correctamente. Revisa que `~/.codex/config.toml` esté guardado correctamente y que `ACEDATACLOUD_API_KEY` sea accesible en el terminal actual:

```bash theme={null}
echo $ACEDATACLOUD_API_KEY
```

También puedes consultar el historial de uso y detalles de facturación en la [Consola de Ace Data Cloud - Historial de uso](https://platform.acedata.cloud/console/usages) y verificar el saldo restante en la [Consola de Ace Data Cloud - Lista de aplicaciones](https://platform.acedata.cloud/console/applications).

## Cómo funciona

Codex CLI usa nativamente el protocolo OpenAI Responses API. Ace Data Cloud ofrece un servicio proxy compatible en `https://api.acedata.cloud/v1/responses`, por lo que Codex CLI no necesita un proxy local ni plugins adicionales.

El flujo de trabajo es:

1. Codex CLI lee `model_provider` en `~/.codex/config.toml` y carga el bloque de configuración correspondiente `[model_providers.acedatacloud]`.
2. Codex CLI lee el API Token desde la variable de entorno indicada en `env_key` (`ACEDATACLOUD_API_KEY`).
3. La solicitud se envía usando el protocolo `wire_api = "responses"` a `base_url + /responses`, es decir, `https://api.acedata.cloud/v1/responses`.
4. Ace Data Cloud valida la identidad con tu API Token, verifica el saldo y reenvía la solicitud al canal de modelo disponible.
5. Al completarse la solicitud, la plataforma registra el uso real y deduce el crédito correspondiente.

Esto significa que sigues usando el comando original `codex` y la experiencia nativa de Codex CLI, solo que el servicio de modelo subyacente cambia a Ace Data Cloud.

## Configurar el modelo

El campo `model` en `~/.codex/config.toml` determina el modelo predeterminado que usa Codex. El servicio OpenAI Responses de Ace Data Cloud soporta varios modelos comunes, entre ellos:

| Modelo             | Descripción                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `gpt-5`            | Modelo recomendado por defecto, adecuado para la mayoría de tareas de codificación |
| `gpt-5-mini`       | Más ligero y rápido, ideal para tareas simples                                     |
| `gpt-5.5`          | Versión más reciente con mayor capacidad                                           |
| `gpt-5.5-pro`      | Versión mejorada para tareas de razonamiento complejas                             |
| `gpt-4.1`          | Modelo principal de la generación anterior                                         |
| `o3`               | Modelo con razonamiento mejorado, para tareas que requieren razonamiento profundo  |
| `o4-mini-high-all` | Modelo ligero para razonamiento                                                    |

Para cambiar de modelo temporalmente, puedes usar el parámetro en línea al iniciar Codex:

```bash theme={null}
codex --model gpt-5-mini
```

O modificar directamente el campo `model` en `~/.codex/config.toml` y reiniciar. La lista completa de modelos está disponible en la [documentación del servicio OpenAI de Ace Data Cloud](https://platform.acedata.cloud/documents/openai).

## Nivel de confianza del proyecto

Codex CLI permite configurar diferentes niveles de confianza para distintos proyectos, controlando qué operaciones puede ejecutar el agente. Puedes añadir al final de `~/.codex/config.toml`:

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

Donde:

* `trusted`: el agente tiene permisos completos, puede ejecutar comandos y modificar archivos.
* `untrusted`: el agente tiene permisos limitados, más adecuado para proyectos desconocidos.

## Más información

* [Repositorio oficial de Codex CLI](https://github.com/openai/codex)
* [Documentación del servicio OpenAI de Ace Data Cloud](https://platform.acedata.cloud/documents/openai)
* [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications)