Conectar modelos externos a Codex

Esta guía abarca dos vías de integración para modelos alojados por terceros:

Primero debe comprender una limitación importante:

Esta guía se aplica a los clientes de Codex que se ejecutan localmente, incluidos Codex CLI, la extensión de Codex para IDE y los clientes de escritorio que leen el mismo config.toml. Actualmente, los chats de Codex en la nube no pueden cambiar a un modelo personalizado mediante esta configuración.

Antes de comenzar

Instalar o actualizar Codex CLI

npm install -g @openai/codex@latest
codex --version

Después de la primera instalación, ejecute Codex al menos una vez:

codex

Esto inicializa el directorio de configuración del usuario.

Ubicaciones del archivo de configuración de Codex

macOS y Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Haga una copia de seguridad del archivo antes de realizar cambios.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Los proveedores, MCP y las puertas de enlace de modelos son diferentes

Estos conceptos resuelven problemas diferentes:

• model_provider determina dónde envía Codex las solicitudes del modelo;
• MCP añade herramientas y contexto, como GitHub, navegadores o bases de datos;
• una puerta de enlace de modelos gestiona la conversión de protocolos, la autenticación, el enrutamiento, los registros o la limitación de velocidad entre Codex y un modelo de origen.

Para cambiar el modelo subyacente, configure un proveedor en lugar de MCP.

Proteger las API key

No confirme API key reales en un repositorio de Git ni exponga claves completas en capturas de pantalla, registros o solicitudes de soporte.

Para los proveedores configurados manualmente, use preferentemente variables de entorno:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch almacena la configuración del proveedor localmente y modifica la configuración local de Codex cuando cambia de proveedor. Es una herramienta de código abierto de terceros, no un producto de OpenAI. Instálela únicamente desde el sitio web oficial de CC Switch o su repositorio de GitHub, y proteja su base de datos local, su configuración y sus copias de seguridad.

1. Conectar modelos de terceros con CC Switch

CC Switch es la opción más sencilla para la mayoría de los modelos de terceros. Gestiona proveedores, API key, listas de modelos y enrutamiento local, y puede traducir protocolos de origen incompatibles.

1.1 Qué resuelve CC Switch

Los clientes modernos de Codex envían solicitudes de Responses API, mientras que muchos servicios de terceros ofrecen una de las siguientes opciones:

• OpenAI Chat Completions;
• Anthropic Messages;
• ID de modelos que Codex no enumera de forma predeterminada;
• parámetros de razonamiento o formatos de eventos de streaming específicos del proveedor.

CC Switch puede traducir la ruta de la solicitud de la siguiente manera:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Un proveedor que admite Responses de forma nativa no necesita conversión del protocolo Chat. Un proveedor de Chat Completions o Anthropic Messages requiere enrutamiento local.

1.2 Instalar CC Switch

Use únicamente los canales de distribución oficiales:

• Sitio web oficial de CC Switch
• Repositorio de GitHub de CC Switch
• Versiones de CC Switch

En macOS, se recomienda Homebrew:

brew install --cask cc-switch

Para actualizar:

brew upgrade --cask cc-switch

En Windows, descargue el instalador .msi o el archivo portátil desde Releases.

En Linux, descargue el paquete .deb, .rpm o AppImage desde Releases. Las etiquetas pueden cambiar ligeramente entre versiones, por lo que debe usar la versión estable más reciente y considerar autoritativas las opciones que se muestran en la aplicación.

1.3 Requisitos previos

Prepare lo siguiente:

1. Codex está instalado y se ha iniciado al menos una vez;
2. CC Switch está instalado y se inicia correctamente;
3. dispone de una API key para el servicio del modelo de destino;
4. ha confirmado la Base URL, el ID del modelo y el protocolo de origen en la documentación del proveedor;
5. si necesita funciones oficiales de la cuenta de Codex, complete primero un inicio de sesión oficial.

Compruebe el estado actual de inicio de sesión de Codex:

codex login status

Inicie sesión cuando sea necesario:

codex login

También está disponible el inicio de sesión mediante código de dispositivo:

codex login --device-auth

1.4 Opcional: conservar el inicio de sesión oficial al usar un proveedor externo

Esto resulta útil principalmente cuando desea conservar las funciones de escritorio, los plugins oficiales o las funciones de control remoto mientras las solicitudes del modelo se envían a un proveedor externo. Los usuarios que solo usan CLI y no dependen de las funciones de la cuenta oficial pueden omitirlo.

Orden recomendado:

1. seleccione OpenAI Official en el panel de Codex de CC Switch;
2. inicie Codex e inicie sesión con una cuenta oficial;
3. abra Settings → General → Codex App Enhancements en CC Switch;
4. active Keep official login when switching third-party providers;
5. añada o cambie al proveedor externo.

Con esta opción activada, CC Switch intenta conservar:

• ~/.codex/auth.json para el estado del inicio de sesión oficial;
• ~/.codex/config.toml para la configuración del proveedor externo activo, el modelo, el punto de conexión y la autenticación.

auth.json contiene datos de inicio de sesión confidenciales. No lo comparta ni lo confirme en el control de versiones.

1.5 Añadir un proveedor externo

Abra CC Switch, cambie al panel de nivel superior Codex y haga clic en el botón para añadir situado en la esquina superior derecha.

Preferir un ajuste predefinido integrado

Cuando exista un ajuste predefinido, úselo e introduzca únicamente la API key y los valores específicos de la cuenta que sean necesarios. Normalmente, un ajuste predefinido configura:

• la Base URL;
• el modelo predeterminado;
• el protocolo de origen;
• si se requiere enrutamiento local;
• las asignaciones de modelos;
• los parámetros de razonamiento seleccionados.

La lista de ajustes predefinidos cambia a medida que evoluciona CC Switch. La documentación de larga duración no debe codificar de forma rígida el ID actual del modelo de un proveedor; use la lista de la aplicación y la documentación oficial del proveedor.

Crear un proveedor personalizado

Cuando no haya ningún ajuste predefinido disponible, elija una configuración personalizada y proporcione lo siguiente:

La opción más importante es Upstream Format:

No seleccione Responses únicamente porque un proveedor anuncie «compatibilidad con OpenAI». Muchas API compatibles con OpenAI solo implementan Chat Completions.

1.6 Introducir correctamente la Base URL

De forma predeterminada, CC Switch añade la ruta de API adecuada a la Base URL. En la mayoría de los casos, introduzca la raíz de la API indicada en la documentación del proveedor en lugar de repetir usted mismo /chat/completions o /responses.

Por ejemplo, si el proveedor documenta:

POST https://api.example.com/v1/chat/completions

es posible que deba introducir:

https://api.example.com

o, según el ajuste predefinido y la documentación del proveedor:

https://api.example.com/v1

Que /v1 forme parte de la Base URL depende del proveedor y del ajuste predefinido de CC Switch. Use la comprobación de conectividad integrada o los registros de enrutamiento para confirmar la URL final de la solicitud.

Use Full URL Mode únicamente cuando el proveedor requiera una ruta completa y no estándar para el punto de conexión.

1.7 Configurar Needs Local Routing y la asignación de modelos

Active Needs Local Routing cuando el proveedor use Chat Completions, Anthropic Messages o nombres de modelos que Codex no reconozca de forma predeterminada.

Los ajustes predefinidos orientados a Chat suelen activarlo automáticamente. Compruebe esta opción en los proveedores personalizados.

Una vez activado, estará disponible una tabla de asignación de modelos. Los campos habituales incluyen:

Puntos importantes:

• use el ID exacto del modelo indicado en la documentación del proveedor;
• no adivine la ventana de contexto;
• reinicie Codex después de cambiar la lista de modelos;
• CC Switch genera el catálogo de modelos de Codex a partir de estas asignaciones;
• si un servicio de retransmisión cambia el dominio o el nombre del modelo, la detección automática de las capacidades de razonamiento puede ser incorrecta y debe revisarse en la configuración avanzada.

1.8 Activar el enrutamiento local y la toma de control de Codex

En CC Switch, abra:

Settings → Routing → Local Routing

A continuación:

1. active el interruptor principal de enrutamiento local;
2. active Codex en Routing Enabled;
3. confirme la opción Needs Local Routing del proveedor;
4. mantenga CC Switch en ejecución mientras se use el proveedor.

La ruta local predeterminada suele ser:

http://127.0.0.1:15721

Tras la toma de control, la configuración activa de Codex apunta a la ruta local de CC Switch. A continuación, CC Switch reenvía las solicitudes al proveedor de origen seleccionado actualmente.

Para un servicio de origen de Chat Completions, el flujo suele ser:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Cambiar de proveedor y reiniciar Codex

Vuelva a la lista de proveedores de Codex en CC Switch, seleccione el proveedor que configuró y actívelo.

Reinicie Codex por completo después del cambio porque:

• Codex lee config.toml durante el inicio;
• el menú /model suele cargar su catálogo durante el inicio;
• la extensión del IDE o el cliente de escritorio pueden almacenar en caché el proveedor anterior;
• las sesiones existentes pueden conservar metadatos del modelo anterior.

Los usuarios de CLI pueden simplemente iniciar un proceso nuevo:

codex

1.10 Verificar la integración

Dentro de Codex, ejecute:

/status

Revise el modelo y el proveedor activos, los permisos y la información del contexto.

Abra el selector de modelos:

/model

Inspeccione las capas de configuración:

/debug-config

Compruebe también:

• el proveedor activo de Codex en CC Switch;
• los registros o las estadísticas del enrutamiento local de CC Switch;
• el historial de solicitudes y los cambios de saldo en el panel del proveedor;
• si ~/.codex/config.toml apunta actualmente a la ruta local.

No valide la configuración únicamente con un saludo sencillo. Ejecute al menos una prueba de las capacidades del agente:

1. pida a Codex que enumere los archivos del proyecto actual;
2. pídale que lea y resuma un archivo;
3. pídale que modifique un archivo pequeño;
4. pídale que ejecute las pruebas;
5. deje un fallo sencillo sin resolver y compruebe que pueda usar el resultado de la prueba para seguir corrigiendo el proyecto.

Que la generación de texto funcione no demuestra que las llamadas a herramientas y los flujos de trabajo de agentes con varios turnos sean compatibles.

1.11 Volver al proveedor oficial de OpenAI

Seleccione OpenAI Official en CC Switch y reinicie Codex.

Compruebe el estado de inicio de sesión:

codex login status

Si es necesario, vuelva a iniciar sesión:

codex login

Cuando necesite tanto el estado de inicio de sesión oficial como las solicitudes de modelos de terceros, confirme que Keep official login when switching third-party providers sigue activado.

1.12 Limitaciones y consideraciones operativas

CC Switch simplifica la configuración, pero no elimina las limitaciones del servicio de origen:

• CC Switch debe permanecer en ejecución para convertir Chat o Messages;
• la conversión de protocolos no puede reproducir todas las funciones específicas de cada proveedor;
• algunos modelos pueden conversar, pero no realizan llamadas a herramientas de forma fiable;
• Web Search, la entrada de imágenes, WebSockets o el almacenamiento de respuestas podrían no estar disponibles;
• se siguen aplicando los límites de velocidad, la facturación y las políticas de conservación de datos del proveedor de origen;
• un servicio de retransmisión de API puede volver a modificar las solicitudes y respuestas;
• las configuraciones deben volver a probarse después de actualizar CC Switch, Codex o el proveedor.

CC Switch es más adecuado para el desarrollo local en equipos de escritorio. Para servidores, CI o automatizaciones sin interfaz de larga duración, prefiera un proveedor nativo de Responses o una puerta de enlace autoalojada.

2. Conectar una API alojada mediante un proveedor de modelos personalizado

Configure un proveedor directamente solo cuando el servicio admita de forma nativa la Responses API que requiere Codex.

Si el servicio ofrece únicamente /chat/completions o Anthropic Messages, use el flujo de trabajo de CC Switch de la sección 1. No intente resolver la incompatibilidad con wire_api = "chat".

2.1 Capacidades de API necesarias

Un proveedor adecuado para la integración directa con Codex debe admitir como mínimo:

• POST /responses;
• objetos JSON de Responses;
• eventos de streaming SSE de Responses;
• llamadas a funciones o herramientas;
• parámetros de herramientas de JSON Schema;
• continuación después de devolver los resultados de las herramientas;
• solicitudes de varios turnos o un equivalente de previous_response_id;
• una ventana de contexto suficiente y solicitudes estables de larga duración;
• autenticación, límites de velocidad y respuestas de error documentados.

La generación de texto convencional por sí sola no basta para disponer de un agente Codex fiable.

2.2 Configuración genérica

Edite la configuración del usuario:

~/.codex/config.toml

Añada:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

No use estos ID de proveedor reservados:

openai
ollama
lmstudio

En su lugar, use un ID personalizado como third_party o company_gateway.

2.3 Campos de configuración

Que base_url incluya /v1 depende de la documentación del proveedor. Un punto de conexión final habitual es:

https://provider.example.com/v1/responses

2.4 Establecer la API key

Sesión actual de bash / zsh:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Sesión actual de PowerShell:

$env:THIRD_PARTY_API_KEY = "your API key"

Consérvela para el usuario actual de Windows:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Reinicie el terminal, el IDE o el cliente de escritorio después de establecer una variable de entorno persistente.

2.5 Probar primero el punto de conexión de Responses

Antes de iniciar Codex, llame directamente al proveedor:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Compruebe que:

• el punto de conexión no devuelva 404;
• la respuesta tenga una estructura de tipo Responses y no solo una matriz choices de Chat Completions;
• se acepte el ID del modelo;
• la autenticación sea correcta;
• los errores contengan información de diagnóstico útil.

A continuación, pruebe por separado:

• stream: true;
• las llamadas a herramientas;
• la continuación con resultados de herramientas;
• varios turnos;
• contextos largos;
• la concurrencia y los límites de velocidad.

2.6 Validar la configuración de Codex

Inicie en modo estricto:

codex --strict-config

--strict-config trata las claves de configuración desconocidas como errores, lo que ayuda a identificar campos copiados de guías obsoletas.

Dentro de Codex, ejecute:

/status

Para inspeccionar las fuentes de configuración, ejecute:

/debug-config

Sobrescriba el proveedor y el modelo para una sola ejecución sin cambiar la configuración predeterminada:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Catálogos de modelos y Unknown model

Un catálogo de modelos de Codex puede describir:

• el tamaño de la ventana de contexto;
• los niveles de razonamiento admitidos;
• las modalidades de entrada;
• las capacidades de llamada a herramientas;
• el comportamiento de truncamiento;
• las versiones mínimas del cliente.

Cuando el proveedor suministre un catálogo de modelos compatible con Codex, guárdelo localmente y configure:

model_catalog_json = "~/.codex/provider-models.json"

Cuando no exista ningún catálogo, establezca una ventana de contexto solo después de confirmar el valor real:

model_context_window = 131072

No copie metadatos de un modelo no relacionado simplemente para eliminar una advertencia. Los metadatos incorrectos de capacidades o contexto pueden provocar un truncamiento prematuro, errores de límites del servicio de origen o llamadas a herramientas que no funcionen.

2.8 Lista completa de comprobación de compatibilidad

Antes de usarlo en producción, pruebe:

• texto /responses sin streaming;
• streaming SSE de Responses;
• una llamada a una herramienta;
• varias llamadas secuenciales o paralelas a herramientas;
• parámetros de JSON Schema;
• continuación con resultados de herramientas;
• contextos largos y compactación automática;
• parámetros de razonamiento;
• imágenes u otras modalidades de entrada;
• límites de velocidad y comportamiento de los reintentos;
• si un proxy almacena en búfer los eventos SSE;
• si el proveedor elimina o reescribe campos de herramientas;
• las políticas de conservación de datos, registro y privacidad.

2.9 Dónde debe ubicarse la configuración del proveedor

Coloque model_provider, model_providers y la autenticación del proveedor en el archivo del usuario:

~/.codex/config.toml

No los coloque en el archivo del repositorio:

<project>/.codex/config.toml

Codex ignora los campos locales del proyecto que podrían redirigir las solicitudes del modelo o cambiar la autenticación del proveedor. Esto impide que un repositorio clonado que no sea de confianza reenvíe las solicitudes de forma silenciosa a otro servidor.

3. Gestionar varios proveedores externos mediante perfiles

Normalmente, los usuarios de CC Switch pueden cambiar de proveedor en la aplicación y no necesitan perfiles de Codex.

Los perfiles son útiles cuando configura manualmente varios proveedores nativos de Responses. Mantenga las definiciones de los proveedores en la configuración base y use archivos de perfil independientes para seleccionar un proveedor y un modelo.

~/.codex/config.toml base:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Cree:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Cree otro perfil:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Seleccione un perfil al iniciar Codex:

codex --profile fast
codex --profile quality

Modo no interactivo:

codex exec --profile quality "Review the current changes"

Los archivos de perfil se encuentran en:

$CODEX_HOME/<profile-name>.config.toml

El CODEX_HOME predeterminado es ~/.codex.

Las versiones recientes de Codex usan archivos de perfil independientes y ya no leen las tablas [profiles.<name>] heredadas. Migre cada perfil heredado a su propio archivo <name>.config.toml.

4. Encabezados personalizados y autenticación avanzada

4.1 Tokens de portador estándar

La mayoría de los servicios de terceros funcionan con:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex lee la clave del entorno y aplica la autenticación mediante token de portador del proveedor.

4.2 Encabezados personalizados de API key

Algunos servicios requieren:

x-api-key: <key>

Use env_http_headers:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

El valor VENDOR_API_KEY es el nombre de una variable de entorno, no el secreto en sí.

export VENDOR_API_KEY="your API key"

4.3 Encabezados estáticos y parámetros de consulta

Añada encabezados estáticos que no sean confidenciales:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Añada parámetros de consulta:

query_params = { "api-version" = "2026-08-01" }

No coloque secretos reales en http_headers.

4.4 Autenticación mediante comandos

Un entorno empresarial puede obtener tokens de corta duración desde un llavero, una herramienta auxiliar de credenciales en la nube o un comando interno:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

El comando debe imprimir únicamente el token en la salida estándar.

No combine estos métodos de autenticación:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 Reutilizar la autenticación de OpenAI mediante un proxy

Establezca lo siguiente únicamente cuando el proxy siga accediendo a modelos de OpenAI y Codex deba usar la autenticación oficial de OpenAI:

requires_openai_auth = true

Esta no es la opción correcta para una API key normal de un modelo externo. Cuando está activada, Codex ignora el env_key del proveedor.

5. Solución de problemas

5.1 CC Switch cambia de proveedor, pero Codex sigue usando el modelo anterior

Compruebe cada elemento:

1. el proveedor de Codex deseado está activado en CC Switch;
2. el interruptor principal de enrutamiento local está activado;
3. Codex está activado en Routing Enabled;
4. los proveedores de Chat o Messages tienen activado Needs Local Routing;
5. CC Switch sigue en ejecución;
6. Codex, el IDE o el cliente de escritorio se han reiniciado por completo;
7. /debug-config muestra la fuente de configuración esperada.

Reinicie Codex después de cambiar las asignaciones de modelos para que el menú /model pueda volver a cargar su catálogo.

5.2 404, 400 o falta un punto de conexión /responses

Entre las causas habituales se incluyen:

• tratar un proveedor de Chat Completions como un proveedor nativo de Responses;
• añadir o eliminar /v1 de forma incorrecta;
• añadir /chat/completions dos veces;
• no activar Full URL Mode para un punto de conexión no estándar;
• el enrutamiento local no toma el control de Codex;
• una implementación incompleta de Responses en la puerta de enlace externa.

Los usuarios de CC Switch deben inspeccionar Upstream Format y los registros de enrutamiento. Los usuarios de proveedores directos deben llamar a <base_url>/responses con curl.

5.3 401 Unauthorized o 403 Forbidden

Compruebe:

• si la API key es válida;
• si pertenece a la región, el proyecto o el plan correctos;
• si la cuenta tiene saldo y permisos suficientes;
• si el servicio espera un token de portador o x-api-key;
• si el nombre de la variable de entorno coincide exactamente con env_key;
• si CC Switch guardó la clave correcta;
• si un proxy eliminó el encabezado de autenticación.

No imprima una clave completa en registros compartidos.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 El modelo no aparece en /model

Compruebe:

• si Model Mapping de CC Switch contiene el ID exacto del modelo de origen;
• si el proveedor se ha guardado y activado;
• si Codex se ha reiniciado;
• si un proveedor manual tiene un model_catalog_json válido;
• si el JSON del catálogo es válido;
• si el proveedor cambió el nombre del modelo o lo retiró.

5.5 El texto funciona, pero Codex no puede leer archivos, editar código ni ejecutar comandos

Causas posibles:

• el modelo tiene poca capacidad para llamar a herramientas;
• el servicio de origen no implementa llamadas a funciones;
• un servicio de retransmisión elimina los ID de las llamadas a herramientas;
• los fragmentos de llamadas a herramientas transmitidos mediante streaming no se vuelven a ensamblar correctamente;
• JSON Schema se reescribe;
• los resultados de las herramientas no se devuelven en el siguiente turno;
• el contexto del modelo es demasiado corto;
• el catálogo de modelos anuncia capacidades incorrectas.

Pruebe un ciclo real de «leer → editar → ejecutar pruebas → inspeccionar el fallo → corregir» en lugar de una simple instrucción de chat.

5.6 El streaming se desconecta con frecuencia

Los usuarios de CC Switch deben inspeccionar primero los registros del enrutamiento local y las respuestas del servicio de origen. Entre las causas habituales se incluyen:

• colas del servicio de origen o tiempos de razonamiento prolongados;
• una puerta de enlace que no emite eventos SSE con prontitud;
• almacenamiento en búfer por parte de una CDN, un proxy inverso o una red corporativa;
• eventos de origen no estándar;
• problemas de compatibilidad en una versión concreta de CC Switch o del proveedor.

Para un proveedor directo, puede aumentar:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Los tiempos de espera más largos pueden mitigar problemas de red o inferencia lenta, pero no pueden reparar una implementación incorrecta del protocolo.

5.7 wire_api = "chat" impide que Codex se inicie

Este valor aparece en guías antiguas. La configuración actual de Codex solo admite:

wire_api = "responses"

Use CC Switch cuando el servicio de origen solo ofrezca Chat Completions.

Compruebe si hay otros campos obsoletos con:

codex --strict-config

5.8 Editar la configuración del proyecto no cambia el proveedor

La configuración del proveedor debe estar en:

~/.codex/config.toml

Un .codex/config.toml del proyecto no puede sobrescribir campos que redirigen solicitudes o cambian la autenticación del proveedor, incluidos model_provider y model_providers.

5.9 El terminal funciona, pero la extensión del IDE no encuentra la API key

A menudo, las aplicaciones con interfaz gráfica no heredan las variables que se exportaron temporalmente en un terminal existente.

Entre las opciones se incluyen:

• iniciar el IDE desde el terminal en el que está establecida la variable;
• conservar la variable en el entorno del usuario del sistema operativo;
• cerrar por completo y volver a abrir el IDE;
• usar CC Switch para gestionar la configuración del proveedor local.

5.10 El inicio de sesión oficial o las funciones oficiales dejan de funcionar después de un cambio

Compruebe:

• si se ha vuelto a seleccionar OpenAI Official;
• si Keep official login when switching third-party providers está activado;
• si un flujo de trabajo antiguo sobrescribió ~/.codex/auth.json;
• si codex login status funciona correctamente.

Cuando sea necesario, vuelva a iniciar sesión:

codex login

No comparta ni edite manualmente un archivo auth.json que contenga tokens de acceso.

5.11 Web Search, las imágenes u otras capacidades avanzadas no funcionan

Un proveedor que admite texto y llamadas a herramientas no implementa necesariamente todas las capacidades de Codex.

Los proveedores personalizados no anuncian Web Search independiente de forma predeterminada. Establezca lo siguiente solo cuando el proveedor, el modelo y el punto de conexión lo admitan realmente:

supports_standalone_web_search = true

Activarlo de forma incorrecta solo hace que Codex envíe solicitudes que el servicio de origen no puede procesar. Valide por separado la entrada de imágenes, WebSockets, el almacenamiento de respuestas y otras funciones avanzadas.

6. Elegir una vía de integración

Valide cada integración en tres niveles:

1. Conectividad: devuelve texto de forma fiable;
2. Uso de herramientas: puede leer archivos, ejecutar comandos y continuar a partir de los resultados de las herramientas;
3. Finalización de tareas: puede completar un ciclo de edición, prueba y reparación.

Revise también:

• los precios del proveedor externo;
• los límites de velocidad;
• si se registran el código fuente y las instrucciones;
• las regiones de almacenamiento de datos;
• los requisitos de cumplimiento del equipo o de la empresa;
• si las actualizaciones del modelo requieren pruebas de regresión.

Cuando usa una API key de terceros, el uso lo factura dicho proveedor o servicio de retransmisión. No consume ni comparte automáticamente las prestaciones incluidas con ChatGPT Plus, Pro o una suscripción a Codex.

Referencias

• Conceptos básicos de la configuración de Codex
• Configuración avanzada de Codex
• Referencia de configuración de Codex
• Autenticación de Codex
• Comandos para desarrolladores de Codex
• Modelos de Codex
• CC Switch en GitHub
• Manual de usuario de CC Switch
• CC Switch: añadir un proveedor
• CC Switch: conservar el inicio de sesión oficial de Codex