Codex CLI

Codex CLI peut se connecter à HiAPI via l’import en un clic de CC Switch, ou vous pouvez le configurer manuellement (étape 9). Les étapes ci-dessous utilisent gpt-6-astra comme exemple ; HiAPI utilise le protocole OpenAI Responses. Ce tutoriel a été vérifié sur Mac avec Codex CLI 0.162.1 ; les étapes Mac constituent le parcours principal et les étapes Windows sont indiquées séparément. Vous pouvez ignorer l’installation des logiciels que vous avez déjà.

1. Installer Node.js

Installez LTS 22.19 ou une version ultérieure comme décrit dans Installation de Node.js, et ignorez cette étape si vous l’avez déjà. Exécutez ensuite les deux commandes ci-dessous dans un terminal ; voir les numéros de version suffit :

node --version
npm --version

2. Installer Codex CLI

Dans le terminal que vous venez d’ouvrir, exécutez chaque ligne :

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

Voir un numéro de version de codex-cli suffit ; la configuration manuelle (étape 9) nécessite la version 0.134 ou ultérieure. Dans Windows PowerShell, utilisez npm.cmd install -g @openai/codex et codex.cmd --version.

3. Installer et ouvrir CC Switch

Téléchargez, installez et ouvrez CC Switch comme décrit dans Installer CC Switch et importer en un clic ; si vous l’avez déjà, ouvrez-le simplement.

Si vous avez déjà des fournisseurs, notez d’abord le nom de la carte marquée « In use » sur la page Codex, et au besoin exportez une sauvegarde SQL comme décrit dans Sauvegarder la configuration actuelle.

4. Choisir une clé API HiAPI

Choisissez ou créez une clé comme décrit dans Obtenir une clé API et notez son nom. Vous n’avez pas besoin de copier la clé ici ; l’import la reprend.

5. Préparer l’import en un clic sur le web

1. Ouvrez la page de connexion HiAPI Codex et choisissez API Key setup → Codex → Command line → gpt-6-astra → macOS. Sous Windows, choisissez Windows comme système.

2. Cliquez sur Import to CC Switch, choisissez le nom de clé que vous avez noté dans la liste API Key, et vérifiez que le bas de page affiche Responses API · https://api.hiapi.ai/v1.

3. Cliquez sur Prepare import, puis sur Open CC Switch ; autorisez quand le navigateur le demande.

Les captures de chaque étape sont dans Préparer l’import sur la page de connexion.

6. Confirmer l’import dans CC Switch

Dans la fenêtre « Confirm provider import », vérifiez les éléments ci-dessous, laissez Switch to this provider immediately after import désactivé, puis cliquez sur Import :

De retour sur la page Codex de CC Switch, la carte HiAPI - gpt-6-astra signifie que l’import a fonctionné (elle n’est pas encore activée). Voir les captures dans Confirmer l’import dans CC Switch.

7. Activer HiAPI

1. Attendez d’abord que la tâche en cours de Codex se termine. Sur la page Codex → Direct de CC Switch, cliquez sur le bouton Switch / Enable de la carte HiAPI - gpt-6-astra ; HiAPI n’est activé que lorsque la carte est marquée « In use ». Voir les captures dans Activer HiAPI.
2. Quittez complètement Codex puis rouvrez-le pour que la nouvelle configuration prenne effet. CLI et Desktop peuvent partager la configuration Codex locale ; pour revenir plus tard à votre fournisseur d’origine, basculez sur sa carte ici et rouvrez le client.

8. Ouvrir Codex, choisir un modèle et démarrer

1. Ouvrez un nouveau terminal et allez dans le dossier de projet que vous voulez utiliser, ou créez-en un vide d’abord :

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell :

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. La première fois, il demande s’il faut faire confiance au dossier : confirmez que le chemin correspond au dossier que vous venez de choisir, puis validez comme demandé et gardez les permissions par défaut. Avec l’import en un clic, lancez codex directement ; n’ajoutez pas le --profile hiapi utilisé pour la configuration manuelle.

3. Dans la zone de saisie de Codex, tapez /model et appuyez sur Entrée. Utilisez les flèches pour choisir GPT-6 Astra / gpt-6-astra et appuyez sur Enter ; s’il existe un niveau de réflexion, choisissez-en un et confirmez, puis appuyez sur Esc pour revenir.

① Utilisez les flèches pour choisir GPT-6-Astra ; ② appuyez sur Enter pour confirmer.

4. Envoyez « Bonjour, présentez-vous en une phrase. » Une réponse normale signifie que la connexion fonctionne. Si Journal des requêtes dans la console HiAPI affiche cette requête, elle passe bien par HiAPI. Ensuite, écrivez simplement dans la zone de saisie ce que vous voulez accomplir.

9. Configuration manuelle (sans CC Switch)

Ignorez cette étape si vous avez utilisé l’import en un clic. La configuration manuelle ne concerne que Codex CLI, pas Codex Desktop.

1. Sur un Mac, exécutez les trois lignes ci-dessous dans un terminal ; un fichier existant du même nom est d’abord sauvegardé automatiquement :

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. Pour un nouveau fichier, collez tout le contenu ci-dessous ; si le fichier existe, mettez à jour uniquement les champs et tables de même nom, gardez le reste et n’ajoutez pas de doublons. Les champs de premier niveau doivent précéder [model_providers.hiapi]. env_key = "HIAPI_API_KEY" indique comment Codex lit une variable d’environnement ; laissez-le tel quel.

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Appuyez sur Ctrl+O → Enter → Ctrl+X pour enregistrer et quitter. Le nom du fichier doit être hiapi.config.toml, pas .toml.txt. Si vous avez défini CODEX_HOME, enregistrez le fichier dans ce dossier.

4. Retournez dans HiAPI Console → API Keys, cliquez sur l’icône de copie à côté de la clé et copiez la clé API HiAPI complète. Dans le même terminal que celui où vous lancerez Codex, exécutez la commande ci-dessous (remplacez YOUR_HIAPI_API_KEY par votre clé API HiAPI et conservez les guillemets), puis allez dans le dossier de votre projet et démarrez :

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. Sous Windows, utilisez PowerShell pour créer le dossier $env:USERPROFILE\.codex, ouvrez hiapi.config.toml dans Notepad et collez le même TOML ; sauvegardez d’abord un fichier existant. Dans Save as, choisissez « All files » et UTF-8, et vérifiez qu’il n’y a pas de suffixe .txt. Dans la même fenêtre PowerShell et le même dossier de projet, exécutez :

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

La variable d’environnement ne s’applique qu’au terminal actuel ; redéfinissez-la après avoir fermé le terminal. Une fois démarré, choisissez un modèle comme à l’étape 8.

Dépannage

Seuls les problèmes propres à Codex CLI sont listés ici. Pour les erreurs courantes comme 401, 404 et 429, voir Erreurs courantes.