Флаг Codex CLI —image (-i): как прикрепить изображения к запросу

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

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

Флаг особенно полезен в задачах, где текст не передаёт всей информации. По скриншоту ошибки можно попросить найти причину сбоя, по макету — сверстать компонент, по диаграмме — объяснить архитектуру, а по фотографии документа — извлечь структуру данных. Ниже разберём синтаксис, ограничения, практические сценарии и отличия --image от похожих возможностей Codex CLI.

Как использовать

Флаг --image указывается вместе с путём к изображению и текстом запроса. Базовая форма выглядит так: codex --image <путь-к-файлу> "ваш запрос". Короткая запись -i делает то же самое: codex -i <путь-к-файлу> "ваш запрос".

Чем точнее сформулирован текстовый запрос, тем полезнее будет анализ картинки: изображение показывает «что есть», а инструкция объясняет, что именно нужно с этим сделать.

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

Вариант	Пример	Когда удобен
Относительный путь	screenshots/error.png	Файл находится внутри текущего проекта
Абсолютный путь в Unix-системах	/home/user/images/mockup.png	Нужно явно указать расположение файла
Абсолютный путь в Windows	C:UsersUserPicturesmockup.png	Файл находится вне рабочей директории
Путь с пробелами	"design files/header.png"	Имя папки или файла содержит пробелы

Один файл и текстовый запрос

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

codex --image screenshot.png "Определи, почему на этом экране возникает ошибка, и предложи план исправления без изменения файлов"

Если команда запускается из другой папки, проверьте, откуда выполняется процесс. Путь ./screenshot.png интерпретируется относительно текущего рабочего каталога, а не обязательно относительно каталога, где установлен Codex CLI.

Запрос	Недостаток	Более удачная формулировка
Посмотри картинку	Непонятно, какой результат требуется	Опиши проблему на скриншоте и назови вероятную причину
Сделай красиво	Нет измеримых критериев	Предложи изменения отступов, цветов и типографики для мобильной версии
Исправь ошибку	Неясно, можно ли менять файлы	Найди связанный компонент, объясни исправление и сначала покажи план

Короткая форма -i

Аналог -i удобен в терминале, скриптах и командах, которые приходится набирать часто. Функционально он не добавляет отдельного режима: это сокращённая запись длинного флага --image.

codex -i ui-state.png "Сравни состояние интерфейса с реализацией в проекте и перечисли расхождения"

В документации команды обычно рекомендуется длинная форма, если команду читают другие люди: --image понятнее с первого взгляда. В личных интерактивных командах или коротких shell-скриптах -i экономит место.

Форма	Преимущество	Рекомендуемое применение
--image	Самоописываемая запись	Документация, CI-скрипты, командные инструкции
-i	Краткость	Интерактивная работа и частый ручной запуск

Несколько изображений

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

codex --image before.png --image after.png "Сравни два состояния интерфейса и перечисли изменения, которые нужно внести в код"

Чтобы модель не перепутала файлы, полезно называть их понятно: before.png, after.png, mobile.png, desktop.png. Если порядок изображений важен, прямо укажите в запросе, какое изображение считать первым, а какое — вторым.

Сценарий	Подходящие имена файлов	Что попросить
Сравнение до и после	before.png, after.png	Найти визуальные и функциональные расхождения
Адаптивность	desktop.png, mobile.png	Проверить, какие элементы не адаптировались
Несколько экранов	step-1.png, step-2.png, step-3.png	Восстановить пользовательский сценарий
Варианты дизайна	variant-a.png, variant-b.png	Сравнить решения по заданным критериям

Проверка доступности изображения

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

ls -lh screenshots/login.png
codex --image screenshots/login.png "Проверь макет на очевидные проблемы доступности и объясни каждую найденную проблему"

В Windows аналогичную проверку можно выполнить средствами PowerShell. Если путь содержит пробелы, заключите его в кавычки, иначе оболочка может воспринять части пути как отдельные аргументы.

Проверка	Что выявляет	Почему это важно
Файл существует	Опечатки и неверный каталог	Предотвращает ошибку запуска
Расширение корректно	Случайно выбранный текстовый или временный файл	Помогает передать именно изображение
Размер разумный	Слишком большой скриншот или экспорт без оптимизации	Уменьшает время обработки и объём контекста
Содержимое читаемо	Размытый текст, слишком маленькие элементы	Повышает точность анализа

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

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

Хорошая задача для --image возникает там, где человеку проще показать проблему, чем описать её словами: «вот этот блок съехал», «в этом месте появляется ошибка», «на мобильном экране исчезает кнопка».

Скриншоты ошибок

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

codex --image browser-error.png "Разбери ошибку на скриншоте, найди в проекте возможный источник проблемы и перечисли, какие логи нужно проверить"

Не стоит просить модель «исправить всё» только по изображению. Лучше разделить задачу на этапы: распознать сообщение, связать его с кодом, предложить гипотезы, затем проверить гипотезу тестом или повторным запуском.

Что есть на скриншоте	Что дополнительно указать	Ожидаемый результат
Сообщение об ошибке	Действие, после которого она появилась	Гипотезы о причине и план проверки
Стек вызовов	Версию приложения и окружение	Связь ошибки с конкретным участком кода
Сбой в браузере	Браузер, устройство и шаги воспроизведения	Анализ клиентской или адаптивной проблемы

Макеты и интерфейсы

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

codex --image dashboard-mockup.png "Найди подходящий экран в проекте и предложи пошаговый план реализации этого макета на существующих компонентах"

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

Цель	Уточнение в запросе	Что проверить в результате
Сверстать новый экран	Какие компоненты уже разрешено использовать	Повторное использование существующих решений
Повторить дизайн	Какие размеры и цвета являются обязательными	Соответствие макету и токенам проекта
Исправить расхождения	Сравнивать ли с desktop- и mobile-версией	Отсутствие ухудшения на других разрешениях

Диаграммы и схемы

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

codex --image architecture.png "Объясни архитектуру на схеме простыми словами, перечисли сервисы и укажи места, где могут возникнуть единичные точки отказа"

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

Тип схемы	Полезный запрос	Ограничение анализа
Архитектура сервисов	Найти зависимости и точки отказа	Не подтверждает фактическую конфигурацию
Блок-схема процесса	Проверить пропущенные ветки	Может не распознать нечитабельные подписи
ER-диаграмма	Объяснить связи сущностей	Не заменяет проверку схемы базы данных

Документы, таблицы и фотографии

Изображение документа можно использовать, чтобы извлечь ключевые поля, объяснить структуру формы или подготовить черновой JSON. Но к персональным данным, коммерческой тайне и внутренним документам нужно относиться осторожно: перед отправкой изображения убедитесь, что его разрешено использовать в выбранной среде.

codex --image invoice.jpg "Извлеки номер счёта, дату, валюту и итоговую сумму. Если поле не читается, укажи это явно и не придумывай значение"

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

Тип данных	Риск ошибки	Мера предосторожности
Числа и суммы	Пропуск запятой или цифры	Сверять с оригиналом и итогами документа
Даты	Неоднозначный формат	Указывать ожидаемый формат в запросе
Персональные данные	Раскрытие чувствительной информации	Удалять или маскировать данные заранее
Табличные строки	Смещение колонок	Проверять каждую строку и заголовки

Визуальные регрессионные проверки

Если есть эталонный скриншот и актуальный результат, Codex может помочь составить список различий. Это не заменяет специализированные инструменты pixel-perfect-сравнения, но хорошо подходит для первичного объяснения: какой компонент изменился, где появился лишний отступ и какие области требуют проверки.

codex --image expected.png --image actual.png "Сравни эталонный и актуальный скриншоты. Раздели отличия на функциональные, типографические и косметические"

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

Условие сравнения	Почему важно	Что сделать
Одинаковое разрешение	Меняется перенос текста и сетка	Зафиксировать viewport
Одинаковый масштаб	Отличается размер элементов	Использовать один zoom
Одинаковые данные	Меняется длина текста и состав блоков	Загрузить одинаковый набор данных
Одинаковые шрифты	Изменяются метрики текста	Проверить загрузку шрифтов

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

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

Анализ скриншота ошибки

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

codex --image error.png "Прочитай сообщение об ошибке, объясни его простыми словами и составь план диагностики с приоритетом проверок"

Поиск причины съехавшей вёрстки

Изображение помогает показать фактический результат, но в запросе стоит попросить проверить конкретные CSS-причины: переполнение, flex/grid, фиксированную ширину, позиционирование и медиазапросы.

codex -i broken-layout.png "Найди в проекте CSS или React-компонент, который может вызвать съехавшую вёрстку. Сначала перечисли гипотезы и файлы для проверки"

Проверка мобильной версии

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

codex --image mobile-screen.png "Проверь мобильную версию: найди элементы, которые выходят за пределы экрана, плохо читаются или перекрывают друг друга"

Сравнение макета и реализации

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

codex --image design.png --image implementation.png "Сравни макет и реализацию. Составь таблицу: область, отличие, вероятная причина, приоритет исправления"

Подготовка структуры компонента

Изображение не обязано сразу приводить к изменению кода. Сначала можно попросить восстановить структуру интерфейса и сопоставить её с уже существующими компонентами.

codex --image profile-page.png "Разложи экран на компоненты, укажи их предполагаемые состояния и предложи структуру файлов без написания кода"

Анализ архитектурной схемы

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

codex --image system-diagram.png "Опиши поток запроса от клиента до базы данных и назови три места, которые нужно уточнить у автора схемы"

Извлечение данных из формы

Для OCR-подобных задач важно заранее определить формат результата и попросить не заполнять пропуски догадками.

codex --image registration-form.png "Верни JSON с полями name, email, company и date. Если значение не читается, используй null и добавь список сомнительных полей"

Проверка доступности интерфейса

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

codex --image checkout.png "Найди на скриншоте возможные проблемы доступности: контраст, размер текста, заметность фокуса, подписи полей и порядок блоков"

Поиск визуальной регрессии

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

codex -i old-version.png -i new-version.png "Сравни версии страницы и составь список изменений, которые могут быть вызваны обновлением CSS"

Объяснение графика

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

codex --image metrics.png "Объясни, какие тренды видны на графике, где есть резкие изменения и какие дополнительные данные нужны для уверенного вывода"

Чем отличается от…

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

--image и обычный текстовый prompt

Обычный prompt передаёт только текстовую инструкцию. Флаг --image добавляет к ней визуальный контекст. Это не две конкурирующие команды, а два источника информации, которые обычно используются вместе.

codex "Объясни, почему кнопка не работает"

codex --image button-error.png "Объясни, почему кнопка не работает, учитывая изображение и исходный код проекта"

Возможность	Текстовый prompt	--image
Передаёт описание	Да	Да, через prompt
Передаёт визуальные детали	Только если их описать вручную	Да
Подходит для скриншотов	Ограниченно	Да
Заменяет логи и исходный код	Нет	Нет

--image и --search

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

codex --search "Какие актуальные рекомендации существуют для этой технологии?"

codex --image architecture.png "Объясни эту конкретную архитектурную схему и найди слабые места"

Критерий	--image	--search
Источник данных	Локальный файл изображения	Внешние результаты поиска
Основная задача	Понять конкретный визуальный артефакт	Найти актуальную информацию
Зависимость от сети	Зависит от общего режима работы CLI	Обычно требует сетевого доступа
Типичный результат	Анализ скриншота или схемы	Сведения, ссылки или контекст по теме

--image и --full-auto

--full-auto относится к режиму автономной работы и разрешениям на действия, а не к анализу изображений. Эти параметры могут использоваться вместе, но выполняют разные функции: --image передаёт контекст, а --full-auto меняет степень самостоятельности CLI.

codex --image ui-bug.png --full-auto "Найди причину проблемы и подготовь исправление, но перед изменением файлов сначала перечисли план"

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

Параметр	Что меняет	Чего не делает
--image	Добавляет изображение в контекст	Не включает автоматическое редактирование
--full-auto	Увеличивает самостоятельность выполнения	Не улучшает распознавание картинки сам по себе

--image и --cd/-C

Параметр --cd или его короткий вариант -C задаёт рабочий каталог, а --image передаёт файл. Они особенно полезны вместе, когда команду запускают из любой папки, но анализировать нужно конкретный репозиторий.

codex -C ~/projects/shop --image screenshots/cart.png "Проверь экран корзины и найди компонент, отвечающий за отображённую ошибку"

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

Ситуация	Что использовать	Практический эффект
Работа из корня проекта	--image screenshots/a.png	Простой относительный путь
Запуск из другой папки	-C project --image path/a.png	Выбор рабочего каталога проекта
Неоднозначное расположение файла	Абсолютный путь к изображению	Меньше риска ошибки разрешения пути

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

Большинство проблем с --image связано не с самим флагом, а с путями, качеством изображения, недостаточно точным запросом или неверными ожиданиями от визуального анализа. Ниже — ситуации, которые встречаются чаще всего.

Файл не найден

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

pwd
ls -lh "screenshots/login page.png"
codex --image "screenshots/login page.png" "Проанализируй экран входа"

На Windows для проверки можно использовать PowerShell-команду Get-Item. В автоматизации лучше формировать пути средствами используемого языка, а не склеивать их вручную строками.

Симптом	Вероятная причина	Исправление
Файл не найден	Неверный относительный путь	Проверить текущий каталог и путь
Путь разделился на аргументы	В имени есть пробелы	Использовать кавычки
Файл существует, но не читается	Нет доступа или файл занят	Проверить права и открыть копию

Слишком большое или нечёткое изображение

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

codex --image cropped-error-area.png "Сосредоточься на сообщении ошибки и элементах формы рядом с ним. Не делай выводов о невидимых частях страницы"

Проблема изображения	Что происходит	Что сделать
Мелкий текст	Символы распознаются неоднозначно	Увеличить область или сделать отдельный снимок
Лишние области	Контекст становится размытым	Обрезать изображение
Размытие	Теряются цифры и знаки	Сделать новый скриншот в исходном масштабе
Низкий контраст	Границы элементов неочевидны	Использовать качественный экспорт или оригинал

Нет конкретной задачи

Запрос вроде «посмотри картинку» заставляет модель самостоятельно угадывать цель. Ответ может оказаться подробным, но практически бесполезным. Укажите, что нужно получить: список проблем, код, план, сравнение, JSON или объяснение для новичка.

codex --image screen.png "Найди только проблемы адаптивности. Для каждой укажи область экрана, вероятную CSS-причину и способ проверки"

Ожидание стопроцентного распознавания

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

codex --image document.png "Извлеки данные, но пометь каждое поле как уверенное или требующее ручной проверки. Не восстанавливай нечитаемые символы"

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

Тип ошибки	Риск	Как снизить риск
Неверно прочитанная цифра	Ошибочная сумма или идентификатор	Сверить с оригиналом
Неверная интерпретация цвета	Пропущенное состояние интерфейса	Проверить DOM и CSS
Вывод за пределами изображения	Предположение выдаётся за факт	Просить отделять наблюдения от гипотез
Утечка чувствительных данных	Нарушение политики безопасности	Маскировать данные до передачи

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

Флаг --image и его короткий аналог -i позволяют прикрепить к запросу одно или несколько изображений. Они особенно полезны, когда проблему проще показать, чем описать: скриншот ошибки, макет, диаграмма, фотография документа или результат визуального теста.

Лучший результат получается из связки «качественное изображение + конкретная инструкция + проверка результата». Ни один визуальный анализ не отменяет тестирование и сверку с исходным кодом.

Задача	Команда-шаблон	Рекомендация
Один скриншот	codex --image screen.png "Проанализируй проблему"	Указать ожидаемый результат
Краткая запись	codex -i screen.png "Найди ошибку"	Использовать в частых ручных запусках
Сравнение файлов	codex --image old.png --image new.png "Сравни изображения"	Обязательно задать порядок файлов
Другой проект	codex -C project --image image.png "Проверь компонент"	Учитывать рабочий каталог

1. Проверьте, что файл существует и доступен CLI.
2. Используйте читаемое изображение без лишних областей.
3. Заключайте путь в кавычки, если в нём есть пробелы.
4. Описывайте конкретную цель: найти, сравнить, объяснить, извлечь или предложить.
5. Для нескольких изображений повторяйте флаг и обозначайте роль каждого файла.
6. Не принимайте распознанные данные и предложенный код без проверки.
7. Для чувствительных документов заранее удаляйте или маскируйте закрытую информацию.
8. Если синтаксис отличается, проверьте возможности установленной версии с помощью codex --help.

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