Конфигурация Qwen Code
Qwen Code предоставляет несколько способов настройки своего поведения, включая переменные окружения, аргументы командной строки и файлы настроек. В этом документе описаны различные методы конфигурации и доступные параметры.
Уровни конфигурации
Конфигурация применяется в следующем порядке приоритета (параметры с меньшими номерами переопределяются параметрами с большими номерами):
- Значения по умолчанию: Жестко закодированные значения по умолчанию внутри приложения.
- Файл пользовательских настроек: Глобальные настройки для текущего пользователя.
- Файл настроек проекта: Настройки, специфичные для проекта.
- Файл системных настроек: Настройки на уровне всей системы.
- Переменные окружения: Переменные на уровне всей системы или сессии, потенциально загружаемые из файлов
.env
. - Аргументы командной строки: Значения, переданные при запуске CLI.
Файлы настроек
Qwen Code использует файлы settings.json
для хранения постоянных настроек. Эти файлы могут находиться в трех местах:
-
Файл пользовательских настроек:
- Расположение:
~/.qwen/settings.json
(где~
— это домашняя директория пользователя). - Область применения: Настройки применяются ко всем сессиям Qwen Code для текущего пользователя.
- Расположение:
-
Файл настроек проекта:
- Расположение:
.qwen/settings.json
в корневой директории проекта. - Область применения: Настройки применяются только при запуске Qwen Code из этого конкретного проекта. Настройки проекта переопределяют пользовательские настройки.
- Расположение:
-
Файл системных настроек:
- Расположение:
/etc/qwen-code/settings.json
(Linux),C:\ProgramData\qwen-code\settings.json
(Windows) или/Library/Application Support/QwenCode/settings.json
(macOS). Путь можно изменить с помощью переменной окруженияQWEN_CODE_SYSTEM_SETTINGS_PATH
. - Область применения: Настройки применяются ко всем сессиям Qwen Code в системе, для всех пользователей. Системные настройки переопределяют как пользовательские, так и проектные настройки. Это может быть полезно системным администраторам в корпоративной среде для централизованного управления настройками Qwen Code пользователей.
- Расположение:
Примечание о переменных окружения в настройках: Строковые значения в ваших файлах settings.json
могут ссылаться на переменные окружения, используя синтаксис $VAR_NAME
или ${VAR_NAME}
. Эти переменные будут автоматически подставлены при загрузке настроек. Например, если у вас есть переменная окружения MY_API_TOKEN
, вы можете использовать её в settings.json
следующим образом: "apiKey": "$MY_API_TOKEN"
.
Каталог .qwen
в вашем проекте
Помимо файла настроек проекта, каталог .qwen
может содержать другие файлы, относящиеся к работе Qwen Code, например:
- Пользовательские профили песочницы (например,
.qwen/sandbox-macos-custom.sb
,.qwen/sandbox.Dockerfile
).
Доступные настройки в settings.json
:
-
contextFileName
(string или массив строк):- Описание: Указывает имя файла для контекстных файлов (например,
QWEN.md
,AGENTS.md
). Может быть одним именем файла или списком допустимых имен файлов. - По умолчанию:
QWEN.md
- Пример:
"contextFileName": "AGENTS.md"
- Описание: Указывает имя файла для контекстных файлов (например,
-
bugCommand
(object):- Описание: Переопределяет URL по умолчанию для команды
/bug
. - По умолчанию:
"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"
- Свойства:
urlTemplate
(string): URL, который может содержать заполнители{title}
и{info}
.
- Пример:
"bugCommand": { "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" }
- Описание: Переопределяет URL по умолчанию для команды
-
fileFiltering
(object):- Описание: Управляет поведением фильтрации файлов с учетом git для команд @ и инструментов поиска файлов.
- По умолчанию:
"respectGitIgnore": true, "enableRecursiveFileSearch": true
- Свойства:
respectGitIgnore
(boolean): Следует ли учитывать шаблоны .gitignore при поиске файлов. Если установлено значениеtrue
, файлы, игнорируемые git (например,node_modules/
,dist/
,.env
), автоматически исключаются из команд @ и операций перечисления файлов.enableRecursiveFileSearch
(boolean): Следует ли включить рекурсивный поиск имен файлов в текущем дереве при завершении префиксов @ в prompt.
- Пример:
"fileFiltering": { "respectGitIgnore": true, "enableRecursiveFileSearch": false }
-
coreTools
(массив строк):- Описание: Позволяет указать список имен основных инструментов, которые должны быть доступны модели. Это можно использовать для ограничения набора встроенных инструментов. См. Встроенные инструменты для списка основных инструментов. Вы также можете указать ограничения для конкретных команд для инструментов, которые это поддерживают, например,
ShellTool
. Например,"coreTools": ["ShellTool(ls -l)"]
разрешит выполнение только командыls -l
. - По умолчанию: Все инструменты, доступные для использования моделью.
- Пример:
"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
.
- Описание: Позволяет указать список имен основных инструментов, которые должны быть доступны модели. Это можно использовать для ограничения набора встроенных инструментов. См. Встроенные инструменты для списка основных инструментов. Вы также можете указать ограничения для конкретных команд для инструментов, которые это поддерживают, например,
-
excludeTools
(массив строк):- Описание: Позволяет указать список имен основных инструментов, которые должны быть исключены из модели. Инструмент, указанный и в
excludeTools
, и вcoreTools
, будет исключен. Вы также можете указать ограничения для конкретных команд для инструментов, которые это поддерживают, например,ShellTool
. Например,"excludeTools": ["ShellTool(rm -rf)"]
заблокирует командуrm -rf
. - По умолчанию: Нет исключенных инструментов.
- Пример:
"excludeTools": ["run_shell_command", "findFiles"]
. - Примечание по безопасности: Ограничения для конкретных команд в
excludeTools
дляrun_shell_command
основаны на простом сопоставлении строк и могут быть легко обойдены. Эта функция не является механизмом безопасности и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использоватьcoreTools
для явного выбора команд, которые могут быть выполнены.
- Описание: Позволяет указать список имен основных инструментов, которые должны быть исключены из модели. Инструмент, указанный и в
-
allowMCPServers
(массив строк):- Описание: Позволяет указать список имен серверов MCP, которые должны быть доступны модели. Это можно использовать для ограничения набора серверов MCP, к которым можно подключиться. Обратите внимание, что это будет проигнорировано, если установлен флаг
--allowed-mcp-server-names
. - По умолчанию: Все серверы MCP доступны для использования моделью.
- Пример:
"allowMCPServers": ["myPythonServer"]
. - Примечание по безопасности: Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы являетесь системным администратором и хотите предотвратить обход этого ограничения пользователями, рассмотрите возможность настройки
mcpServers
на уровне системных настроек так, чтобы пользователь не мог настроить свои собственные серверы MCP. Это не следует использовать как надежный механизм безопасности.
- Описание: Позволяет указать список имен серверов MCP, которые должны быть доступны модели. Это можно использовать для ограничения набора серверов MCP, к которым можно подключиться. Обратите внимание, что это будет проигнорировано, если установлен флаг
-
excludeMCPServers
(массив строк):- Описание: Позволяет указать список имен серверов MCP, которые должны быть исключены из модели. Сервер, указанный и в
excludeMCPServers
, и вallowMCPServers
, будет исключен. Обратите внимание, что это будет проигнорировано, если установлен флаг--allowed-mcp-server-names
. - По умолчанию: Нет исключенных серверов MCP.
- Пример:
"excludeMCPServers": ["myNodeServer"]
. - Примечание по безопасности: Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы являетесь системным администратором и хотите предотвратить обход этого ограничения пользователями, рассмотрите возможность настройки
mcpServers
на уровне системных настроек так, чтобы пользователь не мог настроить свои собственные серверы MCP. Это не следует использовать как надежный механизм безопасности.
- Описание: Позволяет указать список имен серверов MCP, которые должны быть исключены из модели. Сервер, указанный и в
-
autoAccept
(boolean):- Описание: Управляет тем, будет ли CLI автоматически принимать и выполнять вызовы инструментов, которые считаются безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение
true
, CLI пропустит запрос на подтверждение для инструментов, считающихся безопасными. - По умолчанию:
false
- Пример:
"autoAccept": true
- Описание: Управляет тем, будет ли CLI автоматически принимать и выполнять вызовы инструментов, которые считаются безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение
-
theme
(string):- Описание: Устанавливает визуальную тему для Qwen Code.
- По умолчанию:
"Default"
- Пример:
"theme": "GitHub"
-
vimMode
(boolean):- Описание: Включает или отключает режим vim для редактирования ввода. При включении область ввода поддерживает команды навигации и редактирования в стиле vim с режимами NORMAL и INSERT. Статус режима vim отображается в нижнем колонтитуле и сохраняется между сессиями.
- По умолчанию:
false
- Пример:
"vimMode": true
-
sandbox
(boolean или string):- Описание: Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено значение
true
, Qwen Code использует предварительно собранный Docker-образqwen-code-sandbox
. Дополнительную информацию см. в разделе Песочница. - По умолчанию:
false
- Пример:
"sandbox": "docker"
- Описание: Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено значение
-
toolDiscoveryCommand
(string):- Описание: Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда shell должна возвращать на
stdout
массив JSON объявлений функций . Обертки инструментов являются необязательными. - По умолчанию: Пусто
- Пример:
"toolDiscoveryCommand": "bin/get_tools"
- Описание: Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда shell должна возвращать на
-
toolCallCommand
(string):- Описание: Определяет пользовательскую shell-команду для вызова конкретного инструмента, обнаруженного с помощью
toolDiscoveryCommand
. Команда shell должна соответствовать следующим критериям:- Она должна принимать имя функции (точно как в объявлении функции ) в качестве первого аргумента командной строки.
- Она должна читать аргументы функции в формате JSON из
stdin
, аналогичноfunctionCall.args
. - Она должна возвращать вывод функции в формате JSON в
stdout
, аналогичноfunctionResponse.response.content
.
- По умолчанию: Пусто
- Пример:
"toolCallCommand": "bin/call_tool"
- Описание: Определяет пользовательскую shell-команду для вызова конкретного инструмента, обнаруженного с помощью
-
mcpServers
(object):- Описание: Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например,
serverAlias__actualToolName
), чтобы избежать конфликтов. Обратите внимание, что система может удалить определенные свойства схемы из определений инструментов MCP для совместимости. Необходимо указать хотя бы одно из следующих:command
,url
илиhttpUrl
. Если указано несколько, приоритет имеет следующий порядок:httpUrl
, затемurl
, затемcommand
. - По умолчанию: Пусто
- Свойства:
<SERVER_NAME>
(object): Параметры сервера для указанного сервера.command
(string, необязательно): Команда для запуска сервера MCP через стандартный ввод/вывод.args
(массив строк, необязательно): Аргументы, передаваемые команде.env
(object, необязательно): Переменные окружения, устанавливаемые для процесса сервера.cwd
(string, необязательно): Рабочая директория, в которой запускается сервер.url
(string, необязательно): URL сервера MCP, использующего Server-Sent Events (SSE) для связи.httpUrl
(string, необязательно): URL сервера MCP, использующего потоковое HTTP для связи.headers
(object, необязательно): Карта HTTP-заголовков, отправляемых с запросами кurl
илиhttpUrl
.timeout
(number, необязательно): Таймаут в миллисекундах для запросов к этому серверу MCP.trust
(boolean, необязательно): Доверять этому серверу и обходить все подтверждения вызова инструментов.description
(string, необязательно): Краткое описание сервера, которое может использоваться для отображения.includeTools
(массив строк, необязательно): Список имен инструментов, которые следует включить с этого сервера MCP. Если указано, только перечисленные здесь инструменты будут доступны с этого сервера (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера.excludeTools
(массив строк, необязательно): Список имен инструментов, которые следует исключить с этого сервера MCP. Перечисленные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. Примечание:excludeTools
имеет приоритет надincludeTools
— если инструмент присутствует в обоих списках, он будет исключен.
- Пример:
"mcpServers": { "myPythonServer": { "command": "python", "args": ["mcp_server.py", "--port", "8080"], "cwd": "./mcp_tools/python", "timeout": 5000, "includeTools": ["safe_tool", "file_reader"], }, "myNodeServer": { "command": "node", "args": ["mcp_server.js"], "cwd": "./mcp_tools/node", "excludeTools": ["dangerous_tool", "file_deleter"] }, "myDockerServer": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"], "env": { "API_KEY": "$MY_API_TOKEN" } }, "mySseServer": { "url": "http://localhost:8081/events", "headers": { "Authorization": "Bearer $MY_SSE_TOKEN" }, "description": "Пример сервера MCP на основе SSE." }, "myStreamableHttpServer": { "httpUrl": "http://localhost:8082/stream", "headers": { "X-API-Key": "$MY_HTTP_API_KEY" }, "description": "Пример сервера MCP на основе потокового HTTP." } }
- Описание: Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например,
-
checkpointing
(object):- Описание: Настраивает функцию контрольных точек, которая позволяет сохранять и восстанавливать состояния разговора и файлов. Подробнее см. в документации по контрольным точкам.
- По умолчанию:
{"enabled": false}
- Свойства:
enabled
(boolean): Еслиtrue
, команда/restore
становится доступной.
-
preferredEditor
(string):- Описание: Указывает предпочтительный редактор для просмотра diff.
- По умолчанию:
vscode
- Пример:
"preferredEditor": "vscode"
-
telemetry
(object)- Описание: Настраивает сбор логов и метрик для Qwen Code. Подробнее см. в разделе Телеметрия.
- По умолчанию:
{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}
- Свойства:
enabled
(boolean): Включена ли телеметрия.target
(string): Назначение для собранной телеметрии. Поддерживаемые значения:local
иgcp
.otlpEndpoint
(string): Конечная точка для экспортера OTLP.logPrompts
(boolean): Включать ли содержимое пользовательских prompt в логи.
- Пример:
"telemetry": { "enabled": true, "target": "local", "otlpEndpoint": "http://localhost:16686", "logPrompts": false }
-
usageStatisticsEnabled
(boolean):- Описание: Включает или отключает сбор статистики использования. Подробнее см. в разделе Статистика использования.
- По умолчанию:
true
- Пример:
"usageStatisticsEnabled": false
-
hideTips
(boolean):-
Описание: Включает или отключает полезные подсказки в интерфейсе CLI.
-
По умолчанию:
false
-
Пример:
"hideTips": true
-
-
**
Пример settings.json
:
{
"theme": "GitHub",
"sandbox": "docker",
"toolDiscoveryCommand": "bin/get_tools",
"toolCallCommand": "bin/call_tool",
"tavilyApiKey": "$TAVILY_API_KEY",
"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
},
"usageStatisticsEnabled": true,
"hideTips": false,
"hideBanner": false,
"maxSessionTurns": 10,
"summarizeToolOutput": {
"run_shell_command": {
"tokenBudget": 100
}
},
"excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"],
"includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
"loadMemoryFromIncludeDirectories": true
}
История Shell
CLI сохраняет историю выполненных вами shell-команд. Чтобы избежать конфликтов между разными проектами, эта история хранится в директории, специфичной для проекта, внутри домашней папки пользователя.
- Расположение:
~/.qwen/tmp/<project_hash>/shell_history
<project_hash>
— это уникальный идентификатор, сгенерированный на основе корневого пути вашего проекта.- История хранится в файле с именем
shell_history
.
Переменные окружения и файлы .env
Переменные окружения — это распространённый способ конфигурации приложений, особенно для чувствительных данных, таких как API keys, или для настроек, которые могут отличаться в зависимости от среды. Подробнее о настройке аутентификации можно прочитать в документации по аутентификации, где описаны все доступные методы.
CLI автоматически загружает переменные окружения из файла .env
. Порядок загрузки следующий:
- Файл
.env
в текущей рабочей директории. - Если файл не найден, CLI ищет его в родительских директориях, пока не найдёт
.env
или не достигнет корня проекта (определяется по наличию папки.git
) или домашней директории. - Если файл всё ещё не найден, CLI проверяет наличие
~/.env
(в домашней директории пользователя).
Исключение переменных окружения: Некоторые переменные (например, DEBUG
и DEBUG_MODE
) по умолчанию исключаются из проектных .env
файлов, чтобы не мешать работе CLI. Переменные из файлов .qwen/.env
никогда не исключаются. Это поведение можно настроить с помощью параметра excludedProjectEnvVars
в файле settings.json
.
OPENAI_API_KEY
:- Один из доступных методов аутентификации.
- Установите в вашем shell-профиле (например,
~/.bashrc
,~/.zshrc
) или в.env
файле.
OPENAI_BASE_URL
:- Один из доступных методов аутентификации.
- Установите в вашем shell-профиле (например,
~/.bashrc
,~/.zshrc
) или в.env
файле.
OPENAI_MODEL
:- Указывает модель OPENAI по умолчанию.
- Переопределяет значение по умолчанию, заданное в коде.
- Пример:
export OPENAI_MODEL="qwen3-coder-plus"
GEMINI_SANDBOX
:- Альтернатива настройке
sandbox
вsettings.json
. - Принимает значения:
true
,false
,docker
,podman
или строку с кастомной командой.
- Альтернатива настройке
SEATBELT_PROFILE
(только для macOS):- Переключает профиль Seatbelt (
sandbox-exec
) в macOS. permissive-open
: (по умолчанию) Ограничивает запись в папку проекта (и несколько других, см.packages/cli/src/utils/sandbox-macos-permissive-open.sb
), но разрешает другие операции.strict
: Использует строгий профиль, который по умолчанию блокирует операции.<profile_name>
: Использует кастомный профиль. Чтобы определить кастомный профиль, создайте файл с именемsandbox-macos-<profile_name>.sb
в директории.qwen/
вашего проекта (например,my-project/.qwen/sandbox-macos-custom.sb
).
- Переключает профиль Seatbelt (
DEBUG
илиDEBUG_MODE
(часто используются библиотеками или самим CLI):- Установите в
true
или1
, чтобы включить подробный debug-лог, полезный при отладке. - Примечание: Эти переменные по умолчанию исключаются из проектных
.env
файлов, чтобы не мешать работе CLI. Если нужно задать их для Qwen Code, используйте файлы.qwen/.env
.
- Установите в
NO_COLOR
:- Установите любое значение, чтобы отключить цветной вывод в CLI.
CLI_TITLE
:- Установите строку, чтобы изменить заголовок CLI.
CODE_ASSIST_ENDPOINT
:- Указывает endpoint для сервера code assist.
- Полезно при разработке и тестировании.
TAVILY_API_KEY
:- Ваш API key для сервиса веб-поиска Tavily.
- Необходим для включения функциональности инструмента
web_search
. - Если не задан, инструмент веб-поиска будет отключён и пропущен.
- Пример:
export TAVILY_API_KEY="tvly-your-api-key-here"
Аргументы командной строки
Аргументы, переданные напрямую при запуске CLI, могут переопределять другие настройки для текущей сессии.
--model <model_name>
(-m <model_name>
):- Указывает, какую модель Qwen использовать в этой сессии.
- Пример:
npm start -- --model qwen3-coder-plus
--prompt <your_prompt>
(-p <your_prompt>
):- Используется для передачи prompt’а напрямую в команду. Это запускает Qwen Code в неинтерактивном режиме.
--prompt-interactive <your_prompt>
(-i <your_prompt>
):- Запускает интерактивную сессию с указанным prompt’ом в качестве начального ввода.
- Prompt обрабатывается внутри интерактивной сессии, а не до неё.
- Не может использоваться при передаче ввода через stdin.
- Пример:
qwen -i "explain this code"
--sandbox
(-s
):- Включает режим песочницы для этой сессии.
--sandbox-image
:- Устанавливает URI образа песочницы.
--debug
(-d
):- Включает режим отладки для этой сессии, предоставляя более подробный вывод.
--all-files
(-a
):- Если установлен, рекурсивно включает все файлы в текущей директории в качестве контекста для prompt’а.
--help
(или-h
):- Отображает справочную информацию по аргументам командной строки.
--show-memory-usage
:- Отображает текущее использование памяти.
--yolo
:- Включает режим YOLO, который автоматически одобряет все вызовы инструментов.
--approval-mode <mode>
:- Устанавливает режим подтверждения вызовов инструментов. Доступные режимы:
default
: Запрашивать подтверждение для каждого вызова инструмента (поведение по умолчанию)auto_edit
: Автоматически одобрять инструменты редактирования (edit, write_file), запрашивая подтверждение для остальныхyolo
: Автоматически одобрять все вызовы инструментов (эквивалент--yolo
)
- Не может использоваться вместе с
--yolo
. Используйте--approval-mode=yolo
вместо--yolo
для нового унифицированного подхода. - Пример:
qwen --approval-mode auto_edit
- Устанавливает режим подтверждения вызовов инструментов. Доступные режимы:
--telemetry
:- Включает телеметрию.
--telemetry-target
:- Устанавливает цель телеметрии. Подробнее см. в телеметрии.
--telemetry-otlp-endpoint
:- Устанавливает OTLP endpoint для телеметрии. Подробнее см. в телеметрии.
--telemetry-otlp-protocol
:- Устанавливает OTLP протокол для телеметрии (
grpc
илиhttp
). По умолчанию —grpc
. Подробнее см. в телеметрии.
- Устанавливает OTLP протокол для телеметрии (
--telemetry-log-prompts
:- Включает логирование prompt’ов для телеметрии. Подробнее см. в телеметрии.
--checkpointing
:- Включает checkpointing.
--extensions <extension_name ...>
(-e <extension_name ...>
):- Указывает список расширений для использования в сессии. Если не указано, используются все доступные расширения.
- Используйте специальное значение
qwen -e none
, чтобы отключить все расширения. - Пример:
qwen -e my-extension -e my-other-extension
--list-extensions
(-l
):- Выводит список всех доступных расширений и завершает работу.
--proxy
:- Устанавливает proxy для CLI.
- Пример:
--proxy http://localhost:7890
.
--include-directories <dir1,dir2,...>
:- Добавляет дополнительные директории в рабочее пространство для поддержки работы с несколькими директориями.
- Можно указывать несколько раз или через запятую.
- Максимум можно добавить 5 директорий.
- Пример:
--include-directories /path/to/project1,/path/to/project2
или--include-directories /path/to/project1 --include-directories /path/to/project2
--version
:- Отображает версию CLI.
--openai-logging
:- Включает логирование вызовов OpenAI API для отладки и анализа. Этот флаг переопределяет настройку
enableOpenAILogging
вsettings.json
.
- Включает логирование вызовов OpenAI API для отладки и анализа. Этот флаг переопределяет настройку
--tavily-api-key <api_key>
:- Устанавливает Tavily API key для функции веб-поиска в этой сессии.
- Пример:
qwen --tavily-api-key tvly-your-api-key-here
Файлы контекста (иерархический instructional context)
Хотя файлы контекста не являются строгой конфигурацией поведения CLI, они играют ключевую роль в настройке инструкционного контекста (также называемого “памятью”). По умолчанию используется файл QWEN.md
, но имя файла можно изменить через настройку contextFileName
. Эта мощная функция позволяет передавать AI проект-специфичные инструкции, руководства по стилю кода или любую другую релевантную информацию, делая ответы модели более точными и соответствующими вашим потребностям. CLI включает UI-элементы, например, индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста.
- Назначение: Эти Markdown-файлы содержат инструкции, руководящие принципы или контекст, который вы хотите, чтобы модель Qwen учитывала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически.
Пример содержимого контекстного файла (например, QWEN.md
)
Вот концептуальный пример того, что может содержать контекстный файл в корне проекта на TypeScript:
# Project: My Awesome TypeScript Library
## Общие инструкции:
- При генерации нового кода на TypeScript следуйте существующему стилю кодирования.
- Убедитесь, что все новые функции и классы сопровождаются комментариями JSDoc.
- Предпочтительно использовать парадигмы функционального программирования, где это уместно.
- Весь код должен быть совместим с TypeScript 5.0 и Node.js 20+.
## Стиль кодирования:
- Используйте 2 пробела для отступов.
- Имена интерфейсов должны начинаться с префикса `I` (например, `IUserService`).
- Приватные члены класса должны начинаться с символа подчеркивания (`_`).
- Всегда используйте строгое равенство (`===` и `!==`).
## Конкретный компонент: `src/api/client.ts`
- Этот файл обрабатывает все исходящие API-запросы.
- При добавлении новых функций вызова API убедитесь, что они включают надежную обработку ошибок и логирование.
- Используйте существующую утилиту `fetchWithRetry` для всех GET-запросов.
```markdown
## О зависимостях:
- Избегайте добавления новых внешних зависимостей, если в этом нет абсолютной необходимости.
- Если новая зависимость необходима, пожалуйста, укажите причину.
Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения по кодированию, а также заметки о конкретных файлах или компонентах. Чем более релевантны и точны ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Мы настоятельно рекомендуем использовать специфичные для проекта контекстные файлы для установления соглашений и контекста.
- **Иерархическая загрузка и приоритет:** CLI реализует сложную иерархическую систему памяти, загружая контекстные файлы (например, `QWEN.md`) из нескольких источников. Содержимое файлов, находящихся ниже в этом списке (более специфичных), обычно переопределяет или дополняет содержимое файлов выше (более общих). Точный порядок объединения и финальный контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки следующий:
1. **Глобальный контекстный файл:**
- Расположение: `~/.qwen/<contextFileName>` (например, `~/.qwen/QWEN.md` в вашем домашнем каталоге пользователя).
- Область применения: Предоставляет стандартные инструкции для всех ваших проектов.
2. **Контекстные файлы корня проекта и его предков:**
- Расположение: CLI ищет указанный контекстный файл в текущем рабочем каталоге, а затем в каждом родительском каталоге вплоть до корня проекта (определяемого папкой `.git`) или вашего домашнего каталога.
- Область применения: Предоставляет контекст, относящийся ко всему проекту или значительной его части.
3. **Контекстные файлы подкаталогов (локальные/контекстуальные):**
- Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущего рабочего каталога (с учетом стандартных игнорируемых паттернов, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`.
- Область применения: Позволяет задавать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта.
- **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного prompt'а. В нижнем колонтитуле CLI отображается количество загруженных контекстных файлов — это позволяет быстро визуально оценить активный инструкционный контекст.
- **Импорт содержимого:** Вы можете модуляризировать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса `@path/to/file.md`. Подробнее см. в [документации Memory Import Processor](../core/memport.md).
- **Команды управления памятью:**
- Используйте `/memory refresh`, чтобы принудительно пересканировать и перезагрузить все контекстные файлы из всех настроенных источников. Это обновит инструкционный контекст ИИ.
- Используйте `/memory show`, чтобы отобразить текущий объединённый инструкционный контекст, что позволит вам проверить иерархию и содержимое, используемое ИИ.
- Полная информация о команде `/memory` и её подкомандах (`show` и `refresh`) доступна в [документации по командам](./commands.md#memory).
Понимая и используя эти уровни конфигурации и иерархическую природу контекстных файлов, вы сможете эффективно управлять памятью ИИ и адаптировать ответы Qwen Code под ваши конкретные нужды и проекты.
Sandboxing
Qwen Code может выполнять потенциально небезопасные операции (например, shell-команды и модификации файлов) в sandbox-окружении, чтобы защитить вашу систему.
По умолчанию sandboxing отключен, но вы можете включить его несколькими способами:
- Используя флаг
--sandbox
или-s
. - Установив переменную окружения
GEMINI_SANDBOX
. - Sandbox включается по умолчанию при использовании
--yolo
или--approval-mode=yolo
.
По умолчанию используется готовый Docker-образ qwen-code-sandbox
.
Если вашему проекту нужны особые настройки sandboxing, вы можете создать собственный Dockerfile по пути .qwen/sandbox.Dockerfile
в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе:
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 для автоматической сборки кастомного sandbox-образа:
```bash
BUILD_SANDBOX=1 qwen -s
Статистика использования
Чтобы помочь нам улучшить Qwen Code, мы собираем анонимизированную статистику использования. Эти данные помогают нам понять, как используется CLI, выявить распространенные проблемы и определить приоритеты для новых функций.
Что мы собираем:
- Вызовы инструментов: Мы записываем названия вызванных инструментов, успешность их выполнения и время выполнения. Мы не собираем аргументы, переданные инструментам, или любые данные, возвращенные ими.
- API-запросы: Мы записываем модель, использованную для каждого запроса, продолжительность запроса и его успешность. Мы не собираем содержимое промтов или ответов.
- Информация о сессии: Мы собираем информацию о конфигурации CLI, например, включенные инструменты и режим подтверждения.
Что мы НЕ собираем:
- Персональные данные (PII): Мы не собираем никакой личной информации, такой как ваше имя, адрес электронной почты или API-ключи.
- Содержимое промтов и ответов: Мы не записываем содержимое ваших промтов или ответов модели.
- Содержимое файлов: Мы не записываем содержимое файлов, которые читаются или записываются CLI.
Как отказаться от сбора:
Вы можете отказаться от сбора статистики использования в любое время, установив значение свойства usageStatisticsEnabled
в false
в вашем файле settings.json
:
{
"usageStatisticsEnabled": false
}
Примечание: Когда статистика использования включена, события отправляются на эндпоинт сбора Alibaba Cloud RUM.
enableWelcomeBack
(boolean):- Описание: Показывать диалог приветствия при возвращении в проект с историей разговора.
- По умолчанию:
true
- Категория: UI
- Требуется перезапуск: Нет
- Пример:
"enableWelcomeBack": false
- Подробности: Если включено, Qwen Code автоматически определит, возвращаетесь ли вы в проект с ранее сгенерированным сводным файлом проекта (
.qwen/PROJECT_SUMMARY.md
), и покажет диалог, позволяющий продолжить предыдущий разговор или начать заново. Эта функция интегрируется с командой/chat summary
и диалогом подтверждения выхода. Подробнее см. в документации Welcome Back.