Краткий обзор ключевых концепций Codex

📚 Навигация по серии: Предыдущая статья 01 · Знакомство с Codex и четырьмя интерфейсами представила четыре воплощения Codex: настольное приложение, командную строку (CLI), расширение для IDE и облачную версию. В этой статье мы сделаем шаг вперед и детально разберем ключевые концепции, к которым будем возвращаться на протяжении всего курса. В следующей статье 03 · Установка и авторизация мы перейдем непосредственно к установке.

Для начала поделюсь забавным случаем из личной практики. В самом начале работы с Codex я попросил его: «переименуй эти три файла пакетно». Он быстро выполнил задачу, но при проверке я обнаружил, что изменения затронули только файлы внутри текущего рабочего каталога проекта, а те два, что лежали на моем рабочем столе, остались нетронутыми. Я удивился: «ведь он умеет выполнять консольные команды, почему он так избирателен?». Позже, изучив документацию, я понял: его сдерживала песочница (Sandbox). По умолчанию Codex разрешено изменять файлы только внутри указанной рабочей области, а для выхода за ее пределы требуется ваше явное одобрение.

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

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

После прочтения этой статьи вы получите:

• Простое объяснение того, что такое «агент» (Agent) в контексте Codex и чем он отличается от обычного чат-бота
• Полное понимание работы песочницы (Sandbox) и подтверждения прав (Approval), причин блокировок и способов их обхода
• Знакомство с файлом AGENTS.md: постоянной инструкцией для Codex с правилами вашего проекта
• Понимание механизмов памяти (Memory) и Chronicle, их статуса по умолчанию и способов активации
• Практическое упражнение по наблюдению за работой ограничений песочницы

⚠️ Примечание: все упоминания конкретных команд, параметров конфигурации и поведения по умолчанию приведены в соответствии с официальной документацией Codex. Названия моделей и тарифных планов могут меняться в зависимости от текущей версии.

---

01 Агент (Agent): Автономия действий вместо простых ответов

Сразу к главному: Codex — это программируемый агент (coding agent) от OpenAI, способный самостоятельно читать код, редактировать файлы и запускать команды, а не просто генерировать текст. В документации он описывается как «OpenAI's coding agent that can read, edit, and run code».

Понятие «агент» (Agent) является ключевым. Дадим простое определение: агент — это искусственный интеллект, способный самостоятельно разбивать задачи на шаги, вызывать необходимые инструменты, анализировать результаты и принимать решения о дальнейших действиях без пошагового контроля со стороны пользователя.

Официальное описание логики работы Codex: «агент выполняет консольные команды в цикле, редактирует код, запускает проверки и пытается валидировать свою работу» (оригинал: The agent runs terminal commands in a loop. It edits code, runs checks, and tries to validate its work).

Простыми словами, его логика строится на трех действиях: подумать → сделать → проверить:

• Подумать: прочитать файлы, изучить логи ошибок, оценить ситуацию
• Сделать: изменить код, создать файлы, выполнить консольные команды
• Проверить: запустить тесты, оценить результат и запустить цикл повторно при обнаружении ошибок

Аналогия: помощник по покупкам (байер) против справочной службы. Обычный чат-бот похож на оператора справочной: вы спрашиваете «сколько стоит эта куртка?», он возвращает цену — и на этом работа закончена. Codex действует как персональный байер: вы просите «купи мне черную куртку размера M», он сам находит товар, сравнивает цены, оформляет заказ, а при получении проверяет соответствие размера и при необходимости оформляет возврат. Самостоятельное выполнение всего процесса «под ключ» — главное отличие агента от чат-бота.

Примеры реальных сценариев:

• Вы спрашиваете: «почему падает этот тест?». Codex сам запускает тесты → читает логи ошибок → локализует баг → исправляет код → запускает тесты повторно для подтверждения, пока вы наблюдаете за выводом в консоли.
• Вы передаете проект без документации с просьбой «разберись в структуре». Он сам сканирует каталоги, ищет ключевые файлы, анализирует их содержимое и строит диаграмму связей — при этом вам не нужно указывать конкретные файлы вручную.
• Вы просите «добавь кэширование для этой функции». Он вносит изменения и заодно оптимизирует все места ее вызова в других файлах, так как видит проект целиком.

💡 Краткий вывод: Codex является полноценным агентом разработки, а не простым чат-ботом. Он автономно выполняет задачи в цикле «подумать → сделать → проверить». Этот механизм идентичен логике работы Claude Code, меняется лишь внешняя обвязка.

---

02 Песочница (Sandbox): Границы дозволенного

Мы подошли к важнейшей теме. Именно песочница стала причиной неудачи с переименованием файлов в начале статьи.

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

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

Забор песочницы контролирует два ресурса: доступ к файловой системе и возможность сетевых подключений. Доступны три режима:

Режим песочницы	Доступ на запись	Доступ к сети	Сценарий использования
read-only (Только чтение)	❌ Нет (требует подтверждения)	❌ Нет	Исследование кодовой базы, аудит и планирование без изменения файлов
workspace-write (Запись в рабочем каталоге)	✅ Только в пределах рабочей папки	❌ По умолчанию закрыт	Основной рабочий режим; рекомендуется по умолчанию для папок под контролем Git (для остальных папок сбрасывается в read-only)
danger-full-access (Полный доступ)	✅ Доступ ко всем файлам системы	✅ Да	Доверительное окружение. Слово danger в названии указано не случайно, используйте с осторожностью

Обратите внимание на ограничение режима workspace-write — «только в пределах рабочей папки». Именно поэтому файлы на моем рабочем столе не были изменены: они располагались вне каталога запуска сессии Codex, то есть за пределами забора песочницы. Агент не проигнорировал команду, он просто физически не мог получить к ним доступ.

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

Реализация песочницы зависит от операционной системы (подробнее в Статье 03):

• macOS: использует встроенный механизм Seatbelt, работает из коробки без дополнительной настройки.
• Windows: запускается непосредственно в среде ОС с использованием стандартной Windows Sandbox (в режимах elevated или unelevated); при работе в WSL2 задействует механизмы Linux.
• Linux / WSL2: требует предварительной установки утилиты bubblewrap для корректной работы песочницы (это обязательное системное требование).

💡 Краткий вывод: Песочница является базовым рубежом защиты. По умолчанию (в режиме workspace-write) она запрещает изменять файлы вне рабочего каталога и закрывает доступ к сети. Расширение полномочий требует ручной настройки.

---

03 Подтверждение прав (Approval): Контроль на границе

Песочница очерчивает границы, а вопрос «кто одобряет действия на границе контура» регулируется механизмом подтверждения прав (Approval).

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

Аналогия: турникет и охранник. Песочница — это турникет (физическое ограждение), а подтверждение прав — строгость охранника на КПП. Один охранник выпускает всех без разбору (never), другой проверяет только незнакомцев (untrusted), третий требует отчета при каждом шаге (on-request). Ограждение статично, но бдительность охраны вы настраиваете сами.

Три основные политики подтверждения прав в документации:

Политика подтверждения	Поведение Codex	Описание простыми словами
untrusted	Запрашивает подтверждение для команд вне «списка доверенных»	Блокирует неизвестные скрипты
on-request	Выполняет операции в песочнице, запрашивая подтверждение только при выходе за ее рамки	Оптимальный сбалансированный режим
never	Выполняет команды без подтверждений	Используется для автоматизации; границы по-прежнему контролируются песочницей

Обратите внимание: untrusted, on-request и never являются независимыми параметрами конфигурации подтверждения прав. Они настраиваются отдельно от режимов песочницы.

Две классические комбинации настроек для работы:

• Повседневный рабочий режим (рекомендуемый): sandbox_mode = "workspace-write" совместно с approval_policy = "on-request". Безопасная работа в рабочей папке и запросы при попытке ее покинуть.
• Автономный режим без ограничений (с осторожностью): sandbox_mode = "danger-full-access" совместно с approval_policy = "never". Устраняет все барьеры и подтверждения. Допускается только в полностью доверенных средах.

Рекомендуемая практика: при работе с новыми проектами или незнакомым кодом всегда начинайте в режиме read-only (только чтение). Это позволит оценить предлагаемые изменения. Как только логика понятна, можно переключаться в workspace-write для записи. Не стоит использовать danger-full-access для рутинных скриптов во избежание случайного повреждения системных файлов.

Для быстрого переключения в сессии используйте команду /permissions в CLI (в IDE и приложении для этого предусмотрен графический селектор прав). Постоянная фиксация настроек выполняется через файлы конфигурации (подробнее в Статье 18, посвященной настройке config.toml).

Схема взаимодействия песочницы и подтверждения прав:

Схема наглядно показывает логику принятия решений: перед каждым действием Codex сначала проверяет границы песочницы, а при выходе за них сверяется с политикой подтверждения (спрашивать ли пользователя). Два независимых уровня контроля.

💡 Краткий вывод: Песочница отвечает за техническую возможность доступа, а подтверждение прав — за запросы к пользователю. Они настраиваются независимо друг от друга. Рекомендуемый набор для ежедневного использования: workspace-write + on-request.

---

04 AGENTS.md: Инструкция к проекту для Codex

Мы обсудили права доступа. Теперь перейдем к важной теме: как зафиксировать правила проекта для Codex, чтобы избавить себя от необходимости объяснять их при каждом запуске.

Для этого используется файл AGENTS.md.

Аналогия: памятка новому сотруднику. При оформлении стажера вы не ходите за ним, напоминая о требованиях «мы используем pnpm вместо npm» или «пиши коммиты на русском». Вы просто даете ему памятку. Файл AGENTS.md — это и есть памятка для Codex: он считывает ее при каждом старте сессии в репозитории и следует правилам.

В документации он позиционируется как «durable project guidance» (постоянное руководство к проекту), которое хранится в корневом каталоге репозитория. Главная рекомендация: держите его лаконичным (Keep it small), избегайте раздувания.

В AGENTS.md обычно прописывают:

• Команды сборки и запуска тестов (например, «для тестов вызывай pytest -q»)
• Требования к качеству кода (например, «после правок запусти линтер»)
• Специфические соглашения проекта (структура каталогов, правила именования)

Файлы правил могут располагаться на двух уровнях, при этом приоритет отдается файлу в рабочем каталоге:

Уровень	Расположение	Область действия
Глобальный	~/.codex/AGENTS.md	Персональные предпочтения разработчика (например, «пиши лаконично»), действуют для всех сессий
Проектный	Корневой или подкаталог репозитория	Правила конкретного проекта, фиксируются в Git для совместной работы

Очень эффективный прием — использование файла правил в качестве обратной связи (feedback loop). Если Codex сделал неверное предположение о коде, не просто поправьте его в чате (это сбросится при закрытии сессии), а попросите его записать исправление в AGENTS.md. Так оно применится в следующей сессии. По мере разработки ваш AGENTS.md наполнится правилами, предотвращающими повторение одних и тех же ошибок.

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

💡 Краткий вывод: AGENTS.md — это свод правил вашего проекта, считываемый Codex на старте. Используйте его для накопления опыта взаимодействия: фиксируйте ошибки в правилах, чтобы повысить точность ответов в будущем.

---

05 Память (Memory) и Chronicle: Сохранение контекста общения

Эта группа функций является относительно новой для Codex и часто вызывает вопросы: сохраняет ли агент контекст прошлых обсуждений?

Разграничим два понятия:

Память (Memory): позволяет Codex переносить полезные знания из прошлых сессий в новые (ваш стек технологий, особенности проектов, частые ошибки), избавляя от повторных инструкций.

Аналогия: сработавшийся коллега. Новому помощнику приходится раз за разом повторять: «мы пишем на TypeScript и не используем точки с запятой». Опытный напарник помнит эти привычки по умолчанию. Функция Memory переводит Codex из статуса «новичка» в статус «опытного напарника».

Необходимо учитывать важные особенности работы механизма памяти:

• По умолчанию отключена (off by default). Для активации включите ее в настройках приложения или добавьте строчку memories = true в блоке [features] файла ~/.codex/config.toml.
• Региональные ограничения. На старте функция недоступна для пользователей из ЕЭЗ, Великобритании и Швейцарии.
• Фоновое обновление. Запись памяти происходит при бездействии сессии, модель не анализирует данные прямо во время вашей активной работы.
• Локальное хранение: файлы памяти сохраняются на вашем компьютере в каталоге ~/.codex/memories/ в формате Markdown.
• Управление сессиями: команда /memories позволяет настроить использование или генерацию памяти для конкретного диалога.

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

💡 Краткий вывод: Механизм памяти адаптирует агента под ваш стиль работы, но по умолчанию отключен и имеет региональные ограничения. Важные правила всегда прописывайте в AGENTS.md.

Что касается функции Chronicle:

⚠️ Экспериментальная функция. В настоящее время Chronicle доступна в режиме превью (opt-in research preview) только для пользователей планов ChatGPT Pro на macOS (кроме ЕЭЗ, Великобритании и Швейцарии).

Chronicle анализирует содержимое экрана для пополнения памяти. В отличие от обычной памяти, считывающей логи диалога, Chronicle анализирует активные окна (открытый файл, PR или страницу документации), помогая Codex понимать текущий рабочий контекст без лишних объяснений.

Аналогия: напарник, который видит ваш дисплей. Обычный коллега слушает ваши объяснения, а этот видит ошибку на экране своими глазами, избавляя вас от пересказа. Это удобно, но имеет цену: расход токенов ускоряется, возрастает риск инъекций подсказок (prompt injection), а логи сохраняются локально без шифрования. Баланс удобства и безопасности. Рекомендуется ставить Chronicle на паузу («Pause Chronicle» в меню) при работе с конфиденциальными данными (пароли, личные переписки, клиентские базы).

Параметр	Память (Memory)	Chronicle
Источник данных	Логи диалогов	Содержимое активного экрана
Статус функции	Стабильная (выключена по умолчанию)	Превью (экспериментальная)
Поддержка платформ	Приложение и CLI	Только macOS, только планы Pro
Рекомендация	Рекомендуется к включению	Для тестирования, приостанавливайте на конфиденциальных экранах

💡 Краткий вывод: Механизм памяти превращает Codex в опытного напарника, но выключен по умолчанию и не заменяет AGENTS.md. Chronicle — экспериментальный инструмент анализа экрана, имеющий очевидные риски безопасности.

---

Давайте объединим эти пять концепций на схеме, чтобы понять логику их взаимодействия:

Логика схемы: центральный Агент выполняет задачи внутри Песочницы. Выход за ее рамки контролируется правилами Подтверждения прав. Файл AGENTS.md задает требования к проекту на старте, а механизмы Памяти и Chronicle накапливают опыт взаимодействия — все концепции выстроены вокруг Агента.

---

06 Практика: Наблюдение за блокировкой песочницы

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

Шаг 1: Создайте папку и запустите Codex

Выполните команды в консоли (в Windows замените mkdir -p на mkdir):

mkdir -p ~/codex-demo && cd ~/codex-demo
codex

Если у вас еще не установлен Codex, ознакомьтесь сначала с инструкцией в Статье 03 и возвращайтесь к этому шагу позже.

Шаг 2: Переключитесь в режим только чтения

Введите команду в сессии Codex:

/permissions

Выберите в меню пункт только чтения (Read Only / read-only). Ожидаемый результат: вывод подтверждения режима —

Permissions updated: read-only

⚠️ Примечание для новых версий: начиная с версии codex-cli 0.142, разработчики представили профили разрешений permission profiles (статус Beta, могут меняться). Меню /permissions теперь может содержать пункты Ask for approval, Approval for me или Full access вместо прямого указания Read Only.

Если пункта Read Only нет в меню, вы можете запустить сессию с флагом codex --sandbox read-only или прописать sandbox_mode = "read-only" в файле ~/.codex/config.toml для фиксации режима.

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

Шаг 3: Вызовите файловую операцию на запись

Отправьте запрос:

帮我新建一个文件 hello.txt，里面写一行字 "hello codex"。

Ожидаемый результат: Codex не создаст файл автоматически, а приостановит работу и запросит подтверждение, так как операция записи выходит за рамки прав read-only:

我需要创建文件 hello.txt，这超出了当前只读模式的权限，
是否允许？(y/n)

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

Шаг 4: Сравнение с разрешенным режимом

Переключите права в /permissions на workspace-write (запись в рабочем каталоге) и повторите запрос. Ожидаемый результат: файл создается молча без дополнительных запросов, так как запись в рабочей папке разрешена правилами песочницы.

已创建 hello.txt

Проверьте статус сессии с помощью команды /status:

/status

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

💡 Краткий вывод: Тест наглядно показывает: одна и та же запись в read-only требует подтверждения, а в workspace-write проходит автоматически. Это пример работы рубежей защиты.

---

07 Резюме

Мы разобрали пять фундаментальных концепций Codex:

Концепция	Краткое описание	Аналог в Claude Code
Агент (Agent)	Автономный AI (цикл подумать → сделать → проверить)	Агентный цикл (идентично)
Песочница (Sandbox)	Границы файловой системы и сети	Контур безопасности
Подтверждение (Approval)	Правила запросов пользователя на границе контура	Режимы разрешений
AGENTS.md	Постоянные правила проекта на старте	Файл CLAUDE.md (различие только в имени)
Память / Chronicle	Накопление опыта и анализ экрана (экспериментальная)	Автопамять / Анализ экрана

Теперь вы понимаете причины блокировки некоторых операций (выход за пределы песочницы), природу всплывающих окон подтверждения и способы фиксации правил проекта в AGENTS.md или изменения прав через /permissions.

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

---

В следующей статье 03 · Установка и авторизация мы перейдем к практике. Мы развернем Codex на macOS, Windows и Linux, пройдем авторизацию и выполним первую команду. Разработчики на Linux увидят практическое применение утилиты bubblewrap, упомянутой в этом разделе.

---

Рекомендуемые материалы

• Знакомство с Codex и четырьмя интерфейсами взаимодействия
• Подключение сторонних и локальных моделей (DeepSeek и др.)
• Практические рекомендации: проверенные методы организации разработки с AI