Как работать с Codex: полное руководство по OpenAI Codex CLI

Codex — это AI-агент от OpenAI, который работает прямо в терминале компьютера и умеет писать, читать и редактировать код самостоятельно. Codex CLI — это open-source кодинг-агент, написанный на Rust, который запускается в терминале и работает с локальной кодовой базой.

В отличие от обычного чат-бота, которому нужно вручную копировать код туда-обратно, Codex видит файлы вашего проекта, может запускать команды в терминале, исправлять ошибки, писать тесты и делать коммиты в git — всё это по текстовому запросу на естественном языке.

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

## Чем Codex CLI отличается от старого Codex 2021 года

Важное уточнение для тех, кто помнит более раннюю историю. В 2021 году OpenAI выпустила модель Codex как версию GPT-3, дообученную на коде — она лежала в основе раннего GitHub Copilot и работала через автодополнение в редакторе.

Современный Codex CLI — это совершенно другой продукт. Это полноценный автономный агент 2025-2026 года, который:

• работает в терминале, а не как автодополнение в редакторе
• может выполнять цепочки действий: прочитать → проанализировать → изменить → протестировать → закоммитить
• использует современные модели семейства GPT-5 (GPT-5.3-Codex, GPT-5.4 и новее)
• поддерживает песочницы (sandbox), политики одобрения действий, MCP-серверы и кастомные инструкции

Когда в 2026 году говорят «Codex» в контексте разработки — почти всегда имеют в виду именно агента, а не модель автодополнения 2021 года.

## Где доступен Codex: три способа использования

Codex доступен в нескольких форматах, и важно понимать разницу между ними.

### 1. Codex CLI — терминальный клиент

Основной инструмент для разработчиков, работающих в командной строке. Устанавливается через npm и запускается прямо из терминала любой операционной системы.

### 2. Codex в браузере (chatgpt.com/codex)

Облачная версия — открываете chatgpt.com/codex в браузере, подключаете GitHub-репозиторий и работаете без локальной установки. Подходит когда нет возможности или желания ставить что-то на компьютер.

### 3. Расширение для VS Code

Устанавливается из маркетплейса VS Code и работает прямо в привычной среде разработки. Также работает в редакторах на основе VS Code — Cursor и Windsurf.

### 4. Десктопное приложение

Изначально приложение Codex Desktop вышло для macOS, а в марте 2026 года OpenAI добавила поддержку Windows. Скачивается с официального сайта OpenAI.

В этой статье фокус на Codex CLI — он наиболее функционален и чаще всего используется для серьёзной работы.

## Как установить Codex CLI: пошаговая инструкция

### Шаг 1. Проверьте версию Node.js

Для установки через npm нужен Node.js версии 22 или выше. Проверить текущую версию:

node --version

Если версия ниже 22 — обновите Node.js перед установкой.

### Шаг 2. Установите Codex через npm

npm i -g @openai/codex

Самая частая ошибка при установке — написать npm i -g codex вместо полного имени пакета @openai/codex. Это разные пакеты, и неправильное имя приведёт к установке не того, что нужно.

### Шаг 3. Запустите и авторизуйтесь

codex

При первом запуске откроется браузер с авторизацией через ChatGPT-аккаунт. После входа Codex привязывается к вашему тарифному плану ChatGPT.

### Альтернатива: установка через API-ключ

Если вы хотите использовать Codex через API вместо подписки ChatGPT, задайте переменную окружения:

export OPENAI_API_KEY="sk-..."

Чтобы сохранить настройку постоянно — создайте файл .env в корневой директории проекта:

OPENAI_API_KEY=sk-...

## Первый запуск: как задать задачу

Самый простой способ — запустить Codex и написать задачу на естественном языке:

codex

После запуска в интерактивном режиме просто опишите, что нужно сделать:

исправь все места, где функция не обрабатывает ошибки, и добавь try-catch

Для одноразовых команд без интерактивного режима используется codex exec:

codex exec "обнови changelog на основе последнего diff"
codex e "запусти тесты и исправь все упавшие"

codex e — это сокращённая форма команды codex exec.

## Режимы автономности: read-only, auto-edit, full-auto

Один из ключевых вопросов при работе с Codex — сколько свободы давать агенту. Есть три основных уровня:

read-only (только чтение) — агент анализирует код, отвечает на вопросы, предлагает изменения, но ничего не меняет сам. Безопасный режим для первого знакомства или для анализа незнакомого проекта.

auto-edit (авторедактирование) — Codex сам редактирует файлы, но не запускает команды в терминале. Можно запустить задачу и проверить результат позже.

full-auto (полная автономия) — Codex пишет код, запускает тесты, исправляет ошибки самостоятельно, без подтверждения каждого шага.

Важная рекомендация по безопасности: full-auto режим стоит использовать на отдельной ветке git, а не на основной (main) ветке — чтобы можно было легко откатить изменения, если агент сделает что-то не то.

## Безопасность Codex: песочница и политика одобрения

Поскольку агент сам запускает команды и правит файлы, важно понимать, что именно ему разрешено делать. Безопасность Codex строится на двух независимых уровнях.

### Уровень 1. Sandbox (песочница) — что агент может технически

Песочница определяет, к каким файлам и сетевым ресурсам у агента вообще есть доступ на уровне операционной системы. Codex использует нативную песочницу ОС: Seatbelt на macOS и Bubblewrap на Linux — это системные механизмы изоляции, которые безопасно ограничивают выполнение команд.

Основные режимы песочницы:

### Уровень 2. Approval Policy (политика одобрения) — когда агент обязан спросить разрешение

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

### Рекомендуемая комбинация для повседневной работы

Связка approval_policy = "on-request" и sandbox_mode = "workspace-write" рекомендуется как разумный баланс по умолчанию: чтение свободное, запись только в проект, опасные команды требуют подтверждения.

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Для автоматизированных pipeline (например, в CI/CD) часто используется отдельный профиль с approval_policy = "never" — но без подтверждений агент работает полностью самостоятельно, поэтому такой режим стоит применять только в контролируемой среде с дополнительными ограничениями.

## Файл AGENTS.md — инструкции для проекта

AGENTS.md — это эквивалент CLAUDE.md из мира Claude Code, применительно к Codex. Это файл с инструкциями для конкретного проекта, который Codex загружает в начале каждой сессии.

Пример содержимого AGENTS.md:

# My Project

## Build Commands
- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint -- --fix`

## Rules
- Используй TypeScript strict mode для всех новых файлов
- Пиши unit-тесты для каждой новой функции
- Никогда не делай коммит напрямую в ветку main
- Все API-эндпоинты должны иметь документацию OpenAPI

Сгенерировать AGENTS.md автоматически на основе анализа вашего проекта можно командой:

/init

Codex проанализирует структуру проекта, определит используемые команды сборки, тестирования и линтинга, и создаст базовый файл инструкций.

## Slash-команды: быстрые действия в сессии

Внутри интерактивной сессии Codex доступны специальные команды, начинающиеся с /. Вот основные:

/model — переключить используемую модель прямо посреди сессии. Полезно перед сложной задачей переключиться на более мощную модель.

/plan — попросить Codex составить план перед тем как вносить правки в несколько файлов. Хорошая практика для крупных изменений: сначала план, затем — после вашего согласия — исполнение.

/diff — посмотреть изменения, которые Codex внёс или собирается внести, перед тем как их зафиксировать.

/review — запустить код-ревью изменений.

/compact — сжать контекст в долгой сессии. Когда диалог становится слишком длинным и агент начинает терять часть контекста, эта команда суммаризирует историю и освобождает место.

/init — автоматически сгенерировать файл AGENTS.md на основе анализа проекта.

### Управление уровнем рассуждений на лету

Если нужно повысить или понизить «глубину размышлений» модели прямо во время сессии, не перезапуская её — используются комбинации клавиш Alt+, и Alt+. для понижения и повышения уровня reasoning effort.

## Конфигурация: файл config.toml

Codex использует конфигурационные файлы в формате TOML. Основной файл находится по пути ~/.codex/config.toml.

### Иерархия конфигурации

Настройки применяются по следующему приоритету — от высшего к низшему:

1. Флаги командной строки
2. Значения профиля
3. Конфигурация проекта (.codex/config.toml)
4. Пользовательская конфигурация (~/.codex/config.toml)
5. Системная конфигурация (/etc/codex/config.toml)
6. Значения по умолчанию

То есть флаг, переданный напрямую в команде, всегда перебивает любые настройки из файлов.

### Пример базового config.toml

# Модель и режим рассуждений
model = "gpt-5.4"
model_reasoning_effort = "high"

# Настройки безопасности по умолчанию
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Личность агента
personality = "pragmatic"

# Веб-поиск
web_search = "cached"

# Производительность
service_tier = "fast"

### Профили: разные настройки для разных задач

Профиль — это именованный набор настроек (модель, sandbox, approval, MCP), который активируется одной командой. Профили — ключевая особенность конфигурации Codex CLI: команды, использующие Codex в продакшене, обычно настраивают как минимум два профиля, выбирают режим песочницы под конкретную нагрузку и подключают хотя бы один MCP-сервер.

Активация профиля происходит явно — либо флагом в командной строке, либо через переменную окружения:

codex --profile dev
# или
CODEX_PROFILE=ci codex

Лучшая практика именования — называть профили по средам (dev, ci, prod, agent), а не по людям или конкретным проектам. Профили, названные в честь людей (alice, bob) плохо масштабируются на команду; профили, названные в честь конкретных задач (migration, refactor-2026), быстро устаревают.

Пример профиля для CI:

[profiles.ci]
approval_policy = "never"
sandbox_mode = "read-only"

## Подключение MCP-серверов

MCP (Model Context Protocol) — это протокол, который даёт Codex доступ к внешним системам: трекерам задач, базам данных, внутренней документации — без ручного копирования данных. Агент сам подтягивает нужную информацию из подключённого источника.

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

Подключение MCP-сервера обычно делается через команду:

codex mcp add <название-сервера> <url-или-команда>

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

## Skills (скиллы): переиспользуемые процессы

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

Скилл — это файл SKILL.md с инструкцией, который Codex применяет одинаково в каждом проекте, где этот файл присутствует. Это позволяет не объяснять одну и ту же последовательность действий заново при каждой новой сессии или в новом проекте.

## Тарифы и доступ к Codex

Codex доступен в рамках тарифных планов ChatGPT. Какую модель Codex использует по умолчанию, зависит от версии CLI или расширения IDE и текущей конфигурации.

Актуальная линейка тарифов на 2026 год:

С апреля 2026 года для тарифов Business и Enterprise ценообразование перешло на модель потребления токен-кредитов вместо фиксированных лимитов сообщений.

Важный момент про конфиденциальность: по умолчанию OpenAI не использует входные и выходные данные из продуктов для бизнес-пользователей — ChatGPT Business, ChatGPT Enterprise и API — для улучшения моделей. При этом владельцы организаций с доступом к API могут отдельно согласиться на передачу данных API в OpenAI для этой цели — это не происходит автоматически.

## Codex CLI vs Claude Code: коротко о разнице

Если вы выбираете между агентами — оба инструмента концептуально похожи: терминальный AI-агент, который читает код, вносит правки, выполняет команды. Основные практические отличия:

• AGENTS.md (Codex) и CLAUDE.md (Claude Code) — функционально аналогичные файлы инструкций для проекта, но с разным форматом ожиданий
• Codex CLI написан на Rust, использует нативную песочницу ОС (Seatbelt/Bubblewrap)
• У обоих агентов есть похожая концепция профилей, MCP-подключений и политик одобрения, но конкретный синтаксис конфигурации различается

Если ваша команда уже выбрала экосистему OpenAI (ChatGPT Business/Enterprise, существующие API-ключи) — Codex CLI логично встраивается в существующий биллинг. Если основная подписка — Claude — аналогичную функциональность даёт Claude Code.

## Частые проблемы и их решения

### Ошибка при установке: "command not found"

Проверьте, что установили именно @openai/codex, а не пакет с похожим названием. Переустановите:

npm uninstall -g codex
npm i -g @openai/codex

### Авторизация не проходит

Убедитесь, что используете актуальную версию Node.js (22+) и что браузер, который открывается для входа, может получить доступ к домену авторизации OpenAI.

### Codex просит подтверждение слишком часто

Это поведение определяется approval_policy. Если untrusted — агент спрашивает почти на каждый шаг. Смените на on-request в config.toml для менее навязчивого поведения.

### Codex теряет контекст в длинной сессии

Используйте /compact для сжатия истории диалога — это освобождает контекстное окно, сохраняя суть предыдущих шагов.

## Чеклист для начала работы

☐ Установлен Node.js версии 22 или выше
☐ Codex установлен: npm i -g @openai/codex
☐ Пройдена авторизация через ChatGPT-аккаунт
☐ В корне проекта создан файл AGENTS.md (через /init или вручную)
☐ Настроен ~/.codex/config.toml с approval_policy = "on-request" 
  и sandbox_mode = "workspace-write"
☐ Первая задача протестирована в read-only или auto-edit режиме
☐ full-auto режим используется только на отдельной ветке git
☐ При необходимости — подключён хотя бы один MCP-сервер

## Часто задаваемые вопросы

Что такое Codex простыми словами?

Codex — это AI-агент от OpenAI, который работает в терминале компьютера, понимает естественный язык и может самостоятельно читать, писать и редактировать код, запускать команды и работать с git.

Чем Codex CLI отличается от Codex 2021 года?

Codex 2021 года — это модель автодополнения кода на базе GPT-3, использовавшаяся в раннем GitHub Copilot. Codex CLI 2025-2026 — это полноценный автономный терминальный агент на новых моделях семейства GPT-5, который выполняет многошаговые задачи самостоятельно.

Как установить Codex CLI?

Через npm командой npm i -g @openai/codex, требуется Node.js версии 22 или выше. После установки запустите codex — откроется браузер для входа через ChatGPT-аккаунт.

Безопасно ли давать Codex полный доступ к файлам?

Безопасность строится на двух уровнях: sandbox (что агент технически может) и approval policy (когда он обязан спрашивать разрешение). Для повседневной работы рекомендуется комбинация workspace-write + on-request — запись только в проект, с подтверждением рискованных действий.

Что такое AGENTS.md?

Файл с инструкциями для конкретного проекта — команды сборки, правила кодирования, ограничения. Codex загружает его в начале каждой сессии. Можно сгенерировать автоматически командой /init.

Можно ли использовать Codex без подписки ChatGPT?

Да, через переменную окружения OPENAI_API_KEY с доступом к OpenAI API — в этом случае оплата идёт по модели использования API, а не по подписке ChatGPT.

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

На начало 2026 года основная модель — GPT-5.3-Codex, специально оптимизированная для агентной работы в CLI. Также доступна GPT-5.4 как модель общего назначения. Переключение — через /model или флаг --model.

Что делать, если Codex слишком часто спрашивает разрешение?

Изменить approval_policy в config.toml с untrusted на on-request — агент будет спрашивать только когда сам сочтёт действие рискованным.

## Итог

Codex CLI — это терминальный AI-агент от OpenAI, который превращает текстовые описания задач в реальные изменения кода: от мелких правок до многошаговых рефакторингов с тестами и коммитами.

Ключевые принципы для эффективной и безопасной работы: начинать с безопасных режимов (read-only, auto-edit) перед переходом к full-auto, настроить AGENTS.md под специфику проекта, использовать комбинацию workspace-write + on-request как разумный баланс между автономией и контролем, и заводить отдельные профили для разработки, CI и продакшен-сценариев.

Освоение Codex — это не запоминание команд, а выстраивание системы: один раз настроенные config.toml, AGENTS.md и профили работают на каждый последующий проект, экономя часы рутинной работы.