Guide de connexion à Codex

0. Conclusion express

La plateforme implémente l’endpoint OpenAI Responses API POST /v1/responses et sa conception répond précisément aux exigences de Codex (séquence d’événements SSE en flux, appel d’outils function, compatibilité sans état via store:false). Codex CLI offre donc deux modes de connexion :

1. Connexion directe (recommandée) : dans ~/.codex/config.toml, définissez wire_api = "responses", pour utiliser directement /v1/responses ;
2. cc-switch : basculez le fournisseur de Codex / Claude Code etc. en un clic via l’outil graphique.

La facturation est strictement identique dans les deux cas (même pipeline pré-autorisation → routage → règlement → grand livre).

1. Prérequis

2. Capacités et limites côté plateforme (/v1/responses)

• Endpoint : POST https://routeall.ai/v1/responses
• Authentification : Authorization: Bearer sk-ra-...

2.1 Supporté (compatibilité Codex)

2.2 Limitations (sous-ensemble texte sans état)

2.3 Facturation et erreurs

• Facturation : même pipeline que /v1/chat/completions exactement, les coûts constatés sont équivalents ; l’en-tête de réponse X-RouteAll-Charge-Credit indique le montant facturé au détail (pas le coût).
• Enveloppe d’erreur : { "error": { "message", "type", "code", "param" } } ; codes HTTP : 401 (clé absente/incorrecte), 402 (solde insuffisant), 429 (limite de débit), 400 (paramètres invalides), 503 (tous les fournisseurs en amont sont indisponibles).

3. Méthode 1 : connexion directe Codex CLI (Responses API, recommandée)

3.1 Configurer ~/.codex/config.toml

model = "deepseek-v4-pro"           # Modèle par défaut, remplacez par le nom canonique de la place de marché
model_provider = "routeall"

[model_providers.routeall]
name = "RouteAll"
base_url = "https://routeall.ai/v1" # URL de base compatible OpenAI de la plateforme (sans /responses)
env_key = "ROUTEALL_API_KEY"
wire_api = "responses"              # responses = utilise /v1/responses (recommandé)

3.2 Définir la variable d’environnement

# Linux / macOS
export ROUTEALL_API_KEY="sk-ra-votreCLE"

# Windows PowerShell
# $env:ROUTEALL_API_KEY = "sk-ra-votreCLE"

3.3 Lancement

codex

3.4 Changer de modèle temporairement

codex --model Codex-haiku-4-5 "refactorise ce module"
codex --model deepseek-v4-flash "explique cette expression régulière"

3.5 À propos de wire_api

Note : le sous-domaine api. de la passerelle n’est pas exposé publiquement pour l’instant (variable serveur PUBLIC_API_DOMAIN=api.localhost interne) ; les routes /v1/* sont servies directement par le site principal routeall.ai, donc utilisez https://routeall.ai/v1 comme base_url.

4. Méthode 2 : cc-switch (bascule graphique en un clic)

cc-switch est un outil de bascule de fournisseur open source (farion1231/cc-switch) qui permet de gérer les configurations de Codex / Claude Code / OpenCode / Gemini etc. et de basculer en un clic.

4.1 Installation

GitHub farion1231/cc-switch → Releases, téléchargez le paquet correspondant à votre système (Windows / macOS / Linux).

4.2 Ajouter un fournisseur

1. Ouvrez cc-switch, allez dans l’onglet Codex → « Ajouter un fournisseur » ;
2. Remplissez :
   • Nom du fournisseur : RouteAll (libre)
   • API Host / Base URL : https://routeall.ai/v1
   • API Key : sk-ra-votreCLE
   • Liste des modèles : noms canoniques de la plateforme (ex. deepseek-v4-pro, Codex-haiku-4-5, plusieurs lignes possibles)
3. Enregistrez.

4.3 Appliquer le changement

Sélectionnez RouteAll → « Basculer / Activer ». cc-switch écrira la configuration du fournisseur dans ~/.codex/config.toml (équivalent à la configuration de la méthode 1), puis lancez codex normalement.

Remarque : certaines versions de cc-switch réécrivent le protocole de Codex en /v1/chat/completions (c’est-à-dire wire_api = "chat"). La plateforme prend en charge les deux chemins (B15 a corrigé l’erreur 400 des clients à base d’outils passant par chat) ; si votre version permet de choisir le protocole, privilégiez Responses, plus proche du natif.

5. Vérification

5.1 Récupérer la liste des modèles disponibles (fiez-vous à la liste, n’inventez pas les noms)

curl https://routeall.ai/v1/models \
  -H "Authorization: Bearer sk-ra-votreCLE"
# ou répertoire public (pas d’authentification, liste uniquement les modèles avec canaux)
curl https://routeall.ai/v1/public/models

5.2 Appel non flux (vérifiez d’abord la connectivité)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-votreCLE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Bonjour, présente-toi en une phrase",
    "max_output_tokens": 200
  }'

Une réponse au format Responses (output[].content[].output_text + output_text + usage) indique un succès.

5.3 Appel en streaming (comportement réel de Codex)

curl -N https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-votreCLE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "Raconte une blague courte",
    "stream": true
  }'

Séquence d’événements : response.created → output_item.added → output_text.delta ×N → output_item.done → response.completed.

5.4 Appel d’outils (boucle agentic)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-votreCLE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": [{"role": "user", "content": "Calcule 17*23 pour moi"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "calculatrice",
        "description": "Effectue les quatre opérations",
        "parameters": {
          "type": "object",
          "properties": { "expr": { "type": "string" } }
        }
      }
    }],
    "tool_choice": "auto"
  }'

output contiendra un élément de type function_call (call_id, name, arguments), après quoi vous pourrez envoyer un élément function_call_output pour réinjecter le résultat et continuer le dialogue.

6. Dépannage

7. Facturation et consignes de sécurité

• Unité de facturation : prix officiel du modèle × coefficient du groupe d’utilisateurs ; le streaming est décompté sur la base de l’usage réel ; les hits de cache sont facturés au prix fort (politique B12, la différence reste acquise à la plateforme, le client ne bénéficie pas de réduction).
• Visibilité de la facturation : en-tête de réponse X-RouteAll-Charge-Credit (montant facturé au détail) ; les champs cost/margin ne sont jamais exposés côté client (INV-8).
• Sécurité des clés : le préfixe sk-ra- n’est stocké qu’en sha256, invisible depuis la console ; ne l’intégrez jamais dans un client ou un dépôt.
• Il est