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

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

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

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

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

  • Причина: Qwen OAuth больше не доступен с 15 апреля 2026 года.
  • Решение: Переключитесь на другой метод аутентификации. Запустите qwen → /auth и выберите один из вариантов:
    • API Key: Используйте API-ключ из 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-трафик. В этом случае Node.js часто требует доверять пользовательскому корневому CA-сертификату.
  • Решение: Установите переменную окружения NODE_EXTRA_CA_CERTS, указав абсолютный путь к файлу корневого CA-сертификата вашей компании.
    • Пример: 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). Примечание: эта ошибка относится только к устаревшему потоку 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 до последней версии?

  • О: Если вы установили его глобально через 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-ключей (например, API-ключ Alibaba Cloud Model Studio или Google Cloud Vertex AI). Вы по-прежнему можете просмотреть общее использование токенов с помощью команды /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 может попытаться выполнить операции, ограниченные её конфигурацией, например, запись за пределами директории проекта или системной временной директории.
  • Решение: Подробнее см. в документации Конфигурация: Песочница, включая информацию о настройке конфигурации песочницы.

• 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 сначала убедитесь, что команда корректно выполняется напрямую в вашем shell.
  • Для инструментов файловой системы убедитесь в правильности путей и проверьте права доступа.

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

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

Поиск существующих GitHub Issues или создание новых

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