Флаг Codex CLI —sandbox (-s): как настроить песочницу

Флаг Codex CLI --sandbox применяется для ограничения возможностей среды, в которой агент выполняет команды и работает с файлами. С его помощью можно запустить Codex в режиме только чтения, разрешить изменения внутри рабочей папки или полностью снять ограничения песочницы. Короткий аналог этого параметра — -s.

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

Это не просто техническая настройка «для продвинутых пользователей». От выбранного режима зависит безопасность проекта, удобство автоматизации и количество запросов на подтверждение. Если выбрать слишком строгий режим, Codex не сможет выполнить полезную задачу. Если сразу использовать максимально широкие права, можно случайно разрешить изменения, которых вы не ожидали. Поэтому важно понимать, чем отличаются режимы read-only, workspace-write и danger-full-access, а также как --sandbox связан с подтверждениями команд.

Как использовать флаг --sandbox

В базовом виде параметр передаётся при запуске Codex CLI после имени команды. Например, режим только чтения задаётся так:

codex --sandbox read-only

Для короткой формы используется тот же режим, но вместо полного имени указывается ключ -s:

codex -s read-only

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

Полная форма	Короткая форма	Назначение
--sandbox read-only	-s read-only	Только чтение файлов и анализ проекта
--sandbox workspace-write	-s workspace-write	Изменение файлов в разрешённой рабочей области
--sandbox danger-full-access	-s danger-full-access	Запуск с максимально широким доступом

В большинстве сценариев разработки разумной отправной точкой считается workspace-write. Он позволяет агенту редактировать проект, но не даёт ему без необходимости полный доступ ко всей системе. Если задача требует только объяснения кода, поиска ошибок или аудита, лучше начать с read-only.

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

Режим можно указывать вместе с другими параметрами запуска. Например, можно одновременно выбрать песочницу и попросить Codex начать работу с конкретной задачей:

codex --sandbox workspace-write "Добавь тесты для модуля авторизации"

Задача	Рекомендуемый режим	Почему
Прочитать незнакомый проект	read-only	Изменения не требуются
Исправить ошибку в коде	workspace-write	Нужно редактировать файлы проекта
Обновить зависимости	workspace-write или более широкий режим	Зависит от ограничений среды и менеджера пакетов
Работать с системными файлами	danger-full-access	Требуется доступ за пределами рабочей папки

Режим read-only

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

Он подходит для code review, объяснения архитектуры, поиска потенциальных ошибок, составления плана миграции и диагностики. Такой режим особенно удобен перед началом незнакомой работы: сначала можно попросить агента изучить проект, а уже затем перезапустить его с правом записи.

codex --sandbox read-only "Проанализируй структуру проекта и назови основные риски"

Что обычно разрешено	Что обычно недоступно
Чтение исходного кода	Сохранение изменений в проекте
Поиск файлов и зависимостей	Автоматическое исправление файлов
Подготовка рекомендаций	Создание или удаление артефактов
Анализ конфигурации	Изменение конфигурации

Режим workspace-write

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

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

codex --sandbox workspace-write "Исправь ошибку в обработчике платежей и добавь регрессионный тест"

Тип работы	Подходит ли workspace-write	Комментарий
Редактирование исходников	Да	Основной сценарий режима
Создание тестов	Да	Тестовые файлы создаются в проекте
Изменение файлов за пределами проекта	Не всегда	Может потребоваться другой режим
Опасные системные операции	Не следует считать разрешёнными	Нужна отдельная оценка риска

Режим danger-full-access

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

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

codex --sandbox danger-full-access "Настрой системный инструмент согласно инструкции проекта"

Преимущество	Цена	Как снизить риск
Меньше ограничений	Выше вероятность нежелательного изменения	Запускать только для конкретной задачи
Доступ к внешним путям	Можно затронуть чужие данные	Проверить рабочую директорию
Удобство системной настройки	Ошибочная команда может иметь широкий эффект	Использовать резервные копии и контроль изменений

Когда применять разные режимы

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

Безопасный режим — это не тот, который запрещает всё, а тот, который даёт ровно необходимые права.

Для последовательной работы удобно использовать ступенчатый подход:

1. Начать с read-only и попросить Codex изучить проект.
2. Проверить план изменений и уточнить спорные места.
3. Перезапустить с workspace-write, если нужны правки внутри проекта.
4. Переходить к danger-full-access только при явной необходимости.

Ситуация	Первый выбор	Следующий шаг
Нужно понять чужой код	read-only	Перейти к записи только после согласования плана
Нужно исправить локальную ошибку	workspace-write	Проверить diff и тесты
Нужно изменить системную настройку	Сначала read-only	Использовать широкий доступ точечно
Нужно запустить опасную миграцию	Подготовить план без записи	Выполнять после резервного копирования

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

Тип проекта	Осторожность	Практическая рекомендация
Учебный репозиторий	Средняя	Можно использовать workspace-write с проверкой diff
Коммерческий сервис	Высокая	Начинать с анализа и работать в отдельной ветке
Проект с инфраструктурой	Очень высокая	Не давать широкий доступ без плана и резервной копии
Каталог с персональными данными	Максимальная	Ограничить область работы и исключить лишние файлы

Примеры использования

Ниже собраны практические сценарии, в которых значение --sandbox меняется в зависимости от цели. Каждый пример показывает не только синтаксис запуска, но и разумный контекст применения.

Анализ нового проекта без изменений

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

codex -s read-only "Опиши структуру проекта, точки входа и основные зависимости"

Поиск потенциальных ошибок

Для аудита можно попросить Codex проверить обработку исключений, работу с вводом пользователя или подозрительные места в запросах. Сначала полезно получить список проблем, а не сразу поручать их исправление.

codex --sandbox read-only "Найди потенциальные уязвимости и объясни, как их проверить"

Исправление исходного файла

Когда проблема понятна и требуется изменить код внутри рабочей области, подходит workspace-write. После выполнения обязательно проверьте список изменённых файлов.

codex -s workspace-write "Исправь обработку пустого ответа API и обнови связанные тесты"

Добавление нового теста

Создание тестов — типичный случай, когда агенту нужно право записи, но полный системный доступ не нужен.

codex --sandbox workspace-write "Добавь тесты для граничных значений функции calculateTotal"

Подготовка миграции базы данных

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

codex -s workspace-write "Создай миграцию для добавления индекса, но не запускай её"

Этап	Режим	Что проверяется
Проектирование миграции	read-only	Схема и существующие ограничения
Создание файла миграции	workspace-write	SQL и обратимость изменений
Запуск миграции	Отдельное подтверждение	Окружение, резервная копия и цель подключения

Обновление документации

Документация обычно не требует широких прав. Codex может изучить код, а затем изменить README или отдельные файлы документации в рамках проекта.

codex --sandbox workspace-write "Обнови README: добавь актуальные команды установки и запуска"

Рефакторинг в отдельной ветке

Безопаснее выполнять заметные изменения не в основной ветке, а в отдельной. Сам параметр --sandbox не заменяет контроль версий, но хорошо сочетается с такой практикой.

git switch -c refactor-parser
codex -s workspace-write "Выполни рефакторинг парсера без изменения публичного API"

Работа с инструментом за пределами проекта

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

codex --sandbox danger-full-access "Проверь конфигурацию внешнего инструмента и предложи безопасное исправление"

Проверка команды перед выполнением

Если вы сомневаетесь в последствиях команды, попросите Codex сначала объяснить её действие в режиме чтения. Такой подход полезен для скриптов очистки, миграций и автоматизации развёртывания.

codex -s read-only "Изучи scripts/cleanup.sh и объясни, какие файлы он может удалить"

Генерация отчёта о diff

Перед слиянием изменений можно поручить агенту проверить уже подготовленный diff. Здесь не требуется разрешать новые записи.

codex --sandbox read-only "Проверь текущий diff и составь список функциональных и стилевых рисков"

Пример	Рекомендуемый режим	Ожидаемый результат
Анализ архитектуры	read-only	Описание структуры и рекомендации
Исправление ошибки	workspace-write	Изменённые файлы и тесты
Создание документации	workspace-write	Обновлённые текстовые файлы
Системная настройка	danger-full-access	Изменения за пределами проекта

Чем отличается --sandbox от похожих команд и параметров

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

--sandbox и --ask-for-approval

Эти параметры часто воспринимают как взаимозаменяемые, но это не так. --sandbox задаёт технические границы доступа, а --ask-for-approval определяет, когда Codex должен спрашивать пользователя перед выполнением действий.

codex --sandbox workspace-write --ask-for-approval on-request "Исправь ошибку и покажи план перед рискованными командами"

Параметр	Главный вопрос	Пример смысла
--sandbox	Что агент технически может сделать?	Может ли он записывать в рабочую область
--ask-for-approval	Когда нужно спросить пользователя?	Нужно ли подтверждение перед командой

--sandbox и --full-auto

Автоматический режим обычно меняет поведение подтверждений и делает выполнение более самостоятельным. Он не должен автоматически означать снятие ограничений песочницы. Поэтому нельзя рассуждать так: «раз включён автоматический режим, значит, доступ открыт ко всему».

codex --full-auto --sandbox workspace-write "Выполни безопасные правки и запусти доступные тесты"

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

--sandbox и --cd

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

codex --cd ./backend --sandbox workspace-write "Исправь обработчик ошибок в сервисе"

Настройка	Что меняет	Чего не меняет
--cd	Начальную рабочую директорию	Уровень доступа сам по себе
--sandbox	Границы чтения и записи	Содержимое проекта и ветку Git

--sandbox и Git

Git отвечает за историю изменений, ветки и возможность сравнить состояние проекта. Песочница отвечает за ограничения действий во время текущего запуска. Они дополняют друг друга, но не заменяют.

git switch -c codex-review
codex --sandbox workspace-write "Обнови код, затем перечисли все изменённые файлы"

Инструмент	Основная функция	Ограничение
--sandbox	Ограничивает доступ агента	Не создаёт историю изменений
Git	Хранит историю и diff	Не запрещает команду до её выполнения
Резервная копия	Позволяет восстановить данные	Не предотвращает ошибку заранее

Типичные ошибки

Ошибки при работе с --sandbox чаще связаны не с синтаксисом, а с неверной моделью безопасности. Пользователь либо ожидает от строгого режима невозможного, либо даёт слишком широкие права для простой задачи.

Ошибка: перепутать режим с флагом без значения

У --sandbox должно быть значение. Запуск без режима может привести к ошибке разбора аргументов или к неожиданному использованию настроек по умолчанию.

codex --sandbox "Проверь проект"

Правильно:
codex --sandbox read-only "Проверь проект"

Ошибка: выбрать danger-full-access для обычного редактирования

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

codex --sandbox danger-full-access "Переименуй одну переменную"

Безопаснее:
codex --sandbox workspace-write "Переименуй одну переменную"

Ошибка: ожидать, что read-only сам внесёт исправления

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

codex -s read-only "Найди ошибку и предложи патч"
Затем, после проверки:
codex -s workspace-write "Внеси согласованный патч"

Ошибка: считать песочницу заменой резервной копии

Ограничения доступа снижают риск, но не отменяют необходимость Git, резервного копирования и проверки diff. Даже разрешённое изменение в рабочей области может оказаться логически неверным.

git status
git diff
codex --sandbox workspace-write "Исправь проблему только в модуле billing"

Ошибка	Последствие	Как исправить привычку
Нет значения у --sandbox	Команда не запускается или ведёт себя не так, как ожидалось	Всегда указывать режим явно
Сразу выбран полный доступ	Избыточная область потенциальных изменений	Начинать с минимально достаточного режима
От read-only ждут записи	Изменения не появляются	После анализа перезапустить с записью
Нет проверки diff	Ошибки обнаруживаются слишком поздно	Проверять статус и изменения после работы

Краткая памятка

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

Нужно сделать	Команда
Только изучить проект	codex -s read-only
Изменить файлы проекта	codex -s workspace-write
Получить максимально широкий доступ	codex -s danger-full-access

Перед запуском задайте себе три вопроса:

1. Нужно ли Codex менять файлы или достаточно анализа?
2. Ограничивается ли задача текущей рабочей областью?
3. Проверены ли текущая директория, ветка Git и возможные последствия команд?

Проверка	Что сделать	Зачем
Режим	Выбрать минимально достаточное значение	Снизить область риска
Рабочая директория	Проверить путь и проект	Не изменить чужой каталог
Git	Создать ветку и посмотреть diff	Сохранить контроль над правками
Подтверждения	Настроить подходящий режим согласования	Не запускать рискованные действия вслепую

Главное правило простое: для анализа используйте read-only, для обычной разработки — workspace-write, а danger-full-access оставляйте для редких задач, которым действительно нужен выход за пределы рабочей области. Такой подход не мешает Codex быть полезным и одновременно не превращает каждую команду в лотерею с системными файлами.