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

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

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

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

• Ошибка: Qwen OAuth free tier was discontinued on 2026-04-15

  • Причина: Qwen OAuth больше не доступен с 15 апреля 2026 года.
  • Решение: Переключитесь на другой метод аутентификации. Выполните qwen → /auth и выберите один из вариантов:
    • API Key: Используйте API key из Alibaba Cloud Model Studio (Beijing  / intl ). См. руководство по настройке API (Beijing  / intl ).
    • Alibaba Cloud Coding Plan: Оформите подписку за фиксированную ежемесячную плату с увеличенными квотами. См. руководство по Coding Plan (Beijing  / intl ).

• Ошибка: 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=/path/to/your/corporate-ca.crt

• Ошибка: Connection error. (cause: fetch failed) при обращении к конечной точке с самоподписанным сертификатом

  • Причина: Вы направляете Qwen Code на самостоятельно размещенный сервер (например, локальную модель за https://), TLS-сертификат которого является самоподписанным, поэтому Node.js его отклоняет.
  • Решение: Предпочтительнее добавить сертификат в доверенные через NODE_EXTRA_CA_CERTS (см. выше). Если это нецелесообразно в доверенной лаборатории/частной сети, пропустите проверку с помощью флага --insecure (или QWEN_TLS_INSECURE=1):
    • Пример: qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ...
    • Предупреждение: Отключение проверки снимает защиту от атак типа «человек посередине». Используйте этот метод только для конечных точек, которым вы полностью доверяете.

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

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

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

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

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

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

  • О: Если вы установили 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 key (например, API key Alibaba Cloud Model Studio или Google Cloud Vertex AI). Вы по-прежнему можете просматривать общее использование токенов с помощью команды /stats.

• В: Кастомизация (расширение, хук, skill, MCP-сервер или подагент), похоже, ломает Qwen Code. Как ее изолировать?

  • О: Запустите Qwen Code с флагом --safe-mode, чтобы отключить все кастомизации — контекстные файлы, хуки, расширения, skills, MCP-серверы, пользовательские подагенты (загружаются только встроенные), правила разрешений, переопределения режима одобрения из настроек, функции памяти и настройки песочницы — для текущей сессии. Примечание: флаги CLI --yolo и --approval-mode продолжают действовать в безопасном режиме. Если проблема исчезает в безопасном режиме, включайте кастомизации по одной, чтобы найти виновника.
    • Пример: qwen --safe-mode
    • Альтернатива: установите переменную окружения QWEN_CODE_SAFE_MODE=true, если CLI не может принимать флаги.

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

• Ошибка: EADDRINUSE (Address already in use) при запуске MCP-сервера.

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

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

  • Причина: CLI установлен некорректно или его нет в системном PATH.
  • Решение: Решение зависит от того, как вы установили Qwen Code:
    • Если вы установили qwen с помощью автономного установщика, повторно выполните команду автономной установки, а затем откройте новый терминал.
    • Если вы установили 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, чтобы исключать меньше переменных.

• Проблема: Прокрутка тачпадом в tmux изменяет историю промптов вместо прокрутки диалога

  • Проблема: В сессии tmux прокрутка тачпадом или колесиком мыши может переключать предыдущие промпты, аналогично нажатию Up Arrow или Down Arrow.
  • Причина: tmux может преобразовывать жесты прокрутки в обычные последовательности клавиш со стрелками. К моменту получения их qwen-code эти последовательности неотличимы от реальных нажатий клавиш со стрелками.
  • Решение: Включите ui.useTerminalBuffer; затем используйте Shift+Up / Shift+Down или колесико мыши, когда tmux передает события прокрутки приложению. Если вы предпочитаете прокрутку хоста, настройте привязки мыши в tmux для событий прокрутки.

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

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

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

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

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

• Отладка CLI:

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

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

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

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

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

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

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

Поиск похожих Issues на GitHub или создание новых

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