Guía de uso para integrar Codex

0. Conclusión en una frase

La plataforma ya tiene implementado el endpoint OpenAI Responses API POST /v1/responses, y ha sido diseñado explícitamente pensando en los requisitos de Codex (secuencia de eventos SSE en streaming, llamadas a funciones como herramientas, y compatibilidad sin estado con store:false).
Por lo tanto, Codex CLI puede conectarse de dos formas:

1. Conexión directa (recomendada): configura wire_api = "responses" en ~/.codex/config.toml y usa directamente /v1/responses;
2. cc-switch: utiliza la herramienta gráfica para cambiar de un clic entre proveedores (Codex, Claude Code, etc.).

En ambos casos la tarificación es exactamente la misma (misma pipeline de reserva → enrutamiento → liquidación → libro mayor).

1. Requisitos previos

2. Capacidades y límites del endpoint de la plataforma (/v1/responses)

• Endpoint: POST https://routeall.ai/v1/responses
• Autenticación: Authorization: Bearer sk-ra-...

2.1 Soportado (compatible con Codex)

2.2 Límites (subconjunto de texto sin estado)

2.3 Tarificación y errores

• Tarificación: exactamente la misma pipeline que /v1/chat/completions, las pruebas muestran coste similar; la cabecera de respuesta X-RouteAll-Charge-Credit indica el importe facturado al cliente (no el coste).
• Formato de error: { "error": { "message", "type", "code", "param" } }; códigos HTTP: 401 (falta clave o es incorrecta), 402 (saldo insuficiente), 429 (limitación de tasa), 400 (parámetros malformados), 503 (todos los canales upstream caídos).

3. Modalidad 1: conexión directa desde Codex CLI (API Responses, recomendada)

3.1 Configuración de ~/.codex/config.toml

model = "deepseek-v4-pro"           # modelo por defecto; cámbialo por el nombre canónico del catálogo
model_provider = "routeall"

[model_providers.routeall]
name = "RouteAll"
base_url = "https://routeall.ai/v1" # URL base compatible con OpenAI (sin el sufijo /responses)
env_key = "ROUTEALL_API_KEY"
wire_api = "responses"              # responses = usa /v1/responses (recomendado)

3.2 Establecer variable de entorno

# Linux / macOS
export ROUTEALL_API_KEY="sk-ra-TU-CLAVE"

# Windows PowerShell
# $env:ROUTEALL_API_KEY = "sk-ra-TU-CLAVE"

3.3 Iniciar

codex

3.4 Cambiar modelo temporalmente

codex --model Codex-haiku-4-5 "Refactoriza este módulo"
codex --model deepseek-v4-flash "Explica esta expresión regular"

3.5 Acerca de wire_api

Nota: el subdominio de la puerta de enlace api. no está habilitado actualmente para el exterior (configuración interna del servidor PUBLIC_API_DOMAIN=api.localhost); los endpoints /v1/* se sirven directamente desde el dominio principal routeall.ai, por lo que la base_url debe usar https://routeall.ai/v1.

4. Modalidad 2: cc-switch (cambio gráfico de un clic)

cc‑switch es una herramienta de código abierto para cambiar de proveedor (farion1231/cc-switch) que permite gestionar las configuraciones de Codex, Claude Code, OpenCode, Gemini, etc., y alternar entre ellas con un solo clic.

4.1 Instalación

Repositorio GitHub farion1231/cc-switch → Releases → descargar el instalador correspondiente a tu sistema (Windows / macOS / Linux).

4.2 Añadir un nuevo proveedor

1. Abre cc‑switch, ve a la pestaña Codex → «Añadir proveedor»;
2. Rellena:
   • Nombre del proveedor: RouteAll (puede ser cualquiera)
   • API Host / Base URL: https://routeall.ai/v1
   • API Key: sk-ra-TU-CLAVE
   • Lista de modelos: nombres canónicos de la plataforma (por ejemplo deepseek-v4-pro, Codex-haiku-4-5; se pueden poner varios en líneas separadas)
3. Guarda.

4.3 Activar y cambiar

Selecciona RouteAll → «Cambiar / Activar». cc-switch escribe la configuración del proveedor en ~/.codex/config.toml (equivalente a la configuración de la modalidad 1). Después solo hay que lanzar codex normalmente.

Nota: algunas versiones de cc-switch reescriben el protocolo de Codex a /v1/chat/completions (es decir, wire_api = "chat"). La plataforma admite ambas vías (el B15 ya corrigió los errores 400 cuando un cliente de herramientas usa chat); si tu versión permite elegir el protocolo, selecciona Responses para una experiencia más nativa.

5. Verificación

5.1 Obtener la lista de modelos disponibles (úsese la lista real, no inventes nombres)

curl https://routeall.ai/v1/models \
  -H "Authorization: Bearer sk-ra-TU-CLAVE"
# O el directorio público (sin autenticación, solo muestra modelos con canales activos)
curl https://routeall.ai/v1/public/models

5.2 No streaming (verifica primero que la conexión funciona)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-TU-CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Hola, preséntate en una frase",
    "max_output_tokens": 200
  }'

Una respuesta exitosa devuelve el formato Responses (output[].content[].output_text + output_text + usage).

5.3 Streaming (tal como lo usa Codex)

curl -N https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-TU-CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Cuenta un chiste corto",
    "stream": true
  }'

Orden de eventos: response.created → output_item.added → output_text.delta ×N → output_item.done → response.completed.

5.4 Llamada a herramientas (bucle agéntico)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-TU-CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": [{"role": "user", "content": "Calcula 17*23"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "calculator",
        "description": "Realiza operaciones aritméticas básicas",
        "parameters": {
          "type": "object",
          "properties": { "expr": { "type": "string" } }
        }
      }
    }],
    "tool_choice": "auto"
  }'

output incluirá un elemento con type: "function_call" (call_id, name, arguments); después se puede enviar un function_call_output con el resultado para continuar la conversación multi-turno.

6. Solución de problemas

7. Tarificación y recomendaciones de seguridad

• Métrica de facturación: precio oficial del modelo × multiplicador del grupo de usuarios; en streaming se liquida según el uso real; los aciertos de caché se facturan al precio completo (estrategia B12, la diferencia de caché la asume la plataforma, al cliente no se le reduce el cargo).
• Visibilidad de costes: cabecera de respuesta X-RouteAll-Charge-Credit (importe facturado); los campos cost/margin nunca aparecen en la respuesta al usuario (INV-8).
• Seguridad de la clave: las claves sk-ra- solo se guardan como hash SHA256 y no son visibles en el panel; jamás las incrustes en código cliente o repositorios.
• Se recomienda probar primero la conexión con un modelo pequeño (verificación vía curl)