Руководство по устранению неполадок
Это руководство содержит решения для часто возникающих проблем и советы по отладке, включая следующие темы:
- Ошибки аутентификации или входа в систему
- Часто задаваемые вопросы (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-фреймворке, определяет такие переменные как признак неинтерактивной CI-среды. - Причина: Пакет
is-in-ci
проверяет наличие переменныхCI
,CONTINUOUS_INTEGRATION
или любых переменных с префиксомCI_
. При обнаружении хотя бы одной из них он считает, что среда неинтерактивна, и CLI не запускается в интерактивном режиме. - Решение: Если переменная с префиксом
CI_
не требуется для работы CLI, её можно временно отключить при запуске команды. Например:env -u CI_TOKEN qwen
- Проблема: Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с
-
DEBUG-режим не работает при установке через .env файл проекта
- Проблема: Установка
DEBUG=true
в.env
файле проекта не включает debug-режим для 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, чтобы проверить запуск.
Коды завершения
Qwen Code использует определенные коды завершения для указания причины остановки. Это особенно полезно при написании скриптов и автоматизации.
Код завершения | Тип ошибки | Описание |
---|---|---|
41 | FatalAuthenticationError | Произошла ошибка в процессе аутентификации. |
42 | FatalInputError | Был предоставлен неверный или отсутствующий ввод в CLI. (только в неинтерактивном режиме) |
44 | FatalSandboxError | Произошла ошибка с песочницей (например, Docker, Podman или Seatbelt). |
52 | FatalConfigError | Конфигурационный файл (settings.json ) недействителен или содержит ошибки. |
53 | FatalTurnLimitedError | Достигнуто максимальное количество шагов диалога в рамках сессии. (только в неинтерактивном режиме) |
Советы по отладке
-
Отладка 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 также приветствуются!