Справочник по конфигурации
Обзор
На этой странице собраны все настройки, влияющие на демон qwen serve и его адаптеры: переменные окружения, флаги CLI, ключи settings.json и программные опции. Страницы, посвященные отдельным функциям, ссылаются сюда, когда требуются сквозные детали конфигурации.
Флаги CLI (qwen serve)
| Флаг | Тип | По умолчанию | Действие |
|---|---|---|---|
--hostname <host> | string | 127.0.0.1 | Адрес привязки. Значения loopback: 127.0.0.1, localhost, ::1, [::1]. Для не-loopback адресов при запуске требуется bearer-токен. Ввод в формате host:port отклоняется с рекомендацией использовать --port. |
--port <n> | number | 4170 | Порт прослушивания; 0 означает эфемерный порт. |
--token <s> | string | env | Bearer-токен. Переопределяет QWEN_SERVER_TOKEN и обрезается при запуске. Отображается в командной строке процесса, поэтому при развертывании лучше использовать переменную окружения. |
--open | boolean | false | Открыть смонтированный Web Shell после готовности среды выполнения. Настроенный токен доставляется как фрагмент URL. Обычный --open остаётся тихим no-op, когда запуск браузера невозможен. |
--open-with-auth | boolean | false | Открыть Web Shell с bearer-аутентификацией на loopback. Требуется включённый Web Shell и собранные ресурсы. Повторно использует выбранный --token / QWEN_SERVER_TOKEN или генерирует 256-битный bearer на время жизни процесса перед прослушиванием. В окружении без поддержки браузера запускается и печатает URL с секретом в фрагменте. Не является настройкой ServeOptions или SDK. |
--require-auth | boolean | false | Расширяет действие bearer-аутентификации на loopback и /health; запуск прерывается, если токен не задан. |
--workspace <dir> | absolute path / repeatable | process.cwd() | Стартовое рабочее пространство; можно повторять для регистрации дополнительных изолированных сред выполнения. Первое является основным. Каждое значение должно быть абсолютным путём к директории; канонизируется при запуске. |
--memory-project-scope <mode> | git-root / workspace | workspace | Разделение памяти проекта. workspace изолирует по точному каталогу рабочего пространства; git-root — устаревшая область совместимости, общая для рабочих пространств с одним Git-корнем. Переопределяет QWEN_CODE_MEMORY_PROJECT_SCOPE. |
--max-sessions <n> | number | 32 | Лимит активных сессий на рабочее пространство. 0 / Infinity означает без ограничений; NaN / отрицательные значения вызывают ошибку. |
--max-total-sessions <n> | number | вычисляется для нескольких рабочих пространств при запуске | Общесистемный лимит активных сессий демона. Если не указан, конечное значение по умолчанию вычисляется один раз из лимита на рабочее пространство и количества рабочих пространств при запуске. 0 / Infinity означает без ограничений. |
--max-pending-prompts-per-session <n> | number | 5 | Лимит принятых, но ожидающих/выполняющихся промптов на сессию. Превышение лимита возвращает 503. 0 / Infinity означает без ограничений; отрицательные или нецелые значения вызывают ошибку. |
--max-connections <n> | number | 256 | server.maxConnections для HTTP-слушателя; 0 / Infinity означает без ограничений. |
--enable-session-shell | boolean | false | Включает прямое выполнение POST /session/:id/shell. Требуется bearer-токен, и каждый вызов должен содержать привязанный к сессии X-Qwen-Client-Id. |
--event-ring-size <n> | number | 8000 | Кольцо повтора SSE для каждой сессии; мягкий лимит — 1_000_000. |
--compacted-replay-max-bytes <n> | positive integer | 4194304 | Ограничение в байтах для ограниченного снимка воспроизведения в памяти, возвращаемого POST /session/:id/load; жёсткий лимит — 268435456. |
--max-journal-events <n> | positive safe integer | 10000 | Базовый лимит на количество записей воспроизведения liveJournal в полёте для незавершённого хода. Адаптивный рост может увеличить его (см. --max-journal-bytes); фиксация любого флага журнала отключает рост. |
--max-journal-bytes <n> | positive safe integer | 8388608 (8 МиБ) | Базовый байтовый лимит liveJournal в полёте для каждой сессии. Когда ход превышает его, адаптивный рост повышает лимиты сессии по требованию, вплоть до удвоения, но ограниченный оставшимся запасом пула и не далее жёсткого лимита 256 МиБ на сессию — в рамках общесистемного пула 5% от эффективного --memory-budget-mb (ограничено 1024 МБ; 0 — рост отключён — когда эффективный бюджет ниже минимума 1024 МБ), общего для каждого bridge рабочего пространства; без запаса самые старые записи отбрасываются с маркером history_truncated. Фиксация любого флага журнала отключает рост. |
--memory-budget-mb <n> | integer in [1024, 1048576] | 50% памяти cgroup или хоста, ограничено максимумом флага (1048576 МБ) | Общий бюджет памяти для дерева процессов демона, ограниченный доступной памятью. Сообщается в limits.memory в статусе демона; не определяет размер дочерних процессов — единственный потребитель на сегодня — адаптивный рост live-journal (см. --max-journal-bytes). Запуск отклоняет значения вне диапазона. |
--memory-pressure-mode <mode> | off | observe | observe | Определяет ли демон уровень давления памяти на основе собственного RSS и кучи V8. Оба режима сообщают runtime.memory.pressure; только observe вызывает daemon_memory_pressure. Только для корневого процесса; без remediation. |
--child-heap-mode <mode> | off | observe | observe | Моделирует ли демон разделение кучи на каждого дочернего процесса из бюджета. observe сообщает об этом и считает запуски сверх лимита; ничего не применяется. off не публикует разделение вообще — maxConcurrentChildren и perChildCeilingMb оба null. |
--http-bridge | boolean | true | Режим моста этапа 1. --no-http-bridge все равно использует резервный http-bridge и выводит предупреждение в stderr. |
--mcp-client-budget <n> | positive integer | unset | Устанавливает WorkspaceMcpBudget.clientBudget и передает его дочернему процессу ACP через childEnvOverrides. |
--mcp-budget-mode <m> | off / warn / enforce | warn, если задан бюджет, иначе off | Устанавливает WorkspaceMcpBudget.mode; для enforce требуется --mcp-client-budget. |
--external-tool-guard-mode <m> | off / required | off | Включает управляемый внешний Guard перед выполнением ACP. required не позволяет запустить демон, если его провайдер loopback не завершит рукопожатие v1. |
--external-tool-guard-endpoint <url> | loopback HTTP(S) origin | unset | Origin провайдера, используется только в режиме required. Должен быть только origin и использовать 127.0.0.1, localhost или ::1; пути, учётные данные, редиректы и маршрутизация через прокси отклоняются. |
--external-tool-guard-timeout-ms <n> | integer 100..30000 | 3000 | Таймаут на каждое рукопожатие и подготовку. Тайм-аут при рукопожатии прерывает запуск; при выполнении — закрывает вызов. |
--allow-origin <pattern> | repeatable string | unset | Белый список cross-origin, заменяющий стандартный запрет CORS. * разрешает любой origin, но требует токен. |
--allow-private-auth-base-url | boolean | false | Позволяет /workspace/auth/provider устанавливать baseUrl для провайдера аутентификации localhost / частной сети; использовать только в доверенной локальной среде разработки. |
--web / --no-web | boolean | true | Раздача собранного Web Shell SPA в корне демона (GET /, /assets/* и навигации по документам /session/:id). Эти точки монтирования размещаются до bearerAuth; каждый API-маршрут остаётся защищённым токеном. --no-web оставляет демон в режиме API-only. |
--prompt-deadline-ms <n> | positive integer | unset | Серверный лимит реального времени выполнения промпта в мс. При тайм-ауте выполнение прерывается и возвращается ошибка. |
--writer-idle-timeout-ms <n> | positive integer | unset | Тайм-аут простоя для каждого SSE-соединения в мс. Демон закрывает SSE-соединение, если в течение этого времени не отправлено ни одного события. |
--channel-idle-timeout-ms <n> | non-negative integer | 0 | Как долго держать дочерний процесс ACP активным после закрытия последней сессии. 0 означает немедленное освобождение ресурсов. |
--initialize-timeout-ms <n> | positive integer | 10000 | Таймаут запросов дочернего процесса ACP, включая рукопожатие initialize (мс). |
--session-restore-timeout-ms <n> | positive integer | 60000 | Таймаут загрузки/восстановления сессии ACP (мс). Когда флаг не указан, явно заданный таймаут инициализации повышает бюджет, но не опускает его ниже значения по умолчанию. |
--permission-response-timeout-ms <n> | non-negative integer | 0 | Общий таймаут реального времени для обычных запросов разрешений и ответов ask_user_question. 0 или отсутствующий флаг ожидает бесконечно; положительное значение включает таймер. |
--session-reap-interval-ms <n> | non-negative integer | 60000 | Интервал сканирования сборщика неактивных сессий; 0 отключает его. |
--session-idle-timeout-ms <n> | non-negative integer | 1800000 | Время простоя отключенной сессии перед сборкой; 0 отключает его. |
--rate-limit / --no-rate-limit | boolean | env / off | Включает HTTP rate limiting для маршрутов промптов, мутаций и чтения с разделением по уровням. |
--rate-limit-prompt <n> | positive integer | 10 | Лимит запросов промптов в окне; требует включения rate limiting. |
--rate-limit-mutation <n> | positive integer | 30 | Лимит запросов мутаций в окне; требует включения rate limiting. |
--rate-limit-read <n> | positive integer | 120 | Лимит запросов на чтение в окне; требует включения rate limiting. |
--rate-limit-window-ms <n> | integer >= 1000 | 60000 | Длина окна rate limiting; требует включения rate limiting. |
| нет флага | - | - | QWEN_SERVE_NO_MCP_POOL=1 полностью отключает пул. |
Переменные окружения
Читаются runQwenServe / Express middleware
| Переменная | Действие |
|---|---|
QWEN_SERVER_TOKEN | Bearer-токен; обрезается при запуске. |
QWEN_SERVE_DEBUG | 1 / true / on / yes (без учета регистра) включает подробные логи в stderr. См. 19-observability.md. |
QWEN_SERVE_NO_MCP_POOL | 1 отключает пул транспортов MCP рабочей области и переключает на McpClientManager для каждой сессии; возможности перестают анонсировать mcp_workspace_pool / mcp_pool_restart. |
QWEN_SERVE_PROMPT_DEADLINE_MS | Резервная переменная окружения для --prompt-deadline-ms. |
QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS | Резервная переменная окружения для --writer-idle-timeout-ms. |
QWEN_SERVE_RATE_LIMIT | 1 / true включает HTTP rate limiting с разделением по уровням; флаги CLI --rate-limit / --no-rate-limit имеют приоритет. |
QWEN_SERVE_RATE_LIMIT_PROMPT | Резервная переменная окружения для --rate-limit-prompt. |
QWEN_SERVE_RATE_LIMIT_MUTATION | Резервная переменная окружения для --rate-limit-mutation. |
QWEN_SERVE_RATE_LIMIT_READ | Резервная переменная окружения для --rate-limit-read. |
QWEN_SERVE_RATE_LIMIT_WINDOW_MS | Резервная переменная окружения для --rate-limit-window-ms. |
QWEN_SERVE_NEW_FILE_MODE | Политика режима новых файлов для текстовых записей демона: owner (по умолчанию — НОВЫЕ файлы создаются 0600, независимо от umask) или system (НОВЫЕ файлы следуют 0o666 & ~umask). Без учета регистра; литерал 0600 принимается как псевдоним для owner (другие восьмеричные режимы не поддерживаются), а нераспознанные значения выводят предупреждение в stderr и сохраняют значение по умолчанию 0600. Существующие файлы всегда сохраняют свой режим. См. qwen-serve.md — Режим новых файлов для текстовых записей агента. |
QWEN_CODE_MEMORY_PROJECT_SCOPE | workspace привязывает память проекта к точному каталогу рабочего пространства; git-root выбирает устаревшую общую область. Когда не установлена, демон подставляет workspace; нераспознанные значения выводят предупреждение один раз и сохраняют устаревшее поведение git-root. Распространяется через базовую переменную окружения среды выполнения, а не childEnvOverrides; --memory-project-scope имеет приоритет. Каждая дорожка remember/forget/dream рабочего пространства ограничивает ожидающие задачи до MAX_PENDING = 16; N рабочих пространств допускают до 16·N задач в очереди без общесистемного лимита. |
Пустые значения QWEN_CODE_MEMORY_PROJECT_SCOPE трактуются как неустановленные и поэтому по умолчанию принимают значение workspace; нераспознанные непустые значения всё ещё выводят предупреждение один раз и сохраняют устаревшее поведение git-root.
Читаются обёрткой CLI qwen serve
| Переменная | Действие |
|---|---|
QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN | Непустой bearer-токен длиной не более 8192 кодовых единиц UTF-16 без управляющих символов, копируется в ServeOptions.externalToolGuard только в режиме required. Затем CLI удаляет значение окружения перед заморозкой сред выполнения; дочерние процессы ACP, воркеры каналов и среды исполнителей также защитно очищают его. |
Передаются дочернему процессу ACP через BridgeOptions.childEnvOverrides
runQwenServe формирует их для каждого обработчика, чтобы два демона в одном процессе не конкурировали за process.env. Переменные бюджета не являются резервными переменными окружения родительского процесса для qwen serve; путь CLI должен генерировать их из --mcp-client-budget / --mcp-budget-mode.
| Переменная | Действие |
|---|---|
QWEN_SERVE_MCP_CLIENT_BUDGET | Строка с положительным целым числом, потребляемая readBudgetFromEnv() дочернего процесса ACP. |
QWEN_SERVE_MCP_BUDGET_MODE | off / warn / enforce. |
QWEN_SERVE_MCP_POOL_TRANSPORTS | Разделенный запятыми белый список транспортов; по умолчанию пул использует stdio,websocket; можно явно добавить http,sse. |
QWEN_SERVE_MCP_POOL_DRAIN_MS | Задержка сброса неактивной записи пула; по умолчанию 30000, ограничена диапазоном 1000..600000 мс. |
Читаются SDK / адаптерами
| Переменная | Действие |
|---|---|
QWEN_DAEMON_URL | Базовый URL демона для CLI TUI адаптера, каналов и IDE-компаньона. |
QWEN_DAEMON_TOKEN | Bearer-токен. |
QWEN_DAEMON_WORKSPACE | Переопределяет cwd, отправляемый в POST /session. |
Ключи settings.json
Демон строит каждую среду выполнения рабочего пространства из объединённых настроек и наложения переменных окружения этого рабочего пространства. Глобальные для процесса опции слушателя/аутентификации разрешаются один раз, тогда как сервисы среды выполнения и дочерние процессы ACP получают снимок владеющей среды выполнения. Некорректные настройки подчиняются документированному поведению фолбэка или ошибки при запуске для затронутой среды выполнения; они не должны приводить к повторному использованию настроек другого рабочего пространства.
| Ключ | Тип | Действие |
|---|---|---|
policy.permissionStrategy | 'first-responder' | 'designated' | 'consensus' | 'local-only' | Устанавливает BridgeOptions.permissionPolicy; активное значение отображается в /capabilities как policy.permission. При запуске проверяется через validatePolicyConfig() на соответствие SERVE_CAPABILITY_REGISTRY.permission_mediation.modes. Неизвестные литералы вызывают InvalidPolicyConfigError и явно прерывают запуск. |
policy.consensusQuorum | positive integer | N для политики consensus. По умолчанию равно floor(M/2) + 1 от votersAtIssue.size (M=2 означает единогласие; большее четное M означает больше половины). Если задано для политики, отличной от consensus, игнорируется, и при запуске выводится предупреждение в stderr. Не положительные целые числа вызывают InvalidPolicyConfigError. См. 04-permission-mediation.md. |
context.fileName | string | Переопределяет getCurrentGeminiMdFilename() через BridgeOptions.contextFilename. |
tools.disabled | string[] | Инструменты, отключенные для следующего запуска дочернего процесса ACP. Нормализуется через normalizeDisabledToolList() (packages/cli/src/config/normalizeDisabledTools.ts): не массив становится [], не строковые элементы пропускаются, пробелы обрезаются, пустые элементы удаляются, дубликаты удаляются с сохранением первого вхождения. Настройки запуска и обновления restartMcpServer обе проходят через эту функцию. ToolRegistry.has(name) работает точно и с учетом регистра. POST /workspace/tools/:name/enable и tool_toggled обновляют этот ключ. |
tools.approvalMode | 'default' | 'auto' | ... | Режим одобрения сессии по умолчанию; POST /session/:id/approval-mode записывает сюда значение, если persist: true. |
telemetry | object | Конфигурация OTel. Ключи включают enabled, otlpEndpoint, otlpProtocol, otlpTracesEndpoint, otlpLogsEndpoint, otlpMetricsEndpoint, target, outfile, userId, includeSensitiveSpanAttributes, sensitiveSpanAttributeMaxLength, resourceAttributes и metrics.includeSessionId. resolveTelemetrySettings() читает её при запуске и инициализирует initializeTelemetry(). userId действует на весь процесс и не должен настраиваться как идентификатор конечного пользователя, когда демон обслуживает нескольких пользователей. |
ServeOptions (программное встраивание)
packages/cli/src/serve/types.ts определяет типизированные опции, передаваемые через публичные API serve. Он дублирует флаги CLI выше и добавляет:
| Поле | Действие |
|---|---|
eventRingSize | Переопределяет размер кольца по умолчанию для каждой сессии. |
memoryProjectScope | Только runQwenServe; приоритет: опция, переменная окружения при запуске, затем workspace. Прямые вызовы createServeApp используют deps.daemonEnv. |
maxPendingPromptsPerSession | Лимит ожидающих промптов на сессию; 0 / Infinity означает без ограничений. |
mcpPoolActive | Программный переключатель, по умолчанию зависит от QWEN_SERVE_NO_MCP_POOL. |
externalToolGuard | Опциональный {mode:'required', endpoint, token, timeoutMs?}. Отсутствие полностью отключает; режим required выполняет рукопожатие с провайдером перед прослушиванием. |
allowOrigins | Белый список cross-origin (string[]), соответствует --allow-origin. |
allowPrivateAuthBaseUrl | Разрешает установку baseUrl для провайдера аутентификации private / localhost. |
serveWebShell | Раздача собранного Web Shell SPA в корне демона (по умолчанию true); false (CLI --no-web) оставляет демон в режиме API-only. Нет эффекта, если сборка не содержит ресурсов оболочки. |
enableSessionShell | Включает выполнение shell в сессии; bearer-токен и привязанный к сессии client id по-прежнему требуются. |
promptDeadlineMs | Лимит реального времени выполнения промпта. |
writerIdleTimeoutMs | Тайм-аут простоя SSE writer. |
channelIdleTimeoutMs | Как долго держать дочерний процесс ACP активным после закрытия последней сессии. |
initializeTimeoutMs | Таймаут запросов дочернего процесса ACP, включая рукопожатие initialize. |
sessionRestoreTimeoutMs | Таймаут загрузки/восстановления сессии ACP. Приоритет: явное значение restore; иначе явное значение initialize увеличивает дефолт 60000, но не опускает его ниже; иначе 60000. |
sessionReapIntervalMs | Интервал сканирования сборщика неактивных сессий. |
sessionIdleTimeoutMs | Время простоя отключенной сессии перед сборкой. |
rateLimit* | Переключатель HTTP rate limiting с разделением по уровням, пороги и окно. |
BridgeOptions (программное встраивание bridge)
В файле packages/acp-bridge/src/bridgeOptions.ts определены опции bridge. Полная таблица приведена в 03-acp-bridge.md. Ключевые поля:
| Field | Effect |
|---|---|
boundWorkspace | Обязательное каноническое рабочее пространство. |
sessionScope | 'single' (по умолчанию) или 'thread'. |
initializeTimeoutMs, sessionRestoreTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession | Ограничения на использование ресурсов. |
channelFactory | Подключаемая фабрика дочерних процессов ACP; по умолчанию используется defaultSpawnChannelFactory. |
fileSystem | Адаптер BridgeFileSystem. См. 07-workspace-filesystem.md. |
permissionPolicy, permissionConsensusQuorum, permissionAudit | Настройка медиатора. |
statusProvider | Ячейки предварительной проверки хоста демона. |
childEnvOverrides | Добавление или удаление переменных окружения для каждого хэндла. |
externalToolGuard | Опциональный обработчик на стороне демона для приватного RPC prepare от дочернего процесса к родительскому. Bridge проверяет принадлежность канала и активный промпт до и после вызова обработчика. |
contextFilename | Переопределяет getCurrentGeminiMdFilename(). |
channelIdleTimeoutMs | Время жизни дочернего процесса ACP после закрытия последней сессии, в мс; по умолчанию 0. |
Важные значения по умолчанию
| Constant | File | Value | Meaning |
|---|---|---|---|
DEFAULT_MAX_SESSIONS | bridge.ts | 32 | Лимит сессий перед возникновением SessionLimitExceededError. |
MAX_EVENT_RING_SIZE | bridge.ts | 1_000_000 | Мягкий лимит для BridgeOptions.eventRingSize; защита от опечаток. |
DEFAULT_RING_SIZE | eventBus.ts | 8000 | Глубина кольца повторной передачи SSE для каждой сессии. |
DEFAULT_MAX_QUEUED | eventBus.ts | 256 | Лимит очереди для каждого подписчика. |
DEFAULT_MAX_SUBSCRIBERS | eventBus.ts | 64 | Лимит подписчиков для каждой шины. |
WARN_THRESHOLD_RATIO | eventBus.ts | 0.75 | Триггер для slow_client_warning. |
WARN_RESET_RATIO | eventBus.ts | 0.375 | Порог сброса гистерезиса. |
DEFAULT_INIT_TIMEOUT_MS | bridge.ts | 10_000 | Таймаут рукопожатия initialize в ACP. |
MCP_RESTART_TIMEOUT_MS | bridge.ts | 300_000 | Таймаут bridge для /workspace/mcp/:server/restart. |
DEFAULT_PERMISSION_TIMEOUT_MS | bridge.ts | 0 | Таймаут запросов разрешений по умолчанию; 0 означает ожидание без ограничений. |
DEFAULT_MAX_PENDING_PER_SESSION | bridge.ts | 64 | Согласовано с DEFAULT_MAX_SUBSCRIBERS. |
MAX_RESOLVED_PERMISSION_RECORDS | permissionMediator.ts | 512 | FIFO для недавно обработанных разрешений. |
KILL_HARD_DEADLINE_MS | spawnChannel.ts | 10_000 | Окно корректного завершения работы для каждого канала. |
SHUTDOWN_FORCE_CLOSE_MS | run-qwen-serve.ts | 5_000 | Таймер принудительного закрытия HTTP-сервера. |
MAX_READ_BYTES | fs/policy.ts | 256 * 1024 | Лимит полного снимка и возвращаемого текста; больший UTF-8 текст требует конечного лимита строк. |
MAX_WRITE_BYTES | fs/policy.ts | 5 * 1024 * 1024 | Лимит записи. |
MAX_DISPLAY_NAME_LENGTH | bridge.ts | 256 | Лимит длины displayName сессии. |
Перекрестные ссылки
- Настройки аутентификации:
12-auth-security.md - Возможности и версия протокола:
11-capabilities-versioning.md - Настройка кольца событий и противодавления:
10-event-bus.md - Пул / бюджет MCP:
05-mcp-transport-pool.mdи06-mcp-budget-guardrails.md - Политика разрешений:
04-permission-mediation.md - Руководство пользователя:
../../users/qwen-serve.md
Last updated on