Руководство по устранению неполадок
Это руководство содержит решения для часто возникающих проблем и советы по отладке, включая следующие темы:
- Ошибки аутентификации или входа в систему
- Часто задаваемые вопросы (FAQ)
- Советы по отладке
- Существующие GitHub Issues, похожие на вашу проблему, или создание новых 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
. Если вы скомпилировали его из исходного кода, извлеките последние изменения из репозитория, а затем пересоберите с помощью командыnpm run build
.
- О: Если вы установили его глобально через
-
В: Где хранятся файлы конфигурации или настроек Qwen Code?
-
О: Конфигурация Qwen Code хранится в двух файлах
settings.json
:- В вашем домашнем каталоге:
~/.qwen/settings.json
. - В корневом каталоге вашего проекта:
./.qwen/settings.json
.
Дополнительную информацию см. в разделе Конфигурация Qwen Code.
- В вашем домашнем каталоге:
-
-
В: Почему я не вижу кэшированные подсчеты токенов в выводе статистики?
- О: Информация о кэшированных токенах отображается только при использовании кэшированных токенов. Эта функция доступна для пользователей API-ключей (Qwen API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды
/stats
.
- О: Информация о кэшированных токенах отображается только при использовании кэшированных токенов. Эта функция доступна для пользователей API-ключей (Qwen API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды
Распространенные сообщения об ошибках и решения
-
Ошибка:
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
.
- Если вы установили
- Причина: CLI не установлен корректно или не добавлен в системную переменную
-
Ошибка:
MODULE_NOT_FOUND
или ошибки импорта.- Причина: Зависимости установлены некорректно или проект не был собран.
- Решение:
- Выполните
npm install
, чтобы убедиться, что все зависимости установлены. - Выполните
npm run build
, чтобы скомпилировать проект. - Убедитесь, что сборка прошла успешно, с помощью
npm run start
.
- Выполните
-
Ошибка: “Operation not permitted”, “Permission denied” или аналогичные.
- Причина: Когда включено sandboxing, Qwen Code может пытаться выполнить операции, запрещенные вашей конфигурацией песочницы, например, запись вне директории проекта или системной временной директории.
- Решение: Обратитесь к документации Configuration: Sandboxing для получения дополнительной информации, включая способы настройки конфигурации песочницы.
-
Qwen Code не запускается в интерактивном режиме в CI-средах
- Проблема: Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с
CI_
(например,CI_TOKEN
). Это происходит потому, что пакетis-in-ci
, используемый в UI-фреймворке, обнаруживает такие переменные и считает, что среда не интерактивна. - Причина: Пакет
is-in-ci
проверяет наличие переменныхCI
,CONTINUOUS_INTEGRATION
или любых переменных с префиксомCI_
. Если такие переменные найдены, это сигнализирует о том, что среда не интерактивна, и CLI не запускается в интерактивном режиме. - Решение: Если переменная с префиксом
CI_
не требуется для работы CLI, вы можете временно отключить её для команды. Например:env -u CI_TOKEN qwen
- Проблема: Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с
-
DEBUG режим не работает из файла .env проекта
- Проблема: Установка
DEBUG=true
в файле.env
проекта не включает режим отладки для CLI. - Причина: Переменные
DEBUG
иDEBUG_MODE
автоматически исключаются из файлов.env
проекта, чтобы не мешать работе CLI. - Решение: Используйте файл
.qwen/.env
вместо этого, или настройте параметрexcludedProjectEnvVars
в вашем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, чтобы убедиться, что он запускается.
Советы по отладке
-
Отладка 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. Если вы не можете найти похожую проблему, рекомендуем создать новый GitHub Issue с подробным описанием. Pull request также приветствуются!