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

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

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

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

• Ошибка: UNABLE_TO_GET_ISSUER_CERT_LOCALLY, UNABLE_TO_VERIFY_LEAF_SIGNATURE или unable to get local issuer certificate

  • Причина: Возможно, вы находитесь в корпоративной сети с файрволом, который перехватывает и проверяет SSL/TLS-трафик. Это часто требует добавления пользовательского корневого CA-сертификата в доверенные для Node.js.
  • Решение: Установите переменную окружения NODE_EXTRA_CA_CERTS, указав абсолютный путь к файлу корневого CA-сертификата вашей компании.
    • Пример: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

• Ошибка: Connection error. (cause: fetch failed) при обращении к конечной точке с самоподписанным сертификатом

  • Причина: Вы направляете Qwen Code на самостоятельно размещенный сервер (например, локальную модель за https://), TLS-сертификат которого является самоподписанным, поэтому Node.js его отклоняет.
  • Решение: Предпочтительнее добавить сертификат в доверенные через NODE_EXTRA_CA_CERTS (см. выше). Если это нецелесообразно в доверенной лаборатории/частной сети, пропустите проверку с помощью флага --insecure (или QWEN_TLS_INSECURE=1):
    • Пример: qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ...
    • Предупреждение: Отключение проверки снимает защиту от атак типа «человек посередине». Используйте этот метод только для конечных точек, которым вы полностью доверяете.

• Ошибка: Device authorization flow failed: fetch failed

  • Причина: Node.js не смог достичь конечных точек Qwen OAuth (часто это проблема прокси или доверия к SSL/TLS). Если возможно, Qwen Code также выведет основную причину ошибки (например: UNABLE_TO_VERIFY_LEAF_SIGNATURE). Примечание: эта ошибка специфична для устаревшего потока Qwen OAuth.
  • Решение:
    • Если вы все еще используете Qwen OAuth, переключитесь на API Key или Coding Plan через /auth.
    • Если вы находитесь за прокси, настройте его через qwen --proxy <url> (или параметр proxy в settings.json).
    • Если в вашей сети используется корпоративный CA для проверки TLS, установите NODE_EXTRA_CA_CERTS, как описано выше.

• Проблема: Невозможно отобразить 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 до последней версии?

  • О: Если вы установили 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 key (например, API key Alibaba Cloud Model Studio или Google Cloud Vertex AI). Вы по-прежнему можете просматривать общее использование токенов с помощью команды /stats.

• В: Кастомизация (расширение, хук, skill, MCP-сервер или подагент), похоже, ломает Qwen Code. Как ее изолировать?

  • О: Запустите Qwen Code с флагом --safe-mode, чтобы отключить все кастомизации — контекстные файлы, хуки, расширения, skills, MCP-серверы, пользовательские подагенты (загружаются только встроенные), правила разрешений, переопределения режима одобрения из настроек, функции памяти, межсессионный обмен сообщениями, LSP и настройки песочницы — для текущей сессии. Примечание: флаги CLI --yolo и --approval-mode продолжают действовать в безопасном режиме. Если проблема исчезает в безопасном режиме, включайте кастомизации по одной, чтобы найти виновника.
    • Пример: qwen --safe-mode
    • Альтернатива: установите переменную окружения QWEN_CODE_SAFE_MODE=true, если CLI не может принимать флаги.
    • Примечание: «MCP-серверы» здесь означают серверы, настроенные в settings.json / проектном .mcp.json — локальное, фоновое состояние, для изоляции которого предназначен безопасный режим. MCP-серверы, которые вы явно передаёте для текущего вызова (например, session/new mcpServers у ACP-клиента для эмбеддингов или --mcp-config), не являются локальным/фоновым состоянием и продолжают работать в безопасном режиме.

Загрузка вложений возвращает HTTP 413 за reverse proxy

Прокси может отклонить запрос до того, как он достигнет qwen serve, даже если вложение находится в пределах лимита демона 8 МиБ. Повышение только лимита тела демона не изменяет лимит прокси.

Используйте сборку демона и TypeScript SDK/Web Shell, поддерживающую session_attachment_chunk_upload. Вложения размером более 512 КиБ затем загружаются запросами по 512 КиБ без изменения их байтов или качества изображения. Старые демоны сохраняют путь загрузки одним запросом. Если вы управляете прокси, вы также можете повысить лимит тела запроса для размещения исходного запроса вложения. Прокси с лимитами ниже 512 КиБ все еще нуждаются в изменении конфигурации.

Лимит вложений остается 8 МиБ. Если загрузка истекает или демон перезапускается, повторите вложение из UI. Завершенная загрузка, ответ на который был потерян, может оставаться во вложениях сессии; отмена не удаляет файл, который уже завершен.

Распространенные сообщения об ошибках и их решения

• Ошибка: EADDRINUSE (Address already in use) при запуске MCP-сервера.

  • Причина: Другой процесс уже использует порт, к которому пытается привязаться MCP-сервер.
  • Решение: Остановите другой процесс, использующий порт, или настройте MCP-сервер на использование другого порта.

• Ошибка: Command not found (при попытке запустить Qwen Code с помощью qwen).

  • Причина: CLI установлен некорректно или его нет в системном PATH.
  • Решение: Решение зависит от того, как вы установили Qwen Code:
    • Если вы установили qwen с помощью автономного установщика, повторно выполните команду автономной установки, а затем откройте новый терминал.
    • Если вы установили 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, чтобы исключать меньше переменных.

• Проблема: Прокрутка тачпадом в tmux изменяет историю промптов вместо прокрутки диалога

  • Проблема: В сессии tmux прокрутка тачпадом или колесиком мыши может переключать предыдущие промпты, аналогично нажатию Up Arrow или Down Arrow.
  • Причина: tmux может преобразовывать жесты прокрутки в обычные последовательности клавиш со стрелками. К моменту получения их qwen-code эти последовательности неотличимы от реальных нажатий клавиш со стрелками.
  • Решение: Если режим чтения с экрана отключён, убедитесь, что ui.useTerminalBuffer включён; затем используйте Shift+Up / Shift+Down или колесико мыши, когда tmux передаёт события прокрутки приложению (требуется ui.mouseTracking). Чтобы передавать обычные Up Arrow / Down Arrow в вьюпорт, когда композер пуст, установите ui.arrowKeysScrollTranscript в true; история ввода тогда доступна через Ctrl+P / Ctrl+N. Если вы предпочитаете прокрутку хоста, настройте привязки мыши в tmux для событий прокрутки.

• Правый клик не работает, ссылки не открываются, текст нельзя выделить в терминале

  • Проблема: Нативные контекстные меню по правому клику, клики по OSC 8-гиперссылкам и нативное выделение текста в терминале перестают работать во время работы Qwen Code.
  • Причина: Когда ui.mouseTracking включён (по умолчанию), Qwen Code перехватывает все события мыши через SGR-отслеживание мыши для обеспечения выделения текста в приложении, позиционирования по клику, наведения на строки, переключения элементов истории и прокрутки вьюпорта. Терминал передаёт все события мыши приложению вместо их нативной обработки. Qwen Code предоставляет собственные замены, пока отслеживание включено: одинарный клик открывает http(s) OSC 8-гиперссылку, а правый клик по ссылке или выделенному тексту открывает контекстное меню в приложении.
  • Решение: Если вы предпочитаете нативную обработку терминалом, установите "ui.mouseTracking": false в вашем settings.json. Это отключает всё взаимодействие с мышью в приложении, включая открытие ссылок и контекстное меню в приложении. В Virtualized History (ui.useTerminalBuffer: true, по умолчанию) колесико больше не будет прокручивать транскрипт — используйте Shift+↑/↓, PgUp/PgDn или Ctrl+Home/End. Чтобы также восстановить нативную прокрутку терминала, установите "ui.useTerminalBuffer": false. Требуется перезапуск.

IDE Companion не подключается

• Убедитесь, что в VS Code открыта только одна папка рабочего пространства.
• Перезапустите интегрированный терминал после установки расширения, чтобы он унаследовал:
  • QWEN_CODE_IDE_WORKSPACE_PATH
  • QWEN_CODE_IDE_SERVER_PORT
• Если вы работаете в контейнере, убедитесь, что host.docker.internal разрешается. В противном случае сопоставьте хост соответствующим образом.
• Переустановите companion с помощью /ide install и используйте «Qwen Code: Run» в Command Palette, чтобы убедиться, что он запускается.

Сбросы соединений в некоторых сетях (TLS-селективные middlebox’ы)

• Проблема: В некоторых сетях операторов или корпоративных сетях HTTPS-соединения с API-эндпоинтами сбрасываются (TCP RST) сразу после TLS ClientHello. Qwen Code продолжает повторять попытки (ECONNRESET — это повторяемая транспортная ошибка), пока не исчерпает бюджет, затем выводит общую ошибку соединения — в то время как curl, Python и другие инструменты работают нормально на том же компьютере и сети в тот же момент.
• Причина: Некоторые middlebox’ы фильтруют соединения по отпечатку TLS ClientHello и сбрасывают те, которые созданы определенными поколениями TLS-стека. На затронутых каналах стеки эпохи OpenSSL 3.0 и Electron/BoringSSL (используемые расширением VS Code и демоном) сбрасываются, в то время как стеки поколения OpenSSL 3.5 — включая текущие сборки Node.js — подключаются нормально.
• Решение: Установите соединение с TLS-стеком поколения 3.5:
  • CLI: используйте актуальную сборку поддерживаемой линейки Node.js (текущие сборки Node 22/24/25 поставляются с OpenSSL поколения 3.5). Старые сборки того же мажорного могут все еще быть на затронутом поколении — обновите, а не привязывайтесь к старому минорному.
  • Расширение VS Code / демон: расширение работает на TLS-стеке Electron и не может изменить его на стороне клиента. Запустите небольшой локальный релей — локальный процесс на стеке поколения 3.5 — и направьте Qwen Code на него через переопределение базового URL модели (пользовательский эндпоинт в settings.json или --openaiBaseUrl для CLI), чтобы TLS-исход происходил с новым стеком.
• Как отличить это от нестабильной сети:
  • сброс детерминирован — каждая попытка немедленно завершается, при повторных попытках, и не восстанавливается со временем;
  • на том же компьютере и в тот же момент другие TLS-стеки успешно подключаются к тому же эндпоинту;
  • привязка версий TLS или изменение разрешения DNS не помогает.

Коды завершения

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

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

• Отладка CLI:

  • Используйте флаг --verbose (если доступен) с командами CLI для получения более подробного вывода.
  • Проверьте логи CLI, которые часто находятся в пользовательском каталоге конфигурации или кэша.

• Отладка ядра:

  • Проверьте вывод консоли сервера на наличие сообщений об ошибках или трассировок стека.
  • Увеличьте детализацию логов, если это настраивается.
  • Используйте инструменты отладки Node.js (например, node --inspect), если вам нужно пошагово пройти по серверному коду.

• Проблемы с инструментами:

  • Если конкретный инструмент не работает, попробуйте изолировать проблему, запустив максимально упрощенную версию команды или операции, которую выполняет инструмент.
  • Для run_shell_command сначала убедитесь, что команда работает напрямую в вашей оболочке.
  • Для инструментов файловой системы убедитесь, что пути указаны правильно, и проверьте права доступа.

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

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

Поиск похожих Issues на GitHub или создание новых

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