Referência de Configuração
Visão Geral
Esta página reúne todas as configurações que afetam o daemon qwen serve e seus adaptadores: variáveis de ambiente, flags da CLI, chaves do settings.json e opções programáticas. Páginas específicas de recursos fazem referência a esta página quando precisam de detalhes de configuração transversais.
Flags da CLI (qwen serve)
| Flag | Tipo | Padrão | Efeito |
|---|---|---|---|
--hostname <host> | string | 127.0.0.1 | Endereço de bind. Valores de loopback: 127.0.0.1, localhost, ::1, [::1]. Valores fora de loopback exigem um bearer token na inicialização. A entrada host:port é rejeitada com orientação para usar --port. |
--port <n> | number | 4170 | Porta de escuta; 0 significa efêmera. |
--token <s> | string | env | Bearer token. Sobrescreve QWEN_SERVER_TOKEN e é aparado na inicialização. Aparece na linha de comando do processo, portanto prefira variáveis de ambiente em deployments. |
--open | boolean | false | Abre o Web Shell montado após a prontidão do runtime. Um token configurado é entregue como fragmento de URL. --open simples continua sendo um no-op silencioso quando o launch do navegador não é elegível. |
--open-with-auth | boolean | false | Abre o Web Shell com autenticação bearer no loopback. Exige um Web Shell habilitado e assets compilados. Reutiliza um --token / QWEN_SERVER_TOKEN selecionado, ou gera um bearer de 256 bits com tempo de vida do processo antes do listen. Em um ambiente sem navegador elegível, inicia e imprime a URL com fragmento contendo o segredo. Não é uma configuração ServeOptions ou SDK. |
--require-auth | boolean | false | Estende a autenticação bearer para loopback e /health; a inicialização recusa iniciar sem um token. |
--workspace <dir> | absolute path / repeatable | process.cwd() | Runtime do workspace na inicialização; repita para registrar runtimes isolados adicionais. O primeiro é o primário. Cada valor deve ser absoluto e um diretório; canonizado na inicialização. |
--memory-project-scope <mode> | git-root / workspace | workspace | Particionamento da memória de projeto. workspace isola pelo diretório exato do workspace; git-root é o escopo de compatibilidade legado compartilhado por workspaces na mesma raiz Git. Sobrescreve QWEN_CODE_MEMORY_PROJECT_SCOPE. |
--max-sessions <n> | number | 32 | Limite de sessões ativas por workspace. 0 / Infinity significa ilimitado; valores NaN / negativos lançam exceção. |
--max-total-sessions <n> | number | derivado para múltiplos workspaces na inicialização/restauração | Limite de sessões ativas em todo o daemon. Quando omitido, um padrão finito é derivado uma vez do limite por workspace e da contagem de workspaces na inicialização/restauração. 0 / Infinity significa ilimitado. |
--max-pending-prompts-per-session <n> | number | 5 | Limite de prompts aceitos, mas pendentes/em execução por sessão. Prompts em excesso retornam 503. 0 / Infinity significa ilimitado; valores negativos ou não inteiros lançam exceção. |
--max-connections <n> | number | 256 | server.maxConnections do listener HTTP; 0 / Infinity significa ilimitado. |
--enable-session-shell | boolean | false | Habilita a execução direta de POST /session/:id/shell. Exige bearer token, e toda chamada deve carregar um X-Qwen-Client-Id vinculado à sessão. |
--event-ring-size <n> | number | 8000 | Ring de replay SSE por sessão; o limite flexível (soft cap) é 1_000_000. |
--compacted-replay-max-bytes <n> | positive integer | 4194304 | Limite de bytes para o snapshot de replay delimitado em memória retornado por POST /session/:id/load; o limite rígido é 268435456. |
--max-journal-events <n> | positive safe integer | 10000 | Limite base por sessão de entradas de replay liveJournal em andamento para o turno inacabado. Crescimento adaptativo pode aumentá-lo (veja --max-journal-bytes); fixar qualquer flag de journal desativa o crescimento. |
--max-journal-bytes <n> | positive safe integer | 8388608 (8 MiB) | Limite base por sessão em bytes do liveJournal em andamento. Quando um turno o ultrapassa, o crescimento adaptativo aumenta os limites da sessão sob demanda, até o dobro mas limitado pelo headroom restante do pool e nunca além de um limite rígido de 256 MiB por sessão — dentro de um pool único por daemon de 5% do --memory-budget-mb efetivo (limitado a 1024 MB; 0 — crescimento desativado — quando o orçamento efetivo está abaixo do mínimo de 1024 MB), compartilhado por toda bridge de workspace; sem headroom as entradas mais antigas são descartas com o marcador history_truncated. Fixar qualquer flag de journal desativa o crescimento. |
--memory-budget-mb <n> | integer em [1024, 1048576] | 50% da memória do cgroup ou do host, limitado ao máximo da flag (1048576 MB) | Orçamento total de memória para a árvore de processos do daemon, limitado à memória disponível resolvida. Reportado sob limits.memory no status do daemon; não dimensiona processos filhos — o único consumidor atualmente é o crescimento adaptativo do live-journal (veja --max-journal-bytes). A inicialização rejeita valores fora do intervalo. |
--memory-pressure-mode <mode> | off | observe | observe | Se o daemon deriva um nível de pressão de memória a partir do próprio RSS e heap V8. Ambos os modos reportam runtime.memory.pressure; apenas observe levanta daemon_memory_pressure. Apenas o processo raiz; sem remediação. |
--child-heap-mode <mode> | off | observe | observe | Se o daemon modela uma partição de heap por filho do orçamento. observe reporta e conta spawns além do limite; nada é aplicado. off não publica nenhuma partição — maxConcurrentChildren e perChildCeilingMb são ambos null. |
--http-bridge | boolean | true | Modo bridge da fase 1. --no-http-bridge ainda faz fallback para http-bridge e imprime no stderr. |
--mcp-client-budget <n> | positive integer | unset | Define WorkspaceMcpBudget.clientBudget e o encaminha para o filho ACP através de childEnvOverrides. |
--mcp-budget-mode <m> | off / warn / enforce | warn quando o budget é definido, caso contrário off | Define WorkspaceMcpBudget.mode; enforce exige --mcp-client-budget. |
--external-tool-guard-mode <m> | off / required | off | Habilita o Guard de pré-execução externo gerenciado pelo ACP. required falha a inicialização a menos que seu provedor de loopback complete o handshake v1. |
--external-tool-guard-endpoint <url> | loopback HTTP(S) origin | unset | Origem do provedor usada apenas no modo required. Deve ser apenas origem e usar 127.0.0.1, localhost ou ::1; caminhos, credenciais, redirecionamentos e roteamento por proxy são rejeitados. |
--external-tool-guard-timeout-ms <n> | integer 100..30000 | 3000 | Prazo por handshake e por preparação. Um timeout falha a inicialização durante o handshake ou falha a invocação fechada durante um turno. |
--allow-origin <pattern> | repeatable string | unset | Allowlist de cross-origin que substitui a negação padrão de CORS. * permite qualquer origem, mas exige um token. |
--allow-private-auth-base-url | boolean | false | Permite que /workspace/auth/provider instale o baseUrl do provedor de autenticação localhost / rede privada; use apenas em desenvolvimento local confiável. |
--web / --no-web | boolean | true | Serve o SPA do Web Shell compilado na raiz do daemon (GET /, /assets/* e navegações de documento /session/:id). Esses pontos de entrada são montados antes de bearerAuth; toda rota de API permanece protegida por token. --no-web deixa o daemon apenas com API. |
--prompt-deadline-ms <n> | positive integer | unset | Limite de wallclock do prompt no lado do servidor em ms. O timeout aborta e retorna um erro. |
--writer-idle-timeout-ms <n> | positive integer | unset | Timeout de ociosidade por conexão SSE em ms. O daemon fecha a conexão SSE quando nenhum evento é enviado por essa duração. |
--channel-idle-timeout-ms <n> | non-negative integer | 0 | Por quanto tempo manter o filho ACP ativo após o fechamento da última sessão. 0 significa recuperar (reclaim) imediatamente. |
--initialize-timeout-ms <n> | positive integer | 10000 | Timeout de requisição do filho ACP, incluindo o handshake de inicialização (ms). |
--session-restore-timeout-ms <n> | positive integer | 60000 | Timeout de load/resume de sessão ACP (ms). Quando esta flag é omitida, um timeout de initialize fornecido explicitamente eleva o orçamento mas nunca o reduz abaixo do padrão. |
--permission-response-timeout-ms <n> | non-negative integer | 0 | Timeout de relógio compartilhado para respostas de permissão ordinárias e ask_user_question. 0 ou uma flag omitida aguarda indefinidamente; um valor positivo ativa o timer. |
--session-reap-interval-ms <n> | non-negative integer | 60000 | Intervalo de varredura do reaper de sessões; 0 o desativa. |
--session-idle-timeout-ms <n> | non-negative integer | 1800000 | Tempo de reaping de ociosidade para sessões desconectadas; 0 o desativa. |
--rate-limit / --no-rate-limit | boolean | env / off | Habilita rate limiting HTTP por tier para rotas de prompt, mutação e leitura. |
--rate-limit-prompt <n> | positive integer | 10 | Limite de requisições de prompt por janela; exige que o rate limiting esteja habilitado. |
--rate-limit-mutation <n> | positive integer | 30 | Limite de requisições de mutação por janela; exige que o rate limiting esteja habilitado. |
--rate-limit-read <n> | positive integer | 120 | Limite de requisições de leitura por janela; exige que o rate limiting esteja habilitado. |
--rate-limit-window-ms <n> | integer >= 1000 | 60000 | Duração da janela de rate limit; exige que o rate limiting esteja habilitado. |
| sem flag | - | - | QWEN_SERVE_NO_MCP_POOL=1 desativa completamente o pool. |
Variáveis de ambiente
Lidas por runQwenServe / middleware Express
| Env | Efeito |
|---|---|
QWEN_SERVER_TOKEN | Bearer token; aparado na inicialização. |
QWEN_SERVE_DEBUG | 1 / true / on / yes (case-insensitive) habilita logs verbosos no stderr. Ver 19-observability.md. |
QWEN_SERVE_NO_MCP_POOL | 1 desativa o pool de transporte MCP do workspace e faz fallback para o McpClientManager por sessão; as capabilities param de anunciar mcp_workspace_pool / mcp_pool_restart. |
QWEN_SERVE_PROMPT_DEADLINE_MS | Fallback de ambiente para --prompt-deadline-ms. |
QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS | Fallback de ambiente para --writer-idle-timeout-ms. |
QWEN_SERVE_RATE_LIMIT | 1 / true habilita rate limiting HTTP por tier; a flag da CLI --rate-limit / --no-rate-limit tem precedência. |
QWEN_SERVE_RATE_LIMIT_PROMPT | Fallback de ambiente para --rate-limit-prompt. |
QWEN_SERVE_RATE_LIMIT_MUTATION | Fallback de ambiente para --rate-limit-mutation. |
QWEN_SERVE_RATE_LIMIT_READ | Fallback de ambiente para --rate-limit-read. |
QWEN_SERVE_RATE_LIMIT_WINDOW_MS | Fallback de ambiente para --rate-limit-window-ms. |
QWEN_SERVE_NEW_FILE_MODE | Política de modo de novos arquivos para escritas de texto do daemon: owner (padrão — novos arquivos são criados 0600, independente do umask) ou system (novos arquivos seguem 0o666 & ~umask). Não diferencia maiúsculas de minúsculas; o literal 0600 é aceito como alias de owner (nenhum outro modo octal é suportado), e valores não reconhecidos emitem aviso no stderr e mantêm o padrão 0600. Arquivos existentes sempre preservam seu modo. Consulte qwen-serve.md — Modo de novos arquivos para escritas de texto do agente. |
QWEN_CODE_MEMORY_PROJECT_SCOPE | workspace chaveia a memória de projeto pelo diretório exato do workspace; git-root seleciona o escopo legado compartilhado. Quando não definida, o daemon injeta workspace; valores não reconhecidos emitem aviso uma vez e mantêm o comportamento legado git-root. Propagado via base env do runtime, não childEnvOverrides; --memory-project-scope tem precedência. Cada lane de remember/forget/dream do workspace limita tarefas pendentes a MAX_PENDING = 16; N workspaces permitem até 16·N tarefas enfileiradas sem limite em todo o daemon. |
Valores em branco de QWEN_CODE_MEMORY_PROJECT_SCOPE são tratados como não definidos e portanto usam o padrão workspace; valores não vazios não reconhecidos ainda emitem aviso uma vez e mantêm o comportamento legado git-root.
Lidas pelo wrapper da CLI qwen serve
| Env | Efeito |
|---|---|
QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN | Bearer token não vazio de no máximo 8192 code units UTF-16 sem caracteres de controle, copiado para ServeOptions.externalToolGuard apenas no modo required. A CLI então deleta o valor ambiente antes que os ambientes de runtime sejam congelados; filhos ACP, channel workers e ambientes de executor também o removem defensivamente. |
Encaminhadas para o filho ACP através de BridgeOptions.childEnvOverrides
O runQwenServe constrói estas variáveis por handle para que dois daemons em um mesmo processo não disputem o process.env. As variáveis de budget não são fallbacks de ambiente do processo pai para o qwen serve; o caminho da CLI deve gerá-las a partir de --mcp-client-budget / --mcp-budget-mode.
| Env | Efeito |
|---|---|
QWEN_SERVE_MCP_CLIENT_BUDGET | String de inteiro positivo consumida pelo readBudgetFromEnv() do filho ACP. |
QWEN_SERVE_MCP_BUDGET_MODE | off / warn / enforce. |
QWEN_SERVE_MCP_POOL_TRANSPORTS | Allowlist de transportes separada por vírgulas; os transportes padrão do pool são stdio,websocket; pode incluir explicitamente http,sse. |
QWEN_SERVE_MCP_POOL_DRAIN_MS | Atraso de drenagem de ociosidade da entrada do pool; padrão 30000, limitado (clamped) a 1000..600000 ms. |
Lidas pelo SDK / adaptadores
| Env | Efeito |
|---|---|
QWEN_DAEMON_URL | URL base do daemon para o adaptador TUI da CLI, canais e companion de IDE. |
QWEN_DAEMON_TOKEN | Bearer token. |
QWEN_DAEMON_WORKSPACE | Sobrescreve o cwd enviado para POST /session. |
Chaves do settings.json
O daemon constrói cada runtime de workspace a partir das configurações mescladas e da sobreposição de ambiente daquele workspace. Opções de listener/autenticação globais do processo são resolvidas uma vez, enquanto serviços específicos do runtime e filhos ACP recebem o snapshot do runtime proprietário. Configurações malformadas seguem o comportamento documentado de fallback ou falha na inicialização para o runtime afetado; não devem causar a reutilização das configurações de outro workspace.
| Key | Tipo | Efeito |
|---|---|---|
policy.permissionStrategy | 'first-responder' | 'designated' | 'consensus' | 'local-only' | Define BridgeOptions.permissionPolicy; o valor ativo aparece em /capabilities como policy.permission. A inicialização valida através de validatePolicyConfig() contra SERVE_CAPABILITY_REGISTRY.permission_mediation.modes. Literais desconhecidos lançam InvalidPolicyConfigError e falham a inicialização explicitamente. |
policy.consensusQuorum | positive integer | N para a política consensus. O padrão é floor(M/2) + 1 sobre votersAtIssue.size (M=2 significa unânime; M par maior significa mais da metade). Se definido sob uma política não-consensus, é ignorado e a inicialização imprime um aviso no stderr. Inteiros não positivos lançam InvalidPolicyConfigError. Ver 04-permission-mediation.md. |
context.fileName | string | Sobrescreve getCurrentGeminiMdFilename() através de BridgeOptions.contextFilename. |
tools.disabled | string[] | Ferramentas desabilitadas para o próximo spawn do filho ACP. Normalizado através de normalizeDisabledToolList() (packages/cli/src/config/normalizeDisabledTools.ts): não-array vira [], entradas não-string são ignoradas, espaços em branco são removidos, entradas vazias são descartadas e duplicatas são removidas preservando a primeira ocorrência. A inicialização e a atualização de configurações do restartMcpServer ambas passam por esta função. ToolRegistry.has(name) é exato e case-sensitive. POST /workspace/tools/:name/enable e tool_toggled atualizam esta chave. |
tools.approvalMode | 'default' | 'auto' | ... | Modo de aprovação de sessão padrão; POST /session/:id/approval-mode escreve aqui quando persist: true. |
telemetry | object | Configuração do OTel. As chaves incluem enabled, otlpEndpoint, otlpProtocol, otlpTracesEndpoint, otlpLogsEndpoint, otlpMetricsEndpoint, target, outfile, userId, includeSensitiveSpanAttributes, sensitiveSpanAttributeMaxLength, resourceAttributes e metrics.includeSessionId. resolveTelemetrySettings() a lê na inicialização e inicializa initializeTelemetry(). userId é global ao processo e não deve ser configurado como identidade de usuário final quando o daemon atende múltiplos usuários. |
ServeOptions (incorporação programática)
O packages/cli/src/serve/types.ts define o objeto de opções tipado aceito tanto por runQwenServe quanto por createServeApp. Ele espelha as flags da CLI acima e adiciona:
| Field | Efeito |
|---|---|
eventRingSize | Sobrescreve o tamanho padrão do ring por sessão. |
memoryProjectScope | Apenas runQwenServe; a precedência é: opção, env de launch, depois workspace. Chamadores diretos de createServeApp usam deps.daemonEnv. |
maxPendingPromptsPerSession | Limite de prompts pendentes por sessão; 0 / Infinity significa ilimitado. |
mcpPoolActive | Switch programático, com padrão vindo de QWEN_SERVE_NO_MCP_POOL. |
externalToolGuard | Opcional {mode:'required', endpoint, token, timeoutMs?}. Omissão desliga completamente; o modo required realiza o handshake do provedor antes de escutar. |
allowOrigins | Allowlist de cross-origin (string[]), correspondente a --allow-origin. |
allowPrivateAuthBaseUrl | Permite a instalação do baseUrl do provedor de autenticação privado / localhost. |
serveWebShell | Serve o SPA do Web Shell compilado na raiz do daemon (padrão true); false (o --no-web da CLI) deixa o daemon apenas com API. Sem efeito quando o build omite os assets do shell. |
enableSessionShell | Habilita a execução do shell de sessão; bearer token e client id vinculado à sessão ainda são exigidos. |
promptDeadlineMs | Limite de wallclock do prompt. |
writerIdleTimeoutMs | Timeout de ociosidade do writer SSE. |
channelIdleTimeoutMs | Por quanto tempo manter o filho ACP aquecido (warm) após o fechamento da última sessão. |
initializeTimeoutMs | Timeout de requisição do filho ACP, incluindo o handshake de inicialização. |
sessionRestoreTimeoutMs | Timeout de load/resume de sessão ACP. Precedência: valor de restore explícito; caso contrário, um valor de initialize explícito eleva o padrão 60000 mas nunca o reduz; caso contrário 60000. |
sessionReapIntervalMs | Intervalo de varredura do reaper de sessões. |
sessionIdleTimeoutMs | Tempo de reaping de ociosidade para sessões desconectadas. |
rateLimit* | Switch de rate limit HTTP por tier, limites (thresholds) e janela. |
BridgeOptions (incorporação programática da bridge)
packages/acp-bridge/src/bridgeOptions.ts define as opções da bridge. Consulte 03-acp-bridge.md para a tabela completa. Campos principais:
| Campo | Efeito |
|---|---|
boundWorkspace | Workspace canônico obrigatório. |
sessionScope | 'single' (padrão) vs 'thread'. |
initializeTimeoutMs, sessionRestoreTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession | Limites máximos de recursos. |
channelFactory | Factory plugável de child ACP; o padrão é defaultSpawnChannelFactory. |
fileSystem | Adaptador BridgeFileSystem. Consulte 07-workspace-filesystem.md. |
permissionPolicy, permissionConsensusQuorum, permissionAudit | Configuração do mediador. |
statusProvider | Células de preflight do host do daemon. |
childEnvOverrides | Adições ou remoções de ambiente por handle. |
externalToolGuard | Handler opcional no daemon para o RPC privado prepare de filho-para-pai. A bridge valida a propriedade do canal e o prompt ativo antes e depois de chamar o handler. |
contextFilename | Substitui getCurrentGeminiMdFilename(). |
channelIdleTimeoutMs | Por quanto tempo manter o child ACP ativo após o fechamento da última sessão, em ms; padrão 0. |
Padrões importantes
| Constante | Arquivo | Valor | Significado |
|---|---|---|---|
DEFAULT_MAX_SESSIONS | bridge.ts | 32 | Limite de sessões antes de SessionLimitExceededError. |
MAX_EVENT_RING_SIZE | bridge.ts | 1_000_000 | Limite flexível (soft cap) para BridgeOptions.eventRingSize; protege contra erros de digitação. |
DEFAULT_RING_SIZE | eventBus.ts | 8000 | Profundidade do ring de replay de SSE por sessão. |
DEFAULT_MAX_QUEUED | eventBus.ts | 256 | Limite da fila por subscriber. |
DEFAULT_MAX_SUBSCRIBERS | eventBus.ts | 64 | Limite de subscribers por bus. |
WARN_THRESHOLD_RATIO | eventBus.ts | 0.75 | Gatilho do slow_client_warning. |
WARN_RESET_RATIO | eventBus.ts | 0.375 | Limite de rearme por histerese. |
DEFAULT_INIT_TIMEOUT_MS | bridge.ts | 10_000 | Timeout do handshake initialize do ACP. |
MCP_RESTART_TIMEOUT_MS | bridge.ts | 300_000 | Timeout da bridge para /workspace/mcp/:server/restart. |
DEFAULT_PERMISSION_TIMEOUT_MS | bridge.ts | 0 | Sem timeout padrão; permissões e ask_user_question aguardam indefinidamente a menos que sobrescrito. |
DEFAULT_MAX_PENDING_PER_SESSION | bridge.ts | 64 | Alinhado com DEFAULT_MAX_SUBSCRIBERS. |
MAX_RESOLVED_PERMISSION_RECORDS | permissionMediator.ts | 512 | FIFO para permissões resolvidas recentemente. |
KILL_HARD_DEADLINE_MS | spawnChannel.ts | 10_000 | Janela de encerramento gracioso (graceful shutdown) por channel. |
SHUTDOWN_FORCE_CLOSE_MS | run-qwen-serve.ts | 5_000 | Timer de fechamento forçado do servidor HTTP. |
MAX_READ_BYTES | fs/policy.ts | 256 * 1024 | Limite de snapshot completo e texto retornado; texto UTF-8 maior exige um limite finito de linhas. |
MAX_WRITE_BYTES | fs/policy.ts | 5 * 1024 * 1024 | Limite de escrita. |
MAX_DISPLAY_NAME_LENGTH | bridge.ts | 256 | Limite do displayName da sessão. |
Referências cruzadas
- Configurações de autenticação:
12-auth-security.md - Capacidades e versão do protocolo:
11-capabilities-versioning.md - Ajuste do event ring e backpressure:
10-event-bus.md - Pool / budget do MCP:
05-mcp-transport-pool.mde06-mcp-budget-guardrails.md - Política de permissões:
04-permission-mediation.md - Guia de operações do usuário:
../../users/qwen-serve.md
Last updated on