Конфигурация 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. Несколько настроек верхнего уровня, такие как proxy и plansDirectory, остаются прямыми корневыми ключами для совместимости.

general

output

ui

ide

privacy

model

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

max_tokens (адаптивное количество выходных токенов):

Если samplingParams.max_tokens не задан, Qwen Code использует адаптивную стратегию выходных токенов для оптимизации использования ресурсов GPU:

1. Запросы начинаются с ограничения по умолчанию в 8K выходных токенов.
2. Если ответ был обрезан (модель достигла лимита), Qwen Code автоматически повторяет запрос с лимитом в 64K токенов.
3. Частичный вывод отбрасывается и заменяется полным ответом из повторного запроса.

Это прозрачно для пользователей — вы можете кратко увидеть индикатор повтора, если произошло повышение лимита. Поскольку 99% ответов имеют объём менее 5K токенов, повтор происходит редко (<1% запросов).

Чтобы переопределить это поведение, задайте samplingParams.max_tokens в настройках или используйте переменную окружения QWEN_CODE_MAX_OUTPUT_TOKENS.

toolResultContentFormat:

Управляет сериализацией текстовых результатов инструментов в запросах, совместимых с OpenAI. Значение по умолчанию "parts" сохраняет стандартную форму массива content-part. Устанавливайте "string" только для устаревших сред выполнения, совместимых с OpenAI, шаблоны инструментов которых игнорируют текстовые content parts, например, старые шаблоны GLM-5.1 vLLM/SGLang. Возвращаемые инструментом медиа по-прежнему контролируются параметром splitToolMedia.

contextWindowSize:

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

Если выбранная модель определена в modelProviders, задавайте contextWindowSize в generationConfig соответствующей записи провайдера, а не в верхнем уровне model.generationConfig. Записи моделей провайдеров являются финализированными, поэтому настройки генерации верхнего уровня не заполняют отсутствующие поля провайдера.

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

fastModel

context

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

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

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

tools

memory

Подробнее о работе автоматической памяти и использовании команд /memory, /remember и /dream см. в разделе Память.

permissions

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

Приоритет решений (от наибольшего к наименьшему): deny > ask > allow > (по умолчанию/интерактивный режим)

Первое совпавшее правило имеет приоритет. Правила используют формат "ToolName" или "ToolName(спецификатор)".

Псевдонимы имён инструментов (любой из них работает в правилах):

Мета-категории:

Некоторые имена правил автоматически охватывают несколько инструментов:

[!important] Read(/path/**) соответствует всем четырём инструментам чтения (чтение файла, grep, glob, список каталогов). Чтобы ограничить только чтение файлов, используйте ReadFile(/path/**) или read_file(/path/**).

Примеры синтаксиса правил:

Предотвращение обхода через shell-команды:

Правила разрешений для Read, Edit и WebFetch также применяются, когда агент выполняет эквивалентные shell-команды. Например, если Read(./.env) указано в deny, агент не сможет обойти это через cat .env в shell-команде. Поддерживаемые shell-команды включают cat, grep, curl, wget, cp, mv, rm, chmod и многие другие. Неизвестные/безопасные команды (например, git) не затрагиваются правилами файлов/сети.

Миграция из устаревших настроек:

Пример конфигурации:

{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm run *)", "Read(//Users/alice/code/**)"],
    "ask": ["Bash(git push *)", "Edit"],
    "deny": ["Bash(rm -rf *)", "Read(.env)", "WebFetch(malicious.com)"]
  }
}

[!tip] Используйте /permissions в интерактивном CLI для просмотра, добавления и удаления правил без редактирования settings.json напрямую.

slashCommands

Управляет тем, какие слеш-команды доступны в CLI. Полезно для ограничения поверхности команд в мультитенантных или корпоративных развертываниях.

Тот же список запрета может быть передан через флаг CLI --disabled-slash-commands (через запятую или повторяющийся) и переменную окружения QWEN_DISABLED_SLASH_COMMANDS; значения из всех трёх источников объединяются.

Пример — блокировка встроенных команд для изолированного развертывания:

{
  "slashCommands": {
    "disabled": ["auth", "mcp", "extensions", "ide", "quit"]
  }
}

С этими значениями в системном settings.json (/etc/qwen-code/settings.json или QWEN_CODE_SYSTEM_SETTINGS_PATH) пользователи не могут уменьшить список запрета из своей области видимости, и отключённые команды не будут отображаться в автодополнении и не будут выполняться при вводе.

[!note] Эта настройка ограничивает только слеш-команды (например, /auth, /mcp). Она не затрагивает разрешения инструментов — для этого используйте permissions.deny. Также она не перехватывает сочетания клавиш, такие как Ctrl+C или Esc.

mcp

lsp

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

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

Настройка LSP-сервера осуществляется через файлы .lsp.json в корневой директории проекта, а не через settings.json. Дополнительные сведения о конфигурации и примеры см. в документации по LSP.

security

advanced

experimental

mcpServers

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

telemetry

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

Пример settings.json

Вот пример файла settings.json с вложенной структурой, начиная с версии v0.3.0:

{
  "proxy": "http://localhost:7890",
  "plansDirectory": "./.qwen/plans",
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of 'em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1",
    "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,
    "includeSensitiveSpanAttributes": false
  },
  "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, могут переопределять другие настройки для данной конкретной сессии.

Для выбора образа sandbox приоритет следующий: --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > встроенный образ по умолчанию.

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

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

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

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

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

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

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

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

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

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

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

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

• Иерархическая загрузка и приоритет: CLI реализует иерархическую систему памяти, загружая контекстные файлы (например, QWEN.md) из нескольких местоположений. Содержимое файлов, расположенных ниже в этом списке (более специфичные), обычно переопределяет или дополняет содержимое из файлов, расположенных выше (более общие). Точный порядок объединения и итоговый контекст можно просмотреть в диалоге /memory. Типичный порядок загрузки:
  1. Глобальный контекстный файл:
     • Расположение: ~/.qwen/<настроенное-имя-контекстного-файла> (например, ~/.qwen/QWEN.md в вашей домашней директории).
     • Область действия: Предоставляет инструкции по умолчанию для всех ваших проектов.
  2. Контекстные файлы корня проекта и родительских директорий:
     • Расположение: CLI ищет настроенный контекстный файл в текущей рабочей директории, а затем в каждой родительской директории вплоть до корня проекта (определяется по папке .git) или вашей домашней директории.
     • Область действия: Предоставляет контекст, релевантный для всего проекта или его значительной части.
• Объединение и индикация в UI: Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их происхождение и путь) и передается как часть системного промпта. Нижний колонтитул CLI отображает количество загруженных контекстных файлов, давая вам быструю визуальную подсказку об активном инструктивном контексте.
• Импорт содержимого: Вы можете модуляризировать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса @path/to/file.md. Для получения дополнительной информации см. Документацию по памяти.
• Команды для управления памятью:
  • Используйте /memory, чтобы открыть диалог управления памятью.
  • Обновите память из диалога, чтобы повторно просканировать и перезагрузить контекстные файлы из всех настроенных местоположений.
  • См. Документацию по командам для получения полной информации о команде /memory.

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

Песочница

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

Песочница отключена по умолчанию, но вы можете включить ее несколькими способами:

• Используя флаг --sandbox или -s.
• Установив переменную окружения QWEN_SANDBOX.
• Установив параметр tools.sandbox в настройках.

⚠️ --yolo не включает автоматически песочницу. Режим YOLO только автоматически одобряет вызовы инструментов; использование песочницы по-прежнему должно быть явно выбрано через --sandbox, QWEN_SANDBOX или tools.sandbox. При безголовых/неинтерактивных запусках с --yolo (или --approval-mode=yolo) и без песочницы модель может выполнять инструменты оболочки, записи и редактирования на уровне привилегий текущего процесса — в этом случае Qwen Code выводит предупреждение в stderr. Подавите его с помощью QWEN_CODE_SUPPRESS_YOLO_WARNING=1, как только вы оцените компромисс. По умолчанию используется предварительно собранный Docker-образ qwen-code-sandbox.

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

FROM qwen-code-sandbox
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

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

BUILD_SANDBOX=1 qwen -s

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

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

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

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

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

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

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

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

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