Zero to Agent

Русский

中文
English
Español
Français
हिन्दी
العربية
Português

Русский

中文
English
Español
Français
हिन्दी
العربية
Português

Troubleshooting FAQ ​

📚 Навигация по серии: Предыдущая статья «36 Лучшие практики» описала выстраивание процессов эффективной разработки. В этой главе мы перейдем к устранению неполадок: разберем проблемы с установкой, авторизацией, правами на изменение файлов и падением качества ответов ИИ. В следующей статье «38 Глоссарий» приведен алфавитный справочник основных терминов.

Ответы на частые вопросы по установке, авторизации и настройке прав доступа Codex CLI.

— Друг, я выполнил команду npm install, но при вводе codex терминал пишет «command not found». Что делать? — У меня не открывается браузер при авторизации, а сам процесс бесконечно висит. Нужна ли настройка прокси? — Codex считывает мой код, но выдает ошибку при попытке изменить файл: пишет, что песочница запрещает запись. Хотя я ничего такого не настраивал.

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

Прочитав эту статью, вы получите:

  • Пошаговые решения для десяти типичных проблем, отсортированные по частоте их возникновения
  • Инструкции по устранению сбоев при установке, авторизации и настройке сетевого подключения
  • Анализ причин блокировки записи файлов песочницей и способы предоставления прав доступа
  • Сравнительную схему работы с переполненным окном контекста через /compact и /new
  • Универсальный трехшаговый алгоритм экспресс-диагностики Codex на вашем компьютере

01 Универсальный алгоритм: проверяем три параметра ​

Базовое правило: при возникновении любого сбоя не торопитесь переустанавливать систему. Проверьте последовательно три параметра: версию, статус авторизации и права доступа. Это позволяет локализовать большинство проблем.

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

bash
# 1. Проверка установки и версии CLI
codex --version

# 2. Проверка статуса авторизации в аккаунте
codex login status

# 3. Просмотр активных прав текущей сессии (внутри чата TUI)
/status

Первая команда подтверждает, что исполняемый файл доступен в системе. Вторая показывает, активен ли токен авторизации. Третья выводит текущий режим песочницы и политики подтверждений команд.

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

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

02 Ошибка «command not found» при запуске ​

Проблема на этапе первоначальной установки CLI.

Симптомы: после установки через npm при вводе команды codex терминал возвращает ошибку command not found: codex (команда не найдена) или процесс установки прерывается сообщениями красного цвета.

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

Решение:

  • Проверьте версию Node.js. Выполните команду node --version. Устаревшие версии (ниже LTS) могут не поддерживать современные CLI-пакеты. Обновите Node.js при необходимости.
  • Настройте переменную PATH. Выполните команду npm config get prefix для просмотра пути к глобальным пакетам. Убедитесь, что подкаталог bin этой папки прописан в переменной окружения PATH вашей операционной системы.
  • Устраните ошибки прав доступа (EACCES). Не устанавливайте глобальные пакеты через команду sudo npm install -g. Это приведет к проблемам с правами доступа при дальнейшей работе. Настройте локальный путь для глобальных пакетов npm или используйте менеджер версий nvm.
  • Используйте альтернативные способы установки. Если устранить проблемы с правами в npm не удается, установите CLI через другие каналы, описанные в документации.

Для операционной системы Windows типичные проблемы установки (WSL, пути к исполняемым файлам) описаны в 33-й статье.

💡 Резюме в одном предложении: Ошибка «команда не найдена» обычно вызвана отсутствием путей npm в переменной PATH, а ошибки записи устраняются настройкой прав локального каталога без использования sudo.

03 Ошибки авторизации и истечение сессии ​

Симптомы: при запуске codex login окно браузера не открывается или процесс авторизации зависает после подтверждения на сайте; либо во время работы возникает ошибка «Unauthorized / Session expired» (сессия истекла).

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

Решение:

  • При зависании процесса на локальной машине убедитесь, что порт 1455 не занят другими службами и не заблокирован локальным файрволом.
  • Для работы в безбраузерных средах (серверы по SSH, контейнеры Docker) используйте авторизацию по коду устройства (device auth):
bash
codex login --device-auth

Команда выведет одноразовый код и веб-ссылку. Откройте эту ссылку на любом устройстве с браузером (например, на смартфоне), введите код и подтвердите вход. Терминал на сервере авторизуется автоматически.

  • При сбое авторизации по коду скопируйте файл с токеном ~/.codex/auth.json с авторизованной локальной машины в аналогичную папку на сервере. Помните: данный файл содержит секретный токен доступа к вашему аккаунту, не публикуйте его содержимое и не добавляйте в репозитории Git.
  • При частом отключении сессии сбросьте кэш авторизации последовательным запуском команд codex logout и codex login. Логи процесса авторизации записываются в файл codex-login.log.

Выбор способа авторизации:

ОкружениеРекомендуемый метод
Локальный ПК с браузеромСтандартная команда codex login
Удаленный сервер / DockerАвторизация по коду устройства codex login --device-auth
Скрипты автоматизацииКопирование готового файла ~/.codex/auth.json
Корпоративная сеть с TLSНастройка сертификата в переменной CODEX_CA_CERTIFICATE

💡 Резюме в одном предложении: При отсутствии браузера на сервере используйте авторизацию через codex login --device-auth, а при сбоях сессий сбросьте кэш командами logout/login.

04 Ошибки сетевого подключения ​

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

Причины: отсутствие сетевого доступа к серверам OpenAI, блокировка трафика корпоративными TLS-прокси или использование самоподписанных сертификатов безопасности в сети компании.

Решение:

  • Убедитесь, что настроен стабильный доступ к серверам OpenAI. Сетевой прокси должен перенаправлять запросы терминала, а не только браузера.
  • Задайте системные переменные окружения HTTP_PROXY и HTTPS_PROXY в настройках вашей консоли для перенаправления запросов CLI через прокси-сервер.
  • При использовании в корпоративных сетях с дешифрацией SSL укажите путь к корневому сертификату компании в переменной окружения:
bash
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

При отсутствии этой переменной Codex попытается прочитать сертификат из системного файла SSL_CERT_FILE.

💡 Резюме в одном предложении: Настройте прокси-сервер для терминала и пропишите путь к сертификату компании в CODEX_CA_CERTIFICATE при ошибках SSL в корпоративной сети.

05 Ошибки выбора моделей ​

Симптомы: в меню /model не отображается нужная модель или при запуске CLI с флагом модели возвращается ошибка «Model not found / unavailable» (модель недоступна).

Причины: доступные модели привязаны к вашему тарифному плану и способу авторизации (подписка ChatGPT Pro vs токены API-ключа), либо вы указали имя устаревшей модели.

Решение:

  • Проверяйте список доступных моделей непосредственно в меню /model вашей сессии, не ориентируясь на устаревшие статьи в сети. Для большинства задач актуальны флагман gpt-5.5 и легкая модель gpt-5.4-mini.
  • Экспериментальная модель gpt-5.3-codex-spark доступна только для пользователей с активной подпиской ChatGPT Pro.
  • Проверьте конфигурационный файл ~/.codex/config.toml и аргументы запуска на наличие имен устаревших моделей gpt-5.2 и gpt-5.3-codex. При обнаружении замените их на актуальные.
  • Активную в данный момент модель проверяйте командой /status внутри чата.

💡 Резюме в одном предложении: Доступность моделей зависит от вашего тарифа, проверяйте список моделей через меню /model и не используйте устаревшие версии в конфигурациях.

06 Песочница блокирует изменение файлов ​

Симптомы: ИИ анализирует код и отвечает на вопросы, но выдает ошибку прав доступа при попытке изменить файлы проекта или запустить тесты.

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

Решение:

  • Для разового разрешения на изменение файлов текущей папки запустите сессию с флагами песочницы --sandbox (-s) и подтверждений --ask-for-approval (-a):
bash
codex --sandbox workspace-write --ask-for-approval on-request

Это разрешит запись файлов в пределах рабочей папки проекта с запросом подтверждений на потенциально опасные действия. Подробнее о режимах читайте в 15-й статье.

  • Для постоянной настройки прав пропишите уровни доступа в файле ~/.codex/config.toml. Вы можете использовать встроенные профили прав (permission profiles, Beta):
Профиль правОписание разрешенийПрименение
:read-onlyЧтение разрешено, запись заблокированаАнализ кода, поиск багов
:workspaceРазрешена запись в рабочей папке и временных каталогахЛокальная разработка (рекомендуется)
:danger-full-accessОтключение ограничений песочницыЗапуск только внутри изолированных контейнеров

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

💡 Резюме в одном предложении: Блокировка записи файлов — это базовая защита Codex; для работы в проекте используйте параметры запуска --sandbox workspace-write или укажите профиль :workspace в файле настроек.

07 Ошибки подключения внешних серверов MCP ​

Симптомы: после добавления сервера MCP его инструменты не отображаются в выводе команды /mcp или при запуске возвращается ошибка соединения.

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

Решение:

  • Запустите сервер MCP в терминале как отдельный процесс, без участия Codex. Это позволит увидеть ошибки компиляции или отсутствие библиотек.
  • Проверьте правильность путей и переменных окружения в блоке настроек MCP в файле config.toml.
  • Убедитесь, что песочница не блокирует доступ сервера MCP к сети (в режиме workspace-write сеть по умолчанию отключена).

Подробный разбор интеграции по протоколу MCP приведен в 20-й статье.

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

08 Падение качества ответов в длинных сессиях ​

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

Причины: переполнение лимита окна контекста (context window). При накоплении большого объема сообщений старые данные вытесняются из памяти ИИ.

Решение:

  • Если вы продолжаете решать текущую задачу, введите команду /compact для сжатия истории сообщений в краткое резюме, что освободит память для новых запросов.
  • При переходе к новой задаче запустите чистую сессию командой /new (сохраняет историю на экране) или /clear (очищает экран консоли).

Выбор команды очистки памяти:

ЗадачаРекомендуемая команда
Продолжение работы над текущей сложной фичей/compact (сжатие истории с сохранением контекста)
Переход к реализации следующей задачи/new (новый диалог в текущем окне)
Полный сброс сессии и очистка терминала/clear
Проверка объема свободной памяти сессии/status

💡 Резюме в одном предложении: При ухудшении качества ответов в длинном чате используйте команду /compact для сжатия истории или откройте новую чистую сессию командой /new.

09 Оптимизация расходов и лимитов токенов ​

Симптомы: быстрое исчерпание лимита запросов на тарифе или высокие счета за использование токенов при работе через API-ключи.

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

Решение:

  • Не используйте флагман gpt-5.5 с интенсивностью high или xhigh для простых правок (исправление опечаток, форматирование).
  • Переводите Codex на легкую модель gpt-5.4-mini с уровнем рассуждений low для простых задач.
  • Зафиксируйте в config.toml сбалансированный режим рассуждений по умолчанию:
toml
model_reasoning_effort = "medium"

Для разовой смены интенсивности в конкретном запросе используйте ключ -c model_reasoning_effort=medium при запуске команды.

  • Массовые рутинные операции по проекту делегируйте под-агентам на базе легкой модели mini.

💡 Резюме в одном предложении: Снижайте расходы токенов за счет перевода рутинных задач на модель gpt-5.4-mini и ограничения интенсивности рассуждений уровнем medium по умолчанию.

10 Откат неверных изменений кода ​

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

Причины: Codex записывает изменения напрямую в файлы проекта и не хранит резервные копии измененных документов.

Решение:

  • Всегда делайте коммит изменений Git перед запуском Codex. Это ваше главное правило безопасности. При сбое вы сможете мгновенно откатить изменения командой:
bash
git restore .
  • Если репозиторий не использовался, вам придется восстанавливать код вручную, сравнивая изменения по истории TUI.
  • Настраивайте жесткие ограничения песочницы (:read-only) для анализа кода, чтобы ИИ физически не мог перезаписать файлы до утверждения вами плана изменений.

💡 Резюме в одном предложении: Фиксируйте состояние кода в Git перед каждым запуском Codex, чтобы иметь возможность мгновенно откатить неудачные изменения командой git restore.

Итоги ​

Мы разобрали типичные проблемы при установке и эксплуатации Codex и методы их локализации.

Краткий чек-лист самопроверки при сбоях:

  • Сеть — настройте прокси для консоли и проверьте доступ к доменам OpenAI.
  • Права — используйте флаги --sandbox workspace-write для разрешения записи файлов проекта.
  • Память — вовремя очищайте переполненный чат командами /compact или /new.
  • Откат — всегда сохраняйте состояние кода в Git перед началом работы с ИИ.

Логический подход к диагностике позволяет быстро вернуть Codex в рабочее состояние.

В следующей статье 38 · Глоссарий мы завершим изучение Codex. Мы соберем все ключевые термины (Sandbox, Approval, MCP, Subagents, TUI, CLI) в единый алфавитный справочник для быстрого поиска определений.

Рекомендуемое чтение ​