> ## 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.

# Guía de uso de Codex para VS Code

> Codex 集成指南 - Ace Data Cloud

Codex es un agente de programación lanzado por OpenAI. Además de la CLI de terminal, también ofrece una extensión para VS Code que permite chatear, leer archivos, citar contexto, generar modificaciones y previsualizar cambios en la barra lateral del editor.

Este documento explica cómo configurar y usar la extensión Codex en VS Code mediante el proxy compatible OpenAI Responses de Ace Data Cloud. La extensión Codex para VS Code y la CLI Codex usan el mismo sistema de configuración local, por lo que basta con apuntar `~/.codex/config.toml` a Ace Data Cloud para que Codex en VS Code use `https://api.acedata.cloud/v1`.

## Proceso de solicitud

Para usar Codex, primero puede obtener su 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 ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión para registrarse o iniciar sesión, y luego volverá a esta página.

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

## Instalar la extensión Codex

Busque `Codex` en el marketplace de extensiones de VS Code e instale la extensión **Codex - OpenAI's coding agent** publicada por OpenAI. Su ID en Marketplace es:

```text theme={null}
openai.chatgpt
```

También puede instalarla desde la línea de comandos:

```bash theme={null}
code --install-extension openai.chatgpt
```

Tras la instalación, reinicie o recargue VS Code. Si no ve la entrada de Codex, abra la paleta de comandos (macOS: `Cmd+Shift+P`, Windows/Linux: `Ctrl+Shift+P`) y ejecute:

```text theme={null}
Codex: Open Codex Sidebar
```

Por defecto, Codex aparecerá en la barra lateral derecha de VS Code. También puede arrastrarlo a la barra de actividades izquierda.

## Instalar Codex CLI (para verificación)

La documentación oficial indica que la extensión Codex para VS Code y la CLI Codex usan la misma capa de configuración. Para verificar que el API Token y el modelo funcionan antes de configurar VS Code, se recomienda instalar también la CLI Codex.

Una forma recomendada es instalarla vía npm, requiriendo Node.js 18 o superior:

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

Usuarios de macOS también pueden instalarla con Homebrew:

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

Tras la instalación, verifique que el comando esté disponible:

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

Si solo desea usar la extensión VS Code, puede omitir la verificación con CLI; seguirá usando la misma configuración `~/.codex/config.toml`.

## Configurar la API de Ace Data Cloud

La extensión Codex para VS Code y la CLI Codex comparten el archivo de configuración. Por defecto, Codex solicita iniciar sesión con la cuenta oficial de OpenAI o configurar la API Key oficial. Para usar Ace Data Cloud, debe configurar el API Token y el archivo `~/.codex/config.toml`.

### Paso 1: configurar variable de entorno

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

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

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

Luego, abra una nueva terminal o ejecute el comando `source` correspondiente para aplicar la configuración inmediatamente:

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

Si VS Code ya está abierto, reinícielo o recárguelo para que la extensión lea la nueva variable de entorno.

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

El archivo de configuración a nivel usuario de Codex está en `~/.codex/config.toml`. Si no existe, créelo:

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

Escriba la siguiente configuración:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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`         | Proveedor de modelo por defecto, corresponde a `[model_providers.acedatacloud]` abajo           |
| `model`                  | ID del modelo por defecto                                                                       |
| `model_reasoning_effort` | Intensidad del razonamiento, valores comunes: `low`, `medium`, `high`                           |
| `approval_policy`        | Política de confirmación antes de ejecutar comandos, se recomienda `on-request` para uso diario |
| `sandbox_mode`           | Permisos sandbox al ejecutar comandos, se recomienda `workspace-write` para desarrollo diario   |
| `base_url`               | URL base de la API compatible OpenAI de Ace Data Cloud                                          |
| `env_key`                | Nombre de la variable de entorno donde Codex lee el API Token                                   |
| `wire_api`               | Tipo de protocolo, para usar OpenAI Responses debe ser `responses`                              |

También puede abrir este archivo desde VS Code haciendo clic en el icono de engranaje en la esquina superior derecha de la extensión Codex y seleccionando **Codex Settings > Open config.toml**.

### Configuración a nivel de proyecto

Si desea que un proyecto use una configuración diferente, puede crear `.codex/config.toml` en la raíz del proyecto. Codex prioriza la configuración a nivel proyecto, pero el proyecto debe estar marcado como trusted para cargar la configuración en `.codex/`.

Ejemplo:

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

Se recomienda mantener los tokens personales en variables de entorno y no incluirlos en el repositorio. La inclusión del archivo `.codex/config.toml` a nivel proyecto debe decidirse según la política del equipo.

## Limpiar sesión guardada de OpenAI

Si antes inició sesión con la cuenta oficial de OpenAI en la extensión Codex, puede que la sesión local siga activa. Antes de cambiar al proxy Ace Data Cloud, puede ejecutar en terminal:

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

Si el comando no está disponible, puede eliminar el archivo de caché local:

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

Luego reinicie o recargue VS Code.

## Uso básico

Tras la configuración, abra el panel Codex en el lado izquierdo o derecho de VS Code y escriba su solicitud. Por ejemplo:

```text theme={null}
Explique la estructura de directorios del proyecto actual y señale el archivo de entrada principal.
```

La extensión Codex puede usar archivos y código seleccionado en el editor como contexto. También puede referenciar archivos con `@` en el cuadro de entrada, por ejemplo:

```text theme={null}
Basándose en @src/App.vue, ayúdame a dividir esta página en componentes más claros.
```

Si selecciona un fragmento de código, puede añadirlo al hilo de Codex ejecutando en la paleta de comandos:

```text theme={null}
Codex: Add to Codex Thread
```

O añadir el archivo completo con:

```text theme={null}
Codex: Add File to Codex Thread
```

## Cambiar modelo e intensidad de razonamiento

La extensión Codex para VS Code permite cambiar el modelo y ajustar el esfuerzo de razonamiento desde el selector debajo del cuadro de entrada. Al usar el proveedor personalizado Ace Data Cloud, lo más seguro es definir el modelo por defecto en `~/.codex/config.toml` y luego cambiarlo en la interfaz según necesidad. Se recomienda usar por defecto:

| Escenario                                           | Modelo recomendado        | Intensidad de razonamiento |
| --------------------------------------------------- | ------------------------- | -------------------------- |
| Lectura de código y pequeñas modificaciones         | `gpt-5-mini`              | `medium`                   |
| Tareas de desarrollo habituales                     | `gpt-5`                   | `high`                     |
| Refactorizaciones complejas y razonamiento profundo | `gpt-5.5` o `gpt-5.5-pro` | `high`                     |
| Tareas con razonamiento potenciado                  | `o3`                      | `high`                     |

Si el modelo deseado no aparece en la interfaz, modifique directamente el campo `model` en `~/.codex/config.toml` y reinicie o recargue VS Code. La lista completa de modelos está en la [documentación del servicio OpenAI de Ace Data Cloud](https://platform.acedata.cloud/documents/openai).

## Seleccionar modo de trabajo

La extensión Codex soporta distintos modos de trabajo. Los más comunes son:

| Modo                  | Escenario adecuado                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Chat`                | Solo discutir, explicar código o planificar sin que Codex modifique archivos directamente                          |
| `Agent`               | Permite que Codex lea archivos, modifique código y ejecute comandos necesarios; recomendado para desarrollo diario |
| `Agent (Full Access)` | Permite mayores permisos y acceso a red; para escenarios donde se conocen los riesgos                              |

Se recomienda usar `Agent` con `approval_policy = "on-request"` para que Codex solicite confirmación antes de ejecutar comandos sensibles, acceder a rutas fuera del workspace o usar la red.

## Verificar configuración

Puede verificar que Codex funcione con Ace Data Cloud usando la CLI con la misma configuración:

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

Si la configuración es correcta, verá una respuesta como:

```text theme={null}
ADC_Codex_OK
```

Luego, en VS Code, abra el panel Codex y escriba una pregunta sencilla:

```text theme={null}
Explique en una frase el propósito del workspace actual.
```

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

## Cómo funciona

La extensión Codex para VS Code no tiene una configuración independiente. Usa la CLI Codex local y comparte la capa de configuración:

1. La extensión Codex en VS Code se inicia y lee `~/.codex/config.toml` a nivel usuario.
2. Si el proyecto está marcado como trusted y contiene `.codex/config.toml`, también carga la configuración a nivel proyecto.
3. Cuando `model_provider` apunta a `acedatacloud`, Codex lee el API Token desde `ACEDATACLOUD_API_KEY`.
4. Las solicitudes se envían mediante el protocolo OpenAI Responses a `https://api.acedata.cloud/v1/responses`.
5. Ace Data Cloud valida la identidad, verifica el crédito, reenvía la solicitud y registra el uso.

Por ello, normalmente solo necesita configurar una vez. Si verifica con la CLI en terminal, la extensión VS Code usará la misma configuración.

## Más información

* [Documentación oficial de la extensión Codex IDE](https://developers.openai.com/codex/ide)
* [Referencia de configuración de la extensión Codex IDE](https://developers.openai.com/codex/ide/settings)
* [Configuración básica de Codex CLI](https://developers.openai.com/codex/config-basic)
* [Documentación del servicio OpenAI de Ace Data Cloud](https://platform.acedata.cloud/documents/openai)