> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Tutorial: conectar AIHubMix en Codex CLI > Conecta AIHubMix en Codex CLI: con una sola clave API cambia libremente entre GLM, Claude, Gemini, DeepSeek y otros modelos desde la lista /model. Incluye configuración de config.toml, un script para generar el catálogo model_catalog_json y preguntas frecuentes de solución de problemas. [Codex CLI](https://openai.com/codex/) es la herramienta oficial de programación en terminal de OpenAI. Tras conectar AIHubMix, una sola clave API te permite invocar y cambiar libremente entre modelos de GLM, Claude, Gemini, DeepSeek y otros proveedores en la terminal, sin atarte a uno solo. Esta guía cubre dos enfoques: el **enfoque básico** (profile + un modelo fijo, el más rápido) y el **enfoque de modelos personalizados** (un archivo de catálogo `model_catalog_json` para cambiar en cualquier momento desde la lista `/model`). ## Instalación ### Descarga oficial (versión macOS) [https://openai.com/en/codex/](https://openai.com/en/codex/) ### Instalación mediante línea de comandos ```bash theme={null} npm install -g @openai/codex ``` ## Configuración de variables de entorno ### Configuración mediante archivos de configuración 1. Modifica el archivo de configuración `~/.codex/config.toml` para añadir los siguientes ajustes: ```toml theme={null} profile = "aihubmix" [model_providers.aihubmix] name = "aihubmix" base_url = "https://aihubmix.com/v1" personality = "pragmatic" wire_api = "responses" [profiles.aihubmix] model = "gpt-5.2" model_provider = "aihubmix" model_reasoning_effort = "high" ``` 2. Modifica el archivo de configuración `~/.codex/auth.json` para cambiar los siguientes ajustes: ```json theme={null} { "OPENAI_API_KEY": "AIHUBMIX_API_KEY" } ``` ### Configuración mediante cc-switch 1. Ejecuta CC-Switch y añade el proveedor. Pantalla para añadir proveedor en CC-Switch 2. Selecciona "AiHubMix" de la lista predefinida. Seleccionar AiHubMix en la lista de preajustes de CC-Switch 3. Introduce tu clave en el campo "API Key" y haz clic en "Add" para guardar los ajustes. Introducir la clave API y guardar en CC-Switch 4. Vuelve a la página de inicio, selecciona "AiHubMix" de la lista de proveedores y haz clic en "Enable" para empezar a usarlo. Activar el proveedor AiHubMix en CC-Switch ## Uso de Codex ### Uso en la terminal 1. Abre la terminal, navega al directorio de tu proyecto y ejecuta el comando `codex`. ```bash theme={null} cd /your/project/path codex ``` 2. Configura los permisos según sea necesario. Configurar permisos de aprobación al iniciar Codex 3. Selecciona el modelo que necesites en función de tus requisitos. Elegir el modelo a usar en Codex 4. Introduce lenguaje natural; si recibes una respuesta normal, la configuración es correcta. Escribir lenguaje natural en la terminal de Codex con respuesta normal ### Uso en la aplicación de escritorio Codex 1. Abre la aplicación de escritorio Codex y selecciona el directorio de trabajo. 2. Introduce la tarea en el cuadro de entrada; si recibes una respuesta normal, la configuración es correcta. Escribir una tarea en Codex de escritorio con respuesta normal ## Referencias de comandos útiles ### Comando de ayuda ```bash theme={null} codex -h ``` ### Opciones completas del comando ```bash theme={null} Usage $ codex [options] Options -h, --help Show help information and exit -m, --model Specify the model to use (default: codex-mini-latest) -i, --image Path to the file containing image input -v, --view View previously saved session records -q, --quiet Non-interactive mode, only prints the final output of the assistant -a, --approval-mode Override approval policy: 'suggest', 'auto-edit', or 'full-auto' --auto-edit Automatically approve file edits; will still prompt for command confirmation --full-auto Automatically approve edits and commands in sandbox environment --no-project-doc Do not automatically include 'codex.md' file from the repository --project-doc Include specified Markdown file as context --full-stdout Do not truncate stdout/stderr of command output Dangerous Options --dangerously-auto-approve-everything Skip all confirmation prompts and execute commands directly (no sandbox protection) For use only in temporary local testing environments Experimental Options -f, --full-context Start in "full context" mode, loading the entire repository into context and applying bulk edits in a single operation Only compatible with --model parameter Examples $ codex "Write and run a Python program that prints ASCII art" $ codex -q "Fix build issues" ```

Usar modelos personalizados en Codex

Por defecto, Codex solo muestra los modelos oficiales de OpenAI en la lista `/model`. Si quieres seleccionar directamente desde la lista cualquier modelo disponible en AIHubMix (GLM, Claude, Gemini, DeepSeek, Kimi, Qwen…), puedes usar el mecanismo de «modelos personalizados» que ofrece el soporte oficial: declara los modelos disponibles mediante un archivo JSON local (`model_catalog_json`) y, con `[model_providers.aihubmix]`, dirige las solicitudes a AIHubMix. > Documentación oficial: [Advanced Configuration · OSS mode / local providers](https://developers.openai.com/codex/config-advanced) ### Dos formas de integración La sección «Configuración de variables de entorno» anterior describe la **forma básica**, mientras que esta sección describe la **forma con modelos personalizados**. Las diferencias son las siguientes; elige según tus necesidades: | | Forma básica (profile + un solo modelo) | Forma con modelos personalizados (esta sección) | | -------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | | Contenido de configuración | Fijar un `model = "xxx"` en `config.toml` | Mantener además un archivo de catálogo `model_catalog_json` | | Cambiar de modelo | Editar el archivo de configuración y reiniciar | Seleccionar directamente en la lista `/model`, cambiando en cualquier momento | | Caso de uso | Usar de forma fija un único modelo a largo plazo | Comparar / cambiar con frecuencia entre varios modelos | | Complejidad | Baja | Media | El flujo completo consta solo de 4 pasos: **generar el archivo de catálogo → editar `config.toml` → definir la variable de entorno → reiniciar y seleccionar el modelo**. ### Paso 1: Generar el archivo de catálogo de modelos El archivo de catálogo tiene una estructura `{ "models": [ ... ] }`, donde cada elemento del array describe un modelo seleccionable en `/model`. A continuación explicaremos los campos con **un único modelo fijo** y después daremos el script para **generar por lotes los 30 modelos principales**. #### 1.1 Primero, entender el formato: un modelo fijo A continuación se muestra un catálogo mínimo completo **verificado como analizable por Codex** (que contiene solo el modelo `glm-5.2`). Basta con guardarlo como `~/.codex/model-catalogs/custom-models.json` para usarlo; si quieres más modelos, sigue añadiendo entradas con la misma estructura al array `models`. ```json theme={null} { "models": [ { "slug": "glm-5.2", "display_name": "GLM 5.2", "description": "GLM 5.2 (via AIHubMix)", "context_window": 1000000, "max_context_window": 1000000, "supported_reasoning_levels": [ { "effort": "low", "description": "Fast responses" }, { "effort": "medium", "description": "Balanced" }, { "effort": "high", "description": "Deeper reasoning" } ], "shell_type": "shell_command", "visibility": "list", "supported_in_api": true, "priority": 0, "availability_nux": null, "upgrade": null, "base_instructions": "You are Codex, a coding agent.", "supports_reasoning_summaries": true, "support_verbosity": false, "default_verbosity": null, "apply_patch_tool_type": null, "truncation_policy": { "mode": "tokens", "limit": 10000 }, "supports_parallel_tool_calls": true, "experimental_supported_tools": [] } ] } ``` Descripción de los campos (los que normalmente modificarás): | Campo | Función | Procedente de la API | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `slug` | ID del modelo; Codex lo usa para iniciar las solicitudes y debe coincidir con el `model_id` devuelto por la API | `model_id` | | `display_name` | Nombre que se muestra en la lista `/model` | `model_name` | | `context_window` / `max_context_window` | Ventana de contexto. **Si no se indica, se recurrirá a un valor predeterminado conservador muy pequeño**; se recomienda rellenarlo con el valor real de la API | `context_length` | | `supported_reasoning_levels` | Niveles de razonamiento; tras cambiar de modelo aún puedes seleccionar el effort con `/model` | — | | `visibility` | Debe estar en `list` para que aparezca en el selector | — | | `priority` | Orden de la lista; cuanto menor sea el número, más arriba aparece | — | **Los demás campos son obligatorios y con valores fijos**: `base_instructions`, `availability_nux`, `upgrade`, `supports_reasoning_summaries`, `support_verbosity`, `default_verbosity`, `apply_patch_tool_type`, `truncation_policy`, `supports_parallel_tool_calls`, `experimental_supported_tools`. Las versiones nuevas de Codex (verificado en `codex-cli 0.130.0`) realizan un análisis estricto: **si falta cualquiera de ellos, se descarta todo el catálogo** y se recurre al catálogo integrado, con un error del tipo `missing field base_instructions`, que se manifiesta como «no aparece ni un solo modelo personalizado en `/model`». Por eso no se puede eliminar ningún campo más del ejemplo anterior. Sobre `base_instructions`: es el **prompt de sistema** de ese modelo. En el ejemplo se usa una sola frase como marcador de posición y el modelo funciona con normalidad; si quieres un rendimiento de codificación lo más parecido posible al Codex nativo, sustitúyelo por las `base_instructions` completas de cualquier modelo integrado de `codex debug models --bundled` (eso es justo lo que hace el script por lotes de la siguiente sección). El catálogo oficial usa campos en **snake\_case** (`display_name`, `supported_in_api`, `visibility`). Dos tipos de errores hacen que se descarte todo el catálogo y que no aparezcan modelos en `/model`: la falta de campos obligatorios provoca `missing field ...`; el uso de formatos antiguos en camelCase como `displayName`, `hidden` o de valores no reconocidos provoca `unknown variant ...`. Atente al conjunto de campos de este documento para evitarlo. #### 1.2 Generar por lotes los 30 principales Escribir varias entradas a mano hace fácil olvidar campos. Para escribir de una sola vez en el catálogo los 30 primeros LLM de la [API de la lista de modelos de AIHubMix](https://aihubmix.com/api/v1/models?type=llm), usa el siguiente script: **clona una plantilla a partir de un modelo integrado**, de modo que los campos obligatorios (incluido el `base_instructions` correcto) están presentes por naturaleza y nunca faltan entre versiones de Codex. Requiere `curl`, `python3` y la CLI `codex` ya instalada: ```bash theme={null} mkdir -p ~/.codex/model-catalogs # 1) Tomar un modelo integrado como plantilla: trae consigo base_instructions y todos los demás campos obligatorios codex debug models --bundled > /tmp/_tpl.json # 2) Descargar la lista de modelos de AIHubMix curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json # 3) Clonar la plantilla para generar cada entrada, sobrescribiendo solo los campos propios de cada modelo python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json import json, sys tpl = json.load(open("/tmp/_tpl.json"))["models"][0] # cualquier modelo integrado como plantilla api = json.load(open("/tmp/_aihubmix.json"))["data"] # omitir los modelos de generación de imágenes (types contiene image_generation), luego tomar los 30 primeros api = [m for m in api if "image_generation" not in (m.get("types") or "")][:30] out = [] for i, m in enumerate(api): e = dict(tpl) # clonar todos los campos de la plantilla ctx = m.get("context_length") or 200000 e["slug"] = m["model_id"] # debe coincidir con el model_id de la API e["display_name"] = m.get("model_name") or m["model_id"] e["description"] = (m.get("model_name") or m["model_id"]) + " (via AIHubMix)" e["context_window"] = ctx e["max_context_window"] = ctx e["visibility"] = "list" e["supported_in_api"] = True e["priority"] = i e["availability_nux"] = None e["upgrade"] = None out.append(e) json.dump({"models": out}, sys.stdout, ensure_ascii=False, indent=2) PY ``` El script solo sobrescribe los campos propios de cada modelo (`slug`, `display_name`, `description`, `context_window`, etc.); todos los demás campos obligatorios se clonan de la plantilla integrada, que es exactamente el mismo conjunto de campos de 1.1, solo que `base_instructions` usa el prompt oficial completo. > El archivo generado es bastante grande (cada entrada contiene las `base_instructions` completas, alrededor de 1 a 2 MB), lo cual es normal. Tras ejecutarlo, usa `codex debug models` para verificar que se analiza correctamente (ver el Paso 5). > La línea del filtro `image_generation` del script se conserva a propósito: en la respuesta de `type=llm` hay unos pocos modelos que también llevan la etiqueta `image_generation` (como `gpt-image-2`), no aptos para conversación; el script los omite automáticamente antes de tomar los 30 primeros. ### Paso 2: Modificar `config.toml` Edita `~/.codex/config.toml`, añade `model_catalog_json` a **nivel raíz** y define el proveedor `aihubmix`: ```toml theme={null} # ⚠️ model_catalog_json debe escribirse a nivel raíz, no dentro de la sección [model_providers.*] model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` `wire_api = "responses"` es clave: **si lo omites o lo pones como `chat`, no podrás conectarte**. Las versiones nuevas de Codex solo usan la Responses API de OpenAI (`/v1/responses`), y AIHubMix ya es compatible de forma nativa con la Responses API, por lo que basta con apuntar directamente a `https://aihubmix.com/v1` sin necesidad de montar un proxy de conversión propio. Si además quieres especificar el **modelo predeterminado** y el **nivel de razonamiento predeterminado** (para usarlos directamente al iniciar, sin tener que seleccionarlos manualmente cada vez), puedes usar esta configuración más completa: ```toml theme={null} model = "glm-5.2" # modelo predeterminado al iniciar; debe existir en el archivo de catálogo model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" model_reasoning_effort = "high" # nivel de razonamiento predeterminado: minimal / low / medium / high [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` Una vez configurado, el `config.toml` se verá aproximadamente así (los recuadros rojos son los elementos clave de este paso: el `model` / `model_provider` / `model_catalog_json` a nivel raíz y la sección `[model_providers.aihubmix]`): Configuración de model_catalog_json y el proveedor aihubmix en config.toml ### Paso 3: Definir la variable de entorno Configura la variable de entorno indicada en `env_key` anterior (ten en cuenta que no debe haber espacios a ambos lados del `=`): ```bash theme={null} export AIHUBMIX_API_KEY=sk-xxx ``` Se recomienda escribirla en `~/.zshrc` / `~/.bashrc` para persistirla. Obtén tu Key en la [consola de AIHubMix](https://aihubmix.com/token). ### Paso 4: Reiniciar y seleccionar el modelo Reinicia la app / TUI de Codex para que surta efecto el archivo de catálogo y, luego: ```bash theme={null} codex # En la interfaz interactiva, escribe /model para ver los 30 modelos declarados en el paso anterior y cambiar entre ellos ``` Tras escribir `/model`, se mostrarán todos los modelos declarados en el catálogo; usa las teclas de dirección para seleccionar y Enter para confirmar: Selector /model de Codex mostrando la lista de modelos personalizados de AIHubMix Una vez seleccionado un modelo, `/model` también te permitirá elegir el nivel de razonamiento (effort); selecciona `low` / `medium` / `high` según tus necesidades. ### Paso 5: Verificar que funciona 1. Tras entrar en Codex, escribe `/model`, confirma que ves los modelos declarados en el catálogo y cambia a uno de ellos (por ejemplo, `glm-5.2`). 2. Haz una pregunta cualquiera para verificar que el enlace funciona. Atención: **no te fíes de «¿qué modelo eres?» para determinarlo**: en `base_instructions` figura «You are Codex... based on GPT-5», por lo que todos los modelos se presentarán como GPT-5 y preguntarlo no te permitirá distinguir el modelo real. Para confirmar qué modelo se llama realmente, inicia sesión en la [consola de AIHubMix](https://aihubmix.com/token), ve a la página «Logs» y mira el `model_id` de ese registro de solicitud: esa es la verdad. Tras un cambio exitoso, en la parte superior aparecerá `Model changed to ...`, y la barra de estado inferior también mostrará el modelo actual y la ventana de contexto (en la imagen siguiente se cambió a `glm-5.2`, con una ventana de 258K): Sesión de Codex y barra de estado tras cambiar a glm-5.2 ## Preguntas frecuentes sobre modelos personalizados * **¿No ves los modelos personalizados en `/model`?** Soluciona el problema en este orden: 1. **Primero ejecuta `codex debug models`**. Si informa de `missing field ...` (lo más común, falta un campo obligatorio) o `unknown variant ...` (nombre/valor de campo incorrecto), significa que todo el catálogo no se pudo analizar y se descartó; vuelve a generarlo con el script «clonar la plantilla integrada» del Paso 1. 2. Confirma que `model_catalog_json` está escrito a **nivel raíz** de `config.toml`, no dentro de la sección `[model_providers.*]`; 3. Confirma que el JSON usa los campos oficiales en snake\_case y que `visibility` es `list`; 4. Si `codex debug models` ya muestra todos los modelos, pero en la **aplicación de escritorio (Desktop App)** solo quedan uno o dos y el modelo actual se muestra como «personalizado», se trata de un bug conocido de la aplicación de escritorio: aplica, por encima del catálogo local, otra capa de filtrado con una lista blanca de slugs oficiales que elimina los modelos no oficiales del selector (ver los GitHub Issue [#19694](https://github.com/openai/codex/issues/19694), [#15138](https://github.com/openai/codex/issues/15138)). En este caso, el modelo en realidad se sigue llamando con normalidad según el `model = "..."` de `config.toml` (puedes confirmarlo en los logs de AIHubMix), solo que el nombre no se muestra. **Para que se muestre correctamente, usa la CLI / TUI `codex` en el terminal**; en la aplicación de escritorio solo puedes fijar directamente `model = "el modelo que quieras"` en `config.toml` y esperar a que lo arreglen oficialmente. * **El catálogo «reemplaza», no «fusiona».** `model_catalog_json` **reemplaza** toda la lista de modelos, en lugar de añadirse a ella (comprobado: si pones solo 2 modelos en el catálogo, `codex debug models` solo deja esos 2 y todos los `gpt-5.x` integrados desaparecen). Si quieres ambos tipos, escríbelos todos juntos en el catálogo personalizado. * **La solicitud informa de un error de protocolo / no se conecta.** Lo más probable es que el `base_url` o el `wire_api` del proveedor no estén bien emparejados. AIHubMix requiere `wire_api = "responses"` + `base_url = "https://aihubmix.com/v1"`. Si te conectas a un tercero que solo admite Chat Completions, necesitarás un proxy de conversión local; los usuarios de AIHubMix no necesitan este paso. * **Reconexiones frecuentes con “Reconnecting”.** En algunos entornos de red/proxy, WebSocket (WSS) no funciona; puedes añadir `supports_websockets = false` en la sección del proveedor para forzar el uso de HTTP. * **El análisis informa de `missing field ...` (como `missing field base_instructions`).** A la entrada le falta un campo obligatorio. Las versiones nuevas de Codex analizan de forma estricta: `base_instructions`, `availability_nux`, `upgrade`, `supports_reasoning_summaries`, `support_verbosity`, `default_verbosity`, `apply_patch_tool_type`, `truncation_policy`, `supports_parallel_tool_calls`, `experimental_supported_tools`, etc., todos deben estar presentes. El script «clonar la plantilla integrada» del Paso 1 puede completarlos todos de una sola vez. * **El análisis informa de `unknown variant`.** El JSON del catálogo contiene un nombre o valor de campo que Codex no reconoce (común con formatos antiguos en camelCase como `displayName`/`hidden`). Cambia al conjunto de campos en snake\_case de este documento. ## Artículos de referencia * Documentación oficial: [Advanced Configuration](https://developers.openai.com/codex/config-advanced) ｜ [Configuration Reference](https://developers.openai.com/codex/config-reference) * Referencia del formato del catálogo oficial integrado: [codex-rs/models-manager/models.json](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) * Guía de la comunidad: [Codex config.toml: integra cualquier proveedor personalizado en 6 líneas](https://www.morphllm.com/codex-provider-configuration) *** Última actualización: 2026-06-25