Skip to Content
Устранение Неполадок

Руководство по устранению неполадок

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

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

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

  • Ошибка: 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

Часто задаваемые вопросы (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 key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды /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 ...). Чтобы обновить, сделайте pull последних изменений из репозитория и пересоберите проект командой npm run build.
  • Ошибка: MODULE_NOT_FOUND или ошибки импорта.

    • Причина: Зависимости установлены некорректно или проект не был собран.
    • Решение:
      1. Выполните npm install, чтобы убедиться, что все зависимости установлены.
      2. Выполните npm run build, чтобы скомпилировать проект.
      3. Убедитесь, что сборка прошла успешно, с помощью npm run start.
  • Ошибка: “Operation not permitted”, “Permission denied” или аналогичные.

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

    • Проблема: Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с CI_ (например, CI_TOKEN). Это происходит потому, что пакет is-in-ci, используемый в UI-фреймворке, обнаруживает такие переменные и считает, что среда не интерактивна.
    • Причина: Пакет 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 вместо этого, или настройте параметр excludedProjectEnvVars в вашем settings.json, чтобы исключить меньше переменных.

IDE Companion не подключается

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

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

  • Отладка CLI:

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

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

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

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

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

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

Last updated on