Настройка Qwen Code

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

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

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

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

Каталог .qwen в вашем проекте

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

• Пользовательские профили песочницы (например, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Навыки агента (экспериментальные) в подкаталоге .qwen/skills/ (каждый навык — это каталог, содержащий файл SKILL.md).

Доступные настройки в settings.json

Настройки организованы по категориям. Все настройки должны размещаться в соответствующих объектах категории верхнего уровня в вашем файле settings.json.

general

output

ui

ide

privacy

model

Пример model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "disableCacheControl": false,
      "customHeaders": {
        "X-Request-ID": "req-123",
        "X-User-ID": "user-456"
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

Поле customHeaders позволяет добавлять пользовательские HTTP-заголовки ко всем API-запросам. Это полезно для трассировки запросов, мониторинга, маршрутизации через API-шлюзы или когда разным моделям требуются разные заголовки. Если customHeaders определен в modelProviders[].generationConfig.customHeaders, он будет использоваться напрямую; в противном случае будут использоваться заголовки из model.generationConfig.customHeaders. Объединение между двумя уровнями не происходит.

Примеры 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"
          },
          "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 обрабатываются атомарно; значения провайдера заменяют весь объект. Если 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. Отключите нечеткий поиск: Если игнорирование файлов не помогает, вы можете отключить нечеткий поиск, установив для параметра disableFuzzySearch значение true в вашем файле settings.json. Это позволит использовать более простой, нечеткий алгоритм сопоставления, который может работать быстрее.
3. Отключите рекурсивный поиск файлов: В крайнем случае, вы можете полностью отключить рекурсивный поиск файлов, установив для параметра enableRecursiveFileSearch значение false. Это будет самым быстрым вариантом, поскольку он избегает рекурсивного обхода вашего проекта. Однако это означает, что вам придется вводить полный путь к файлам при использовании автозаполнения с помощью @.

tools

mcp

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

advanced

experimental

mcpServers

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

телеметрия

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

Пример settings.json

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

Песочница [Sandbox](../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

# КОПИРОВАТЬ ./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
  }
}