Guía de inicio rápido de Cloud Native Codex CLI

¡Bienvenido a Cloud Native Codex CLI! Este es un potente asistente de programación por IA basado en servicio de suscripción de configuración oficial de Codex.

Requisitos del sistema

Requisito	Detalles
Sistema operativo	macOS 12+, Ubuntu 20.04+/Debian 10+ o Windows 11 a través de WSL2
Git (opcional, recomendado)	2.23+ con asistente PR integrado
Memoria	Mínimo 4 GB (8 GB recomendado)

1. Instalar Codex CLI

Elige un método:

npm (universal)

npm i -g @openai/codex
# O en casos en que se necesite el nombre de paquete nativo:
# npm i -g @openai/codex@native
codex --version

Homebrew (macOS)

brew update
brew install codex
codex --version

Si codex no se ejecuta o tu versión de Node es antigua, actualiza Node (normalmente se requiere Node 22+) o instala mediante Homebrew.

---

2. Preparar la clave de API de GPTMeta Pro y configurar Codex

Registrar cuenta de GPTMeta Pro API

Paso 1: Visitar la página de registro

1. Visitar https://coultra.blueshirtmap.com
2. Hacer clic en el botón de registro para crear una nueva cuenta
3. Llenar la información de registro necesaria

Paso 2: Crear clave de API

1. Después del inicio de sesión exitoso, ir a la página de gestión de claves de API
2. Crear un nuevo grupo de claves de API

3. Seleccionar "Canal Estable de Alta Velocidad" como nombre del grupo 4. Generar y copiar su clave de API

Configurar Codex

Codex lee config.toml desde ~/.codex/ al iniciar. Si no existe, créalo:

mkdir -p ~/.codex
nano ~/.codex/config.toml

Añade lo siguiente a config.toml (ajusta según sea necesario):

# Valores por defecto de nivel superior
model = "gpt-4o"            # Rellena según los modelos disponibles en GPTMeta Pro API
model_provider = "coultra"  # Establece el proveedor por defecto

[model_providers.coultra]
name = "GPTMeta Pro API (compatible con OpenAI)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "clave_GPTMeta_Pro_API"    # Ingrese directamente su clave API
wire_api = "chat"           # Usa el protocolo de Chat Completions de OpenAI

# Opcional: define un perfil para cambiar rápido en la CLI
[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"      # Preguntar cuando sea necesario
sandbox_mode = "workspace-write"    # Permite escribir en el proyecto; sigue sin red

Notas sobre campos clave:

• model / model_provider: modelo y proveedor por defecto.
• [model_providers.<id>].base_url: raíz de tu servicio /v1; Codex interactuará mediante el protocolo de Chat Completions (típicamente POST {base_url}/chat/completions).
• env_key: indica a Codex de qué variable de entorno obtener las credenciales.
• wire_api: tipo de protocolo; usa "chat" para compatibilidad con Chat Completions.
• profiles.* y --profile: empaqueta un conjunto de configuraciones para cambiar rápidamente en tiempo de ejecución.

---

3. Ejecutar y verificar

Asegúrate de que la sesión actual tiene COULTRA_API_KEY (ver paso 2), luego:

# Ejecutar con perfil
codex --profile coultra "Explica la estructura del repositorio actual en español"

# O ejecutar con valores por defecto (proveedor ya establecido como coultra)
codex "Genera un script en Python que obtenga datos de una API y los guarde como CSV"

Durante la ejecución, Codex "lee código, modifica archivos y ejecuta comandos" en un sandbox local. Cuando se necesitan permisos, solicita según approval_policy; workspace-write permite escribir solo dentro del directorio del proyecto y se mantiene sin red.

---

4. Referencia rápida de sandbox / política de aprobación

• Política de aprobación:

  • --ask-for-approval o configura approval_policy para controlar el nivel de interacción.
  • --full-auto es una bandera de conveniencia (menos interrupciones, aún en sandbox).

• Niveles de sandbox:

  • read-only: solo lectura (sin escrituras, sin red)
  • workspace-write: puede escribir dentro del proyecto, aún sin red
  • danger-full-access: no recomendado, equivalente a desactivar el sandbox
  • En CLI usa --sandbox MODE; en config usa sandbox_mode="MODE".

¿Necesitas acceso temporal a la red? La versión actual prioriza la seguridad "sin red por defecto". Usa el modo "peligroso" u opciones futuras con precaución.

---

5. Preguntas frecuentes (FAQ)

① 401/403: clave de API inválida o saldo insuficiente

• Regenera una clave en el panel de GPTMeta Pro API; asegúrate de que COULTRA_API_KEY está presente en la sesión actual (echo $COULTRA_API_KEY).
• Inyecta variables de entorno mediante Secrets en CI para evitar hardcodearlas.

② 404 / "Resource not found": base_url incorrecto

• La mayoría de implementaciones compatibles requieren que base_url apunte a …/v1; algunas plataformas (p. ej., Azure) necesitan segmentos de ruta adicionales. Rutas incompletas provocan 404.

③ --profile no aplicado o algunas claves no cargadas

• Actualiza a una versión más reciente; versiones antiguas tenían problemas conocidos al cargar algunas claves de perfil.

④ Tras instalar con npm, codex no está disponible o la versión es incorrecta

• Actualiza Node (recomendado 22+) o instala mediante Homebrew. Versiones recientes cambiaron el empaquetado y el comportamiento de npm.

⑤ Proveedor local/tercero inalcanzable o puerto incorrecto

• Confirma base_url; versiones tempranas tenían errores con base_url/puerto que se resuelven actualizando.

---

6. Configuración mínima viable (MVP) reutilizable

# ~/.codex/config.toml
model = "gpt-4o"
model_provider = "coultra"

[model_providers.coultra]
name = "GPTMeta Pro API (compatible con OpenAI)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "clave_GPTMeta_Pro_API"    # Ingrese directamente su clave API
wire_api = "chat"

[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Comando de inicio:

export COULTRA_API_KEY="tu-clave"
codex --profile coultra "Añade un subcomando de CLI a este repositorio"

---

7. Consejos avanzados de uso

Referencia CLI

Comando	Propósito	Ejemplo
codex	TUI interactivo	codex
codex "..."	TUI interactivo con prompt inicial	codex "fix lint errors"
codex exec "..."	"Modo de automatización" no interactivo	codex exec "explain utils.ts"

Modo no interactivo/CI

Ejecutar Codex sin interfaz en pipelines. Ejemplo de paso de GitHub Action:

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

Protocolo de Contexto de Modelo (MCP)

Codex CLI se puede configurar para usar servidores MCP definiendo una sección mcp_servers en ~/.codex/config.toml. Está diseñado para reflejar cómo herramientas como Claude y Cursor definen mcpServers en sus respectivos archivos de configuración JSON, aunque el formato de Codex es ligeramente diferente ya que usa TOML en lugar de JSON, por ejemplo:

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }