Конфигурация 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.

general

output

ui

ide

privacy

model

Пример model.generationConfig:

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

contextWindowSize:

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

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

modelProviders

Используйте modelProviders, чтобы объявить отобранные списки моделей для каждого типа аутентификации, между которыми можно переключаться в /model. Ключи должны быть действительными типами аутентификации (openai, anthropic, gemini, vertex-ai и т.д.). Каждая запись требует id и должна включать envKey, с необязательными полями name, description, baseUrl и generationConfig. Учетные данные никогда не сохраняются в настройках; во время выполнения они считываются из process.env[envKey]. Модели Qwen OAuth остаются жестко закодированными и не могут быть переопределены.

Пример

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "customHeaders": {
            "X-Model-Version": "v1.0",
            "X-Request-Priority": "high"
          },
          "extra_body": {
            "enable_thinking": true
          },
          "samplingParams": { "temperature": 0.2 }
        }
      }
    ],
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ],
    "vertex-ai": [
      {
        "id": "gemini-1.5-pro-vertex",
        "envKey": "GOOGLE_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ]
  }
}

[!note] Только команда /model предоставляет доступ к нестандартным типам аутентификации. Anthropic, Gemini, Vertex AI и т. д. должны быть определены через modelProviders. Команда /auth намеренно перечисляет только встроенный Qwen OAuth и потоки OpenAI.

Слои разрешения и атомарность

Эффективные значения auth/model/credential выбираются для каждого поля с использованием следующего приоритета (первый присутствующий выигрывает). Вы можете комбинировать --auth-type с --model, чтобы напрямую указать на запись провайдера; эти флаги CLI выполняются перед другими слоями.

*При наличии флаги CLI для аутентификации переопределяют настройки. В противном случае, security.auth.selectedType или неявное значение по умолчанию определяет тип аутентификации. Qwen OAuth и OpenAI — единственные типы аутентификации, которые отображаются без дополнительной настройки.

Значения, полученные из поставщика моделей, применяются атомарно: как только модель провайдера становится активной, каждое поле, которое она определяет, защищено от более низких слоев до тех пор, пока вы вручную не очистите учетные данные через /auth. Окончательный generationConfig представляет собой проекцию по всем слоям — более низкие слои заполняют только пробелы, оставленные более высокими, а слой провайдера остается непроницаемым.

Стратегия объединения для modelProviders — ЗАМЕНА: весь раздел modelProviders из настроек проекта заменит соответствующий раздел в пользовательских настройках, а не будет объединяться с ним.

Слойность конфигурации генерации

Приоритетность по полям для generationConfig:

1. Программные переопределения (например, изменения во время выполнения /model, /auth)
2. modelProviders[authType][].generationConfig
3. settings.model.generationConfig
4. Значения по умолчанию для генератора контента (getDefaultGenerationConfig для OpenAI, getParameterValue для Gemini и т.д.)

samplingParams, customHeaders и extra_body обрабатываются атомарно; значения провайдера заменяют весь объект. Если modelProviders[].generationConfig определяет эти поля, они используются напрямую; в противном случае используются значения из model.generationConfig. Объединение между уровнями конфигурации провайдера и глобальной конфигурации не происходит. Значения по умолчанию от генератора контента применяются последними, чтобы каждый провайдер сохранял свою настроенную базовую линию.

Постоянство выбора и рекомендации

[!important] По возможности определяйте modelProviders в пользовательской области ~/.qwen/settings.json и избегайте сохранения переопределений учетных данных в любой области. Хранение каталога поставщиков в пользовательских настройках предотвращает конфликты объединения/переопределения между проектной и пользовательской областями и гарантирует, что обновления /auth и /model всегда записываются обратно в согласованную область.

• /model и /auth сохраняют model.name (где применимо) и security.auth.selectedType в ближайшую доступную для записи область, которая уже определяет modelProviders; в противном случае они возвращаются к пользовательской области. Это позволяет синхронизировать файлы рабочей области/пользователя с активным каталогом поставщиков.
• Без modelProviders средство разрешения смешивает уровни CLI/env/settings, что приемлемо для установок с одним поставщиком, но неудобно при частом переключении. Определяйте каталоги поставщиков всякий раз, когда многомодульные рабочие процессы являются обычными, чтобы переключения оставались атомарными, с указанием источника и отладкой.

context

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

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

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

tools

mcp

lsp

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

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

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

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

advanced

mcpServers

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

телеметрия

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

Пример settings.json

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

{
  "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",
    "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",
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "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`
- Этот файл обрабатывает все исходящие запросы к API.
- При добавлении новых функций вызова API убедитесь, что они включают надежную обработку ошибок и ведение журнала.
- Используйте существующую утилиту `fetchWithRetry` для всех GET-запросов.

Что касается зависимостей:

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

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

- **Иерархическая загрузка и приоритетность:** 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`.
- Установив переменную окружения `GEMINI_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

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

> [!note]
>
> Когда статистика использования включена, события отправляются на конечную точку сбора данных Alibaba Cloud RUM.