Codex Windows: как поставить агента

Codex Windows: приложение или терминал?

Коротко: Codex Windows - это связка «агент OpenAI Codex плюс компьютер с Windows», и путей в ней два. Есть приложение с окном, а есть Codex CLI - агент, который живёт прямо в терминале. Эта статья про второй путь. Развилку стоит выбрать до установки, потому что ставятся они по-разному.

Сначала отделю лишнее, иначе половина читателей уйдёт не туда. По запросу «codex windows» поисковик подмешивает посторонние продукты с тем же словом в названии: сторонний органайзер для заметок и сервис доступа в сеть. К OpenAI они отношения не имеют. Если ты пришёл за ними - это другая статья и другой продукт.

Дальше под словом Codex я имею в виду агента OpenAI. Сам термин разобран в словаре, а что вообще значит слово «агент» - там же отдельно.

Теперь про развилку, которую русскоязычные инструкции почти не объясняют. Codex на Windows существует в двух видах:

• Приложение с окном. Ставится как обычная программа, агент работает внутри её интерфейса.
• Codex CLI. Программа для терминала: ты открываешь PowerShell, набираешь codex и разговариваешь с агентом текстом в том же окне. Окна у неё нет.

Дальше речь про CLI. Если ты никогда не открывал терминал, это нормально: все команды ниже копируются целиком, придумывать ничего не нужно.

Про Codex Windows в интернете ходят две противоположные инструкции: одна требует сначала поставить внутрь Windows целый Linux, другая говорит, что этого не нужно. Обе ссылаются на официальную документацию, и обе правы - просто это разные её страницы. Разбираю это в третьем разделе.

Что понадобится для установки?

Коротко: для Codex Windows нужна Windows 11 либо Windows 10 версии 1809 и новее, доступный пакетный менеджер winget, аккаунт ChatGPT и права администратора, если хочешь нативную песочницу. Node.js не нужен - он понадобится только тем, кто пойдёт через npm. Свою версию системы можно посмотреть одной командой, она в первом же абзаце ниже.

Официальные требования к системе выглядят так:

Проверить свою версию можно командой winver - она откроет окошко с номером сборки.

Отдельным пунктом документация оговаривает окружение: в системе должен быть доступен winget. Если его нет, сначала обновляется Windows или ставится Windows Package Manager, и только потом Codex.

Ещё понадобится:

• Аккаунт ChatGPT либо ключ платформы OpenAI. Без входа агент не ответит ни на один запрос.
• Права администратора - но только если нужна нативная песочница. Почему она их просит, разбираю отдельным разделом.
• Рабочий доступ к серверам OpenAI. Это отдельная тема со своими граблями, она разобрана в статье про сетевой доступ к Codex.

Нужен ли WSL, чтобы запустить Codex на Windows?

Коротко: нет, не нужен. Начинать стоит с нативного пути в PowerShell. Путаница растёт из самой документации OpenAI: в одном её месте до сих пор написано, что Windows поддерживается только через WSL2, а в другом - что WSL больше не требуется. Свежая страница про Windows написана позже, и старая строка в репозитории ей противоречит.

Вот эти два текста. Первый - таблица системных требований в файле docs/install.md репозитория openai/codex:

Operating systems | macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2

«Операционные системы: macOS 12+, Ubuntu 20.04+/Debian 10+ или Windows 11 через WSL2.»

• OpenAI, docs/install.md, репозиторий openai/codex

Второй - отдельная страница документации про Windows:

The app can run natively in PowerShell with a Windows sandbox instead of requiring WSL or a virtual machine.

«Приложение может работать нативно в PowerShell с песочницей Windows, вместо того чтобы требовать WSL или виртуальную машину.»

• OpenAI, Codex on Windows

Там же сказано прямо, что выбирать по умолчанию:

Use the native Windows sandbox by default. Choose WSL when you need Linux-native tooling, your workflow already lives in WSL2, or neither native Windows sandbox mode meets your needs.

«По умолчанию используйте нативную песочницу Windows. Выбирайте WSL, если вам нужны Linux-нативные инструменты, если ваш рабочий процесс уже живёт в WSL2 или если ни один из режимов нативной песочницы Windows вам не подходит.»

• OpenAI, Codex on Windows

Практический вывод для Codex Windows такой. Строка про WSL2 в репозитории - наследство более раннего этапа, когда нативной песочницы ещё не было. Русскоязычные гайды переписывают друг у друга именно её, поэтому новичка первым делом отправляют ставить Linux внутрь Windows. Это лишний слой, лишний час и лишняя путаница с тем, где потом лежат его файлы.

Порядок я бы держал такой: сначала пробуешь нативный путь, и только если он не подошёл - смотришь раздел про WSL2 ниже.

Шаг 1. Поставить Codex одной командой

Коротко: открываешь PowerShell и выполняешь одну строку из официального README репозитория. Она скачивает установщик и сразу его запускает. Отдельно менять политику выполнения скриптов не надо: нужный ключ уже вшит в саму команду. Ниже эта строка разобрана по частям, чтобы было понятно, что именно ты запускаешь на своей машине.

Команда дословно из README репозитория openai/codex:

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

PowerShell - это встроенное в Windows окно для команд. Открывается так: нажми «Пуск», набери PowerShell и запусти найденное приложение. Появится тёмное окно с мигающим курсором, в него и вставляется строка.

Разбираю её по частям: целиком она выглядит страшнее, чем есть:

1. powershell - запускает саму эту оболочку.
2. -ExecutionPolicy ByPass - разрешает выполнить скрипт для этого одного запуска. Глобальную политику системы команда не меняет.
3. irm - сокращение от Invoke-RestMethod, скачивает файл по адресу.
4. iex - сокращение от Invoke-Expression, выполняет скачанное.

Вертикальная черта между irm и iex передаёт результат первой команды во вторую: скачали - выполнили.

Node.js для этого пути ставить не надо. Ядро Codex написано на языке Rust - это сказано в том же файле docs/install.md в репозитории. Установщик приносит уже готовую программу, никаких дополнительных сред выполнения ей не нужно.

Общая картина по всем способам установки, включая macOS и Linux, разобрана отдельно - как установить Codex. Здесь только то, что относится к Codex Windows.

Шаг 2. Убедиться, что Windows видит команду

Коротко: закрой окно терминала, открой заново и выполни codex –version. Перезапуск обязателен: переменная PATH читается один раз при старте процесса. Если команда не находится, у Codex Windows причину стоит искать в PATH, а не в самой установке. Дальше три проверки, которые показывают, где именно потерялся путь к программе.

PATH - это список папок, в которых Windows ищет программы, когда ты набираешь их имя. Если папки с codex в этом списке нет, система отвечает, что такой команды не знает, даже когда файл лежит на диске.

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

1. Закрой окно PowerShell и открой новое.
2. Выполни codex --version.

Если версия напечаталась - установка закончена, можно идти дальше.

Если нет, терминал ответит примерно так:

codex : The term 'codex' is not recognized as the name of a cmdlet, function, script file, or operable program.

В русской локализации cmd.exe та же ситуация выглядит как «не является внутренней или внешней командой».

Что делать по порядку:

1. Убедись, что окно терминала действительно новое. Переменные среды подхватываются при запуске процесса. Сам факт установки их не обновляет.
2. Выполни where.exe codex. Команда печатает путь к файлу, если система его находит. Пусто - файла нет в PATH.
3. Если ставил через npm, проверь npm prefix -g. Путь оттуда должен лежать в переменной среды пользователя, а не только в текущей сессии PowerShell. Правка вида $env:Path += ... живёт до закрытия окна и после перезапуска пропадает.

Переменные среды пользователя правятся через «Параметры» - «Система» - «О системе» - «Дополнительные параметры системы» - «Переменные среды».

Шаг 3. Войти в аккаунт и запустить первую задачу

Коротко: запусти codex и выбери вход по аккаунту ChatGPT. Вход открывает страницу авторизации в браузере и поднимает на твоей машине локальный сервер, который ловит ответ. После входа перейди в папку проекта и запусти codex ещё раз, чтобы дать агенту первую задачу.

Вход описан в README дословно:

Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Business, Edu, or Enterprise plan.

«Запустите codex и выберите пункт Войти через ChatGPT. Мы рекомендуем входить в аккаунт ChatGPT, чтобы использовать Codex в рамках тарифа Plus, Pro, Business, Edu или Enterprise.»

• OpenAI, README репозитория openai/codex

Второй вариант - ключ платформы OpenAI, но README сразу предупреждает, что он требует дополнительной настройки.

Отдельное место, где вход в Codex Windows может застрять, - локальный порт. Сервер входа слушает 127.0.0.1:1455, и на Windows этот порт бывает занят другой программой или попадает в диапазоны, которые система зарезервировала под себя. Тогда терминал печатает строку Port 127.0.0.1:1455 is already in use. В трекере - так называется публичный список обращений о проблемах у самого проекта - этот случай разобран в обращении #3927, там он описан для связки с WSL.

Посмотреть исключённые диапазоны портов можно так:

netsh interface ipv4 show excludedportrange protocol=tcp

Если вход не проходит совсем и браузер даже не открывается, причину стоит искать в сети. Это отдельная тема, она разобрана в статье про сетевой доступ к Codex.

После входа перейди в папку с проектом и запусти codex. Агент откроется текстовым интерфейсом прямо в окне терминала.

Почему песочница просит администратора и что такое ошибка 1385?

Коротко: песочница Codex Windows устроена не так, как на macOS и Linux. Это два режима в config.toml - elevated и unelevated. Предпочтительный режим заводит отдельных пользователей с пониженными правами, и поэтому просит одобрения администратора. Ошибка 1385 означает, что Windows отказала этим пользователям в правах входа.

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

When you run Codex natively on Windows, agent mode uses a Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval.

«Когда вы запускаете Codex нативно на Windows, режим агента использует песочницу Windows, чтобы блокировать запись в файловую систему за пределами рабочей папки и не допускать доступа в сеть без вашего явного одобрения.»

• OpenAI, Codex on Windows

Режимов два, задаются в файле config.toml:

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

Разница между ними:

Документация прямо говорит: если доступны оба режима, бери elevated; если он не заработал в твоём окружении, переходи на unelevated, пока разбираешься с настройкой.

Отсюда и самая узнаваемая проблема на рабочих ноутбуках. Режим elevated заводит новых пользователей Windows, а это требует прав администратора и подтверждения UAC. Среди известных проблем документация называет ошибку 1385: Windows отказывает пользователям песочницы в нужных правах входа. Сюда же относятся отклонённый запрос UAC (это то самое окно «Разрешить приложению вносить изменения», которое Windows показывает поверх всего), блокировка создания пользователей и корпоративные политики на рабочих машинах.

Ещё одна мелочь, которая экономит время. Если команда падает потому, что песочница не может прочитать нужный каталог, доступ выдаётся слэш-командой прямо в сессии:

/sandbox-add-read-dir C:\absolute\directory\path

Путь должен быть существующим и абсолютным.

Если будешь писать в поддержку про песочницу, в документации сказано приложить лог CODEX_HOME/.sandbox/sandbox.log вместе с версией Windows. Отдельно там оговорено: не прикладывать содержимое папки CODEX_HOME/.sandbox-secrets/.

Когда всё-таки стоит выбрать WSL2?

Коротко: когда тебе нужны Linux-инструменты, когда проект и рабочие файлы уже лежат внутри WSL2 или когда ни один режим нативной песочницы не подошёл. Это три критерия из официальной документации, других причин ставить Linux внутрь Windows у новичка нет. Попал хотя бы в один - ниже порядок установки и два правила, которые экономят часы.

Критерии взяты дословно из страницы про Windows - они приведены выше, в третьем разделе. Если ни один не про тебя, оставайся на нативном пути.

Если про тебя, порядок такой. Сначала ставится сам WSL, командой из документации Microsoft, в PowerShell, запущенном от имени администратора:

wsl --install

Microsoft описывает эту команду так: она включает нужные компоненты и ставит дистрибутив Ubuntu, после чего машину надо перезагрузить. Минимальные требования - Windows 10 версии 2004 (сборка 19041) и новее либо Windows 11.

Дальше момент, который стоит держать в голове. Внутри WSL работает обычный установщик для Linux. PowerShell-скрипт там не нужен:

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

И два правила, которые сэкономят тебе часы:

1. Держи проект внутри домашней папки Linux, например ~/code/my-app. Путь внутри C:\ для этого не годится. Документация прямо предупреждает, что работа через смонтированные windows-пути вида /mnt/c/... медленнее и добавляет проблем с правами и символическими ссылками. Из Проводника эти файлы видны по адресу \\wsl$\Ubuntu\home\<имя>.
2. Нужен именно WSL2. WSL1 поддерживался до версии Codex 0.114; начиная с 0.115 Linux-песочница переехала на bubblewrap, и WSL1 больше не поддерживается.

Почему установка через npm на Windows ломается чаще?

Коротко: для Codex Windows npm-путь добавляет лишний слой и два известных места отказа - платформенный пакет, который может не доехать, и папку глобальных пакетов, которой нет в PATH. Официальному установщику для PowerShell ни npm, ни Node.js не нужны. Идти через npm стоит только тем, у кого Node уже стоит под другие задачи.

Через npm Codex ставится так:

npm install -g @openai/codex

Манифест пакета - это его паспорт с требованиями к системе - указывает Node.js не ниже 16 версии - это единственная цифра, которая подтверждается машинным манифестом пакета. В блогах на этот счёт пишут разное. Актуальная версия пакета на 11 сентября 2026 года - 0.154.0. Свою всегда смотри командой codex --version, а не по статьям в интернете.

Дальше две ловушки именно Windows.

Первая: платформенный бинарник. Сам пакет @openai/codex только запускает настоящую программу, а она приезжает отдельным платформенным пакетом. Если он не доехал, агент не стартует. В трекере это обращение #17432, в нём агент печатает ошибку Missing optional dependency @openai/codex-win32-x64.

Вторая: PATH. Глобальные пакеты npm кладут не codex.exe, а файл-переходник codex.cmd, и лежит он в папке глобальных пакетов npm. Путь к ней показывает npm prefix -g. Если этой папки нет в переменной среды пользователя, терминал будет отвечать, что команда не распознана, хотя пакет установлен.

Отсюда вывод, который я бы держал по умолчанию: на Windows начинай с официального установщика для PowerShell. К npm имеет смысл идти, только если Node.js у тебя уже стоит под другие задачи.

И отдельно - не ставь двумя способами сразу. Тогда в системе оказываются две программы codex, а какая из них запустится, решает порядок путей в PATH. Выглядит это так, будто обновление проходит, но ничего не меняется.

Что делать, если кириллица в консоли превращается в мусор?

Коротко: это не поломка Codex, а кодировка консоли Windows. Классическая PowerShell 5.1, которая идёт в системе по умолчанию, работает не в UTF-8, поэтому русские буквы в выводе и в файлах превращаются в нечитаемые символы. Лечится сменой терминала и латинским путём к проекту.

Тема кодировки в трекере openai/codex всплывает регулярно, отдельными обращениями про UTF-8 в консоли Windows. Корень у всех один: классическая консоль отдаёт текст в однобайтовой кодировке, а агент ждёт UTF-8.

Что помогает по порядку, от простого к сложному:

1. Поставить Терминал Windows и PowerShell 7 вместо классической консоли. Современный терминал работает с UTF-8 без плясок.
2. Держать путь к проекту латиницей. Папка вида C:\Users\Иван\Проекты\Сайт создаёт лишние поводы для сбоя. C:\code\site таких поводов не создаёт.
3. Проверить текущую кодовую страницу консоли командой chcp. Для UTF-8 это 65001.

Соседняя проблема того же рода: агент иногда пробует выполнять команды не из мира Windows - sh, grep и подобные. В трекере на это заведено обращение #316. Если видишь такое, скажи агенту прямым текстом, что у тебя PowerShell на Windows, и он перестроит команды.

Что видишь в терминале и что это значит?

Коротко: я свёл в одну таблицу строки, на которых останавливается установка Codex Windows, и что каждая из них означает. Сверяйся с таблицей прежде, чем сносить всё и ставить заново: почти все эти случаи чинятся точечно, а переустановка чаще всего возвращает ту же самую строку на том же самом шаге.

Пять ошибок установки Codex Windows

Коротко: пять вещей, которые новички делают на Windows и которые стоят больше всего времени. Четыре из пяти лечатся тем, что ты просто не делаешь лишнего: не ставишь WSL без причины, не трогаешь глобальные политики, не тянешь Node.js и не совмещаешь два способа установки в одной системе.

1. Ставить WSL «на всякий случай». Если ты не попадаешь ни под один из трёх критериев из документации, Linux внутри Windows тебе не нужен. Нативный путь официально объявлен путём по умолчанию.
2. Менять глобальную политику выполнения PowerShell на Unrestricted. Не нужно: ключ -ExecutionPolicy ByPass уже вшит в команду установки и действует только на один запуск.
3. Ставить через npm, не имея Node.js. Это лишняя зависимость и два лишних места отказа. Официальный установщик Node не требует.
4. Править PATH только в текущем окне. Строка $env:Path += ... живёт до закрытия окна. Путь прописывается в переменные среды пользователя.
5. Ставить двумя способами сразу. В системе оказываются две программы codex, запускается та, что раньше в PATH, и обновления выглядят как будто не работают.

Что дальше

Коротко: Codex Windows установлен и отвечает - дальше агента стоит научить твоим задачам. Ближайший шаг после установки - скиллы: готовые наборы инструкций, которые агент подхватывает сам и применяет, когда задача под них подходит. Ставятся они отдельно, и на Windows порядок ровно тот же, что и на других системах.

Следующий шаг после установки - научить агента делать что-то полезное руками. У Codex для этого есть плагины и скиллы, они разобраны в статье как поставить скиллы в Codex. Готовые скиллы с инструкциями по установке собраны в каталоге.

Что из этого стоит держать под рукой именно на Windows и чем докручивать агента дальше - собрано в базе знаний ClaudeBase.

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

Источники

• README репозитория openai/codex - команда установки для Windows, вход по аккаунту ChatGPT.
• docs/install.md, репозиторий openai/codex - таблица системных требований со строкой про WSL2, факт про Rust.
• Codex on Windows, документация OpenAI - нативная песочница, матрица версий Windows, режимы elevated и unelevated, ошибка 1385, слэш-команда /sandbox-add-read-dir.
• Sandboxing, документация OpenAI - режимы доступа и политики одобрения.
• Codex CLI, документация OpenAI - установка и команды сессии.
• Манифест пакета @openai/codex, npm registry - версия 0.154.0 и требование Node не ниже 16.
• Codex с WSL, документация OpenAI - критерии выбора WSL2, установка внутрь WSL, домашняя папка и отказ от поддержки WSL1.
• Установка WSL, Microsoft Learn - команда wsl --install, дистрибутив Ubuntu, требования к версии Windows.
• openai/codex, обращение 17432 - ошибка Missing optional dependency @openai/codex-win32-x64 при установке через npm.
• openai/codex, обращение 3927 - Port 127.0.0.1:1455 is already in use.
• openai/codex, обращение 316 - агент пробует выполнить sh в PowerShell.