Codex на Windows: установка нативно и в WSL с подключением к шлюзу

Codex CLI от OpenAI запускается на Windows двумя способами: нативно в PowerShell и внутри WSL2. Выбор влияет на путь установки, расположение конфига и поведение песочницы. Ниже: как поставить Codex для Windows, как подключить его к шлюзу Zukko и как справиться с типичными проблемами.

Установочные команды и сведения о песочнице взяты из README репозитория github.com/openai/codex и документации OpenAI для Codex на 18 октября 2026. Версии меняются, поэтому при расхождениях ориентируйтесь на документацию.

Нативно или WSL

По документации OpenAI, на Windows по умолчанию стоит использовать нативную песочницу. WSL2 выбирают, когда нужны Linux-инструменты, репозитории и рабочий процесс уже живут в WSL2, либо нативные варианты песочницы не подходят. WSL1 поддерживался до версии Codex 0.114, начиная с 0.115 его не поддерживают.

Что касается версии Windows: Windows 11 указана как рекомендуемая база. Для Windows 10 нужна современная консоль (ConPTY), на практике версия 1809 или новее, и работа на ней описана как «по возможности». Также в документации сказано, что должен быть доступен winget.

Установка нативно

Официальный установочный скрипт для PowerShell, как в README:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Скрипт скачивает и запускает код из интернета. Если вы не хотите этого делать, поставьте через npm (нужен Node.js):

npm install -g @openai/codex

После установки в новом окне PowerShell выполните codex --version, чтобы убедиться, что команда видна.

Песочница

Codex на Windows исполняет команды в песочнице. В документации перечислены три реализации: mxc (рекомендуемая на совместимых устройствах, требует поддержки на уровне Windows 11 24H2 или 25H2 с нужной сборкой), elevated (запасной вариант, требует подтверждения администратора при настройке) и unelevated (ослабленный запасной вариант с более слабой сетевой изоляцией). Выбрать запасной вариант можно в config.toml:

[windows]
sandbox = "elevated" # или "unelevated"

Если установка песочницы elevated не прошла, документация называет типичные причины: отклонённый запрос UAC, запрет на создание локальных пользователей или правил брандмауэра и корпоративные политики. Тогда на время можно переключиться на unelevated, если политика компании это разрешает. Отдельно описана ошибка 1385: Windows запрещает нужный тип входа для созданных песочницей пользователей, это решается на уровне политик устройства, и при обращении в поддержку полезно приложить CODEX_HOME\.sandbox\sandbox.log.

Установка в WSL2

В PowerShell от администратора:

wsl --install
wsl

Дальше в оболочке WSL:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Две рекомендации из документации. Держите репозитории в домашнем каталоге Linux (~/code/...), а не в /mnt/c/...: так быстрее ввод-вывод и меньше проблем с правами и симлинками. Если нужен доступ из Windows, файлы доступны по пути \\wsl$\Ubuntu\home\<user> в Проводнике. Расширение для VS Code в этом режиме запускают из окна, открытого в WSL (code . из оболочки WSL): так открывается удалённое окно WSL, и встроенный терминал работает в Linux.

Подключение к шлюзу Zukko

Codex читает config.toml из каталога .codex в домашней папке: в Windows это %USERPROFILE%\.codex\config.toml, в WSL ~/.codex/config.toml внутри Linux. Это разные файлы: настройка, сделанная в Windows, не видна изнутри WSL, и наоборот. Если пользуетесь обоими, настройте оба.

Файл конфигурации:

model = "gpt-6.1-sol"
model_provider = "zukko"
model_reasoning_effort = "medium"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Ключ fetch_... создаётся в кабинете↗. Передайте его через переменную окружения. В PowerShell на уровне пользователя:

[Environment]::SetEnvironmentVariable("ZUKKO_API_KEY", "fetch_ваш_ключ", "User")

Откройте новое окно PowerShell, чтобы переменная подхватилась. В WSL добавьте строку export ZUKKO_API_KEY=fetch_ваш_ключ в ~/.bashrc и перезапустите оболочку.

Пояснения. base_url с суффиксом /v1, как для любого OpenAI-совместимого клиента. wire_api = "responses": по документации OpenAI это единственное поддерживаемое значение, и Codex общается через Responses API, который шлюз поддерживает (POST /v1/responses). В документации Zukko для Codex описан и другой способ: requires_openai_auth = true и ключ в %USERPROFILE%\.codex\auth.json в виде { "OPENAI_API_KEY": "fetch_..." }. Он тоже рабочий; если создаёте файл из PowerShell, записывайте его в UTF-8 без BOM, иначе JSON может не прочитаться. Актуальные подробности: документация по Codex↗.

По данным документации Zukko, через Codex работают модели GPT и Claude, модели GLM в нём не работают. Поэтому для проверки берите gpt-6.1-sol или claude-sonnet-5-5. Список доступных моделей выдаёт GET https://api.zukko.pro/v1/models. Если ключ ограничен списком моделей, добавьте в него выбранную.

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

Перейдите в каталог проекта (в нативном режиме это путь Windows, в WSL путь Linux) и запустите:

codex "кратко опиши структуру этого проекта"

Для оценки расхода: пусть пробная сессия сделала 10 запросов по 20 000 входных токенов и по 500 выходных. Вход 200 000, выход 5 000. На gpt-6.1-sol (вход $0.27, выход $1.32 за 1M, цены на 18 октября 2026): 0,2 × 0,27 + 0,005 × 1,32 = 0,054 + 0,0066 = $0.0606. Реальная сумма зависит от проекта; ориентируйтесь на историю расходов в кабинете.

Типичные ошибки

• codex не найден. Откройте новое окно терминала; при установке через npm проверьте, что каталог глобальных пакетов есть в PATH. В WSL выполните which codex.
• 401. Переменная ZUKKO_API_KEY не видна процессу: запустили терминал до её создания либо опечатка в имени. Проверьте echo $env:ZUKKO_API_KEY в PowerShell.
• 404 на каждый запрос. Нет /v1 в base_url или неверное имя модели (404 model_not_found).
• 402. Не хватает баланса. Пополнение: СБП (платёжная страница добавляет комиссию 8,5% сверху), криптовалюта, карты MasterCard.
• Сбой настройки песочницы. См. раздел о песочнице выше; уточните политику у администратора компьютера.
• Расширение VS Code не отвечает. В документации OpenAI причиной названо отсутствие компонентов Visual C++ (Build Tools и Redistributable); после установки полностью перезапустите VS Code.

Общую картину по ошибкам подключения даёт статья 401, 402, model not found: разбор ошибок↗. Для сравнения подхода у другого агента см. Claude Code на Windows↗.

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

Codex для Windows нужно ставить через WSL?

Нет. Документация OpenAI называет нативную песочницу вариантом по умолчанию, а WSL2 выбором для тех, кому нужен Linux-тулчейн.

Можно ли использовать подписку ChatGPT и Zukko одновременно?

Codex поддерживает вход через ChatGPT и вход по API-ключу. Условия подписки смотрите на сайте OpenAI. При схеме с env_key провайдер Zukko подключается отдельно от входа в аккаунт, но выбранный model_provider определяет, куда пойдут запросы.

Где лежит конфиг, если я использую и Windows, и WSL?

В двух местах: %USERPROFILE%\.codex\config.toml в Windows и ~/.codex/config.toml внутри Linux. Файлы независимы.

Какую модель поставить для начала?

Для проверки подойдёт gpt-6.1-sol или claude-sonnet-5-5. Качество на вашей задаче проверяйте сами, сравнивая цену и результат.

Создайте ключ в кабинете Zukko, пропишите провайдера в config.toml и запустите первую задачу на небольшом репозитории.