Tutoriel : connecter AIHubMix dans Codex CLI

​

Installation

​

Téléchargement officiel (version macOS)

​

Installation via la ligne de commande

npm install -g @openai/codex

​

Configuration de base

​

Configurer à l’aide des fichiers de configuration

1. Modifiez le fichier de configuration ~/.codex/config.toml en ajoutant les paramètres suivants :

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

2. Affectez votre clé API AIHubMix à la variable d’environnement indiquée par env_key (attention à ne pas mettre d’espaces de part et d’autre du =) :

export AIHUBMIX_API_KEY=sk-xxx

​

Configurer via cc-switch

1. Lancez CC-Switch et ajoutez le fournisseur.

2. Sélectionnez « AiHubMix » dans la liste prédéfinie.

3. Saisissez votre clé dans le champ « API Key » et cliquez sur « Add » pour enregistrer les paramètres.

4. Revenez à la page d’accueil, sélectionnez « AiHubMix » dans la liste des fournisseurs et cliquez sur « Enable » pour commencer à l’utiliser.

​

Utilisation de Codex

​

Utilisation dans le terminal

1. Ouvrez le terminal, accédez au répertoire de votre projet et exécutez la commande codex.

cd /your/project/path
codex

2. Définissez les autorisations selon vos besoins ; vous pouvez les modifier à tout moment avec /permissions.
3. Sélectionnez le modèle dont vous avez besoin. La barre d’état en bas affiche le modèle courant ; saisissez /model pour en changer.

4. Saisissez du langage naturel ; si vous recevez une réponse normale, la configuration est réussie.

​

Utilisation dans l’application de bureau Codex

1. Ouvrez l’application de bureau Codex et sélectionnez le répertoire de travail.
2. Saisissez la tâche dans la zone de saisie ; si vous recevez une réponse normale, la configuration est réussie.

​

Références de commandes utiles

​

Utiliser des modèles personnalisés dans Codex

Documentation officielle : Advanced Configuration · Custom model providers

​

Deux méthodes d’intégration

​

Étape 1 : générer le fichier de catalogue de modèles

​

1.1 Comprendre d’abord le format : un modèle fixe

{
  "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": []
    }
  ]
}

​

1.2 Générer en masse les 30 premiers modèles

mkdir -p ~/.codex/model-catalogs

# 1) Utiliser un modèle intégré comme modèle de référence : il contient déjà base_instructions et tous les champs obligatoires
codex debug models --bundled > /tmp/_tpl.json

# 2) Récupérer la liste des modèles AIHubMix
curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json

# 3) Cloner le modèle de référence pour chaque modèle, en ne remplaçant que les champs propres à chacun
python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json
import json, sys
tpl = json.load(open("/tmp/_tpl.json"))["models"][0]   # n'importe quel modèle intégré comme modèle de référence
# Les modèles intégrés comme la série gpt-6 utilisent le mode code par défaut, et les clones n'envoient alors aucune liste d'outils standard : on le désactive
tpl["tool_mode"] = None
tpl["use_responses_lite"] = False
api = json.load(open("/tmp/_aihubmix.json"))["data"]
# ignorer les modèles de génération d'images (types contenant image_generation), puis prendre les 30 premiers
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)                                       # cloner tous les champs du modèle de référence
    ctx = m.get("context_length") or 200000
    e["slug"] = m["model_id"]                           # doit être identique au model_id de l'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["supported_reasoning_levels"] = [                 # limiter à low / medium / high
        {"effort": "low", "description": "Fast responses"},
        {"effort": "medium", "description": "Balanced"},
        {"effort": "high", "description": "Deeper reasoning"},
    ]
    e["default_reasoning_level"] = "medium"
    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

Le fichier généré est volumineux (chaque entrée contient les base_instructions complètes, soit environ 1 à 2 Mo), ce qui est normal. Après l’exécution, vérifiez avec codex debug models qu’il est correctement analysé (voir l’étape 5).

La ligne de filtrage image_generation du script est intentionnellement conservée : parmi les résultats de type=llm, quelques rares modèles portent aussi le label image_generation (par exemple gemini-3.1-flash-image), qui ne conviennent pas au dialogue ; le script les ignore automatiquement avant de prendre les 30 premiers.

​

Étape 2 : modifier config.toml

# ⚠️ model_catalog_json doit être au niveau racine, pas dans [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"

model = "claude-opus-5-5"           # modèle par défaut au démarrage ; doit exister dans le fichier de catalogue
model_provider = "aihubmix"
model_catalog_json = "~/.codex/model-catalogs/custom-models.json"
model_reasoning_effort = "high"     # niveau de raisonnement par défaut ; doit être un niveau proposé par le modèle : low / medium / high

[model_providers.aihubmix]
name = "Aihubmix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

​

Étape 3 : définir la variable d’environnement

export AIHUBMIX_API_KEY=sk-xxx

​

Étape 4 : redémarrer et choisir le modèle

codex
# saisissez /model dans l'interface interactive pour voir les 30 modèles déclarés à l'étape précédente et en changer

​

Étape 5 : vérifier la prise en compte

1. Une fois dans Codex, saisissez /model, vérifiez que vous voyez bien les modèles déclarés dans le catalogue et basculez sur l’un d’eux (par exemple claude-opus-5-5).
2. Posez une question quelconque pour vérifier que la chaîne fonctionne. Attention : ne vous fiez pas à la question « quel modèle es-tu ? » : base_instructions indique « You are Codex… based on GPT-5 », si bien que tous les modèles se présenteront comme GPT-5 ; la question ne permet pas de distinguer le modèle réel. Pour confirmer le modèle réellement appelé, connectez-vous à la console AIHubMix, ouvrez la page « Journaux » et consultez le model_id de cette requête : c’est cela qui fait foi.

​

Questions fréquentes sur les modèles personnalisés

• Le démarrage échoue avec legacy profile = "..." config is no longer supported. Depuis Codex 0.134.0, profile = et [profiles.xxx] ne sont plus pris en charge. Supprimez ces deux éléments et réécrivez la configuration comme indiqué dans la section « Configuration de base » plus haut.
• Catalogue généré avec l’ancien script. L’ancien script ne désactivait pas le mode code sur le modèle intégré servant de modèle de référence. Avec les mises à jour de Codex, le premier modèle intégré est désormais un modèle de la série gpt-6 : le catalogue obtenu s’analyse toujours correctement, mais les requêtes ne transmettent aucune liste d’outils standard. Régénérez le catalogue avec le nouveau script de l’étape 1.
• Vous ne voyez pas les modèles personnalisés dans /model ? Vérifiez dans l’ordre suivant :
  1. Exécutez d’abord codex debug models. S’il signale missing field ... (le plus fréquent, champ obligatoire manquant) ou unknown variant ... (nom de champ / valeur incorrect), c’est que l’intégralité du catalogue a échoué à l’analyse et a été ignorée : régénérez-le avec le script « cloner le modèle intégré » de l’étape 1.
  2. Vérifiez que model_catalog_json est bien au niveau racine de config.toml, et non dans une section [model_providers.*] ;
  3. Vérifiez que le JSON utilise les champs officiels en snake_case et que visibility vaut list ;
  4. Si codex debug models affiche déjà tous les modèles mais que, dans l’application de bureau (Desktop App), il n’en reste qu’un ou deux et que le modèle courant s’affiche comme « personnalisé », il s’agit d’un bug connu de l’application de bureau : elle superpose, au-dessus du catalogue local, un filtre par liste blanche de slugs officiels, qui supprime du sélecteur les modèles non officiels (voir les GitHub Issues #19694 et #15138). Dans ce cas, le modèle est en réalité toujours appelé conformément au model = "..." de config.toml (les journaux AIHubMix le confirment) ; seul son nom ne s’affiche pas. Pour un affichage correct, utilisez la CLI codex / le TUI dans le terminal ; sur l’application de bureau, vous ne pouvez que coder en dur model = "le modèle souhaité" dans config.toml, en attendant un correctif officiel.
• Le catalogue « remplace », il ne « fusionne » pas. model_catalog_json remplace l’intégralité de la liste de modèles au lieu d’y ajouter des entrées (vérifié : avec seulement 2 modèles dans le catalogue, codex debug models n’en montre plus que 2, tous les gpt-5.x intégrés ayant disparu). Si vous voulez les deux types, écrivez-les ensemble dans votre catalogue personnalisé.
• La requête signale une erreur de protocole / impossible de se connecter. C’est le plus souvent que le base_url ou le wire_api du fournisseur n’est pas correctement apparié. Pour AIHubMix, il faut impérativement wire_api = "responses" + base_url = "https://aihubmix.com/v1". Si vous intégrez un tiers ne prenant en charge que Chat Completions, un proxy de conversion local est nécessaire ; les utilisateurs d’AIHubMix n’ont pas besoin de cette étape.
• « Reconnecting » en boucle, puis une erreur. Commencez par lire la dernière ligne d’erreur. 401 Unauthorized signifie que la requête est partie sans clé : vérifiez que la section du fournisseur définit bien env_key et que la variable est définie dans le terminal depuis lequel vous lancez Codex (ouvrez un nouveau terminal ou exécutez source ~/.zshrc). Une clé présente uniquement dans auth.json n’est pas utilisée par les fournisseurs personnalisés.
• L’analyse signale missing field ... (par exemple missing field base_instructions). Une entrée n’a pas de champ obligatoire. Les versions récentes de Codex appliquent une analyse stricte : 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., doivent tous être présents. Le script « cloner le modèle intégré » de l’étape 1 permet de tout compléter en une fois.
• L’analyse signale unknown variant. Le JSON du catalogue contient un nom de champ ou une valeur que Codex ne reconnaît pas (souvent des anciens formats camelCase comme displayName / hidden). Passez au jeu de champs snake_case présenté dans cet article.

​

Articles de référence

• Documentation officielle : Advanced Configuration ｜ Configuration Reference
• Format de référence du catalogue officiel intégré : codex-rs/models-manager/models.json
• Guide communautaire : Codex config.toml : intégrer n’importe quel fournisseur personnalisé en 6 lignes