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

top-level

general

output

ui

ide

privacy

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

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.

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

fastModel

context

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

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

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

tools

memory

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

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

Управляет доступностью слэш-команд в 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

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",
  "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
  },
  "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 см. Authentication.

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

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

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

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

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

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

Хотя это не строго конфигурация поведения CLI, файлы контекста (по умолчанию QWEN.md, но настраивается через context.fileName) критически важны для настройки инструктивного контекста (также называемого «памятью»). Эта мощная функция позволяет давать проекту специфичные инструкции, руководства по стилю кода или любую релевантную справочную информацию для ИИ, делая его ответы более адаптированными и точными под ваши нужды. 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 20+.

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

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

Песочница

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

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

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

По умолчанию используется предварительно собранный 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
  }
}