Documentación/Guía de integración

Configurar Codex con el proveedor unificado de CC Switch

Acerca de este documento

Este documento explica cómo usar la función de proveedor unificado (Universal Provider) de CC Switch para conectar la herramienta de línea de comandos OpenAI Codex a una API gateway indicada y hacer que la configuración surta efecto.

Versiones aplicables: CC Switch v3.16.x y posteriores.

Fuente de la información: manual de usuario y código fuente del repositorio oficial de CC Switch. El software evoluciona con rapidez; si la interfaz del producto no coincide con lo descrito en este documento, prevalece lo que se muestre en la aplicación.

Terminología

Término Descripción
Codex Asistente de programación con IA de línea de comandos proporcionado por OpenAI. Tras instalarlo, se inicia ejecutando el comando codex en la terminal.
CC Switch Herramienta de escritorio multiplataforma de gestión de configuración, para administrar los endpoints de servicio y las credenciales de herramientas como Codex, Claude Code y Gemini CLI. CC Switch en sí no ofrece capacidades de IA; solo se encarga de generar y cambiar archivos de configuración.
Proveedor (Provider) Parte que proporciona capacidad de inferencia de modelos. Puede ser el servicio oficial de un fabricante de modelos, o una API gateway de desarrollo propio o adquirida.
API Key Cadena de clave usada para la autenticación; normalmente empieza por sk-.
Proveedor unificado (Universal Provider) Una función de CC Switch. Una misma configuración se puede sincronizar a la vez con las tres herramientas Claude Code, Codex y Gemini CLI. Es adecuada para gateways que admiten varios protocolos de API a la vez (por ejemplo, NewAPI).
Proveedor específico de la aplicación Configuración de proveedor que solo se aplica a una herramienta, a diferencia del proveedor unificado.

Antes de empezar

Requisitos del sistema

Sistema operativo Versión mínima Arquitectura
Windows Windows 10 x64
macOS macOS 12 (Monterey) Intel (x64) / Apple Silicon (arm64)
Linux Ubuntu 22.04 / Debian 11 / Fedora 34 y versiones equivalentes x64 / ARM64

Además, necesitas Node.js 18 o una versión superior. Los pasos de instalación están en la «Tarea 1».

Información que debes obtener de antemano

Antes de empezar a configurar, obtén estos cuatro datos del proveedor del servicio de API. Si falta cualquiera de ellos, no podrás completar la configuración.

Elemento Descripción Ejemplo
Dirección de la API (Base URL) Dirección de servicio de la gateway https://seedrouter.net
API Key Clave de autenticación sk-xxxxxxxxxxxx
Nombre del modelo Identificador del modelo que usa Codex gpt-5.6-sol
Soporte del protocolo Si la gateway admite el protocolo OpenAI Responses Soportado / No soportado

Puntos clave: El cuarto punto determina si este documento es aplicable. En la configuración que el proveedor unificado genera para Codex, el protocolo de comunicación queda fijado en wire_api = "responses" y no se puede modificar. Si el gateway no admite el protocolo Responses y solo admite el protocolo Chat Completions, no puedes usar el proveedor unificado; usa la solución F de la sección «Diagnóstico de fallos».

Abrir la terminal

En varios puntos de este documento hay que ejecutar comandos en la terminal. Así se abre:

  • Windows: pulsa Win + R, escribe powershell y pulsa Enter.
  • macOS: pulsa Command + Espacio, escribe terminal y pulsa Enter.
  • Linux: usa la aplicación de terminal incluida en la distribución.

Tarea 1: Instalar Node.js

Acerca de esta tarea

Codex se distribuye mediante npm, el gestor de paquetes de Node.js. Aunque uses la instalación en un clic de CC Switch, primero necesitas un entorno de ejecución de Node.js.

Procedimiento

  1. Visita el sitio web oficial de Node.js.

  2. Descarga el paquete de instalación marcado como LTS (versión con soporte a largo plazo). No descargues la versión Current.

  3. Ejecuta el instalador y completa la instalación con las opciones predeterminadas, sin modificar ninguna opción de configuración.

    Si usas macOS y ya tienes Homebrew instalado, también puedes ejecutar en la terminal brew install node.

  4. Cierra todas las ventanas de terminal abiertas y abre una ventana de terminal nueva.

  5. Ejecuta los comandos siguientes, en este orden, para comprobar la instalación:

    node --version
      npm --version

Resultado

Si ambos comandos muestran un número de versión (por ejemplo, v22.14.0 y 10.9.2) y la versión de Node.js no es inferior a v18, la instalación se ha realizado correctamente.

Nota: Si aparece «no se reconoce como un comando interno o externo» o «command not found», normalmente es porque no has vuelto a abrir la ventana de la terminal. Los comandos recién instalados solo están disponibles en una sesión de terminal nueva.

Tarea 2: Instalar CC Switch

Acerca de esta tarea

CC Switch es software gratuito y de código abierto, y solo se distribuye por estos dos canales:

Advertencia: Cualquier sitio web o cliente de «CC Switch» que exija un pago, una recarga o las credenciales de inicio de sesión de una cuenta no es un canal oficial. No lo descargues ni lo uses.

Procedimiento

Windows

  1. Abre la página de Releases de GitHub y, en el área Assets de la entrada de la versión más reciente, localiza CC-Switch-v3.16.x-Windows.msi.

  2. Descarga el instalador, haz doble clic para ejecutarlo y completa la instalación siguiendo las indicaciones.

    Si al hacer doble clic no ocurre nada, el archivo está bloqueado por la política de seguridad del sistema. Haz clic con el botón derecho en el archivo, elige Propiedades y, en el área Seguridad de la parte inferior de la pestaña General, marca Desbloquear. Haz clic en Aceptar y vuelve a ejecutarlo.

    Si no quieres instalarlo en el sistema, también puedes descargar la versión sin instalación CC-Switch-v3.16.x-Windows-Portable.zip; descomprímela y ejecuta directamente CC-Switch.exe.

macOS

Usa cualquiera de estos métodos:

  • Opción 1 (recomendada si ya tienes Homebrew instalado): ejecuta en la terminal

    brew install --cask cc-switch

  • Opción 2: descarga CC-Switch-v3.16.x-macOS.dmg, ábrelo con doble clic y arrastra el icono de CC Switch a la carpeta «Aplicaciones».

    Nota: La versión para macOS está firmada con código y notarizada por Apple, así que puedes instalarla y abrirla directamente. No aparece el aviso «no se puede verificar el desarrollador» y no hace falta ninguna operación adicional para quitar la cuarentena.

Linux

Elige según la distribución:

  • Debian / Ubuntu: descarga el paquete .deb y ejecuta

    sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

  • Arch Linux: paru -S cc-switch-bin

  • Otras distribuciones: descarga el .AppImage, ejecuta chmod +x para añadir el permiso de ejecución y ejecútalo directamente.

Resultado

Tras iniciar CC Switch, la ventana principal se muestra con normalidad y el icono de CC Switch aparece en la bandeja del sistema (en Windows, en la esquina inferior derecha; en macOS, a la derecha de la barra de menús), lo que indica que la instalación se ha realizado correctamente.

Si al iniciarlo por primera vez se te pide importar la configuración existente de herramientas CLI, te recomendamos que elijas importar. Esta operación guarda la configuración actual como un proveedor predeterminado y no provoca la pérdida de la configuración.

Tarea 3: Instalar Codex

Acerca de esta tarea

Puedes instalarlo desde la interfaz gráfica de CC Switch o mediante la línea de comandos. Si es la primera vez que lo usas, te recomendamos el método A.

Procedimiento

Método A: Instalar mediante CC Switch (recomendado)

  1. Inicia CC Switch.

  2. Ve a Settings > About.

  3. En el área Local Environment Check, revisa el estado de la fila de Codex.

  4. Si se muestra que no se ha detectado, haz clic en el botón Install a la derecha de esa fila.

    La instalación se ejecuta en segundo plano y en silencio; el botón muestra el progreso y, al terminar, el número de versión se actualiza automáticamente.

Nota: Las actualizaciones posteriores también se realizan en esta interfaz. Cuando se detecta una versión nueva, puedes actualizarla por separado o hacer clic en Upgrade All para procesarlas por lotes.

Método B: Instalar mediante la línea de comandos

  1. Abre la terminal.

  2. Ejecuta el siguiente comando:

    npm install -g @openai/codex

    Si la descarga es demasiado lenta, puedes cambiar a un mirror:

    npm install -g @openai/codex --registry=https://registry.npmmirror.com

    Si necesitas usar el mirror a largo plazo, puedes ejecutar primero una sola vez el siguiente comando para establecer la configuración global:

    npm config set registry https://registry.npmmirror.com

Resultado

Después de cerrar la terminal y volver a abrirla, ejecuta el siguiente comando:

codex --version

Si se muestra el número de versión, la instalación se ha realizado correctamente.

Nota: En este momento aún no se ha completado la configuración del proveedor. Si ejecutas codex directamente, se producirá un error por falta de credenciales válidas; es el comportamiento esperado. La configuración se completa en la tarea 4.

Tarea 4: Crear un proveedor unificado

Acerca de esta tarea

En esta tarea se crea en CC Switch una configuración de proveedor unificado y se sincroniza con la lista de proveedores de Codex.

Procedimiento

  1. Inicia CC Switch.

  2. En el selector de aplicaciones de la parte superior, cambia a Codex.

    Si cambias al panel de Claude o al de Gemini, también puedes acceder a la entrada del proveedor unificado; los tres comparten la misma configuración.

  3. Haz clic en el botón ＋ de la esquina superior derecha para abrir el panel de añadir proveedor.

  4. En la parte superior del panel, selecciona la pestaña Unified Provider.

    Limitación: Los paneles de OpenCode, OpenClaw, Hermes y Claude Desktop no admiten el proveedor unificado y no muestran esta pestaña. Si no ves la pestaña, cambia primero al panel de Claude, Codex o Gemini.

  5. Haz clic en Add Unified Provider.

  6. Rellena los campos del formulario según la tabla siguiente:

    Campo Instrucciones para rellenar
    Select Preset Type Si el gateway es NewAPI, selecciona NewAPI; en los demás casos, o si no estás seguro, selecciona Custom Gateway. Los campos de ambas opciones son exactamente los mismos; solo difieren los valores predeterminados.
    Name Un nombre identificativo personalizado, por ejemplo Pasarela NewAPI. Este nombre se mostrará en la tarjeta de proveedor de Codex.
    API Address Introduce el Base URL obtenido previamente. Las reglas para rellenarlo se describen más abajo, en "Reglas de procesamiento de la dirección API".
    API Key Introduce la clave obtenida previamente. Puedes hacer clic en el icono del ojo de la derecha para alternar la visualización en texto claro.
    Official Website Opcional. Si lo rellenas, puedes acceder directamente desde la tarjeta del proveedor.
    Remarks Opcional. Se recomienda anotar el origen de la clave, el periodo de validez y otra información similar.
    Enabled Apps Incluye tres interruptores: Claude Code, OpenAI Codex y Gemini. Debes activar OpenAI Codex. Si este gateway también se usa con las otras dos herramientas, puedes activarlas a la vez.
    Model Configuration > Codex > Model Introduce el nombre del modelo obtenido previamente, por ejemplo gpt-5.6-sol.
    Model Configuration > Codex > Reasoning Effort Intensidad del razonamiento. Los valores son low, medium o high. Si no tienes requisitos especiales, indica high.

    Nota: el formulario de proveedor unificado no ofrece el botón "Get Models". El nombre del modelo debe introducirse manualmente y distingue entre mayúsculas y minúsculas.

  7. Haz clic en Add.

Resultado

La interfaz muestra "Unified provider added and synced". En ese momento, CC Switch ya ha generado una tarjeta de proveedor con el mismo nombre en la lista de proveedores de Codex; si marcaste otras aplicaciones, también se genera una tarjeta en las listas correspondientes.

Punto clave: sincronizar no equivale a habilitar. En este momento la configuración aún no se ha escrito en el archivo de configuración de ejecución de Codex y debes continuar con la tarea 5.

Reglas de procesamiento de la dirección de API

Cuando CC Switch genera la configuración para Codex, procesa la dirección de API introducida de la siguiente manera:

Forma de la dirección introducida Resultado del procesamiento
Solo el dominio, sin ruta, por ejemplo https://seedrouter.net Se completa automáticamente como https://seedrouter.net/v1
Ya termina en /v1, por ejemplo https://seedrouter.net/v1 Se usa tal cual
Contiene otra ruta, por ejemplo https://api.example.com/openai Se usa tal cual, sin completar /v1

El criterio es el siguiente: la dirección procesada, seguida de /responses, debe ser la ruta de interfaz que el gateway puede usar realmente. Antes de rellenarla, confirma con el proveedor del servicio la dirección completa de la interfaz y, a partir de la tabla anterior, deduce qué debes introducir. Una dirección incorrecta hará que la solicitud devuelva 404.

Tarea 5: habilitar el proveedor y aplicar la configuración

Acerca de esta tarea

Una vez generada la tarjeta del proveedor, debes habilitarla manualmente; solo entonces la configuración se escribe en el archivo de configuración de Codex. Codex no admite el hot reload de la configuración; después de habilitarla, debes reiniciar la terminal.

Proceso

  1. Cierra el panel de añadir proveedor.

  2. En el selector de aplicaciones de la parte superior, cambia a Codex.

  3. En la lista de proveedores, localiza la tarjeta del mismo nombre creada en la tarea 4.

  4. Haz clic en el botón Enable de la tarjeta.

    La tarjeta se muestra con un borde azul y la etiqueta "Currently enabled", lo que indica que la configuración ya se ha escrito.

  5. Cierra por completo la ventana de la terminal actual y luego abre una nueva ventana de terminal.

    Punto clave: esto se refiere a cerrar toda la ventana de la terminal, no a salir del proceso codex y volver a ejecutar el comando codex. Las diferencias entre herramientas en la forma de aplicar el cambio son las siguientes:

    Herramienta Forma de aplicación tras cambiar de proveedor
    Claude Code Efecto inmediato; admite hot reload
    Gemini CLI Efecto inmediato; vuelve a leer la configuración en cada solicitud
    Codex Hay que cerrar y volver a abrir la terminal
    OpenCode / OpenClaw Hay que cerrar y volver a abrir la terminal

  6. En la nueva terminal, ejecuta:

    codex

  7. Después de iniciarlo, introduce una frase de prueba, por ejemplo "Hola, preséntate brevemente".

Resultado

El modelo devuelve una respuesta con normalidad, lo que indica que la configuración está completa y que Codex ya está conectado al gateway indicado.

Referencia: archivos de configuración generados

CC Switch sigue el principio de mínima intrusión. Tras habilitar el proveedor, la configuración se escribe directamente en el propio archivo de configuración de Codex; aunque desinstales CC Switch, Codex puede seguir funcionando con normalidad.

Los archivos implicados son los siguientes. ~ en la ruta indica el directorio del usuario actual: en Windows es C:\Users\<nombre de usuario>\, y en macOS y Linux es /Users/<nombre de usuario>/ o /home/<nombre de usuario>/.

~/.codex/auth.json — almacena las credenciales:

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — almacena la configuración del modelo y del endpoint:

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

Los datos del propio CC Switch se almacenan en el directorio ~/.cc-switch/. El archivo de base de datos es cc-switch.db, y las copias de seguridad automáticas están en el subdirectorio backups/, que conserva las 10 más recientes.

Operaciones de mantenimiento

Modificar la configuración

Al modificar la API Key, el nombre del modelo o la dirección del servicio:

  1. Haz clic en el botón ＋ y cambia a la pestaña Unified Provider.

  2. En la tarjeta de destino, haz clic en el icono de edición.

  3. Modifica los campos correspondientes.

    En el modo de edición, la parte inferior del formulario incluye el área Config JSON Preview, donde puedes confirmar, antes de sincronizar, el contenido real que se escribirá en cada aplicación.

  4. Haz clic en Save and Sync.

  5. Confirma la operación en el cuadro de diálogo de confirmación. Esta operación sobrescribirá la configuración de proveedores vinculada en Claude, Codex y Gemini.

  6. Cierra la terminal y vuelve a abrirla.

Operaciones de la tarjeta de proveedor

Operación Descripción
Sync Vuelve a enviar manualmente la configuración actual a cada aplicación vinculada; sirve para corregirla cuando no coincide.
Copy Crea una copia a partir de la configuración actual, para configurar una clave de reserva.
Edit Modifica el contenido de la configuración.
Delete Elimina el proveedor unificado y, al mismo tiempo, las tarjetas de proveedor vinculadas que generó en Claude, Codex y Gemini.

Cambio rápido

Haz clic con el botón derecho en el icono de CC Switch de la bandeja del sistema y, en el submenú Codex, haz clic directamente en el nombre del proveedor de destino para cambiar, sin abrir la interfaz principal. Después del cambio, también tienes que reiniciar la terminal.

Diagnóstico de fallos

A. Se devuelve 401 o 403: fallo de autenticación

Causa posible Solución
La API Key incluye espacios o saltos de línea de más al copiarla Vuelve a copiarla y pegarla, con cuidado al seleccionar el texto
La API Key ha caducado o se ha agotado la cuota Confirma el estado de la clave con el proveedor del servicio
La API Key no coincide con la dirección de la API Comprueba que ambas procedan del mismo servicio

B. Se devuelve 404 o se indica que la interfaz no existe

En la mayoría de los casos, la dirección de la API ha quedado incorrecta tras procesarla. Vuelve a comprobarla según "Tarea 4 > Reglas de procesamiento de la dirección de la API" y confirma con el proveedor del servicio la dirección completa de la interfaz.

C. No hay ningún cambio después de modificar la configuración

No se ha reiniciado la terminal. Cierra por completo la ventana de la terminal y vuelve a abrirla. Es el problema más habitual al usar Codex.

D. La parte superior de la interfaz muestra una advertencia de conflicto de variables de entorno

En el sistema hay variables de entorno como OPENAI_API_KEY. Las variables de entorno tienen prioridad sobre los archivos de configuración y sobrescriben la configuración que escribe CC Switch, de modo que la solicitud se envía a un endpoint incorrecto o se usa una clave incorrecta.

Pasos:

  1. Haz clic en Expand en el banner de advertencia para ver el nombre, el valor y el origen de las variables en conflicto.
  2. Marca las variables que debas eliminar o haz clic en Select All.
  3. Haz clic en Delete Selected y confirma.

Antes de eliminarlas, CC Switch guarda automáticamente una copia de seguridad en ~/.cc-switch/env-backups/. Si necesitas restaurarlas, puedes recuperarlas manualmente desde los archivos JSON de ese directorio.

E. La terminal indica que el comando codex no existe

Causa posible Solución
No se ha vuelto a abrir la terminal después de la instalación Cierra todas las ventanas de la terminal y vuelve a abrirlas
Node.js no está instalado correctamente Vuelve a la tarea 1 y comprueba si npm --version muestra una salida normal
El directorio global de npm no está en PATH Vuelve a instalarlo desde Settings > About > Local Environment Check de CC Switch

F. El gateway solo admite el protocolo Chat Completions

El protocolo de comunicación de Unified Provider está fijado en Responses. No es aplicable en este caso; debes usar un proveedor específico de la aplicación.

  1. En CC Switch, cambia al panel Codex y haz clic en el botón ＋.
  2. Quédate en la pestaña Codex Provider de la izquierda y no cambies a Unified Provider.
  3. En el desplegable de presets, elige el proveedor correspondiente. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI y otros son presets de tipo Chat Completions.
  4. Al elegir un preset de este tipo, CC Switch activa automáticamente el interruptor "Local route mapping required" y configura la tabla de mapeo de modelos. El proxy local realiza la conversión de protocolo, sin configuración manual.
  5. Introduce la API Key, haz clic en Add y, a continuación, activa ese proveedor y reinicia la terminal.

G. Necesitas volver al inicio de sesión con la cuenta oficial

  1. En el panel Codex, añade un proveedor con el preset "OpenAI Official".
  2. Activa ese proveedor y reinicia la terminal.
  3. Completa la autenticación siguiendo el flujo de inicio de sesión propio de Codex.

Cuando termines, puedes cambiar libremente entre el inicio de sesión oficial y los proveedores de terceros.

Referencia para elegir: proveedor unificado y proveedor específico de la aplicación

Escenario de uso Solución recomendada
Un único gateway da servicio a la vez a Claude Code, Codex y Gemini CLI, y admite el protocolo Responses Proveedor unificado
Usar solo la herramienta Codex Las dos sirven; la ruta de configuración del proveedor específico de la aplicación es más corta
El gateway solo admite el protocolo Chat Completions Proveedor específico de la aplicación, junto con el preset integrado
Cada herramienta se conecta a un servicio distinto Proveedor específico de la aplicación, con configuración por separado
Hay que configurar OpenCode, OpenClaw o Hermes Proveedor específico de la aplicación; estas tres herramientas no admiten el proveedor unificado

Precauciones de seguridad

  1. La API key tiene la misma sensibilidad que las credenciales de la cuenta. No la transmitas en herramientas de mensajería instantánea, no la compartas en capturas de pantalla ni la subas a un repositorio de código.
  2. Obtén el paquete de instalación de CC Switch únicamente desde el sitio oficial de CC Switch o el repositorio oficial de GitHub.
  3. Si cambias de dispositivo o sospechas que la clave se ha filtrado, sustitúyela de inmediato.
  4. La función de exportación de la configuración de CC Switch escribe toda la información de los proveedores en texto plano en un archivo de copia de seguridad .sql. Guarda el archivo exportado de forma adecuada y evita almacenarlo en un directorio compartido.

Referencia rápida

1. Instalar Node.js                 nodejs.org, elige la versión LTS
      2. Instalar CC Switch         ccswitch.io o GitHub Releases
      3. Instalar Codex             CC Switch > Configuración > Acerca de > Comprobación del entorno local > Instalar
      4. Crear proveedor unificado  Cambia al panel de Codex > ＋ > Proveedor unificado > Añadir proveedor unificado
                                    Rellena el nombre, la dirección de la API y la API Key
                                    Activa el interruptor de OpenAI Codex y escribe el nombre del modelo
      5. Activar el proveedor       Panel de Codex > tarjeta de destino > Activar
      6. Reiniciar el terminal      Cierra por completo la ventana del terminal y vuelve a abrirla
      7. Verificar                  Ejecuta el comando codex y envía un mensaje de prueba

Al enviar comentarios sobre un problema, incluye también una captura de pantalla con el mensaje de error completo y la dirección de la API indicada en la tarea 4 (la parte de la clave debe ir enmascarada), para acortar el ciclo de diagnóstico.

Obtener la API key de SeedRouter Volver al inicio de la documentación