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

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

• Ошибки аутентификации или входа в систему
• Часто задаваемые вопросы (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 в абсолютный путь к файлу корневого сертификата центра сертификации вашей компании.
    • Пример: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

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

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

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

  • Причина: При включенном песочнице 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 не подключается

• Убедитесь, что в 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 с подробным описанием. Также приветствуются пулл-реквесты!