AiHubMix Documentation Hub

Codex CLI 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/

Instalación mediante línea de comandos

npm install -g @openai/codex

Configuración de variables de entorno

Configuración mediante archivos de configuración

Modifica el archivo de configuración ~/.codex/config.toml para añadir los siguientes ajustes:

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"

Modifica el archivo de configuración ~/.codex/auth.json para cambiar los siguientes ajustes:

{
  "OPENAI_API_KEY": "AIHUBMIX_API_KEY"
}

Configuración mediante cc-switch

Ejecuta CC-Switch y añade el proveedor.

Pantalla para añadir proveedor en CC-Switch

Selecciona “AiHubMix” de la lista predefinida.

Seleccionar AiHubMix en la lista de preajustes de CC-Switch

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

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

Abre la terminal, navega al directorio de tu proyecto y ejecuta el comando codex.

cd /your/project/path
codex

Configura los permisos según sea necesario.

Configurar permisos de aprobación al iniciar Codex

Selecciona el modelo que necesites en función de tus requisitos.

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

Abre la aplicación de escritorio Codex y selecciona el directorio de trabajo.
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

codex -h

Opciones completas del comando

Usage
  $ codex [options] <prompt>

Options
  -h, --help                 Show help information and exit
  -m, --model <model>        Specify the model to use (default: codex-mini-latest)
  -i, --image <path>         Path to the file containing image input
  -v, --view <rollout>       View previously saved session records
  -q, --quiet                Non-interactive mode, only prints the final output of the assistant
  -a, --approval-mode <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 <file>       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

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.

{
  "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, 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:

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:

# ⚠️ 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:

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 =):

export AIHUBMIX_API_KEY=sk-xxx

Se recomienda escribirla en ~/.zshrc / ~/.bashrc para persistirla. Obtén tu Key en la consola de AIHubMix.

Paso 4: Reiniciar y seleccionar el modelo

Reinicia la app / TUI de Codex para que surta efecto el archivo de catálogo y, luego:

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

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).
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, 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, #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 ｜ Configuration Reference
Referencia del formato del catálogo oficial integrado: codex-rs/models-manager/models.json
Guía de la comunidad: Codex config.toml: integra cualquier proveedor personalizado en 6 líneas

Última actualización: 2026-06-25

Asistentes de código

Integraciones IDE

Agente / Workflow

SDKs y frameworks

Tutorial: conectar AIHubMix en Codex CLI

Instalación

Descarga oficial (versión macOS)

Instalación mediante línea de comandos

Configuración de variables de entorno

Configuración mediante archivos de configuración

Configuración mediante cc-switch

Uso de Codex

Uso en la terminal

Uso en la aplicación de escritorio Codex

Referencias de comandos útiles

Comando de ayuda

Opciones completas del comando

Usar modelos personalizados en Codex

Dos formas de integración

Paso 1: Generar el archivo de catálogo de modelos

1.1 Primero, entender el formato: un modelo fijo

1.2 Generar por lotes los 30 principales

Paso 2: Modificar `config.toml`

Paso 3: Definir la variable de entorno

Paso 4: Reiniciar y seleccionar el modelo

Paso 5: Verificar que funciona

Preguntas frecuentes sobre modelos personalizados

Artículos de referencia

​Instalación

​Descarga oficial (versión macOS)

​Instalación mediante línea de comandos

​Configuración de variables de entorno

​Configuración mediante archivos de configuración

​Configuración mediante cc-switch

​Uso de Codex

​Uso en la terminal

​Uso en la aplicación de escritorio Codex

​Referencias de comandos útiles

​Comando de ayuda

​Opciones completas del comando

​Usar modelos personalizados en Codex

​Dos formas de integración

​Paso 1: Generar el archivo de catálogo de modelos

​1.1 Primero, entender el formato: un modelo fijo

​1.2 Generar por lotes los 30 principales

​Paso 2: Modificar config.toml

​Paso 3: Definir la variable de entorno

​Paso 4: Reiniciar y seleccionar el modelo

​Paso 5: Verificar que funciona

​Preguntas frecuentes sobre modelos personalizados

​Artículos de referencia

Instalación

Descarga oficial (versión macOS)

Instalación mediante línea de comandos

Configuración de variables de entorno

Configuración mediante archivos de configuración

Configuración mediante cc-switch

Uso de Codex

Uso en la terminal

Uso en la aplicación de escritorio Codex

Referencias de comandos útiles

Comando de ayuda

Opciones completas del comando

Usar modelos personalizados en Codex

Dos formas de integración

Paso 1: Generar el archivo de catálogo de modelos

1.1 Primero, entender el formato: un modelo fijo

1.2 Generar por lotes los 30 principales

Paso 2: Modificar `config.toml`

Paso 3: Definir la variable de entorno

Paso 4: Reiniciar y seleccionar el modelo

Paso 5: Verificar que funciona

Preguntas frecuentes sobre modelos personalizados

Artículos de referencia