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

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

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

• Проблема: Не удается отобразить 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. Если вы скомпилировали из исходного кода, выполните pull последних изменений из репозитория, а затем пересоберите проект командой 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 (Address already in use) при запуске сервера 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 может пытаться выполнить операции, запрещённые вашей конфигурацией песочницы — например, запись вне директории проекта или системной временной директории.
  • Решение: Обратитесь к документации Конфигурация: Песочница (Sandboxing) за дополнительной информацией, включая способы настройки конфигурации песочницы.

• 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 проекта не активирует debug-режим для 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” из Command Palette, чтобы убедиться, что он запускается.

Коды выхода

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

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

• Отладка 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. Если вы не можете найти Issue, похожую на вашу, рекомендуем создать новую GitHub Issue с подробным описанием проблемы. Также приветствуются Pull request’ы!