Устранение неполадок

Это руководство содержит решения распространённых проблем и советы по отладке, включая следующие темы:

• Ошибки аутентификации или входа в систему
• Часто задаваемые вопросы (FAQ)
• Советы по отладке
• Существующие проблемы на GitHub, схожие с вашей, или создание новых проблем

Ошибки аутентификации или входа в систему

• Ошибка: UNABLE_TO_GET_ISSUER_CERT_LOCALLY, UNABLE_TO_VERIFY_LEAF_SIGNATURE или unable to get local issuer certificate

  • Причина: Вы, возможно, находитесь в корпоративной сети с брандмауэром, который перехватывает и проверяет трафик SSL/TLS. Это часто требует доверия к пользовательскому корневому сертификату центра сертификации (CA) со стороны Node.js.
  • Решение: Установите переменную окружения NODE_EXTRA_CA_CERTS, указав абсолютный путь к файлу корневого сертификата CA вашей организации.
    • Пример: export NODE_EXTRA_CA_CERTS=/путь/к/вашему/corporate-ca.crt

• Ошибка: Device authorization flow failed: fetch failed

  • Причина: Node.js не может получить доступ к конечным точкам OAuth Qwen (часто из-за прокси-сервера или проблем с доверием SSL/TLS). При наличии Qwen Code также выводит основную причину ошибки (например: UNABLE_TO_VERIFY_LEAF_SIGNATURE).
  • Решение:
    • Убедитесь, что вы можете открыть https://chat.qwen.ai с того же компьютера и в той же сети.
    • Если вы используете прокси-сервер, укажите его с помощью команды qwen --proxy <url> (или установите параметр proxy в файле settings.json).
    • Если в вашей сети используется корпоративный CA для инспекции TLS, задайте переменную NODE_EXTRA_CA_CERTS, как описано выше.

• Проблема: Не удается отобразить интерфейс после сбоя аутентификации

  • Причина: Если аутентификация завершилась неудачно после выбора типа аутентификации, значение параметра security.auth.selectedType может быть сохранено в файле settings.json. При перезапуске CLI может «зависнуть», пытаясь выполнить аутентификацию с ранее неудачным типом и не отобразить интерфейс.
  • Решение: Удалите параметр security.auth.selectedType из файла settings.json:
    • Откройте ~/.qwen/settings.json (или ./.qwen/settings.json — для настроек, специфичных для проекта)
    • Удалите поле security.auth.selectedType
    • Перезапустите CLI, чтобы он снова предложил выбрать способ аутентификации

Часто задаваемые вопросы (FAQ)

• В: Как обновить Qwen Code до последней версии?

  • О: Если вы установили его глобально через npm, обновите его с помощью команды npm install -g @qwen-code/qwen-code@latest. Если вы собрали его из исходного кода, получите последние изменения из репозитория и выполните пересборку командой npm run build.

• В: Где хранятся файлы конфигурации или настроек Qwen Code?

  • О: Конфигурация Qwen Code хранится в двух файлах settings.json:

    1. В вашем домашнем каталоге: ~/.qwen/settings.json.
    2. В корневом каталоге вашего проекта: ./.qwen/settings.json.

    Подробнее см. в разделе Конфигурация Qwen Code.

• В: Почему в выводе статистики не отображаются кэшированные подсчёты токенов?

  • О: Информация о кэшированных токенах отображается только при использовании кэшированных токенов. Эта функция доступна пользователям API-ключей (Qwen API-ключ или Google Cloud Vertex AI), но недоступна пользователям, вошедшим через OAuth (например, личные или корпоративные учётные записи Google — Gmail или Google Workspace соответственно). Причина в том, что API Qwen Code Assist не поддерживает создание кэшированного контента. Тем не менее, общее количество использованных токенов можно посмотреть с помощью команды /stats.

Распространённые сообщения об ошибках и способы их устранения

• Ошибка: EADDRINUSE (адрес уже используется) при запуске сервера MCP.

  • Причина: Другой процесс уже использует порт, к которому пытается привязаться сервер MCP.
  • Решение:
    Остановите другой процесс, использующий этот порт, или настройте сервер MCP на использование другого порта.

• Ошибка: команда не найдена (при попытке запустить Qwen Code с помощью qwen).

  • Причина: CLI установлен некорректно или его исполняемый файл отсутствует в переменной окружения PATH.
  • Решение:
    Способ обновления зависит от способа установки Qwen Code:
    • Если вы установили qwen глобально, убедитесь, что глобальный каталог бинарных файлов npm присутствует в вашей переменной PATH. Обновите пакет командой npm install -g @qwen-code/qwen-code@latest.
    • Если вы запускаете qwen из исходного кода, убедитесь, что используете правильную команду для его вызова (например, node packages/cli/dist/index.js ...). Чтобы обновить, получите последние изменения из репозитория и выполните пересборку командой npm run build.

• Ошибка: MODULE_NOT_FOUND или ошибки импорта.

  • Причина: Зависимости установлены некорректно или проект ещё не собран.
  • Решение:
    1. Выполните npm install, чтобы убедиться, что все зависимости установлены.
    2. Выполните npm run build, чтобы собрать проект.
    3. Убедитесь, что сборка завершилась успешно, выполнив npm run start.

• Ошибка: «Операция запрещена», «Отказано в доступе» или аналогичная.

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

• Qwen Code не работает в интерактивном режиме в средах «CI»

  • Проблема: Qwen Code не переходит в интерактивный режим (приглашение не отображается), если задана переменная окружения, начинающаяся с CI_ (например, CI_TOKEN). Это происходит потому, что пакет is-in-ci, используемый базовой UI-библиотекой, обнаруживает такие переменные и делает вывод, что среда — неинтерактивная CI-среда.
  • Причина: Пакет is-in-ci проверяет наличие переменных CI, CONTINUOUS_INTEGRATION или любой переменной с префиксом CI_. При обнаружении любой из них он определяет среду как неинтерактивную, из-за чего CLI не запускается в интерактивном режиме.
  • Решение: Если переменная с префиксом CI_ не требуется для работы CLI, её можно временно удалить перед выполнением команды. Например: env -u CI_TOKEN qwen.

• Режим отладки (DEBUG) не включается из .env-файла проекта

  • Проблема: Установка DEBUG=true в .env-файле проекта не включает режим отладки для CLI.
  • Причина: Переменные DEBUG и DEBUG_MODE автоматически исключаются из .env-файлов проекта, чтобы предотвратить влияние на поведение CLI.
  • Решение: Вместо этого используйте файл .qwen/.env, либо настройте параметр advanced.excludedEnvVars в вашем файле settings.json, чтобы исключать меньшее количество переменных.

Не удаётся подключиться к IDE Companion

• Убедитесь, что в VS Code открыта только одна рабочая папка.
• Перезапустите интегрированный терминал после установки расширения, чтобы он унаследовал следующие переменные среды:
  • QWEN_CODE_IDE_WORKSPACE_PATH
  • QWEN_CODE_IDE_SERVER_PORT
• Если вы запускаете среду в контейнере, убедитесь, что имя host.docker.internal разрешается. В противном случае настройте соответствующее сопоставление хоста.
• Переустановите companion-приложение с помощью команды /ide install и используйте команду «Qwen Code: Run» в палитре команд, чтобы проверить, запускается ли оно.

Коды завершения

Qwen Code использует специальные коды завершения для указания причины завершения работы. Это особенно полезно при написании скриптов и автоматизации.

Советы по отладке

• Отладка CLI:

  • Используйте флаг --verbose (если доступен) с командами CLI для получения более подробного вывода.
  • Проверьте логи CLI, которые обычно находятся в пользовательской конфигурационной или кэш-директории.

• Отладка ядра:

  • Проверьте вывод консоли сервера на наличие сообщений об ошибках или трассировок стека.
  • Увеличьте детализацию логов, если это настраивается.
  • Используйте инструменты отладки Node.js (например, node --inspect), если требуется пошаговое выполнение серверного кода.

• Проблемы с инструментами:

  • Если конкретный инструмент завершается с ошибкой, попробуйте изолировать проблему, выполнив максимально упрощённую версию команды или операции, которую выполняет этот инструмент.
  • Для run_shell_command сначала проверьте, работает ли команда напрямую в вашей оболочке.
  • Для инструментов файловой системы убедитесь в корректности путей и проверьте права доступа.

• Предварительные проверки:

  • Всегда запускайте npm run preflight перед коммитом кода. Эта команда позволяет выявить множество распространённых проблем, связанных с форматированием, линтингом и ошибками типов.

Существующие проблемы на GitHub, похожие на вашу, или создание новых проблем

Если вы столкнулись с проблемой, которая не описана в этом руководстве по устранению неполадок, попробуйте выполнить поиск в трекере проблем Qwen Code на GitHub . Если вы не нашли проблему, похожую на вашу, создайте новую задачу на GitHub с подробным описанием. Также приветствуются пул-реквесты!