Codex CLI: первый запуск за 20 минут
Коротко
Codex CLI ставится одной командой: curl -fsSL https://chatgpt.com/codex/install.sh | sh на macOS и Linux, powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" на Windows. Есть и пакетные менеджеры: npm install -g @openai/codex или brew install --cask codex. Дальше запускаете codex в папке проекта и выбираете способ входа: аккаунт ChatGPT (Plus, Pro, Business, Edu, Enterprise) либо ключ OpenAI API. Ключ передаётся только через stdin: printenv OPENAI_API_KEY | codex login --with-api-key — старый флаг --api-key больше не принимается. Проверить вход — codex login status, посмотреть остаток лимита — /usage внутри сессии.
Узкое место для России: страны нет в списке поддерживаемых OpenAI, поэтому и подписка ChatGPT, и API-ключ упираются в оплату и регион. Рабочих путей три — зарубежная карта, посредник-реселлер или полный отказ от облака: codex --oss поднимает агента на локальной модели через Ollama или LM Studio, по умолчанию gpt-oss:20b. Первый коммит Codex за вас не сделает: он покажет diff, а git commit вы пишете сами.
В чём задача
Установить Codex CLI просто. Дойти до момента, когда он реально правит ваш код и вы не боитесь нажать Enter, — сложнее. Между этими точками три развилки, на которых люди застревают:
- Чем платить. Codex не работает анонимно: нужен либо аккаунт ChatGPT с подпиской, либо ключ API с балансом. Из России ни то ни другое не оформляется в лоб.
- Какие права дать. По умолчанию агент спрашивает разрешение на команды. Люди в первый же час выключают все подтверждения, получают снесённую ветку и удаляют инструмент.
- Что считать результатом. Codex меняет файлы на диске, но не коммитит. Если не проверить diff, в репозиторий уедет мусор.
Ниже — маршрут, который закрывает все три. Он написан под версию 0.145.0 (опубликована 21 июля 2026 года в npm-пакете @openai/codex), лицензия Apache-2.0. Все команды и флаги сверены с исходниками и документацией репозитория — русскоязычные гайды заметно отстают от релизов, и ниже видно, где именно.
Пошагово
Шаг 0. Проверьте, что система тянет. Документация репозитория требует macOS 12+, Ubuntu 20.04+/Debian 10+ или Windows 11 через WSL2, минимум 4 ГБ RAM (рекомендуется 8) и Git 2.23+ для встроенных PR-хелперов. Codex написан на Rust, Node.js для standalone-установщика не нужен вовсе; npm-пакет требует Node >= 16.
Шаг 1. Установка. Самый простой путь — официальный установщик:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Он тянет бинарь с releases.openai.com и откатывается на GitHub Releases, если метаданные недоступны. Принудительно переключиться на GitHub:
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh
Через npm — только с префиксом организации:
npm install -g @openai/codex
Пакет codex без @openai/ — это генератор статических сайтов 2012 года (последняя версия 0.2.3 от 7 мая 2012-го, по данным npm registry). Ошибка стоит получаса недоумения.
Шаг 2. Вход. Запустите codex в папке проекта — откроется TUI и предложит выбрать способ входа. Вариант «Sign in with ChatGPT» открывает браузер и привязывает CLI к подписке. Вариант с ключом настраивается отдельно:
printenv OPENAI_API_KEY | codex login --with-api-key
Ключ читается из stdin намеренно: так он не попадает в историю команд. Флаг --api-key <ключ> в текущих версиях удалён — при попытке использовать его CLI выводит подсказку с правильной формой.
Проверка:
codex login status
Ответ будет одним из: Logged in using ChatGPT, Logged in using an API key, Logged in using access token. Выйти — codex logout.
Шаг 3. Права. Разберитесь с песочницей до первой задачи, а не после. Флаг --sandbox (-s) принимает три значения:
| Режим | Что можно агенту | Когда включать |
|---|---|---|
read-only |
читать файлы, ничего не менять | первое знакомство, чужой репозиторий, аудит кода |
workspace-write |
писать в рабочую папку, запускать команды в ней | обычная работа по задаче |
danger-full-access |
всё, без ограничений | только в одноразовом контейнере |
Отдельно живёт --dangerously-bypass-approvals-and-sandbox: он одновременно снимает подтверждения и ставит danger-full-access. Название честное — относитесь к нему буквально.
Флаг --full-auto, который до сих пор кочует по русскоязычным гайдам, объявлен устаревшим: CLI отвечает warning: --full-auto is deprecated; use --sandbox workspace-write instead. Если инструкция советует --full-auto, она написана по старой версии — и остальное в ней тоже стоит перепроверить.
Шаг 4. Контекст проекта. Внутри сессии выполните /init — команда создаёт AGENTS.md с инструкциями для агента: как собирать проект, какие команды тестов, чего не трогать. Это тот же жанр, что CLAUDE.md у соседнего инструмента; сравнение двух подходов есть в разборе Claude Code против Codex.
Шаг 5. Первая задача и первый коммит. Дайте узкую формулировку: «добавь обработку пустого ответа в api/client.ts, тесты не трогай». Дальше:
/diff # git diff, включая неотслеживаемые файлы
/review # агент сам ищет проблемы в своих же правках
И только потом — руками:
git add -p
git commit -m "fix: пустой ответ в api/client"
Codex не коммитит сам и не пушит. Это правильно: агент, у которого есть право на git push, — это агент, который может испортить общую ветку.
Проверка результата
Пять команд, которые говорят, что всё встало как надо:
| Команда | Где выполнять | Что должно быть в ответе |
|---|---|---|
codex --version |
терминал | номер версии, без ошибок PATH |
codex login status |
терминал | строка Logged in using ... |
/status |
сессия | текущая модель, режим песочницы, расход токенов |
/usage |
сессия | остаток лимита и время сброса |
/model |
сессия | список моделей и уровней reasoning |
Если codex --version отвечает «command not found», проблема почти всегда в PATH: установщик кладёт бинарь в пользовательскую папку, которая не подхватилась текущей оболочкой. Перезапустите терминал.
Если сессия ведёт себя странно и нужны логи, задайте каталог явно:
codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
Состояние Codex по умолчанию лежит в ~/.codex (config.toml, логи), путь переопределяется переменной CODEX_HOME.
Подводные камни
Оплата из России. России нет в официальном списке поддерживаемых стран OpenAI — он опубликован в справке OpenAI. Практических следствий три: карта РФ не пройдёт, аккаунт может быть заблокирован за доступ из неподдерживаемого региона, а деньги на балансе при блокировке не возвращаются автоматически. Варианты и их цена:
| Путь | Что нужно | Риск | Кому подходит |
|---|---|---|---|
| Зарубежная карта + свой доступ | карта, стабильный адрес, аккуратность | блокировка при рассинхроне региона | тем, у кого карта уже есть |
| Реселлер / прокси-API | оплата рублями, чужой ключ | ключ и код проходят через третью сторону; условия могут поменяться в любой день | быстрый старт, некритичный код |
| Локальная модель | 16+ ГБ RAM, Ollama или LM Studio | заметно слабее облачных моделей | закрытый код, отсутствие оплаты |
Третий путь встроен в сам CLI:
codex --oss # локальный провайдер, модель gpt-oss:20b
codex --oss --local-provider ollama -m gpt-oss:20b
Ollama по умолчанию слушает http://localhost:11434; при первом запуске Codex предложит скачать модель. Честно: 20b-модель на ноутбуке справляется с правкой одного файла и объяснением кода, но не с рефакторингом на десять файлов. Ждать паритета с облаком не стоит — это инструмент для случая «код нельзя выпускать наружу» или «платить нечем».
Про оплату соседнего стека — какие способы работают и какие отваливаются — отдельно разобрано в статье про Claude API из России.
Лимиты. Расход CLI, веба и IDE-расширения идёт из общего лимита вашего плана: скользящее окно на несколько часов плюс недельный потолок. Точных цифр в этой статье нет намеренно — OpenAI меняет их вместе с релизами моделей, и любая табличка устареет за месяц. Смотрите две вещи: страницу тарифов Codex и команду /usage, которая показывает ваш фактический остаток и время сброса.
Ключ утечёт быстрее, чем вы думаете. Ключ, вписанный в .zshrc и закоммиченный вместе с дотфайлами, — самый частый способ его потерять. Базовая гигиена секретов разобрана в памятке про API-ключи.
Windows без WSL2. Установщик отработает, но поддерживаемая конфигурация — Windows 11 через WSL2. На чистом Windows часть команд песочницы ведёт себя иначе; если что-то отваливается непредсказуемо, первым делом переезжайте в WSL.
Codex — не единственный, и не всегда лучший. Что именно он умеет и где проигрывает конкурентам, разбирается в обзоре OpenAI Codex.
Частые вопросы
Нужен ли Node.js для Codex CLI?
Для официального установщика — нет: он ставит готовый бинарь, собранный на Rust. Node.js нужен только если вы ставите через npm-пакет @openai/codex; там в engines указано node >= 16. Homebrew-вариант (brew install --cask codex) тоже обходится без Node.
Можно ли пользоваться Codex без подписки ChatGPT?
Да, двумя способами. Первый — ключ OpenAI API с оплатой по факту потребления: printenv OPENAI_API_KEY | codex login --with-api-key. Второй — полностью локально, codex --oss, без аккаунта OpenAI вообще. Второй способ бесплатен, но качество модели на порядок ниже, и тяжёлые задачи она не вытянет.
Что делать, если Codex удалил нужные файлы?
Восстановить из git — поэтому первое правило: не запускать агента в папке без инициализированного репозитория. Если репозиторий есть, git checkout -- <файл> или git stash вернут состояние. Чтобы такого не повторялось, работайте в --sandbox workspace-write и не отключайте подтверждения на разрушающие команды.
Как посмотреть, сколько лимита осталось?
Внутри сессии — /usage: команда показывает расход по аккаунту и время сброса ограничения. Смежная /status выводит конфигурацию текущей сессии, включая модель, режим песочницы и потраченные токены. Обе работают одинаково для подписки и для API-ключа, но при работе по ключу основной ориентир — баланс в личном кабинете OpenAI.
Чем AGENTS.md отличается от обычного README?
README пишут для человека, AGENTS.md — для агента: там короткие императивные правила (какой командой собирать, что запускать перед коммитом, какие каталоги не трогать). Файл создаётся командой /init и подхватывается автоматически при старте сессии в этой папке. Чем конкретнее правила, тем меньше агент импровизирует.