Codex CLI: установка, первый запуск и работа с проектом

Codex CLI — помощник OpenAI, который работает в терминале рядом с файлами проекта. Ему можно поручить разобраться в репозитории, исправить небольшую ошибку и запустить проверку. Чтобы первый запуск оказался полезным, нужны три вещи: подходящий способ входа, понятные границы доступа и задача, результат которой легко проверить.

Ниже — путь от установки до первого просмотренного diff. Команды и возможности сверены с официальной документацией на 1 ноября 2026 года. Название модели специально не закрепляем: доступные варианты и настройки аккаунта могут меняться независимо от самого CLI.

Что Codex CLI делает в проекте

Обычному чату приходится передавать код вручную. CLI запускается в рабочей папке: агент может читать доступные файлы, находить связанные участки, предлагать изменения и выполнять команды в пределах разрешений. Поэтому объяснение ошибки и её исправление превращаются в одну последовательность действий.

Это удобно для небольших задач с ясным окончанием: добавить проверку входного значения, найти причину падения теста, объяснить незнакомый модуль. Запрос «переделай весь сайт» оставляет слишком много решений агенту. Для первого знакомства лучше выбрать изменение в одном файле и заранее записать ожидаемое поведение.

Если вы пока выбираете среду, посмотрите сравнение Cursor, Claude Code и Copilot. Здесь разберём именно работу через терминал: установку, доступ к проекту и контроль результата.

Установка: выбираем один способ

В официальной инструкции есть отдельные установщики для Windows и macOS/Linux, пакет npm и вариант Homebrew для macOS. Для разработчика с уже установленными Node.js и npm понятный общий путь — глобальный пакет:

npm install -g @openai/codex

Эта же команда обновляет npm-установку. Перед запуском убедитесь, что терминал видит npm: команда npm --version должна вернуть номер версии. Если npm отсутствует, используйте соответствующий вашей системе установщик из официальной инструкции Codex CLI. Установщик и пакет npm — альтернативные способы; применять их все подряд не нужно.

После установки откройте новый терминал и выполните codex --version. Если команда не найдена, сначала проверьте завершение установки и PATH — список каталогов, в которых оболочка ищет программы. Повторная установка несколькими способами затрудняет диагностику: в системе могут оказаться разные копии CLI.

На Windows доступен нативный запуск, поэтому WSL не является обязательным условием. Но возможности песочницы зависят от версии Windows, конфигурации устройства и правил организации. Если настройка защиты не проходит, воспользуйтесь инструкцией по Windows sandbox. Отключать ограничения ради завершения установки — плохой способ устранить причину ошибки.

Вход через ChatGPT или API

При первом запуске Codex предложит авторизацию. Для локальной работы предусмотрены вход с аккаунтом ChatGPT и вход по API-ключу; конкретные варианты могут ограничиваться политиками рабочего пространства. Вход через ChatGPT открывает браузер, после подтверждения CLI получает данные для сессии.

Это два разных способа оплаты. Вход с ChatGPT использует доступ и лимиты соответствующего плана. API-ключ связан с учётом использования в OpenAI Platform: наличие подписки ChatGPT само по себе не означает оплаченный баланс API. Перед выбором проверьте, какой вариант доступен вашему аккаунту; текущие условия приведены в документации по авторизации.

Ключ не нужно вставлять в промпт, AGENTS.md или файл с исходным кодом. Для него предназначен отдельный процесс авторизации. Секрет в репозитории может попасть в историю Git и в контекст дальнейших задач. Для учебного запуска удобнее начать со входа через браузер, если этот способ доступен.

Первый запуск — сначала чтение

Откройте терминал в небольшой тестовой копии проекта. Перед работой выполните git status: важно понимать, какие изменения уже существовали. Если Git ещё не используется, сделайте резервную копию. Контрольная точка нужна для сравнения и отката, а не только на случай сбоя программы.

cd my-project
codex --sandbox read-only --ask-for-approval on-request

Режим read-only ограничивает запись в файловую систему. Политика on-request отдельно определяет запрос расширенных разрешений. Это не обещание «никаких команд»: разрешённые операции чтения и команды в песочнице могут выполняться. Сеть и дополнительные действия зависят от действующей конфигурации и правил организации.

Посмотри структуру проекта и файл package.json. Объясни, как запускается приложение и какие проверки уже предусмотрены. Пока ничего не меняй, зависимости не устанавливай, сетевые запросы не выполняй. Укажи файлы, на которых основан ответ.

Проверьте, что агент назвал реально существующие файлы и команды. Если тестов нет, полезный результат — прямо сказать об этом. Придуманная команда проверки хуже честного сообщения, что её ещё нужно выбрать. Такой пробный проход показывает, правильно ли открыта папка и хватает ли контекста.

AGENTS.md: короткие правила для репозитория

Файл AGENTS.md помогает сохранить повторяющиеся инструкции: структуру проекта, допустимые команды, ограничения изменений. Codex читает такие инструкции перед работой; более близкие к текущей папке правила уточняют общие. Для старта достаточно файла в корне репозитория:

# Правила проекта
- Сначала объясняй причину ошибки и план изменения.
- Не меняй зависимости без отдельного согласования.
- Не открывай файлы с секретами.
- Исправляй только файлы, относящиеся к задаче.
- В отчёте указывай выполненные проверки и их результат.

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

Текстовые правила дополняют песочницу, но не заменяют её. Запись «не трогай секреты» помогает направить поведение, однако доступ к файлам задаётся разрешениями среды. Основные риски и границы доступа разобраны в статье о безопасности ИИ-агентов.

Первая правка: один файл и явные условия

Для редактирования можно завершить ознакомительную сессию и запустить CLI с записью в рабочую папку:

codex --sandbox workspace-write --ask-for-approval on-request

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

Найди функцию расчёта числа страниц. Для нулевого количества записей она должна возвращать 0; для 21 записи при размере страницы 10 — 3. Сохрани остальное поведение. Сначала покажи план. Измени только нужную функцию и существующий тест, если он есть. Не добавляй библиотеки. После правки запусти подходящую проверку и приведи результат.

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

Как принять результат и продолжить работу

Сначала посмотрите git diff и git status. Совпадает ли список файлов с заданием? Не появились ли изменения конфигурации, форматирование всего проекта или новая зависимость? Затем проверьте вывод теста: сообщение «готово» не заменяет команду, код завершения и объяснение результата.

Для дополнительного просмотра есть команда /review. В CLI можно выбрать проверку незакоммиченных изменений, коммита или сравнения с базовой веткой. Режим ревью анализирует код и сообщает замечания, а исправления нужно поручить отдельно. Это второй взгляд того же класса инструмента, поэтому ручной просмотр важного участка всё равно нужен.

Если результат не подходит, сформулируйте конкретное замечание: «изменение затронуло сортировку, хотя требовалась только пустая выдача». Для следующей задачи сохраните принятую контрольную точку Git. Не откатывайте весь репозиторий одной командой, если в нём остались ваши собственные изменения.

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