Faire tourner Kimi K3.1 Pro dans Claude Code et Codex : la configuration, les échecs silencieux et le basculement en une ligne

Kimi K3.1 Pro parle trois protocoles : OpenAI Chat Completions, OpenAI Responses et Anthropic Messages. C’est toute la raison pour laquelle il peut s’intégrer à Claude Code et Codex sans proxy de traduction — chaque outil parle déjà l’un des trois, et Moonshot sert ce protocole nativement. La configuration tient à une poignée de variables d’environnement dans un cas et à un bloc TOML de cinq lignes dans l’autre. Ce qui coûte un après-midi aux gens, ce n’est pas la configuration ; c’est le mode de défaillance. Claude Code utilise quatre niveaux de modèles différents pour différentes tâches, et tout niveau laissé non défini échoue en silence plutôt que de signaler l’erreur bruyamment.

Ce guide est rédigé à partir de la documentation d’intégration de Moonshot elle-même, vérifiée le 24 octobre 2026, avec les mises en garde que la documentation dissimule. Lorsqu’une valeur diffère selon que vous pointez les mêmes outils vers une passerelle de routage plutôt que directement vers Moonshot, cela est signalé.

Pourquoi aucun proxy n’est nécessaire

Claude Code talks to Anthropic's Messages API; Codex talks to the Responses API. Moonshot exposes both. Its Anthropic-compatible surface lives at https://api.moonshot.ai/anthropic and its Responses API at https://api.moonshot.ai/v1, and the model id is kimi-k3.1-pro on both. Nothing in either client needs to know it is not talking to the vendor it was built for.

Une conséquence mérite d’être signalée avant la configuration : le modèle raisonne toujours. Il n’existe pas de bascule de réflexion, et la profondeur est définie avec un champ de premier niveau reasoning_effort qui accepte low, high et max, avec max par défaut. Les paramètres d’échantillonnage sont fixes — temperature 1.0, top-p 0.95, n à 1 — et transmettre d’autres valeurs renvoie une erreur. Si votre configuration précédente ajustait la température, cet ajustement ne survit pas au changement.

Claude Code : le bloc d'environnement

Claude Code lit sa configuration depuis le bloc env de ~/.claude/settings.json. Les variables qui y sont écrites prévalent sur celles de même nom exportées dans votre shell, ce qui est à la fois une fonctionnalité et un piège : une exportation obsolète dans votre terminal ne vous sauvera pas si le fichier indique autre chose.

• ANTHROPIC_BASE_URL — the Kimi endpoint root. Set it to https://api.moonshot.ai/anthropic. If you leave it unset, requests go to Anthropic and fail authentication.

• ANTHROPIC_AUTH_TOKEN — votre clé API Kimi. C'est la variable que Claude Code utilise réellement pour le jeton Bearer ; une clé API placée dans ANTHROPIC_API_KEY à la place est la raison la plus courante pour laquelle une configuration qui semble correcte renvoie une erreur 401.

• ANTHROPIC_MODEL — le modèle de conversation principal : kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — un par niveau. Configurez au minimum les trois premiers, et faites pointer HAIKU vers un modèle rapide et bon marché plutôt que vers le modèle phare ; l'exemple de Moonshot lui-même associe ce niveau à son modèle de codage.

• CLAUDE_CODE_SUBAGENT_MODEL — ce que les sous-agents utilisent. S'il n'est pas défini, le travail des sous-agents se dégrade ou échoue.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — défini sur 1000000, en correspondance avec la fenêtre de contexte. Une valeur trop petite compacte trop tôt et jette du contexte ; une valeur trop grande produit des erreurs de longueur de contexte.

• CLAUDE_CODE_EFFORT_LEVEL — le guide de Moonshot définit cette valeur sur max, qui est aussi la valeur par défaut du modèle. La réduire diminue la qualité sur les tâches complexes, et la modifier en cours de session invalide les hits du cache de préfixe.

Les quatre niveaux qui échouent en silence

C'est l'échec pour lequel il vaut la peine de planifier. Claude Code utilise différents modèles pour la conversation principale, le résumé en arrière-plan, les sous-agents et les petits appels utilitaires. Si vous ne configurez que ANTHROPIC_MODEL, les autres chemins ne renvoient pas d'erreur — ils ne font discrètement rien d'utile, ou se rabattent d'une manière qui donne l'impression que l'outil est cassé sans en nommer la cause. Le tableau de référence de Moonshot indique explicitement que chaque niveau non défini entraîne l'échec de la tâche correspondante, et les symptômes ressemblent à ceux d'un agent lent ou confus plutôt qu'à une erreur de configuration.

La liste de vérification pratique consiste à définir les quatre variables de niveau ainsi que la variable de sous-agent en une seule modification, à redémarrer Claude Code, puis à confirmer dans une session qu’un sous-agent s’exécute réellement. En cas de blocage, le niveau est la première chose à vérifier, pas le modèle.

Codex : un bloc TOML

Codex reads ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). The connection is defined by four values in a provider block: the model id kimi-k3.1-pro, a provider named kimi, base_url pointing at https://api.moonshot.ai/v1, the environment-variable name that holds the key, and — the setting that makes the direct connection work — wire_api = "responses". Set model_context_window to 1048576 as well; without it Codex falls back to default model metadata, which degrades behaviour on long inputs.

La clé elle-même doit se trouver dans l’environnement, pas dans le fichier. Codex la lit depuis la variable nommée dans env_key, donc gardez config.toml exempt de secrets et définissez la variable dans le profil de votre shell ou dans l’environnement système.

Deux limites à connaître avant de signaler un bug. Codex CLI n’accepte pas la vidéo en entrée, même si le modèle le fait — c’est une limitation de la couche d’entrée de Codex, donc le travail sur la vidéo doit passer directement par l’API. Et la gestion du contexte propre à Codex s’applique toujours : une fenêtre de 1M tokens ne signifie pas que chaque session doit en utiliser une.

Faire pointer les deux outils vers une seule passerelle à la place

Tout ce qui précède fonctionne sans modification si vous remplacez les URL de base de Moonshot par celles d'une passerelle, ce qui est utile lorsque la même base de code appelle également des modèles d'autres fournisseurs. OrcaRouter expose les trois interfaces pour Kimi K3.1 Pro — /v1/chat/completions, /v1/responses et /v1/messages — et publie le modèle sous l'identifiant kimi/kimi-k3.1-pro.

For Claude Code, that means ANTHROPIC_BASE_URL set to the gateway root (https://api.orcarouter.ai) with the provider-prefixed model id in the four tier variables. For Codex, the same TOML block with the base URL pointing at https://api.orcarouter.ai/v1 and the model id kimi/kimi-k3.1-pro. The key variable stays the same shape; it just holds a gateway key instead of a vendor key.

Ce que vous obtenez en échange de la substitution, c’est un identifiant pour chaque modèle du catalogue et une politique de routage capable de déplacer une requête entre fournisseurs sans modifier le code de l’application — ce qui rend possible un plan de repli lorsqu’un nouveau modèle subit des limites de débit sur son point de terminaison la semaine du lancement. Ce à quoi vous renoncez, c’est à la console propre au fournisseur et à toute surface bêta spécifique au fournisseur. Les prix sont répercutés au tarif catalogue du fournisseur : 2,00 $ par million de jetons d’entrée et 10,00 $ par million de jetons de sortie pour Kimi K3.1 Pro, sans marge ajoutée.

Une vérification de cinq minutes

Appelez directement le point de terminaison avant de toucher au client : une requête POST vers la route Messages ou Chat Completions avec une requête d’un jeton doit renvoyer du JSON, et un 401 signifie que la clé est incorrecte ou appartient à l’autre plateforme.

• Dans Claude Code, posez une question qui force le recours à un sous-agent — une recherche dans plusieurs fichiers — et regardez s’il va jusqu’au bout. C’est le test le plus rapide de la configuration des niveaux.

• Dans Codex, démarrez une session sur un petit dépôt et vérifiez que le modèle indique la fenêtre de 1 M ; s'il indique une valeur par défaut plus petite, model_context_window n'a pas pris effet.

• Définissez l'effort délibérément, une seule fois, au début de la session : max pour le débogage difficile, élevé pour les modifications ordinaires, faible pour l'extraction et le formatage. La valeur par défaut est max et, sur ce modèle, c'est le choix coûteux.