CC-Switch

Управление конфигурациями AGTCloud и переключение между ними с помощью CC-Switch.

CC-Switch — кроссплатформенный инструмент управления локальными конфигурациями. Он позволяет сохранять несколько Provider для Claude Code, Codex и других инструментов программирования и записывать активную конфигурацию в файлы соответствующего инструмента. С его помощью можно переключаться между AGTCloud и другими сохранёнными конфигурациями без ручного редактирования файлов при каждом переключении.

В этом руководстве рассматриваются только Provider для отдельных приложений Claude Code и Codex. Запросы отправляются соответствующим инструментом программирования напрямую в AGTCloud; Local Proxy, Failover, преобразование протоколов и Universal Provider в CC-Switch не включаются.

Переключение изменяет локальную конфигурацию инструмента

CC-Switch обновляет рабочие файлы конфигурации Claude Code или Codex. Перед первым использованием убедитесь, что существующие настройки импортированы правильно, и экспортируйте резервную копию до добавления AGTCloud.

Подготовка

Перед началом убедитесь, что вы:

Установили Claude Code или Codex и выполнили первоначальный запуск;
Зарегистрировались и вошли в AGTCloud;
Создали ключ API AGTCloud на странице API Keys;
Скопировали из каталога моделей ID модели, доступной текущему ключу API и поддерживающей протокол нужного инструмента;
Подготовили тестовый проект без конфиденциального кода и производственных учётных данных.

Для Claude Code выбирайте модель с поддержкой Anthropic Messages, а для Codex — модель с поддержкой OpenAI Responses. MODEL_ID — заполнитель, который необходимо заменить, а не настоящее название модели.

Загрузка и установка CC-Switch

Загружайте установочные пакеты только с официального сайта CC-Switch или из GitHub Releases. Сайты и клиенты, которые требуют пополнения баланса, оплаты самого CC-Switch или передачи учётных данных для входа, не являются официальными каналами.

Для обычной установки выберите Windows MSI текущей версии в GitHub Releases;
Если установка не нужна, выберите Windows Portable ZIP;
Распакуйте Portable-версию и запустите CC-Switch.exe;
Если Windows блокирует запуск, сначала проверьте источник файла и цифровую подпись; не отключайте системные средства защиты.

CC-Switch управляет конфигурацией, но не заменяет Claude Code или Codex. Сначала убедитесь, что нужный инструмент программирования запускается нормально.

Первый запуск и резервное копирование

Проверка автоматического импорта

При первом запуске CC-Switch пытается импортировать существующие локальные конфигурации Claude Code, Codex и других инструментов. Откройте страницу каждого приложения и убедитесь, что прежняя официальная конфигурация или пользовательский Provider присутствует в списке.

Сохранение прежнего Provider

Не удаляйте автоматически импортированную официальную конфигурацию. Если потребуется прекратить использование AGTCloud, вы сможете снова включить этот Provider и восстановить прежний способ подключения.

Экспорт резервной копии

Перейдите в Настройки → Дополнительно → Управление данными и сохраните резервную копию с помощью функции экспорта текущей версии. Она может содержать ключи API и другие конфиденциальные данные Provider. Храните её в доверенном месте, не загружайте в репозиторий или общедоступное облачное хранилище.

Это руководство не требует ручного редактирования конфигурационных файлов

CC-Switch самостоятельно записывает настройки соответствующих инструментов. Не перезаписывайте ~/.claude/settings.json, ~/.codex/auth.json или ~/.codex/config.toml ради применения примеров с других платформ.

Добавление Provider AGTCloud

Выберите нужное приложение в верхней части окна, нажмите кнопку добавления справа вверху и используйте пользовательскую конфигурацию в разделе поставщиков для отдельных приложений. Claude Code и Codex используют разные протоколы и Base URL, поэтому создайте отдельный Provider для каждого.

Открытие страницы Provider Claude Code

Выберите Claude Code в верхней части CC-Switch, нажмите добавление поставщика и выберите «Пользовательский» или соответствующий пункт пользовательского Provider в текущей версии.

Заполнение параметров подключения

Поле	Значение
`Provider Name`	`AGTCloud`
`Base URL`	`https://api.agtcloud.cn`
`API Key`	`your-api-key`
`Primary Model`	`MODEL_ID`
`Authentication`	Используйте ключ API, а не `ANTHROPIC_AUTH_TOKEN`

В Base URL укажите только API Origin, показанный на этой странице, без /v1. Claude Code самостоятельно обращается к /v1/messages.

Настройка соответствия моделей

Если текущая версия показывает сопоставление ролей Haiku, Sonnet и Opus, при первом подключении можно назначить всем трём один MODEL_ID с подтверждённой поддержкой Anthropic Messages. Разные модели назначайте только после проверки их реальных возможностей.

Сохранение без включения прокси

Сохраните Provider. Не включайте Local Proxy, Failover, преобразование протоколов или другие расширенные функции маршрутизации.

Аутентификация с помощью ключа API

Конфигурация Claude Code для AGTCloud использует аутентификацию ключом API через ANTHROPIC_API_KEY. Не копируйте настройки других платформ, использующие ANTHROPIC_AUTH_TOKEN или Bearer Token.

Включение и проверка конфигурации

Включение AGTCloud

Вернитесь к списку поставщиков нужного приложения и нажмите «Включить» на карточке AGTCloud. Убедитесь, что карточка показывает «Сейчас включён» или эквивалентный статус текущей версии.

Перезапуск целевого инструмента

Claude Code обычно обнаруживает изменения конфигурации, но для проверки рекомендуется открыть новый сеанс;
Для Codex закройте текущее окно терминала, затем откройте терминал заново и запустите Codex.

Не оценивайте успешность переключения по старому сеансу, в котором уже отправлялись запросы.

Проверка текущей конфигурации

Выполните в целевом инструменте:

/status

Проверьте Provider, Base URL, источник аутентификации и ID модели. В Claude Code не должно быть повторяющегося /v1; Base URL Codex должен оканчиваться одним /v1.

Тест только для чтения

В безопасном тестовом проекте с README.md введите:

Прочитайте README.md и в трёх пунктах опишите назначение проекта. Не изменяйте никакие файлы.

Если результат возвращается нормально и не происходит неразрешённых изменений, базовое подключение установлено. Этот шаг создаёт обычный расход API.

Быстрое переключение через системный трей

CC-Switch предоставляет отдельные списки Provider для разных приложений в системном трее. Щёлкните значок правой кнопкой мыши, откройте подменю Claude или Codex и выберите Provider, который нужно включить.

Переключение через трей — лишь другой способ изменения конфигурации; включать Local Proxy не требуется. После переключения Codex всё равно необходимо заново открыть терминал.

Возврат к прежней конфигурации

Откройте страницу Claude Code или Codex в CC-Switch;
Найдите официальный Provider, импортированный при первом запуске;
Нажмите «Включить»;
Откройте новый сеанс Claude Code или заново откройте терминал Codex и подтвердите восстановление.

Provider Claude Code и Codex изолированы друг от друга. Переключение Claude Code не изменяет Codex автоматически, и наоборот.

Частые вопросы

Симптом	Что проверить сначала	Решение
Нет подходящего установочного пакета	Источник загрузки, ОС и архитектуру процессора	Загружайте текущую версию только с `ccswitch.io` или официального GitHub Releases
Прежний Provider отсутствует	Результат первого импорта и путь конфигурации исходного инструмента	Убедитесь, что Claude Code или Codex установлен и имеет конфигурацию, затем снова откройте CC-Switch
При включении невозможно записать настройки	Права и занятость конфигурационных файлов	Закройте целевой инструмент, проверьте права на пользовательский каталог конфигурации и повторите попытку
Ответ `401`	Содержимое ключа API и способ аутентификации	Используйте действующий ключ API; для Claude Code не используйте `ANTHROPIC_AUTH_TOKEN`
Ответ `403`	Состояние ключа, права аккаунта и доступ к модели	Проверьте текущий ключ API и доступные модели в консоли
Ответ `404`	Base URL, повторный `/v1`, полный Endpoint и ID модели	Для Claude Code используйте `https://api.agtcloud.cn`, для Codex — `https://api.agtcloud.cn/v1`; не указывайте полный путь запроса
Список моделей не загружается	Поддержку `/v1/models`, сеть и ключ API	Скопируйте полный ID модели, доступной текущему ключу, из каталога моделей и введите его вручную
Claude Code использует старую конфигурацию	Активный Provider и кэш старого сеанса	Убедитесь, что карточка AGTCloud активна, откройте новый сеанс Claude Code и выполните `/status`
Codex использует старую конфигурацию	Перезапущен ли терминал	Закройте текущее окно терминала, откройте новое и запустите Codex
Диалог работает, но вызов инструментов завершается ошибкой	Протокол и поддержку вызова инструментов моделью	Для Claude Code выбирайте модель с Anthropic Messages и вызовом инструментов; для Codex — модель с Responses
Base URL превратился в `/v1/v1`	Тип приложения и формат URL	Удалите `/v1` для Claude Code; для Codex оставьте только один `/v1`

Если причину найти не удаётся, запишите целевой инструмент, время запроса, API Base URL, ID модели, HTTP-статус и обезличенную ошибку, затем обратитесь к разделу ошибок и диагностики. Не отправляйте полный ключ API или резервную копию данных CC-Switch.