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

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

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

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

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

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

  • Причина: Если аутентификация завершается ошибкой после выбора типа, настройка 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). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды /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 открыта только одна рабочая папка (workspace folder).
• Перезапустите интегрированный терминал после установки расширения, чтобы он унаследовал:
  • 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 сначала убедитесь, что команда корректно выполняется напрямую в вашем шелле.
  • Для инструментов файловой системы проверьте корректность путей и права доступа.

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

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

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

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