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

Уровни конфигурации

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

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

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

Директория .qwen в вашем проекте

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

• Пользовательские профили песочницы (например, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Навыки агента (Agent Skills) в директории .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
      }
    }
  }
}

timeout (таймаут запроса):

timeout — это таймаут для каждого запроса в миллисекундах (по умолчанию 120000). Установите значение 0, чтобы отключить таймаут запроса (согласно соглашению QWEN_STREAM_IDLE_TIMEOUT_MS=0), вместо прерывания запроса. Также его можно задать через переменную окружения QWEN_CODE_API_TIMEOUT_MS. Это отличается от QWEN_STREAM_IDLE_TIMEOUT_MS, который ограничивает время неактивности между потоковыми чанками.

max_tokens (лимит токенов на вывод):

Если не заданы ни samplingParams.max_tokens, ни QWEN_CODE_MAX_OUTPUT_TOKENS, Qwen Code обычно использует заявленный лимит вывода выбранной модели в качестве лимита по умолчанию для запроса. Если ответ всё равно достигает этого лимита, Qwen Code может повторить попытку с повышенным лимитом (с нижним порогом 64K) и затем продолжить работу в следующих итерациях.

Для OpenAI-совместимых провайдеров samplingParams также служит обходным путём для передачи параметров «как есть»: если он задан, его ключи передаются дословно, и Qwen Code не генерирует значение max_tokens по умолчанию. Используйте это для специфичных для провайдера параметров, таких как max_completion_tokens.

Чтобы принудительно установить фиксированный лимит вывода, задайте 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

visionModel

voiceModel

modelFallbacks

modelPricing

context

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

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

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

tools

memory

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

permissions

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

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

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

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

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

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

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

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

Префиксы шаблонов путей:

Предотвращение обхода команд оболочки:

Правила разрешений для Read, Edit и WebFetch также применяются, когда агент выполняет эквивалентные команды оболочки. Например, если Read(./.env) находится в deny, агент не сможет обойти это с помощью cat .env в команде оболочки. Поддерживаемые команды оболочки включают 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

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

Тот же самый список блокировок (denylist) можно передать через флаг 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] Эта настройка управляет только slash-командами (например, /auth, /mcp). Она не влияет на разрешения инструментов — для этого см. permissions.deny. Она также не перехватывает сочетания клавиш, такие как Ctrl+C или Esc.

skills

Управляет тем, какие навыки (Skills) доступны модели.

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.

Телеметрия

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

Пример settings.json

Вот пример файла settings.json с вложенной структурой, новой начиная с версии 0.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 > встроенный образ по умолчанию.

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

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

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

• Назначение: Эти 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.

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

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

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

Песочница

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
  }
}