CC-Switch

CC-Switch est un gestionnaire de configuration local multiplateforme. Il enregistre plusieurs Provider pour des outils de programmation tels que Claude Code et Codex, puis écrit la configuration active dans leurs fichiers respectifs. Vous pouvez ainsi passer d’AGTCloud à d’autres configurations sans éditer les fichiers à chaque fois.

Ce tutoriel couvre uniquement les Provider propres à Claude Code et Codex. L’outil de programmation envoie directement les requêtes à AGTCloud ; Local Proxy, Failover, conversion de protocole et Universal Provider ne sont pas activés.

La bascule modifie la configuration locale des outils

CC-Switch met à jour les fichiers actifs de Claude Code ou Codex. Avant la première utilisation, vérifiez l’importation de votre configuration existante et exportez une sauvegarde avant d’ajouter AGTCloud.

Prérequis

Avant de commencer, vérifiez que vous avez :

Installé Claude Code ou Codex et validé son démarrage de base ;
Créé un compte AGTCloud et ouvert une session ;
Créé une API Key AGTCloud dans API Keys ;
Copié dans le catalogue de modèles un ID accessible à l’API Key et compatible avec le protocole de l’outil ;
Préparé un projet de test sans code sensible ni identifiants de production.

Choisissez un modèle Anthropic Messages pour Claude Code et un modèle OpenAI Responses pour Codex. MODEL_ID est une valeur à remplacer, pas un nom de modèle réel.

Télécharger et installer CC-Switch

Téléchargez uniquement depuis le site officiel CC-Switch ou les GitHub Releases. Les sites ou clients demandant un paiement, un crédit ou vos identifiants de connexion pour CC-Switch lui-même ne sont pas officiels.

Pour une installation standard, choisissez le MSI Windows de la version actuelle dans GitHub Releases ;
Pour une utilisation sans installation, choisissez le ZIP Windows Portable ;
Décompressez la version Portable, puis exécutez CC-Switch.exe ;
Si Windows bloque l’exécution, vérifiez d’abord l’origine du fichier et sa signature numérique, sans désactiver la sécurité système.

CC-Switch gère la configuration, mais ne remplace pas Claude Code ou Codex. Vérifiez d’abord que l’outil cible démarre normalement.

Premier démarrage et sauvegarde

Vérifier l’importation automatique

Au premier démarrage, CC-Switch tente d’importer les configurations locales de Claude Code, Codex et des autres outils. Ouvrez la page de chaque application et vérifiez la présence des configurations officielles ou des Provider personnalisés existants.

Conserver le Provider précédent

Ne supprimez pas la configuration officielle importée. Vous pourrez la réactiver pour quitter AGTCloud et retrouver la connexion précédente.

Exporter une sauvegarde

Ouvrez Paramètres → Avancé → Gestion des données et utilisez la fonction d’export de votre version. La sauvegarde peut contenir des API Key et d’autres informations sensibles de Provider. Conservez-la dans un emplacement fiable, jamais dans un dépôt ou un stockage public.

Ce tutoriel ne nécessite pas d’éditer directement les fichiers

CC-Switch écrit la configuration de l’outil concerné. N’écrasez pas ~/.claude/settings.json, ~/.codex/auth.json ou ~/.codex/config.toml pour reprendre l’exemple d’une autre plateforme.

Ajouter un Provider AGTCloud

Choisissez l’application en haut, cliquez sur le bouton d’ajout à droite, puis utilisez la configuration personnalisée des fournisseurs propres à l’application. Claude Code et Codex ont des protocoles et des Base URL différents : créez un Provider distinct pour chacun.

Ouvrir les Provider Claude Code

Sélectionnez Claude Code en haut de CC-Switch, cliquez sur l’ajout de fournisseur, puis choisissez « Personnalisé » ou l’entrée équivalente de votre version.

Renseigner la connexion

Champ	Valeur
`Provider Name`	`AGTCloud`
`Base URL`	`https://api.agtcloud.cn`
`API Key`	`your-api-key`
`Primary Model`	`MODEL_ID`
`Authentication`	Utiliser une API Key, pas `ANTHROPIC_AUTH_TOKEN`

Utilisez seulement l’API Origin affiché ici comme Base URL, sans /v1. Claude Code demande lui-même /v1/messages.

Configurer les correspondances de modèles

Si votre version présente les rôles Haiku, Sonnet et Opus, vous pouvez d’abord les associer au même MODEL_ID dont le support d’Anthropic Messages est confirmé. Attribuez des modèles distincts uniquement lorsque vous connaissez leurs capacités réelles.

Enregistrer sans activer de proxy

Enregistrez le Provider sans activer Local Proxy, Failover, conversion de protocole ou routage avancé.

Utilisez l’authentification API Key

La configuration Claude Code d’AGTCloud utilise l’authentification API Key associée à ANTHROPIC_API_KEY. Ne copiez pas une configuration d’une autre plateforme utilisant ANTHROPIC_AUTH_TOKEN ou un Bearer Token.

Activer et valider la configuration

Activer AGTCloud

Revenez à la liste des fournisseurs de l’application et cliquez sur « Activer » dans la carte AGTCloud. Vérifiez l’état « Actif » ou son équivalent dans votre version.

Recharger l’outil cible

Claude Code détecte généralement les changements, mais ouvrez de préférence une nouvelle session pour valider ;
Pour Codex, fermez la fenêtre du terminal, rouvrez le terminal et redémarrez Codex.

N’évaluez pas la bascule dans une ancienne session ayant déjà envoyé des requêtes.

Vérifier la configuration actuelle

Exécutez dans l’outil cible :

/status

Vérifiez le Provider, la Base URL, la source d’authentification et l’ID du modèle. Claude Code ne doit pas avoir de /v1 dupliqué ; la Base URL Codex doit se terminer par un unique /v1.

Effectuer un test en lecture seule

Dans un projet de test sûr contenant README.md, saisissez :

Veuillez lire README.md et résumer l’objectif du projet en trois points. Ne modifiez aucun fichier.

Un résultat normal sans modification non autorisée confirme la connexion de base. Cette étape entraîne une consommation API normale.

Basculer depuis la zone de notification

CC-Switch propose une liste de Provider distincte pour chaque application dans la zone de notification. Cliquez avec le bouton droit sur l’icône, ouvrez le sous-menu Claude ou Codex et sélectionnez le Provider.

Cette bascule est simplement une autre interface de configuration et n’exige pas Local Proxy. Après une bascule Codex, rouvrez toujours le terminal.

Rétablir la configuration précédente

Ouvrez la page Claude Code ou Codex dans CC-Switch ;
Retrouvez le Provider officiel importé au premier démarrage ;
Cliquez sur « Activer » ;
Ouvrez une nouvelle session Claude Code ou un nouveau terminal Codex pour vérifier le rétablissement.

Les Provider Claude Code et Codex sont isolés. Une bascule Claude Code ne modifie pas automatiquement Codex, et inversement.

Questions fréquentes

Symptôme	Vérifier en priorité	Solution
Aucun installateur adapté	Origine, système et architecture du processeur	Téléchargez la version actuelle uniquement depuis `ccswitch.io` ou les GitHub Releases officiels
Le Provider précédent n’apparaît pas	Importation initiale et chemin de configuration de l’outil	Vérifiez que Claude Code ou Codex est installé et possède une configuration, puis rouvrez CC-Switch
L’activation ne peut pas écrire	Autorisations et utilisation du fichier de configuration	Fermez l’outil cible, vérifiez les droits du répertoire de configuration utilisateur et réessayez
Réponse `401`	API Key et méthode d’authentification	Utilisez une API Key valide ; pour Claude Code, n’utilisez pas `ANTHROPIC_AUTH_TOKEN`
Réponse `403`	État de la clé, autorisations du compte et du modèle	Vérifiez dans la console l’API Key et les modèles accessibles
Réponse `404`	Base URL, doublon `/v1`, Endpoint complet et ID du modèle	Claude Code : `https://api.agtcloud.cn` ; Codex : `https://api.agtcloud.cn/v1`, sans chemin complet
Liste de modèles indisponible	Support de `/v1/models`, réseau et API Key	Copiez un ID complet accessible à la clé dans le catalogue de modèles et saisissez-le manuellement
Claude Code utilise encore l’ancienne configuration	Provider actif et cache de l’ancienne session	Vérifiez que la carte AGTCloud est active, puis ouvrez une nouvelle session et exécutez `/status`
Codex utilise encore l’ancienne configuration	Redémarrage du terminal	Fermez la fenêtre du terminal, rouvrez-le, puis démarrez Codex
La conversation fonctionne, mais pas les outils	Protocole et capacités d’appel d’outils du modèle	Choisissez Anthropic Messages avec appels d’outils pour Claude Code, et Responses pour Codex
Base URL égale à `/v1/v1`	Application et saisie de l’URL	Retirez `/v1` pour Claude Code ; conservez-en un seul pour Codex

En cas de problème non identifié, consignez l’outil, l’heure, l’API Base URL, l’ID du modèle, le code HTTP et l’erreur expurgée, puis consultez Erreurs et dépannage. Ne fournissez pas d’API Key complète ni de sauvegarde CC-Switch.

Conseils de sécurité

N’inscrivez pas l’API Key dans les captures d’écran, journaux, dépôts ou configurations partagées ;
Les exports CC-Switch peuvent contenir des informations sensibles de Provider : protégez-les comme une sauvegarde d’identifiants ;
Installez CC-Switch uniquement depuis les canaux officiels et ne confiez pas vos identifiants de plateforme à des clients tiers ;
Validez d’abord dans un projet de test sûr et conservez les approbations des actions dans Claude Code et Codex ;
En cas de fuite présumée, désactivez ou supprimez immédiatement l’API Key dans la console, puis créez-en une nouvelle.