Конфигурация Qwen Code

Слои конфигурации

Конфигурация применяется в следующем порядке приоритета (значения с меньшими номерами переопределяются значениями с большими номерами):

Файлы настроек

Qwen Code использует файлы настроек в формате JSON для постоянной конфигурации. Существует четыре возможных расположения таких файлов:

Каталог .qwen в вашем проекте

Помимо файла настроек проекта, каталог .qwen проекта может содержать другие файлы, специфичные для проекта и связанные с работой Qwen Code, например:

• Пользовательские профили песочницы (например, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Навыки агента в подкаталоге .qwen/skills/ (каждый навык — это каталог, содержащий файл SKILL.md).

Миграция конфигурации

Qwen Code автоматически переносит устаревшие параметры конфигурации в новый формат. Перед миграцией резервные копии старых файлов настроек сохраняются. Следующие параметры были переименованы: вместо отрицательных (disable*) теперь используются положительные (enable*) имена:

Политика объединения для параметров disableAutoUpdate и disableUpdateNag

Если оба устаревших параметра присутствуют и имеют разные значения, миграция выполняется по следующему правилу: если хотя бы один из параметров — disableAutoUpdate или disableUpdateNag — имеет значение true, то enableAutoUpdate становится false:

Доступные параметры в файле settings.json

Параметры сгруппированы по категориям. Все параметры должны быть размещены внутри соответствующего объекта верхнего уровня в вашем файле settings.json.

Общие настройки

output

ui

ide

конфиденциальность

model

Пример model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "modalities": {
        "image": true
      },
      "enableCacheControl": true,
      "customHeaders": {
        "X-Client-Request-ID": "req-123"
      },
      "extra_body": {
        "enable_thinking": true
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

contextWindowSize:

Переопределяет размер окна контекста по умолчанию для выбранной модели. Qwen Code определяет окно контекста на основе встроенных значений, соответствующих имени модели, с резервным константным значением. Используйте этот параметр, если эффективный лимит контекста у провайдера отличается от значения по умолчанию в Qwen Code. Данное значение задаёт предполагаемую максимальную ёмкость контекста модели, а не лимит токенов на один запрос.

modalities:

Переопределяет автоматически определённые типы входных данных для выбранной модели. Qwen Code автоматически определяет поддерживаемые типы (изображения, PDF, аудио, видео) по шаблону имени модели. Используйте этот параметр, если автодетекция работает некорректно — например, чтобы включить поддержку pdf для модели, которая её поддерживает, но не распознаётся. Формат: { "image": true, "pdf": true, "audio": true, "video": true }. Пропустите ключ или установите его в false, чтобы отключить неподдерживаемый тип.

customHeaders:

Позволяет добавлять пользовательские HTTP-заголовки ко всем API-запросам. Это полезно для трассировки запросов, мониторинга, маршрутизации через шлюзы API или при необходимости разных заголовков для разных моделей. Если customHeaders определён в modelProviders[].generationConfig.customHeaders, он будет использоваться напрямую; в противном случае применяются заголовки из model.generationConfig.customHeaders. Объединение заголовков между этими уровнями не выполняется.

Поле extra_body позволяет добавлять пользовательские параметры в тело запроса, отправляемого в API. Это полезно для провайдер-специфичных опций, не покрываемых стандартными полями конфигурации. Важно: это поле поддерживается только для провайдеров, совместимых с OpenAI (openai, qwen-oauth). Для провайдеров Anthropic и Gemini оно игнорируется. Если extra_body определён в modelProviders[].generationConfig.extra_body, он будет использоваться напрямую; в противном случае применяются значения из model.generationConfig.extra_body.

Примеры model.openAILoggingDir:

• "~/qwen-logs" — логи сохраняются в каталог ~/qwen-logs
• "./custom-logs" — логи сохраняются в каталог ./custom-logs относительно текущего каталога
• "/tmp/openai-logs" — логи сохраняются по абсолютному пути /tmp/openai-logs

контекст

Устранение проблем с производительностью поиска файлов

Если вы сталкиваетесь с проблемами производительности при поиске файлов (например, при использовании автозавершения @), особенно в проектах с очень большим количеством файлов, попробуйте следующие решения в порядке их рекомендованности:

1. Используйте файл .qwenignore: Создайте файл .qwenignore в корне проекта, чтобы исключить каталоги, содержащие большое количество файлов, на которые вы не ссылаетесь (например, артефакты сборки, логи, node_modules). Сокращение общего числа обрабатываемых файлов — наиболее эффективный способ повышения производительности.
2. Отключите нечёткий поиск: Если игнорирование файлов недостаточно, отключите нечёткий поиск, установив параметр enableFuzzySearch в значение false в файле settings.json. В этом случае будет использоваться более простой алгоритм точного соответствия, который работает быстрее.
3. Отключите рекурсивный поиск файлов: В крайнем случае можно полностью отключить рекурсивный поиск файлов, установив параметр enableRecursiveFileSearch в значение false. Это обеспечит максимальную скорость, поскольку исключает рекурсивное сканирование проекта. Однако при этом при использовании автозавершения @ вам потребуется вводить полные пути к файлам.

Инструменты

mcp

LSP

[!warning] Экспериментальная функция: Поддержка LSP в настоящее время находится на стадии эксперимента и отключена по умолчанию. Включите её с помощью флага командной строки --experimental-lsp.

Протокол сервера языка (LSP) предоставляет функции интеллектуальной поддержки кода, такие как переход к определению, поиск ссылок и диагностика.

Конфигурация сервера LSP выполняется через файлы .lsp.json в корневом каталоге проекта, а не через settings.json. Подробные сведения о конфигурации и примеры приведены в документации по LSP.

Безопасность

расширенные параметры

mcpServers

Конфигурирует подключения к одному или нескольким серверам протокола Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP, чтобы обнаружить доступные инструменты. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, заданным в конфигурации (например, serverAlias__actualToolName), чтобы избежать конфликтов. Обратите внимание, что система может удалять определённые свойства схемы из определений инструментов MCP для обеспечения совместимости. Необходимо указать хотя бы одно из следующих полей: command, url или httpUrl. При указании нескольких полей порядок приоритета следующий: httpUrl, затем url, затем command.

телеметрия

Конфигурация сбора журналов и метрик для Qwen Code. Дополнительную информацию см. в разделе телеметрия.

Пример файла settings.json

Ниже приведён пример файла settings.json с вложенной структурой, появившейся начиная с версии 0.3.0:

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "Вы забываете тысячу вещей каждый день. Убедитесь, что эта — одна из них",
      "Подключение к ИИО"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10,
    "enableOpenAILogging": false,
    "openAILoggingDir": "~/qwen-logs",
  },
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

История командной оболочки

CLI сохраняет историю выполняемых вами команд оболочки. Чтобы избежать конфликтов между различными проектами, эта история хранится в каталоге, привязанном к конкретному проекту, внутри домашнего каталога пользователя.

• Расположение: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> — уникальный идентификатор, сгенерированный на основе корневого пути вашего проекта.
  • История хранится в файле с именем shell_history.

Переменные окружения и файлы .env

Переменные окружения — это распространённый способ настройки приложений, особенно для хранения конфиденциальной информации (например, токенов) или параметров, которые могут отличаться в разных средах.

Qwen Code может автоматически загружать переменные окружения из файлов .env.
Дополнительную информацию об использовании переменных окружения, связанных с аутентификацией (например, OPENAI_*), и рекомендованном подходе с файлом .qwen/.env см. в разделе Аутентификация.

Таблица переменных окружения

Аргументы командной строки

Аргументы, переданные непосредственно при запуске CLI, могут переопределять другие конфигурации для текущей сессии.

Таблица аргументов командной строки

Файлы контекста (иерархический инструктивный контекст)

Хотя файлы контекста (по умолчанию — QWEN.md, но имя можно изменить через настройку context.fileName) формально не являются конфигурацией поведения CLI, они играют ключевую роль в настройке инструктивного контекста (также называемого «памятью»). Эта мощная функция позволяет передавать модели проектно-специфические инструкции, руководства по стилю кодирования или любую другую релевантную фоновую информацию, что делает ответы ИИ более персонализированными и точными с учётом ваших задач. В CLI предусмотрены элементы пользовательского интерфейса, например индикатор в нижнем колонтитуле, отображающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста.

• Назначение: Эти файлы в формате Markdown содержат инструкции, рекомендации или контекст, которые вы хотите, чтобы модель Qwen учитывала в ходе взаимодействия. Система спроектирована так, чтобы управлять этим инструктивным контекстом иерархически.

Пример содержимого файла контекста (например, QWEN.md)

Ниже приведён концептуальный пример содержимого файла контекста, расположенного в корне проекта на TypeScript:

# Проект: Моя потрясающая библиотека на TypeScript

## Общие инструкции:
- При генерации нового кода на TypeScript соблюдайте существующий стиль кодирования.
- Убедитесь, что все новые функции и классы снабжены комментариями в формате JSDoc.
- По возможности отдавайте предпочтение парадигме функционального программирования.
- Весь код должен быть совместим с TypeScript 5.0 и Node.js 20+.

## Стиль кодирования:
- Используйте отступы в 2 пробела.
- Имена интерфейсов должны начинаться с префикса `I` (например, `IUserService`).
- Приватные члены классов должны начинаться с символа подчёркивания (`_`).
- Всегда используйте строгое сравнение (`===` и `!==`).

## Конкретный компонент: `src/api/client.ts`
- Этот файл отвечает за все исходящие HTTP-запросы к API.
- При добавлении новых функций вызова API убедитесь, что они включают надёжную обработку ошибок и логирование.
- Для всех GET-запросов используйте существующую утилиту `fetchWithRetry`.

О зависимостях:

• Избегайте добавления новых внешних зависимостей, если это не абсолютно необходимо.
• Если новая зависимость всё же требуется, укажите причину её введения.

В этом примере показано, как можно предоставить общие сведения о проекте, конкретные соглашения по написанию кода и даже примечания к отдельным файлам или компонентам. Чем более релевантными и точными будут ваши файлы контекста, тем лучше ИИ сможет вам помочь. Для установления соглашений и контекста настоятельно рекомендуется использовать файлы контекста, специфичные для проекта.

- **Иерархическая загрузка и приоритет:** CLI реализует иерархическую систему памяти, загружая файлы контекста (например, `QWEN.md`) из нескольких расположений. Содержимое файлов, перечисленных ниже в этом списке (более специфичных), как правило, переопределяет или дополняет содержимое файлов, указанных выше (более общих). Точный порядок объединения и итоговый контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки:
  1. **Глобальный файл контекста:**
     - Расположение: `~/.qwen/<имя-настроенного-файла-контекста>` (например, `~/.qwen/QWEN.md` в домашнем каталоге пользователя).
     - Область действия: содержит инструкции по умолчанию для всех ваших проектов.
  2. **Файлы контекста корня проекта и его родительских каталогов:**
     - Расположение: CLI ищет настроенный файл контекста в текущем рабочем каталоге, а затем — в каждом родительском каталоге вплоть до корня проекта (определяемого наличием папки `.git`) или до домашнего каталога пользователя.
     - Область действия: содержит контекст, относящийся ко всему проекту или его значительной части.
- **Объединение и индикация в интерфейсе:** Содержимое всех найденных файлов контекста объединяется (с разделителями, указывающими их происхождение и путь) и передаётся как часть системного промпта. В нижнем колонтитуле CLI отображается количество загруженных файлов контекста, что даёт быструю визуальную подсказку об активном инструктивном контексте.
- **Импорт содержимого:** Вы можете модульно организовать свои файлы контекста, импортируя другие Markdown-файлы с помощью синтаксиса `@путь/к/файлу.md`. Подробнее см. в [документации по процессору импорта памяти](../configuration/memory).
- **Команды управления памятью:**
  - Используйте `/memory refresh`, чтобы принудительно повторно просканировать и перезагрузить все файлы контекста из всех настроенных расположений. Это обновляет инструктивный контекст ИИ.
  - Используйте `/memory show`, чтобы отобразить объединённый инструктивный контекст, загруженный в данный момент, что позволяет проверить используемую иерархию и содержимое.
  - Полные сведения о команде `/memory` и её подкомандах (`show` и `refresh`) см. в [документации по командам](../features/commands).

Понимание и использование этих уровней конфигурации, а также иерархической природы файлов контекста позволяют эффективно управлять памятью ИИ и адаптировать ответы Qwen Code под ваши конкретные потребности и проекты.

## Песочница

Qwen Code может выполнять потенциально небезопасные операции (например, команды оболочки и модификации файлов) в изолированной среде песочницы для защиты вашей системы.

[Песочница](../features/sandbox) отключена по умолчанию, но её можно включить несколькими способами:

- С помощью флага `--sandbox` или `-s`.
- Установив переменную окружения `QWEN_SANDBOX`.
- Песочница включается автоматически при использовании флагов `--yolo` или `--approval-mode=yolo`.

По умолчанию используется предварительно собранное Docker-образ `qwen-code-sandbox`.

Для проектно-специфических требований к песочнице вы можете создать пользовательский `Dockerfile` по пути `.qwen/sandbox.Dockerfile` в корневом каталоге вашего проекта. Этот `Dockerfile` может быть основан на базовом образе песочницы:

FROM qwen-code-sandbox

Добавьте здесь ваши пользовательские зависимости или конфигурации

Например:

RUN apt-get update && apt-get install -y some-package

# КОПИРОВАТЬ ./my-config /app/my-config

Если файл .qwen/sandbox.Dockerfile существует, при запуске Qwen Code можно использовать переменную окружения BUILD_SANDBOX для автоматической сборки пользовательского образа песочницы:

BUILD_SANDBOX=1 qwen -s

Статистика использования

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

Что мы собираем:

• Вызовы инструментов: Мы регистрируем имена вызываемых инструментов, информацию об их успешном или неуспешном выполнении, а также время выполнения. Мы не собираем аргументы, передаваемые инструментам, и никакие данные, возвращаемые ими.
• API-запросы: Мы регистрируем модель, используемую для каждого запроса, продолжительность запроса и его успешность. Мы не собираем содержимое промптов или ответов.
• Информация о сессии: Мы собираем информацию о конфигурации CLI, например, список включённых инструментов и режим подтверждения.

Что мы НЕ собираем:

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

Как отказаться от сбора статистики:

Вы можете в любое время отказаться от сбора статистики использования, установив свойство usageStatisticsEnabled в значение false в разделе privacy вашего файла settings.json:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}