Быстрый старт в CLI-клиенте

📚 Навигация по серии: Предыдущая статья 07 Обзор настольного приложения познакомила вас с графическим клиентом, параллельным выполнением задач и проверкой diff. В этой статье мы перейдем к работе с терминалом и разберем консольную утилиту codex: структуру команды, интерфейс TUI, основные параметры и слэш-команды. В следующей статье 09 Расширения для IDE (VS Code и др.) мы разберем интеграцию агента с редакторами кода.

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

Поработав с обоими интерфейсами более полугода, я пришел к выводу: настольное приложение оптимально для визуальной оценки (аудита), а CLI — для выполнения задач. Настольная версия удобна для построчного ревью изменений и параллельного ведения пяти потоков. Но если вам требуется настроить регулярные автоматические проверки кода, запускавать агента на удаленных серверах без GUI или интегрировать его в пайплайны CI/CD — все эти задачи решаются только через CLI.

Более того, консольная версия не является классической командной строкой. После запуска codex вы попадаете во встроенный полноэкранный интерфейс TUI (Terminal User Interface — терминальный пользовательский интерфейс). Он содержит чат, поле ввода и статусную строку, не уступая по информативности настольному приложению, но управляется полностью с клавиатуры. При первом запуске это вызывает приятное удивление: перед вами полноценный графический интерфейс, развернутый внутри консоли.

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

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

• Схему структуры вызовов команды codex с описанием подопций и параметров
• Описание трех областей интерфейса TUI (область вывода, строка ввода, статус-бар) и правил работы с ними
• Справочник по основным флагам и параметрам CLI (--model, --sandbox, --cd, --search, -i и др.), сверенный со спецификацией
• Список полезных слэш-команд и горячих клавиш терминала с пошаговым тестом для проверки
• Различия между интерактивным запуском TUI и автономным режимом exec для выбора оптимального пути

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

---

01 Структура вызовов CLI

Разберем структуру команды на понятные части. Вызов вида codex exec --sandbox workspace-write --model xxx "запрос" состоит из стандартных блоков.

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

Аналогия: заказ кофе. Базовая команда codex — это фраза «сделайте кофе». Выбор конкретного напитка (американо или латте) — это подкоманда (exec, resume, cloud). Ваши пожелания («добавь сироп, без льда») — это флаги и опции (параметры с -- в начале). Текст запроса («проверь этот код») — это сам заказ. Порядок аргументов всегда одинаков.

Схема команды:

codex   [子命令]   [选项...]   ["提示词"]
  │         │          │            │
 主命令   换跑法     调参数      要干的活

Описание блоков:

• Базовая команда codex: вызывает исполняемый файл. Запуск codex без параметров открывает интерактивный TUI.
• Подкоманда (Subcommand): определяет сценарий запуска. Например, exec запускает автономное выполнение без открытия интерфейса, resume продолжает прошлую сессию, login выполняет вход. По умолчанию открывается интерфейс TUI.
• Флаги (Options/Flags): параметры настройки, начинающиеся с - или --. Например, --model задает модель, --sandbox переключает песочницу, --cd указывает каталог запуска. Большинство флагов поддерживают сокращенную запись (например, -m вместо --model).
• Текст запроса (Prompt): строка в кавычках с описанием задачи. Если параметр опущен, Codex откроет чат для диалога; если указан — начнет выполнение задачи сразу после старта.

Примеры вызовов:

# 啥都不带，进交互界面
codex

# 带一句提示词，进界面后它直接开干
codex "解释一下这个项目的结构"

# 换个模型 + 指定工作目录
codex --model gpt-5.5 --cd ~/my-project "把 README 补全"

Имя модели gpt-5.5 указано для примера. Проверить доступные модели в вашей версии можно с помощью слэш-команды /model.

💡 Краткий вывод: Любой вызов строится по схеме: базовая команда + подкоманда (при наличии) + флаги параметров + текст запроса.

---

02 Разделы интерактивного интерфейса TUI

При первом запуске TUI важно сориентироваться в рабочей области. Интерфейс разделен на три логических блока:

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

Аналогия: окно стриминга. Область по центру отображает действия агента (вещание: планы, сгенерированный код, diff с подсветкой синтаксиса). Нижняя строка чата предназначена для ввода ваших сообщений и слэш-команд. Тонкая нижняя строка статуса выводит текущие параметры сессии (активная модель, занятость контекста, рабочий каталог).

Описание разделов:

• Диалоговая область (по центру): основное окно вывода. Здесь отображаются рассуждения AI, сгенерированные файлы и разметка diff с автоматической подсветкой синтаксиса для облегчения чтения.
• Строка ввода (внизу): единственный интерфейс взаимодействия. Предназначена для ввода запросов, файлов и вызова слэш-команд.
• Статусная строка (Status Bar): выводит служебные параметры сессии: модель, свободный объем контекста, рабочую директорию и текущую ветку Git. Строка настраивается с помощью команды /statusline.

Частая проблема новичков: частичное зависание интерфейса или графические артефакты при работе внутри терминальных мультиплексоров (например, tmux). Это не сбой программы. Для очистки экрана и принудительной перерисовки интерфейса нажмите сочетание клавиш Ctrl+L — это восстановит отображение без сброса активной сессии.

Не путайте это действие со слэш-командой:

Ctrl+L очищает визуальную область терминала, сохраняя контекст диалога. Слэш-команда /clear полностью сбрасывает историю сессии и удаляет контекст. Используйте их осмотрительно.

💡 Краткий вывод: Разделы TUI: окно чата, поле ввода и статусная строка. Сочетание Ctrl+L очищает экран терминала с сохранением контекста; /clear сбрасывает сессию.

---

03 Ключевые флаги настройки CLI

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

Аналогия: настройки фотоаппарата. Вы используете ограниченный набор переключателей (выдержка, диафрагма, ISO) для большинства снимков, обращаясь к дополнительному меню только при необходимости. Флаги CLI работают аналогично.

Справочник флагов Codex CLI:

Флаг (длинный / короткий)	Назначение	Пример использования
--model / -m	Указать модель для текущей сессии	codex -m gpt-5.5 "выполни рефакторинг"
--sandbox / -s	Задать режим песочницы (доступ на запись)	codex -s read-only "проведи аудит кода"
--ask-for-approval / -a	Настроить политику подтверждения действий	codex -a on-request "исправь ошибку"
--cd / -C	Указать рабочий каталог запуска	codex --cd ~/proj "опиши проект"
--add-dir	Предоставить доступ к дополнительному каталогу	codex --cd app --add-dir ../shared
--image / -i	Передать файл изображения (скриншот, макет)	codex -i error.png "разбери лог ошибки"
--search	Активировать поиск в реальном времени в сети	codex --search "напиши код под новое API"
--oss	Переключиться на запуск локальной LLM (через Ollama)	codex --oss "напиши скрипт офлайн"

Флаг --cd избавляет от необходимости вручную переходить в каталог проекта перед запуском клиента. Команда codex --cd ~/project запускает сессию непосредственно в указанной директории.

Параметры --sandbox и --ask-for-approval задают правила безопасности сессии (подробнее в Статьях 02 и 15). Сбалансированный вариант: --sandbox workspace-write совместно с --ask-for-approval on-request.

По умолчанию поиск Codex обращается к сохраненным кэшированным результатам OpenAI для снижения рисков инъекций. Флаг --search активирует обращение к поисковым системам в реальном времени. Будьте осторожны с кодом, полученным со сторонних веб-страниц.

Особый предупреждающий флаг:

⚠️ Флаг --dangerously-bypass-approvals-and-sandbox (или --yolo) отключает все проверки и песочницу, запуская команды без подтверждений со стороны пользователя. Рекомендуется только в изолированных тестовых контейнерах. Не используйте его при обычном программировании.

💡 Краткий вывод: Начните с освоения ключевых флагов: переключение модели (-m), настройки безопасности (-s/-a), смена каталога (--cd), передача картинок (-i) и сетевой поиск (--search).

---

04 Слэш-команды в процессе сессии

Слэш-команды вызываются непосредственно в чате TUI через символ / и служат для настройки активной сессии:

Аналогия: кнопки на пульте управления телевизора. Вы не выключаете телевизор из сети для регулировки громкости. Слэш-команды позволяют менять настройки (модели, права доступа, очистку контекста) на лету без перезапуска клиента.

Основные слэш-команды для работы:

Слэш-команда	Назначение	Когда использовать
/model	Смена активной модели в чате	Переход на более легкую или тяжелую модель
/permissions	Изменение прав доступа песочницы	Тонкая настройка подтверждений записи
/status	Просмотр ID потока, размера контекста и лимитов	Проверка лимитов и активных каталогов
/diff	Просмотр разметки Git diff	Проверка изменений перед коммитом
/compact	Сжатие истории диалога в саммари	Освобождение объема контекста сессии
/review	Запуск отдельного агента ревью	Дополнительный аудит сгенерированного кода
/init	Генерация шаблона файла AGENTS.md	Фиксация стандартов проекта
/clear	Сброс диалога и очистка контекста	Начало обсуждения новой задачи с нуля

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

Справочник по слэш-командам и правила создания пользовательских скриптов описаны в Статье 12. Для старта достаточно освоить приведенные базовые команды настройки.

💡 Краткий вывод: Четыре основных инструмента управления TUI: /model (выбор модели), /permissions (права), /status (лимиты), /diff (контроль изменений). Очередь выполнения настраивается клавишей Tab.

---

05 Горячие клавиши terminal

Основные клавиатурные сочетания при работе в TUI:

Сочетание клавиш	Назначение
Ctrl+C	Прерывание текущей операции или закрытие сессии (аналог /exit)
Ctrl+L	Принудительная перерисовка и очистка экрана терминала
↑ / ↓ (стрелки)	Перемещение по истории введенных промптов (включая макеты картинок)
Ctrl+R	Интерактивный поиск по истории промптов
Ctrl+O	Копирование последнего сгенерированного ответа в буфер обмена
Tab	Постановка команды в очередь выполнения во время расчетов
Esc Esc (при пустой строке)	Переход к редактированию вашего последнего отправленного сообщения
Ctrl+G	Написание длинного промпта во внешнем текстовом редакторе

Две полезные особенности работы в TUI:

Префикс ! для запуска локальных команд. Ввод символа ! в начале строки чата (например, !git status или !ls) запускает команду непосредственно в вашей системной консоли. Вывод команды передается в контекст диалога. Это позволяет быстро проверить файлы или статус Git без обращения к AI-вычислениям.

!git status

Сочетание Ctrl+G для написания длинных промптов. При необходимости ввода сложной многострочной спецификации нажмите Ctrl+G. Агент откроет текстовый редактор, заданный в системной переменной VISUAL или EDITOR. Напишите текст, сохраните и закройте файл — его содержимое автоматически скопируется в строку ввода чата.

Символ @ в строке ввода вызывает интерактивный поиск по файлам репозитория. Выберите нужный файл стрелками и нажмите Enter для добавления пути к нему в ваш промпт.

Спецификации раскладки клавиатуры и назначение сочетаний клавиш в TUI можно проверить и переназначить с помощью слэш-команды /keymap.

💡 Краткий вывод: Используйте префикс ! для запуска локальных команд, @ для быстрого указания файлов, Ctrl+G для открытия редактора длинных промптов и /keymap для просмотра раскладки клавиш.

---

06 Практический тест CLI

Выполним проверку основных функций в консольном клиенте TUI:

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

Команды для создания папки и запуска:

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

Ожидаемый результат: открытие интерфейса TUI на весь экран терминала.

Шаг 2: Проверьте статус параметров сессии

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

/status

Ожидаемый результат: вывод лога параметров активной сессии (модель, лимиты, свободный контекст).

Справочные утилиты (например, token-tracker на схеме выше) выводят эти метрики в графическом виде, показывая остаток токенов за 5 часов и 7 дней.

Шаг 3: Запустите локальную команду через префикс !

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

!echo hello-codex-cli

Ожидаемый результат: моментальный вывод строки hello-codex-cli без обращения к вычислениям AI.

Шаг 4: Проверьте историю введенных команд

Нажмите клавишу ↑ при пустой строке ввода.

Ожидаемый результат: вызов ранее введенного запроса в поле чата. Очистите поле.

Шаг 5: Проверка изменений и вызов /diff

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

新建一个文件 hi.txt，里面写一行 "hello from codex cli"。

После подтверждения создания файла введите команду:

/diff

Ожидаемый результат: вывод структуры изменений Git с подсветкой добавленных строк.

Шаг 6: Завершение сессии

/exit

Ожидаемый результат: закрытие TUI и возвращение в стандартный терминал.

Вы проверили базовые концепции управления консольным клиентом на практике.

💡 Краткий вывод: Тест CLI-сессии: проверка /status → вызов shell через ! → история промптов стрелками → ревью изменений через /diff → выход по /exit.

---

07 Интерактивный TUI против автономного запуска (exec)

Главным преимуществом CLI является поддержка автономного запуска без интерфейса TUI через команду codex exec.

Обычный запуск codex открывает TUI для пошагового согласования. Но для рутинных фоновых задач (составление ежедневных отчетов по логам Git, автоматический прогон тестов в CI/CD) интерактивный контроль избыточен. Подкоманда exec (или сокращенно codex e) выполняет задачу в фоне и возвращает результат в терминал.

Аналогия: обед в ресторане против заказа доставки на дом. Интерактивный режим — это обед в зале: вы наблюдаете за процессом и даете повару комментарии по ходу готовки. Автономный exec — это заказ доставки готовой еды: вы отправляете промпт, скрипт отрабатывает в фоне и выводит результат сборки в стандартный поток вывода (stdout).

Пример вызова:

codex exec "审查当前改动，列出潜在 bug"

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

Полезные флаги подкоманды exec:

Флаг подкоманды exec	Назначение
--model / -m	Имя целевой модели для выполнения
--json	Вывод в формате JSON-строк для автоматического парсинга
--output-last-message / -o	Запись итогового текстового ответа в файл
--skip-git-repo-check	Отключение обязательной проверки Git в папке запуска
--ephemeral	Запуск без записи истории сессии в локальный кэш

Сравнение интерактивного и автономного режимов:

Критерий	Интерактивный TUI	Автономный codex exec
Поведение по завершении	Ожидание команд в TUI	Завершение процесса и выход
Сценарий применения	Отладка логики, сложные архитектурные диалоги	Скрипты сборки, CI/CD, пакетные задачи
Требуется ли контроль	Да (пошаговое согласование)	Нет (выполнение в фоновом режиме)
Способ вывода результатов	Окно чата с подсветкой	Поток stdout, вывод структурированного JSON
Пример использования	Пошаговый рефакторинг сложных функций	Автоматическая генерация документации по часам

При интеграции в CI/CD используйте флаги --json и --output-last-message для сохранения структурированных логов процесса и итогового описания сборки на естественном языке.

Поскольку exec ориентирован на фоновую автоматизацию, политика подтверждения прав в нем сбрасывается в never. Во избежание случайных ошибок настраивайте строгие правила песочницы (--sandbox workspace-write или read-only) при запуске автономных сессий на рабочих репозиториях.

💡 Краткий вывод: Интерактивный режим TUI предназначен для пошаговой совместной разработки; автономный exec ориентирован на фоновую автоматизацию в CI/CD без участия человека. Это ключевое преимущество CLI перед настольным клиентом.

---

08 Резюме

Основные команды CLI:

Задача	Решение
Открытие чата TUI	Вызов codex (с промптом для автозапуска)
Настройка параметров старта	Флаги --model, --sandbox, --ask-for-approval
Смена рабочей папки	Флаг --cd <путь>
Передача изображения	Флаг -i <файл>
Управление параметрами в сессии	Слэш-команды /model, /status, /diff
Запуск локального скрипта	Префикс ! в строке ввода
Очистка артефактов экрана	Сочетание Ctrl+L
Написание сложного промпта	Сочетание Ctrl+G
Фоновая автоматизация	Вызов codex exec "задача"

Теперь вы можете: свободно читать синтаксис команды codex, ориентироваться в структуре TUI, использовать управляющие флаги и слэш-команды, пересылать вывод локальных скриптов префиксом !, вызывать редактор по Ctrl+G и выбирать между интерактивным режимом TUI и фоновым exec.

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

В следующей статье 09 · Интеграция с IDE (VS Code и др.) мы разберем расширения для редакторов кода (VS Code, Cursor). Мы научимся вызывать диалоговые панели и проверять diff изменений непосредственно в окне редактора.

---

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

• Разработка на Windows: особенности настройки путей и WSL
• Справочник по командам и параметрам настроек
• Установка и авторизация в системе (macOS, Windows, Linux)