Настройка Codex через универсального провайдера CC Switch

Об этом документе

В этом документе описано, как с помощью функции универсального провайдера (Universal Provider) в CC Switch подключить инструмент командной строки OpenAI Codex к указанному API-шлюзу и ввести конфигурацию в действие.

Применимые версии: CC Switch v3.16.x и выше.

Источник информации: руководство пользователя и исходный код официального репозитория CC Switch. Продукт быстро обновляется; если интерфейс продукта не совпадает с описанием в этом документе, ориентируйтесь на то, что фактически отображается в приложении.

Термины

Термин	Описание
Codex	ИИ-помощник для программирования в командной строке от OpenAI. После установки запускается в терминале командой `codex`.
CC Switch	Кроссплатформенный десктопный инструмент управления конфигурацией для эндпоинтов сервисов и учётных данных Codex, Claude Code, Gemini CLI и других инструментов. Сам CC Switch не предоставляет возможности ИИ и только создаёт и переключает файлы конфигурации.
Провайдер (Provider)	Сторона, предоставляющая инференс моделей. Это может быть официальный сервис производителя моделей либо собственный или приобретённый API-шлюз.
API Key	Строка секретного ключа для аутентификации, обычно начинается с `sk-`.
Универсальный провайдер (Universal Provider)	Функция CC Switch. Одна конфигурация одновременно синхронизируется в три инструмента: Claude Code, Codex и Gemini CLI. Подходит для шлюзов, которые одновременно поддерживают несколько протоколов API (например, NewAPI).
Провайдер отдельного приложения	Конфигурация провайдера, которая действует только на один инструмент, в противоположность универсальному провайдеру.

Перед началом

Системные требования

Операционная система	Минимальная версия	Архитектура
Windows	Windows 10	x64
macOS	macOS 12 (Monterey)	Intel (x64) / Apple Silicon (arm64)
Linux	Ubuntu 22.04 / Debian 11 / Fedora 34 и эквивалентные версии	x64 / ARM64

Кроме того, требуется Node.js 18 или более новая версия. Шаги установки см. в «Задаче 1».

Сведения, которые нужно получить заранее

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

Пункт	Описание	Пример
Адрес API (Base URL)	Адрес сервиса шлюза	`https://seedrouter.net`
API Key	Ключ аутентификации	`sk-xxxxxxxxxxxx`
Название модели	Идентификатор модели на стороне Codex	`gpt-5.6-sol`
Поддержка протокола	Поддерживает ли шлюз протокол OpenAI Responses	Поддерживается / не поддерживается

Главное: четвёртый пункт определяет, применим ли этот документ. В конфигурации, которую единый провайдер генерирует для Codex, протокол связи зафиксирован как wire_api = "responses" и не может быть изменён. Если шлюз не поддерживает протокол Responses и поддерживает только протокол Chat Completions, использовать единый провайдер нельзя. Используйте вместо этого вариант F из раздела «Диагностика неполадок».

Открыть терминал

В этом документе во многих местах нужно выполнять команды в терминале. Откройте терминал следующим образом:

Windows: нажмите Win + R, введите powershell, нажмите клавишу Enter.
macOS: нажмите Command + пробел, введите terminal, нажмите клавишу Enter.
Linux: используйте приложение терминала, входящее в состав дистрибутива.

Задача 1: установка Node.js

Об этой задаче

Codex распространяется через npm, менеджер пакетов Node.js. Даже если вы используете установку в один клик через CC Switch, сначала необходима среда выполнения Node.js.

Процедура

Перейдите на официальный сайт Node.js.
Скачайте установочный пакет с пометкой LTS (версия с долгосрочной поддержкой). Не скачивайте версию Current.
Запустите программу установки и завершите установку с параметрами по умолчанию. Менять параметры конфигурации не нужно.

Пользователи macOS, у которых уже установлен Homebrew, также могут выполнить в терминале brew install node.
Закройте все текущие окна терминала и заново откройте одно новое окно терминала.
По очереди выполните следующие команды, чтобы проверить установку:
```
node --version
      npm --version
```

Результат

Обе команды выводят номер версии (например, v22.14.0 и 10.9.2), и версия Node.js не ниже v18. Это означает, что установка прошла успешно.

Примечание: если появляется сообщение «не является внутренней или внешней командой» или «command not found», обычно это потому, что окно терминала не открывали заново. Только что установленные команды вступают в силу только в новой сессии терминала.

Задача 2: установка CC Switch

Об этой задаче

CC Switch — бесплатное программное обеспечение с открытым исходным кодом. Оно распространяется только по следующим двум каналам:

Официальный сайт: ccswitch.io
Страница релизов GitHub: farion1231/cc-switch Releases

Предупреждение: любой сайт или клиент «CC Switch», который требует оплаты, пополнения баланса или запрашивает учётные данные для входа в аккаунт, не является официальным каналом. Не скачивайте и не используйте его.

Процедура

Windows

Откройте страницу релизов GitHub и в области Assets под записью о последней версии найдите CC-Switch-v3.16.x-Windows.msi.
Скачайте установщик, запустите его двойным щелчком и завершите установку по подсказкам.

Если после двойного щелчка ничего не происходит, это означает, что файл заблокирован политикой безопасности системы. Щёлкните этот файл правой кнопкой мыши, выберите Свойства, на вкладке Общие внизу в области Безопасность установите флажок Разблокировать, нажмите ОК и запустите его снова.

Если вы не хотите устанавливать программу в систему, можно также скачать версию без установки CC-Switch-v3.16.x-Windows-Portable.zip, распаковать её и сразу запустить CC-Switch.exe.

macOS

Используйте любой из следующих способов:

Первый способ (рекомендуется, если Homebrew уже установлен): выполните в терминале
```
brew install --cask cc-switch
```
Второй способ: скачайте CC-Switch-v3.16.x-macOS.dmg, откройте его двойным щелчком и перетащите значок CC Switch в папку «Программы».

Примечание: версия для macOS уже прошла подпись кода и нотариальное заверение Apple, её можно сразу установить и открыть, сообщение «не удается проверить разработчика» не появится, дополнительные действия по снятию карантина не требуются.

Linux

Выберите в зависимости от дистрибутива:

Debian / Ubuntu: скачайте пакет .deb, затем выполните

sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

Arch Linux: paru -S cc-switch-bin
Другие дистрибутивы: скачайте .AppImage, выполните chmod +x, чтобы добавить право на выполнение, затем сразу запустите файл.

Результат

После запуска CC Switch главное окно отображается нормально, а в области системного трея (в Windows — в правом нижнем углу, в macOS — справа в строке меню) появляется значок CC Switch. Это означает, что установка прошла успешно.

При первом запуске, если предлагается импортировать существующую конфигурацию CLI-инструментов, рекомендуется выбрать импорт. Эта операция сохранит текущую имеющуюся конфигурацию как провайдера по умолчанию и не приведёт к потере конфигурации.

Задача 3: установка Codex

Об этой задаче

Установить можно через графический интерфейс CC Switch или из командной строки. При первом использовании рекомендуется способ A.

Процедура

Способ A: установка через CC Switch (рекомендуется)

Запустите CC Switch.
Последовательно откройте Settings > About.
В области Local Environment Check посмотрите состояние строки Codex.
Если показано Not detected, нажмите кнопку Install справа в этой строке.

Установка выполняется молча в фоновом режиме, на кнопке отображается прогресс, а после завершения номер версии обновляется автоматически.

Примечание: последующие обновления также выполняются в этом интерфейсе. При обнаружении новой версии можно обновить её отдельно или нажать Upgrade All для пакетной обработки.

Способ B: установка из командной строки

Откройте терминал.
Выполните следующую команду:
```
npm install -g @openai/codex
```
Если скорость загрузки слишком низкая, можно перейти на зеркало:
```
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```
Если зеркало нужно использовать постоянно, можно сначала один раз выполнить следующую команду для глобальной настройки:
```
npm config set registry https://registry.npmmirror.com
```

Результат

Закройте терминал и снова откройте его, затем выполните следующую команду:

codex --version

Вывод номера версии означает, что установка прошла успешно.

Примечание: на этом этапе настройка провайдера ещё не завершена. Если запустить codex напрямую, возникнет ошибка из-за отсутствия действительных учётных данных. Это ожидаемое поведение. Настройка выполняется в задаче 4.

Задача 4: создание единого провайдера

Об этой задаче

В этой задаче в CC Switch создаётся одна конфигурация единого провайдера, и она синхронизируется со списком провайдеров Codex.

Процедура

Запустите CC Switch.
В переключателе приложений вверху переключитесь на Codex.

Переключение на панель Claude или Gemini также открывает вход к единому провайдеру. Все три используют одну и ту же конфигурацию.
Нажмите кнопку ＋ в правом верхнем углу, чтобы открыть панель добавления провайдера.
В верхней части панели выберите вкладку Unified Provider.

Ограничение: панели OpenCode, OpenClaw, Hermes и Claude Desktop не поддерживают единый провайдер, и на этих панелях вкладка не отображается. Если вкладка не видна, сначала переключитесь на панель Claude, Codex или Gemini.
Нажмите Add Unified Provider.

Заполните поля формы по таблице ниже:

Поле	Как заполнять
Select Preset Type	Если шлюз — NewAPI, выберите NewAPI; в остальных случаях или если вы не уверены, выберите Custom Gateway. Поля у обоих вариантов полностью совпадают, различаются только значения по умолчанию.
Name	Собственное имя-идентификатор, например `шлюз NewAPI`. Это имя будет показано на карточке провайдера Codex.
API Address	Укажите заранее полученный Base URL. Правила заполнения см. ниже: «Правила обработки адреса API».
API Key	Укажите заранее полученный ключ. Значок глаза справа переключает отображение открытым текстом.
Official Website	Необязательно. После заполнения с карточки провайдера можно перейти напрямую.
Notes	Необязательно. Рекомендуется указать источник ключа, срок действия и другие сведения.
Enabled Apps	Содержит три переключателя: Claude Code, OpenAI Codex и Gemini. Необходимо включить OpenAI Codex. Если этот шлюз также используется для двух других инструментов, их можно включить вместе с ним.
Model Configuration > Codex > Model	Укажите заранее полученное имя модели, например `gpt-5.6-sol`.
Model Configuration > Codex > Reasoning Effort	Интенсивность рассуждения; допустимые значения — `low`, `medium` или `high`. Если особых требований нет, укажите `high`.

Примечание: форма Unified Provider не предоставляет кнопку «Fetch Models»; имя модели необходимо заполнить вручную, с учётом регистра.

Нажмите Add.

Результат

Интерфейс сообщает «Unified Provider added and synced». В этот момент CC Switch уже создал в списке поставщиков Codex одну карточку поставщика с тем же именем; если вы отметили другие приложения, карточки также создаются в соответствующих списках.

Важно: синхронизация не означает включение. Сейчас конфигурация ещё не записана в файл конфигурации, который Codex читает при работе; вы должны продолжить выполнение задачи 5.

Правила обработки адреса API

Когда CC Switch формирует конфигурацию для Codex, введённый адрес API обрабатывается так:

Вид введённого адреса	Результат обработки
Только домен, без пути, например `https://seedrouter.net`	Автоматически дополняется до `https://seedrouter.net/v1`
Уже оканчивается на `/v1`, например `https://seedrouter.net/v1`	Используется без изменений
Содержит другой путь, например `https://api.example.com/openai`	Используется без изменений, `/v1` не дополняется

Критерий: после добавления /responses к обработанному адресу должен получиться путь интерфейса, реально доступный на шлюзе. Перед заполнением рекомендуем вам подтвердить у поставщика услуг полный адрес интерфейса, а затем по таблице выше вычислить обратным путём, что следует ввести. Неверный адрес приведёт к тому, что запрос вернёт 404.

Задача 5: включить поставщика и ввести конфигурацию в действие

Об этой задаче

После создания карточки поставщика её необходимо включить вручную, и только тогда конфигурация записывается в файл конфигурации Codex. Codex не поддерживает hot reload конфигурации; после включения вы должны перезапустить терминал.

Процедура

Закройте панель добавления поставщика.
В переключателе приложений сверху переключитесь на Codex.
В списке поставщиков найдите карточку с тем же именем, созданную в задаче 4.
Нажмите кнопку Enable на карточке.

Карточка отображается с синей рамкой и меткой «Currently Enabled», что означает, что конфигурация записана.

Полностью закройте текущее окно терминала, затем заново откройте новое окно терминала.

Важно: здесь имеется в виду закрыть всё окно терминала, а не выйти из процесса codex и заново выполнить команду codex. Различия в способе вступления в силу у разных инструментов:

Инструмент	Способ вступления в силу после переключения поставщика
Claude Code	Вступает в силу сразу, поддерживается hot reload
Gemini CLI	Вступает в силу сразу, при каждом запросе конфигурация читается заново
Codex	Нужно закрыть и заново открыть терминал
OpenCode / OpenClaw	Нужно закрыть и заново открыть терминал

В новом терминале выполните:
```
codex
```
После запуска введите одну тестовую фразу, например «Здравствуйте, пожалуйста, кратко представьтесь».

Результат

Модель нормально возвращает ответ, а значит, настройка завершена и Codex подключён к указанному шлюзу.

Справка: сгенерированный файл конфигурации

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

Затрагиваются следующие файлы. В пути ~ обозначает каталог текущего пользователя: в Windows это C:\Users\<имя_пользователя>\, в macOS и Linux — /Users/<имя_пользователя>/ или /home/<имя_пользователя>/.

~/.codex/auth.json — хранит учётные данные:

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — хранит конфигурацию модели и endpoint:

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

Собственные данные CC Switch хранятся в каталоге ~/.cc-switch/. Файл базы данных — cc-switch.db, автоматические резервные копии находятся в подкаталоге backups/, сохраняются последние 10 копий.

Операции обслуживания

Изменение конфигурации

Чтобы изменить API Key, название модели или адрес сервиса:

Нажмите кнопку ＋ и перейдите на вкладку Unified Provider.
На нужной карточке нажмите значок редактирования.
Измените соответствующие поля.

В режиме редактирования внизу формы есть область Config JSON Preview. Перед синхронизацией в ней можно подтвердить фактическое содержимое, которое будет записано в каждое приложение.
Нажмите Save and Sync.
Подтвердите операцию в диалоге подтверждения. Эта операция перезапишет связанные конфигурации провайдеров в Claude, Codex и Gemini.
Закройте терминал и откройте его снова.

Операции с карточкой провайдера

Операция	Описание
Sync	Вручную повторно отправить текущую конфигурацию в каждое связанное приложение, чтобы исправить несовпадение конфигураций.
Copy	Создать копию на основе текущей конфигурации, чтобы удобнее задать запасной ключ.
Edit	Изменить содержимое конфигурации.
Delete	Удалить единого провайдера и одновременно удалить созданные им в Claude, Codex и Gemini связанные карточки провайдеров.

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

Щёлкните правой кнопкой мыши значок CC Switch в системном трее и в подменю Codex нажмите имя нужного провайдера. Переключение выполняется без открытия главного интерфейса. После переключения терминал также нужно перезапустить.

Диагностика неполадок

A. Возвращается 401 или 403, ошибка аутентификации

Возможная причина	Решение
При копировании API Key захвачены лишние пробелы или переводы строки	Скопируйте и вставьте ещё раз, следя за границами выделения
Срок действия API Key истёк или квота исчерпана	Уточните у поставщика сервиса состояние ключа
API Key не соответствует адресу API	Проверьте, что оба значения относятся к одному и тому же сервису

B. Возвращается 404 или сообщение, что endpoint не существует

В большинстве случаев адрес API после обработки оказался неверным. Ещё раз сверьтесь с разделом «Задача 4 > Правила обработки адреса API» и уточните у поставщика сервиса полный адрес endpoint.

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

Терминал не был перезапущен. Полностью закройте окно терминала и откройте его снова. Это самая частая проблема при использовании Codex.

D. Вверху интерфейса показано предупреждение о конфликте переменных окружения

В системе заданы переменные окружения, такие как OPENAI_API_KEY. У переменных окружения приоритет выше, чем у файла конфигурации: они перезаписывают конфигурацию, записанную CC Switch, и запрос уходит на неверный endpoint или с неверным ключом.

Порядок действий:

Нажмите Expand на баннере предупреждения и посмотрите имена, значения и источники конфликтующих переменных.
Отметьте переменные, которые нужно удалить, или нажмите Select All.
Нажмите Delete Selected и подтвердите.

Перед удалением CC Switch автоматически сохраняет резервную копию в ~/.cc-switch/env-backups/. Если вам нужно восстановить данные, вручную верните их из JSON-файла в этом каталоге.

E. Терминал сообщает, что команда codex не существует

Возможная причина	Решение
После установки терминал не открывали заново	Закройте все окна терминала и откройте его снова
Node.js установлен неправильно	Вернитесь к задаче 1 и проверьте, что `npm --version` нормально выводит результат
Глобальный каталог npm не добавлен в PATH	Переустановите через Settings > About > Local Environment Check в CC Switch

F. Шлюз поддерживает только протокол Chat Completions

Протокол связи единого провайдера зафиксирован как Responses. В этом случае он не подходит, нужно использовать провайдера для конкретного приложения.

В CC Switch перейдите на панель Codex и нажмите кнопку ＋.
Останьтесь на вкладке Codex Provider слева и не переключайтесь на Unified Provider.
В выпадающем списке пресетов выберите соответствующего поставщика. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI и другие относятся к пресетам типа Chat Completions.
После выбора такого пресета CC Switch автоматически включает переключатель «Requires local route mapping» и настраивает таблицу сопоставления моделей. Преобразование протокола выполняет локальный прокси, вручную ничего задавать не нужно.
Введите API Key, нажмите Add, затем включите этого провайдера и перезапустите терминал.

G. Нужно вернуться ко входу с официальной учётной записью

На панели Codex добавьте провайдера из пресета «OpenAI Official».
Включите этого провайдера и перезапустите терминал.
Пройдите аутентификацию по собственному процессу входа Codex.

После этого вы можете свободно переключаться между официальным входом и сторонними провайдерами.

Справка по выбору: Unified Provider и App-specific Provider

Сценарий использования	Рекомендуемый вариант
Один шлюз одновременно обслуживает Claude Code, Codex и Gemini CLI и поддерживает протокол Responses	Unified Provider
Используется только один инструмент, Codex	Подходят оба варианта, путь настройки App-specific Provider короче
Шлюз поддерживает только протокол Chat Completions	App-specific Provider вместе со встроенным пресетом
Каждый инструмент подключается к своему поставщику услуг	App-specific Provider, настройка по отдельности
Нужно настроить OpenCode, OpenClaw или Hermes	App-specific Provider: эти три инструмента не поддерживают Unified Provider

Меры безопасности

API Key столь же чувствителен, как учётные данные аккаунта. Не передавайте его в мессенджерах, не делитесь скриншотами и не отправляйте его в репозиторий кода.
Получайте установочный пакет CC Switch только с официального сайта CC Switch или из официального репозитория GitHub.
При смене устройства или подозрении на утечку ключа сразу замените ключ.
Функция экспорта конфигурации CC Switch записывает сведения обо всех провайдерах открытым текстом в резервный файл .sql. Экспортированный файл храните надёжно и не помещайте его в общий каталог.

Краткая справка

1. Установить Node.js               nodejs.org, выберите версию LTS
      2. Установить CC Switch             ccswitch.io или GitHub Releases
      3. Установить Codex                 CC Switch > Settings > About > Local Environment Check > Install
      4. Создать Unified Provider             Перейдите на панель Codex > ＋ > Unified Provider > Add Unified Provider
                                    Укажите название, адрес API и API Key
                                    Включите переключатель OpenAI Codex и укажите название модели
      5. Включить провайдера                 Панель Codex > целевая карточка > Enable
      6. Перезапустить терминал                   Полностью закройте окно терминала и откройте его снова
      7. Проверить                       Выполните команду codex и отправьте тестовое сообщение

При отправке отзыва о проблеме приложите полный скриншот с информацией об ошибке, а также адрес API, который вы указали в задаче 4 (часть с ключом замаскируйте), чтобы сократить время разбора.