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

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" сохраняет стандартную структуру массива частей содержимого. Устанавливайте "string" только для устаревших сред выполнения, совместимых с OpenAI, в шаблонах инструментов которых игнорируются текстовые части содержимого, например старые шаблоны 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, см. в разделе Memory.

permissions

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

Приоритет принятия решений (от высшего к низшему): deny > ask > allow > (default/interactive mode)

Первое совпавшее правило побеждает. Правила используют формат "ToolName" или "ToolName(specifier)".

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

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

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

[!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,
    "sensitiveSpanAttributeMaxLength": 1048576
  },
  "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-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > встроенный образ по умолчанию.

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

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

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

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

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

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

# Project: My Awesome TypeScript Library

## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 22+.

## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

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

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

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

Песочница (Sandbox)

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

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

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

⚠️ --yolo не включает песочницу автоматически. Режим YOLO только автоматически подтверждает вызовы инструментов; использование песочницы все равно должно быть включено через --sandbox, QWEN_SANDBOX или tools.sandbox. В headless/неинтерактивных запусках с --yolo (или --approval-mode=yolo) и без песочницы модель может выполнять инструменты shell, write и edit на уровне привилегий текущего процесса — в этом случае 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
  }
}