Команда codex debug models в Codex CLI служит для просмотра сведений о моделях, которые текущая установка CLI может определить и показать в своём каталоге или конфигурации. Это диагностический инструмент: он помогает понять, какие модели видит именно установленный экземпляр Codex CLI, а также отделить проблему с моделью от проблем с авторизацией, сетью, конфигурацией или самой версией программы.
Список моделей — это не всегда список моделей, к которым у вас уже есть доступ. Он показывает результат работы CLI с его каталогом, настройками и источниками данных, но не гарантирует успешный запуск каждой модели в конкретной организации или аккаунте.
Команда особенно полезна в ситуациях, когда интерфейс предлагает не тот набор моделей, параметр выбора модели не срабатывает, после обновления CLI появились расхождения или нужно быстро собрать диагностическую информацию. Ниже разберём назначение команды, базовый синтаксис, особенности вывода, границы её возможностей и практические сценарии использования без предположений о функциях, которых у конкретной версии Codex CLI может не быть.
- Обзор команды codex debug models
- Зачем исследовать каталог моделей
- Что означает «доступная модель»
- Синтаксис команды
- Команда без позиционных аргументов: codex debug models
- Справка для codex debug models
- Необязательные параметры и ограничения версии
- Практические примеры
- Пример 1. Первый просмотр списка моделей
- Пример 2. Проверка наличия конкретного имени во внешнем фильтре
- Пример 3. Сохранение результата для сравнения
- Пример 4. Сравнение до и после обновления
- Пример 5. Сопоставление двух установок Codex CLI
- Пример 6. Проверка конфигурации выбора модели
- Пример 7. Диагностика ошибки «модель не найдена»
- Пример 8. Проверка результата в автоматизации
- Пример 9. Диагностика после изменения переменных окружения
- Пример 10. Сбор минимального диагностического отчёта
- Пример 11. Проверка справки перед использованием неизвестного флага
- Пример 12. Сравнение с фактическим рабочим запуском
- Как читать вывод команды
- Диагностика проблем с определением моделей
- Модель отсутствует в списке
- Модель есть, но запуск не работает
- Ограничения и безопасная интерпретация
- Рекомендации по рабочему использованию
- Итоги
Обзор команды codex debug models
Подкоманда находится в диагностической ветке Codex CLI. В отличие от обычного запуска codex, который открывает рабочую сессию, codex debug models предназначена не для выполнения задачи, а для проверки того, какие сведения о моделях доступны локальному клиенту.
Диагностическая команда отвечает прежде всего на вопрос «что видит CLI?», а не на вопрос «что гарантированно разрешено моему аккаунту?». Это важное различие, которое предотвращает множество ошибочных выводов.
При выполнении команда обычно обращается к внутреннему каталогу моделей или к данным, которыми Codex CLI располагает для выбора модели. Конкретные столбцы, порядок строк, названия полей и формат представления зависят от версии CLI. Поэтому вывод следует воспринимать как диагностический снимок текущего окружения, а не как вечный и неизменный справочник.
| Что можно выяснить | Какой вопрос это закрывает | Что нельзя утверждать только по выводу |
|---|---|---|
| Какие модели перечисляет CLI | Видит ли текущая установка ожидаемые записи? | Что каждая модель доступна аккаунту |
| Есть ли различия между окружениями | Почему на одном компьютере список другой? | Что причина различий обязательно в сети |
| Какие метаданные показывает каталог | Есть ли сведения о названии или свойствах модели? | Что все поля являются публичным API |
| Изменился ли список после обновления | Повлияло ли обновление CLI на обнаружение моделей? | Что изменение списка означает поломку |
Команда не заменяет проверку рабочего запуска. Модель может присутствовать в списке, но быть недоступной из-за прав, ограничений организации, неподходящего API-режима, отсутствующей авторизации или временной ошибки сервиса. И наоборот, отсутствие конкретной записи может быть следствием устаревшего каталога, особенностей версии или локальной конфигурации.
Зачем исследовать каталог моделей
Исследование каталога полезно, когда необходимо сначала установить факт, а уже потом искать причину. Без этого диагностика часто превращается в перебор случайных параметров: пользователь меняет имя модели, переменные окружения и конфигурационные файлы, хотя проблема находится совсем в другом месте.
$ codex debug models # Сохраните фактический вывод команды. # Сравните его с ожидаемым списком и с выводом на другом окружении.
| Ситуация | Что проверяет команда | Следующий шаг |
|---|---|---|
| Ожидаемая модель не отображается | Есть ли запись в локально видимом каталоге | Проверить версию CLI и источник конфигурации |
| Список неожиданно изменился | Изменился ли набор моделей после обновления | Сравнить версии и сохранённые результаты |
| Запуск модели завершается ошибкой | Известна ли модель диагностическому слою | Проверить права, сеть и рабочий запуск |
| Два компьютера показывают разное | Различается ли локальный результат | Сопоставить версии, конфигурацию и окружение |
Что означает «доступная модель»
В контексте этой команды слово «доступная» нужно употреблять осторожно. Оно может означать, что модель присутствует в данных, известных CLI, но не обязательно означает, что конкретный пользователь может успешно отправить ей запрос.
| Уровень проверки | Что подтверждается | Чего ещё не хватает |
|---|---|---|
| Модель есть в выводе | CLI смог её перечислить | Подтверждения прав и работоспособности запроса |
| Модель выбрана в конфигурации | Настройка содержит соответствующее значение | Подтверждения, что значение принято сервером |
| Тестовый запуск успешен | Запрос прошёл в конкретном окружении | Гарантии стабильности и доступности в будущем |
| Модель отвечает с ошибкой доступа | Сервис распознал запрос, но отказал | Необходимость проверить права или ограничения |
Синтаксис команды
Базовый синтаксис команды предельно короткий: в стандартном сценарии указывают только последовательность codex debug models. Это важно: не следует автоматически добавлять вымышленные параметры вроде --provider, --all или --json, если их нет в справке именно вашей версии CLI.
Для диагностических подкоманд справка конкретной версии важнее примера из старой статьи: интерфейс CLI может развиваться, а внутренние команды особенно чувствительны к изменениям.
| Часть команды | Роль | Обязательность |
|---|---|---|
codex |
Запуск Codex CLI | Обязательна |
debug |
Переход к диагностическим подкомандам | Обязательна |
models |
Выбор диагностики каталога моделей | Обязательна |
| Дополнительные параметры | Зависят от установленной версии | Не следует предполагать заранее |
Команда без позиционных аргументов: codex debug models
Основной вариант не содержит имени модели после models. Он запрашивает общий диагностический вывод, а не проверяет одну выбранную модель по имени.
$ codex debug models
Если команда отработала успешно, изучайте не только сами названия, но и структуру результата: наличие идентификаторов, отображаемых имён, признаков доступности или иных полей, если они предусмотрены вашей версией. Не стоит трактовать незнакомое поле без сверки со справкой, документацией или исходным кодом соответствующего релиза.
Справка для codex debug models
Для проверки поддерживаемых параметров используйте встроенную справку. Она особенно важна перед автоматизацией, потому что набор флагов может различаться между версиями.
$ codex debug models --help
Если такой вызов не принимается, можно запросить справку на уровне родительской команды:
$ codex debug --help $ codex --help
| Проверка | Команда | Зачем нужна |
|---|---|---|
| Справка подкоманды | codex debug models --help |
Показывает параметры, признанные текущей версией |
| Справка диагностического раздела | codex debug --help |
Помогает убедиться, что подкоманда существует |
| Общая справка | codex --help |
Показывает общую структуру CLI |
Необязательные параметры и ограничения версии
В опубликованных примерах иногда встречаются флаги, которые относятся к другой версии CLI, обёртке, скрипту или соседней диагностической команде. Поэтому корректный способ узнать синтаксис — запросить справку локально и проверить код возврата команды.
| Намерение пользователя | Безопасный подход | Риск неправильного подхода |
|---|---|---|
| Получить машинно читаемый вывод | Проверить, есть ли соответствующий флаг в --help |
Команда завершится ошибкой из-за неизвестного параметра |
| Посмотреть одну модель | Получить полный вывод и отфильтровать его внешним инструментом | Можно приписать CLI несуществующий аргумент |
| Указать провайдера | Проверить документацию именно вашей сборки | Каталог может не поддерживать такой фильтр |
| Использовать в CI | Зафиксировать версию и протестировать синтаксис | Обновление сломает автоматическую проверку |
Практические примеры
Ниже приведены сценарии, в которых команда помогает отвечать на конкретные диагностические вопросы. Примеры намеренно не предполагают фиксированный формат вывода: у разных релизов Codex CLI он может выглядеть по-разному.
Пример 1. Первый просмотр списка моделей
Начните с обычного запуска без дополнительных параметров. Это базовая точка отсчёта, которую удобно сохранить перед изменениями конфигурации.
$ codex debug models # Просмотрите весь результат. # Отметьте названия и поля, которые выводит именно ваша версия.
| Наблюдение | Осторожный вывод | Необоснованный вывод |
|---|---|---|
| Модель присутствует | Она известна диагностическому слою CLI | Она гарантированно разрешена аккаунту |
| Модель отсутствует | Текущий вывод её не содержит | Модель окончательно недоступна |
| Вывод пустой | Нужно исследовать версию, конфигурацию или ошибку выполнения | В сервисе нет моделей |
Пример 2. Проверка наличия конкретного имени во внешнем фильтре
У команды может не быть собственного аргумента для фильтрации по имени. Если нужно быстро найти строку в уже полученном выводе, используйте стандартный инструмент операционной системы, не выдавая его за функцию Codex CLI.
$ codex debug models | grep -i "название-модели"
В Windows вместо grep можно применить findstr:
PS> codex debug models | findstr /I "название-модели"
Отсутствие совпадения означает только то, что указанная текстовая последовательность не встретилась в стандартном выводе. Возможно, CLI показывает другое отображаемое имя, идентификатор или сокращённую запись.
Пример 3. Сохранение результата для сравнения
Снимок вывода помогает увидеть изменения после обновления Codex CLI или изменения окружения.
$ codex debug models > models-before.txt $ cat models-before.txt
Сохранение результата не превращает его в официальный реестр. Это локальная диагностическая фиксация, полезная именно для сравнения.
Пример 4. Сравнение до и после обновления
Если после обновления список выглядит иначе, сохраните два вывода и сравните их обычными средствами.
$ codex debug models > models-new.txt $ diff -u models-before.txt models-new.txt
| Изменение | Возможное объяснение | Что проверить дополнительно |
|---|---|---|
| Появились новые строки | Обновился каталог или формат вывода | Версию CLI и описание релиза |
| Исчезли строки | Изменились встроенные данные или фильтрация | Конфигурацию и права доступа |
| Изменились только заголовки | Изменился формат представления | Смысл полей в справке |
| Вывод стал ошибочным | Проблема запуска, окружения или несовместимости | Код возврата и сообщение об ошибке |
Пример 5. Сопоставление двух установок Codex CLI
Разные результаты на рабочем компьютере и в контейнере не следует сразу объяснять разными правами. Сначала сравните версии и сами диагностические снимки.
# На первом окружении $ codex --version $ codex debug models > models-workstation.txt # В контейнере или на втором окружении $ codex --version $ codex debug models > models-container.txt
| Что сравнивать | Почему это важно |
|---|---|
| Версию Codex CLI | Разные релизы могут иметь разные каталоги и формат |
| Операционную систему | Могут различаться пути и переменные окружения |
| Файл конфигурации | Локальные настройки могут влиять на поведение CLI |
| Авторизацию | Разные профили могут иметь разные разрешения |
| Сетевые ограничения | Прокси и firewall способны менять результат внешних запросов |
Пример 6. Проверка конфигурации выбора модели
Если CLI запускается с неожиданной моделью, сначала отделите два вопроса: видит ли её каталог и какое значение задаёт конфигурация. Команда codex debug models отвечает только на первый вопрос в пределах своего вывода.
$ codex debug models $ codex --help # Затем проверьте документацию вашей версии о параметре выбора модели # и сопоставьте его значение с идентификаторами из диагностического вывода.
Не меняйте сразу несколько настроек. Иначе после исправления будет трудно понять, какая именно перемена повлияла на результат.
Пример 7. Диагностика ошибки «модель не найдена»
При сообщении о неизвестной модели полезно проверить, существует ли соответствующая запись в выводе команды.
$ codex debug models > available-models.txt $ grep -i "model-name" available-models.txt
| Результат фильтрации | Что это может означать | Дальнейшее действие |
|---|---|---|
| Совпадение найдено | Имя или идентификатор присутствует в выводе | Проверить точность значения и права доступа |
| Совпадение не найдено | В стандартном выводе такой текст отсутствует | Проверить точный идентификатор и версию CLI |
| Команда завершилась ошибкой | Нельзя делать вывод о каталоге моделей | Исследовать само сообщение об ошибке |
Пример 8. Проверка результата в автоматизации
В CI команду можно использовать как предварительный диагностический шаг, но не следует считать сам факт ненулевого или нулевого кода возврата доказательством полной доступности каждой модели.
$ set -o pipefail
$ codex debug models | tee models-ci.txt
$ status=${PIPESTATUS[0]}
$ echo "codex debug models exit code: $status"
$ test "$status" -eq 0
Такой сценарий проверяет, что команда смогла выполниться в CI-окружении. Для проверки реального запроса к модели нужен отдельный, разрешённый вашей политикой тестовый запуск.
Пример 9. Диагностика после изменения переменных окружения
Если результат изменился после настройки прокси, профиля или иных переменных, полезно сравнить снимки до и после изменения, не публикуя секреты.
$ codex debug models > models-default.txt # Измените окружение согласно документации вашей организации $ codex debug models > models-configured.txt $ diff -u models-default.txt models-configured.txt
Не помещайте в отчёт значения токенов, ключей и чувствительных переменных. Сам вывод каталога может быть менее чувствительным, но перед отправкой в поддержку его всё равно стоит просмотреть.
Пример 10. Сбор минимального диагностического отчёта
Для обращения к администратору или в поддержку полезно приложить воспроизводимые факты: версию CLI, операционную систему, команду и её вывод.
$ {
echo "Codex version:"
codex --version
echo
echo "Models diagnostic:"
codex debug models
} 2>models-debug-error.txt | tee models-debug-report.txt
| Элемент отчёта | Практическая ценность |
|---|---|
| Версия Codex CLI | Позволяет сопоставить поведение с конкретным релизом |
| Команда запуска | Исключает неоднозначность воспроизведения |
| Стандартный вывод | Показывает, что именно увидел пользователь |
| Сообщения об ошибках | Помогают отличить ошибку каталога от ошибки окружения |
| Описание окружения | Объясняет различия между локальным компьютером и CI |
Пример 11. Проверка справки перед использованием неизвестного флага
Если в статье, скрипте или сообщении коллеги встретился дополнительный параметр, сначала проверьте его существование в своей установке.
$ codex debug models --help $ codex debug models --unknown-option
Второй вызов приведён специально как диагностический пример: неизвестный параметр должен привести к сообщению об ошибке, а не к скрытому включению какой-либо функции. Не используйте подобную проверку в автоматизации без обработки ожидаемого ненулевого кода возврата.
Пример 12. Сравнение с фактическим рабочим запуском
Финальная проверка должна разделять каталог и реальную доступность. Сначала сохраните список, затем выполните обычную операцию Codex CLI в соответствии с документацией вашей версии и политикой доступа.
$ codex debug models > models-catalog.txt # Далее используйте штатный способ запуска Codex # с моделью, которая указана в вашей конфигурации. $ codex
| Итог | Корректная интерпретация |
|---|---|
| Есть в каталоге и рабочий запуск успешен | Модель успешно использована в данном окружении в данный момент |
| Есть в каталоге, но запуск запрещён | Каталог не равен разрешениям аккаунта |
| Нет в каталоге, но другой путь запуска работает | Нужно изучить различия идентификаторов и версий |
| Нет в каталоге и запуск не работает | Вероятна проблема с именем, конфигурацией, правами или поддержкой |
Как читать вывод команды
Главная сложность начинается не с запуска, а с интерпретации результата. Пользователь видит таблицу или список названий и естественным образом воспринимает его как перечень гарантированно доступных моделей. На практике это лишь один слой диагностики.
Наличие записи показывает обнаружение, а не успешное выполнение запроса. Между этими событиями находятся авторизация, права организации, сетевой маршрут, корректность идентификатора и состояние сервиса.
Если вывод содержит несколько похожих полей, не смешивайте отображаемое имя с идентификатором. Человеко-читаемое название может быть предназначено для интерфейса, тогда как для конфигурации требуется точное машинное значение. Используйте только те поля, назначение которых подтверждено справкой или документацией вашей версии.
| Тип данных в выводе | Как обычно использовать | Чего избегать |
|---|---|---|
| Идентификатор | Сверять с настройками и сообщениями об ошибках | Менять регистр или сокращать без оснований |
| Отображаемое имя | Понимать, какая модель имеется в виду | Считать его допустимым значением конфигурации |
| Описание или метаданные | Сравнивать записи между версиями | Приписывать полю официальный контракт |
| Статусный признак | Учитывать как сигнал диагностики | Считать его гарантией доступа к API |
Диагностика проблем с определением моделей
Когда ожидаемая модель не отображается, проблема может находиться на нескольких уровнях: старая версия CLI, неверный идентификатор, изменённый каталог, локальная конфигурация, сетевые ограничения или различия между профилями. Команда помогает сузить область поиска, но не всегда определяет единственную причину автоматически.
Хорошая диагностика движется от наблюдаемого факта к проверяемой гипотезе: сначала фиксируется вывод, затем меняется один фактор, после чего результат сравнивается.
Начните с повторного запуска в том же терминале. Затем запишите версию CLI, проверьте справку, сравните окружение с рабочим компьютером и только после этого исследуйте авторизацию. Такой порядок экономит время: нет смысла отлаживать права аккаунта, если установленная версия вообще не знает нужной записи.
| Шаг | Проверка | Что помогает исключить |
|---|---|---|
| 1 | codex --version |
Случай с устаревшим или неожиданным релизом |
| 2 | codex debug models |
Отсутствие записи в видимом каталоге |
| 3 | codex debug models --help |
Ошибочные предположения о параметрах |
| 4 | Сравнение конфигурации | Различия локальных настроек |
| 5 | Тестовый рабочий запуск | Отличие каталога от реального доступа |
Модель отсутствует в списке
Сначала проверьте точность названия. В экосистемах с большим числом моделей легко перепутать отображаемое имя, идентификатор, устаревший псевдоним и значение из документации другого инструмента.
Затем сопоставьте версию CLI с документацией. Если в документации описана более новая модель, а локальный каталог её не показывает, это может быть обычным расхождением версий, а не неисправностью.
Модель есть, но запуск не работает
В этом случае команда уже дала важный результат: запись распознаётся диагностическим слоем. Дальше проверяйте авторизацию, права проекта или организации, сетевую доступность и точное значение параметра выбора модели.
| Симптом запуска | Вероятный класс причины | Что проверить |
|---|---|---|
| Неизвестная модель | Ошибка имени или несовместимый каталог | Идентификатор, версию и конфигурацию |
| Отказ в доступе | Права пользователя или организации | Профиль, разрешения и политику доступа |
| Ошибка сети | Прокси, DNS, firewall или сервис | Сетевой маршрут и переменные окружения |
| Неверный параметр | Несовместимая версия CLI | Локальную справку и документацию релиза |
Ограничения и безопасная интерпретация
codex debug models полезна именно как узкий диагностический инструмент. Не стоит превращать её в универсальный тест состояния всей платформы или в доказательство того, что каждая показанная модель доступна каждому пользователю.
Чем уже сформулирован вопрос, тем точнее ответ команды: «что перечисляет мой CLI?» — хороший вопрос; «почему сервис отказал в запросе?» — уже задача для нескольких независимых проверок.
Также учитывайте, что формат вывода может измениться. Если скрипт разбирает строки по позициям или ожидает конкретные заголовки, обновление CLI способно нарушить такую автоматизацию. Для критичных процессов фиксируйте версию, тестируйте обновления и обрабатывайте ошибки явно.
| Ошибочное предположение | Более точная формулировка |
|---|---|
| Все показанные модели доступны мне | CLI перечисляет эти модели в текущем диагностическом контексте |
| Модель отсутствует навсегда | Она отсутствует в выводе этой версии и этого окружения |
| Нулевой код возврата проверяет API | Команда успешно выполнила собственную диагностическую операцию |
| Одинаковый список означает одинаковые права | Каталоги совпадают, но права нужно проверять отдельно |
| Любой флаг из интернета поддерживается | Поддержка параметра подтверждается локальной справкой |
Рекомендации по рабочему использованию
Для повседневной диагностики достаточно придерживаться короткого алгоритма: запустить команду, сохранить вывод, зафиксировать версию, сравнить с ожидаемым результатом и затем проверить реальный рабочий сценарий. Такой подход лучше, чем многократный запуск команды без записи результатов.
- Запускайте
codex debug modelsв том же окружении, где возникает проблема. - Сохраняйте вывод до и после обновления CLI.
- Проверяйте справку перед использованием любого дополнительного флага.
- Разделяйте обнаружение модели и подтверждение доступа к ней.
- Не публикуйте токены и секретные переменные вместе с диагностическим отчётом.
- Для CI фиксируйте версию CLI и учитывайте возможные изменения формата вывода.
| Задача | Минимальный набор действий | Результат |
|---|---|---|
| Проверить текущий каталог | Запустить codex debug models |
Снимок сведений, видимых CLI |
| Проверить синтаксис | Запустить codex debug models --help |
Параметры конкретной версии |
| Сравнить окружения | Сохранить вывод и версии на обеих машинах | Набор проверяемых различий |
| Подготовить обращение в поддержку | Приложить команду, версию, вывод и ошибку | Воспроизводимый диагностический отчёт |
Итоги
Команда codex debug models помогает увидеть, какие сведения о моделях доступны текущему Codex CLI. Её основная ценность — не в запуске моделей и не в проверке всех разрешений аккаунта, а в создании понятной отправной точки для диагностики.
Если модель отображается, это подтверждает её присутствие в видимом каталоге, но не гарантирует успешный запрос. Если модель отсутствует, это повод проверить версию, идентификатор, конфигурацию и окружение, а не окончательный приговор её доступности. Такой аккуратный подход позволяет не путать локальное обнаружение, право доступа и фактическую работоспособность сервиса.
В практической работе команда особенно полезна вместе с codex --version, встроенной справкой, сохранением результатов и отдельным тестом рабочего запуска. Именно сочетание этих проверок превращает короткую диагностическую команду в надёжный инструмент поиска проблем, а не в очередной магический шар для терминала.