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

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

• Ошибки аутентификации или входа в систему
• Часто задаваемые вопросы (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

Часто задаваемые вопросы (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 (Адрес уже используется) при запуске 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 не переходит в интерактивный режим (не появляется prompt), если установлена переменная окружения, начинающаяся с 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’ы!