Windows Usage Guide: Native or WSL
📚 Навигация по серии: Предыдущая статья 〔32 Миграция с Claude Code〕 описала перенос наработок и привычек использования ИИ на платформу Codex. Эта глава создана специально для пользователей операционной системы Windows. В предыдущих тридцати статьях мы по умолчанию предполагали работу в Mac или Linux, но на Windows пути файлов, символы перевода строки и механизмы песочницы устроены иначе. В следующей статье 〔34 Комплексная практика〕 мы объединим все полученные знания о Codex в рамках работы над реальным проектом.
Пример ошибки при первой настройке окружения на Windows.
В марте 2026 года я впервые устанавливал Codex на свой рабочий ноутбук под управлением Windows 11. Чтобы сэкономить время, я отказался от настройки WSL и запустил утилиту прямо в нативном терминале PowerShell. Установка прошла успешно, но при первой же попытке поручить ИИ изменить файлы проекта я столкнулся со сбоем. Проанализировав логи, я обнаружил причину: проект был скачан с Mac через git clone, и все файлы имели символ перевода строки LF. При клонировании на Windows Git автоматически преобразовал их в CRLF. После того как Codex изменил файл и сохранил его, в diff отобразился символ ^M для каждой строки файла. В итоге все строки документа оказались помечены как измененные. Сначала я подумал, что это баг в самом Codex, но проблема заключалась в моем непонимании особенностей работы с переводами строк в Windows.
Нативный запуск Codex на Windows поддерживается в полном объеме, но настройки окружения отличаются от Mac/Linux. Механизмы песочницы в Windows имеют свои особенности, файловые пути используют обратный слэш, а символы перевода строк требуют внимания. Если не учесть эти нюансы заранее, вы обязательно столкнетесь со сбоями.
В этой главе мы разберем правила работы в Windows: способы установки, выбор между нативной средой и WSL2, обход трех критических уязвимостей, особенности работы локальной песочницы и запуск тестовой задачи в PowerShell.
Прочитав эту статью, вы получите:
- Рекомендацию по выбору наиболее стабильного и простого способа запуска Codex в среде Windows
- Пошаговую инструкцию по установке Codex CLI через PowerShell-скрипт и список необходимых зависимостей
- Сравнительный анализ сценариев «Нативный PowerShell vs WSL2» для выбора рабочего окружения
- Решения трех специфических для Windows проблем: обратных слэшей в путях, конфликтов
CRLF-переводов строк и предупреждений о правах группыEveryone - Разбор режимов песочницы
elevatedиunelevatedна Windows и способы устранения ошибки с кодом1385 - Практическое руководство по запуску первой задачи ИИ в PowerShell с проверкой целостности файлов
⚠️ Команды, ключи и настройки систем в этой главе основаны на официальной документации Codex для Windows. Доступные версии утилит и лимиты токенов могут меняться, проверяйте их в выводе справки
codex --helpна вашем компьютере. Все команды в руководстве снабжены пометками о типе терминала (PowerShell или WSL), не путайте их при вводе.
01 Какую среду выбрать для запуска
Сразу к выводу, чтобы сэкономить ваше время на выборе:
По умолчанию используйте схему «Нативный Windows + песочница elevated». Это рекомендуемый разработчиками подход, обеспечивающий максимальную скорость работы и надежную изоляцию. Переходите на WSL2 только в том случае, если вся ваша разработка изначально ведется в среде Linux или на компьютере заблокированы необходимые службы песочницы Windows.
В некоторых устаревших руководствах можно встретить рекомендации «использовать только режим unelevated» или «всегда ставить WSL». Эти советы устарели. В актуальной документации сказано: нативная песочница Windows обеспечивает наилучшую производительность, а режим elevated является основным выбором, тогда как unelevated — лишь запасным вариантом.
Аналогия: подключение интернета. Настройка elevated — это прямое оптоволоконное подключение к вашей квартире (самый быстрый и стабильный способ). Если провайдер не может протянуть кабель из-за ограничений дома, вы подключаете витую пару из коридора (режим unelevated). И только если проводной интернет недоступен в принципе, вы идете работать в соседнее здание, где сеть есть (WSL2). Большинству пользователей оптоволокно доступно сразу, поэтому тратить время на настройку обходных путей не требуется.
Сценарии выбора среды:
- Вы разрабатываете под Windows и используете нативные компиляторы — выбирайте нативный запуск в режиме
elevated. - Рабочий ноутбук контролируется ИТ-отделом, права администратора заблокированы — запустить
elevatedне удастся, используйте режимunelevatedи обратитесь в поддержку для разблокировки служб. - Все проекты компилируются в WSL, вы используете Linux-утилиты — запускайте Codex внутри WSL2, не пытаясь настроить связь между Windows-процессом и Linux-файлами.
💡 Резюме в одном предложении: Для большинства пользователей оптимальным выбором является схема «Нативный Windows +
elevated», а WSL2 необходим только тем, чья разработка изначально ведется внутри Linux-окружения.
02 Установка и зависимости
Для установки Codex CLI на Windows используйте готовый сценарий PowerShell.
Запустите команду в терминале PowerShell или Windows Terminal:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Если на компьютере установлен Node.js, можно выполнить установку через пакетный менеджер npm:
npm install -g @openai/codexПосле завершения установки перезапустите терминал для обновления переменных окружения и проверьте работу:
codex --versionВывод команды должен содержать номер установленной версии Codex CLI.
Если вы предпочитаете графический интерфейс, установите Desktop App Codex из магазина Microsoft Store или выполните команду в консоли:
winget install Codex -s msstore. В этой главе мы рассматриваем работу с консольной версией CLI.
Список необходимых компонентов:
| Компонент | Назначение | Способ установки / требования |
|---|---|---|
| Windows 11 (рекомендуется) | Стабильная платформа для работы песочницы | Обновление системы (на Win 10 требуется сборка 1809 или новее) |
| winget | Пакетный менеджер для установки зависимостей | Поставляется с обновлениями Windows (App Installer) |
| Права администратора | Требуются для инициализации песочницы elevated | Подтверждение запроса UAC при первом запуске |
| C++ Build Tools | Компиляция бинарных зависимостей плагина IDE | Установка через winget: winget install --id Microsoft.VisualStudio.2022.BuildTools -e |
Если вы планируете использовать плагин Codex для VS Code, обязательно установите Visual Studio Build Tools с поддержкой компилятора C++. Без этого компонента плагин может зависать на этапе инициализации из-за невозможности скомпилировать локальные бинарные модули.
💡 Резюме в одном предложении: Установка Codex CLI на Windows выполняется в одну строку через PowerShell-скрипт. Убедитесь в наличии прав администратора и установите C++ Build Tools при использовании плагина для IDE.
03 Выбор между нативным PowerShell и WSL2
Выбор среды запуска должен опираться на особенности ваших рабочих проектов.
Аналогия: выбор места регистрации бизнеса. Нативный PowerShell — это открытие офиса в вашей стране. Все процессы идут по местным законам, у вас есть прямой доступ ко всем службам. WSL2 — это открытие филиала за рубежом (внутри виртуальной машины Linux). Если все производство завязано на иностранное оборудование (Linux-утилиты), вам проще работать там. Но переносить документы между офисами каждый день неудобно — выберите одну основную рабочую зону.
Сравнение окружений:
| Критерий | Нативный PowerShell | WSL2 |
|---|---|---|
| Сложность настройки | Минимальная, установка в один шаг | Требуется установка WSL и дистрибутива Linux |
| Производительность | Максимальная нативная скорость | Ниже при работе с файлами за пределами Linux-диска |
| Песочница | Специальные службы Windows | Механизм bubblewrap ОС Linux |
| Инструменты | Поддержка .exe файлов Windows | Нативная поддержка bash-скриптов и утилит Linux |
| Рекомендовано для | Большинства разработчиков | Проектов, скомпилированных под Linux |
При работе в WSL2 устанавливайте Codex внутри Linux-системы, а не вызывайте Windows-версию утилиты.
Для установки WSL2 запустите в PowerShell с правами администратора:
wsl --install
wslВнутри открывшегося Linux-терминала выполните установку Codex:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codexКритически важное правило производительности в WSL2: не размещайте файлы проектов в папках общего доступа Windows (например, в каталогах /mnt/c/Users/...). Обращение к файлам Windows из виртуальной машины Linux происходит крайне медленно. Перенесите проекты в домашнюю директорию Linux:
mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repoДля редактирования файлов в Linux-окружении из проводника Windows используйте сетевой путь \\wsl$\Ubuntu\home\<имя_пользователя>. Поддержка устаревшей версии WSL1 в Codex прекращена начиная с версии 0.115 в связи с переходом на систему изоляции bubblewrap.
💡 Резюме в одном предложении: Используйте нативный PowerShell для проектов Windows и WSL2 — для проектов Linux, размещая файлы строго внутри файловой системы Linux для сохранения скорости дисковых операций.
04 Три типичные проблемы Windows: пути, переводы строк и права
Разберем особенности настройки Windows, которые могут вызывать сбои при работе с Codex.
1. Символы обратного слэша в путях файлов
В Windows пути разделяются обратным слэшем (C:\Users\User\project), а в UNIX-системах — прямым слэшем. Codex автоматически сопоставляет форматы, но при ручном редактировании настроек соблюдайте правила:
- В файле конфигурации
~/.codex/config.tomlвсегда указывайте полные абсолютные пути. - При добавлении папок в список разрешенных для чтения в песочнице используйте команду в чате (папка должна реально существовать на диске):
/sandbox-add-read-dir C:\absolute\directory\pathЭта настройка действует только в рамках текущей сессии.
2. Конфликты символов перевода строк (CRLF vs LF)
Эта проблема часто возникает при совместной работе над проектом разработчиков на Windows и Mac. В UNIX используется перевод строки LF, а в Windows — CRLF (с добавлением символа возврата каретки \r). При клонировании репозитория Git на Windows может автоматически переписать переводы строк, из-за чего Codex при сохранении изменений покажет модификацию всего файла.
Для решения этой проблемы добавьте в корень проекта файл .gitattributes со строкой:
* text=auto eol=lfИли отключите автоконвертацию глобально в настройках Git на вашем компьютере:
git config --global core.autocrlf falseЭто предотвратит появление лишнего шума в diff изменений.
3. Предупреждения о правах доступа группы Everyone
Если при запуске Codex сообщает о небезопасных правах доступа к папкам проекта со стороны группы Everyone (Все), это означает, что настройки безопасности Windows позволяют любому пользователю системы изменять файлы. Ограничьте права доступа к папке проекта в свойствах безопасности Windows, убрав разрешения на запись для группы Everyone, и перезапустите Codex.
Сводная таблица решений проблем:
| Проблема | Симптомы | Решение |
|---|---|---|
| Обратные слэши | Не применяются пути в конфигурациях | Указывать абсолютные пути, папки для /sandbox-add-read-dir должны существовать |
| Переводы строк CRLF | Весь файл помечен как измененный, символы ^M в diff | Настройка .gitattributes или отключение core.autocrlf в Git |
| Группа Everyone | Предупреждение безопасности при старте | Ограничение прав на запись для группы Everyone в свойствах папки |
💡 Резюме в одном предложении: Задавайте абсолютные пути в конфигурациях, блокируйте автоконвертацию перевода строк через
.gitattributesи ограничивайте права группыEveryoneдля папок проекта.
05 Механизмы песочницы на Windows
Система изоляции Codex на Windows имеет собственную архитектуру, отличную от систем Apple Sandbox и Linux namespaces.
Вы можете переключать режимы песочницы в конфигурационном файле ~/.codex/config.toml:
[windows]
sandbox = "elevated" # или "unelevated"Сравнение режимов песочницы Windows:
| Режим | Уровень защиты | Реализация в системе | Сфера применения |
|---|---|---|---|
elevated (основной) | Максимальный | Использование выделенного локального пользователя, правил брандмауэра и групповых политик | Рекомендуется для всех систем. Максимальная безопасность |
unelevated (запасной) | Базовый | Ограничение токена текущего пользователя, настройка списков доступа ACL | Используется при блокировке создания пользователей политиками IT |
Разработчики рекомендуют использовать режим elevated. Режим unelevated является резервным для систем, где учетная запись пользователя заблокирована от выполнения административных действий. По умолчанию оба режима используют изоляцию рабочего стола (Private Desktop), не отключайте параметр windows.sandbox_private_desktop без явной необходимости совместимости со старыми станциями окон Winsta0\Default.
Решение ошибки с кодом 1385
При запуске в режиме elevated на корпоративных компьютерах может возникнуть ошибка авторизации с кодом 1385 (Вход в систему не произведен: выбранный режим входа не предоставлен пользователю на этом компьютере). Это означает, что групповые политики вашей компании запрещают созданному песочницей пользователю авторизоваться в системе.
Для решения этой проблемы:
- Обратитесь к администраторам ИТ-отдела для предоставления прав авторизации локальному пользователю Codex.
- В качестве временного решения переключите режим песочницы на
unelevatedв конфигурационном файле. - Логи ошибок для анализа ИТ-специалистами можно найти в файле
CODEX_HOME/.sandbox/sandbox.log.
⚠️ Важно: при отправке логов для анализа никогда не копируйте содержимое папки
CODEX_HOME/.sandbox-secrets/, так как в ней хранятся приватные ключи шифрования вашей сессии.
При блокировке доступа к внешним папкам в песочнице используйте команду /sandbox-add-read-dir для добавления директорий в список разрешенных.
💡 Резюме в одном предложении: Песочница на Windows работает в режимах
elevated(основной) илиunelevated(резервный). Ошибка с кодом1385вызвана ограничениями прав пользователей в групповых политиках компании, для её обхода временно переключитесь в режимunelevated.
06 Практический тест: первый запуск на Windows
Пройдем шаги настройки проекта и внесения изменений через Codex в консоли PowerShell.
Шаг 1: Создание проекта в PowerShell
mkdir codex-win-test
cd codex-win-test
git init
"console.log('hi')" | Out-File -Encoding utf8 app.jsПри использовании старых версий PowerShell (5.1) команда Out-File может добавить BOM-символ в начало файла. В PowerShell 7+ для создания чистых файлов без BOM используйте команду Set-Content -Encoding utf8NoBOM.
Шаг 2: Настройка правил перевода строк
Создайте файл .gitattributes в корне папки с текстом:
* text=auto eol=lfШаг 3: Запуск Codex
codexПри первом запуске песочницы elevated операционная система может запросить права администратора через окно UAC. Нажмите «Да» для завершения настройки. Если права заблокированы, Codex выдаст предупреждение и переключит песочницу в режим unelevated.
Шаг 4: Постановка задачи ИИ
В интерактивном окне введите команду:
Замени 'hi' на 'hello, codex on windows' в файле app.jsОжидаемый результат: Codex проанализирует файл, выведет diff изменений и запросит подтверждение на запись. После вашего согласия изменения будут внесены.
Проверьте содержимое файла:
Get-Content app.jsВывод должен содержать измененную строку console.log('hello, codex on windows').
Шаг 5: Проверка diff в Git
Выйдите из сессии Codex и запустите проверку изменений:
git diffОжидаемый результат: В выводе diff должна быть только одна строка изменения. Отсутствие символов ^M и предупреждений об изменении всего файла подтверждает правильную настройку перевода строк.
💡 Резюме в одном предложении: Практический тест включает шаги: создание тестовой папки → добавление
.gitattributes→ инициализация сессии Codex с принятием UAC-прав → внесение изменений в файл → проверка diff на отсутствие мусорных символов перевода строк.
Итоги
Мы разобрали правила настройки рабочего окружения Codex на операционной системе Windows.
Ключевые выводы главы:
| Параметр | Описание | Решение |
|---|---|---|
| Рекомендуемая среда | Нативный Windows | Оптимален по скорости и уровню безопасности |
| Резервная среда | WSL2 (Linux) | Используется, если проект компилируется под Linux |
| Установка CLI | Скрипт PowerShell | Выполняется одной командой в терминале |
| Конфликт переводов строк | Мусорные символы в diff | Настройка .gitattributes с фиксацией eol=lf |
| Песочница Windows | Режимы elevated/unelevated | По умолчанию elevated. При ошибке 1385 переключите на unelevated |
| Права доступа | Ошибки чтения файлов в песочнице | Добавление папок через /sandbox-add-read-dir |
Теперь вы умеете:
- Устанавливать и проверять Codex CLI на операционной системе Windows.
- Выбирать между нативным запуском в PowerShell и виртуальным окружением WSL2.
- Устранять проблемы с переводами строк и путями файлов при совместной работе.
- Настраивать режимы песочницы и обходить ошибки авторизации локального пользователя.
- Запускать задачи и проверять чистоту внесенных ИИ изменений с помощью Git.
Правильная настройка окружения на Windows обеспечивает надежную и быструю работу Codex с файлами ваших проектов.
В следующей статье 34 · Комплексная практика мы перейдем к финальному практическому проекту. Мы применим все полученные знания на практике: от настройки правил AGENTS.md до разработки функционала и автоматического исправления ошибок в коде реального приложения.