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

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

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

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

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

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

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

  • Причина: Если аутентификация не удалась после выбора типа аутентификации, настройка 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 (Address already in use) при запуске сервера MCP.

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

• Ошибка: Command not found (при попытке запустить 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.

• Ошибка: “Operation not permitted”, “Permission denied” или аналогичные.

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

• 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 не подключается

• Убедитесь, что в VS Code открыта одна рабочая папка.
• Перезапустите интегрированный терминал после установки расширения, чтобы он наследовал:
  • QWEN_CODE_IDE_WORKSPACE_PATH
  • QWEN_CODE_IDE_SERVER_PORT
• Если запуск происходит в контейнере, убедитесь, что host.docker.internal разрешается. В противном случае, правильно сопоставьте хост.
• Переустановите сопутствующее приложение с помощью /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 с подробным описанием. Также приветствуются запросы на слияние (Pull requests)!