Início rápido e operações

Esta página foca em como iniciar o qwen serve, como verificar se ele está funcionando e como é a cadeia de chamadas interna do qwen serve até o servidor de escuta. Detalhes de arquitetura, componentes e protocolo de comunicação estão nas outras páginas de aprofundamento do daemon.

1. Caminho mais curto

qwen serve

Saída:

qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge, workspace=/your/cwd)
qwen serve: bound to workspace "/your/cwd"
qwen serve: bearer auth disabled (loopback default). Set QWEN_SERVER_TOKEN to enable.

Abra http://127.0.0.1:4170/ em um navegador para obter a UI do Web Shell: chat, lista de sessões e inspeção de workspace. createServeApp() monta os assets do Web Shell empacotados (packages/cli/src/serve/web-shell-static.ts) antes de bearerAuth, então o shell carrega sem token; suas próprias chamadas de API carregam o bearer quando um está configurado — inicie o daemon com --open (que coloca o token no fragmento da URL, nunca enviado ao servidor) ou adicione #token=… manualmente quando a autenticação estiver habilitada. --no-web desativa e deixa o daemon apenas com API.

2. Receitas de inicialização

# 1. Local dev default (loopback, no token)
qwen serve
 
# 2. Explicit workspace + ephemeral port
qwen serve --workspace /path/to/repo --port 0
 
# 3. Hardened loopback development (force bearer even on loopback)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) qwen serve --require-auth
 
# 4. Expose to LAN (non-loopback requires a token)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) \
  qwen serve --hostname 0.0.0.0 --port 4170
 
# 5. Tune for many sessions and a larger replay ring
qwen serve --max-sessions 0 --event-ring-size 32000
 
# 6. Multi-client collaboration + strict MCP budget
QWEN_SERVER_TOKEN=secret \
  qwen serve --require-auth \
             --mcp-client-budget 10 \
             --mcp-budget-mode enforce
 
# 7. Start with a consensus policy configured in settings.json
# settings.json: { "policy": { "permissionStrategy": "consensus", "consensusQuorum": 2 } }
qwen serve
 
# 8. Debug logging
QWEN_SERVE_DEBUG=1 qwen serve
 
# 9. Disable the F2 pool (fallback to per-session MCP clients)
QWEN_SERVE_NO_MCP_POOL=1 qwen serve
 
# 10. Allow browser web UI cross-origin access
QWEN_SERVER_TOKEN=secret \
  qwen serve --allow-origin 'http://localhost:3000'
 
# 11. Prompt deadline + SSE idle timeout
qwen serve --prompt-deadline-ms 300000 --writer-idle-timeout-ms 600000
 
# 12. Keep the ACP child warm after the last session closes
qwen serve --channel-idle-timeout-ms 60000
 
# 13. Enable HTTP rate limiting
QWEN_SERVE_RATE_LIMIT=1 qwen serve

Com a receita de loopback reforçado (3), /health é registrado após bearerAuth, então as sondas devem carregar o token como qualquer outra rota de API (a superfície estática do Web Shell permanece pré-auth por design; use --no-web para um daemon apenas com API).

3. Flags de inicialização completas

A CLI é definida em packages/cli/src/commands/serve.ts:

4. Variáveis de ambiente

As substituições de env por handle são intencionais: dois daemons rodando no mesmo processo não competem por process.env. defaultSpawnChannelFactory tira um snapshot do env no momento do spawn.

5. settings.json também é lido

A inicialização chama loadSettings(boundWorkspace) uma vez:

Falhas de I/O de configurações, como JSON malformado, fazem fallback para os padrões. InvalidPolicyConfigError é a exceção: configuração incorreta de política falha explicitamente na inicialização.

6. Cenários de recusa de inicialização (falhas explícitas)

run-qwen-serve.ts intencionalmente lança erros em vez de fazer fallback nestes casos:

7. Checklist de verificação com Curl

# 1. Liveness
curl http://127.0.0.1:4170/health
# -> {"status":"ok"}
 
# 1.1 Deep health
curl -s 'http://127.0.0.1:4170/health?deep=1' | jq
 
# 2. Capabilities
curl -s http://127.0.0.1:4170/capabilities | jq
 
# 3. Preflight readiness
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# 4. Env snapshot (secrets only report presence)
curl -s http://127.0.0.1:4170/workspace/env | jq
 
# 5. MCP pool / budget snapshot
curl -s http://127.0.0.1:4170/workspace/mcp | jq
 
# 6. Create a session
curl -s -X POST http://127.0.0.1:4170/session \
  -H 'Content-Type: application/json' \
  -H 'X-Qwen-Client-Id: curl-debug' \
  -d '{}' | jq
 
# 7. Tail SSE (replace <sid>)
curl -N \
  -H 'Accept: text/event-stream' \
  -H 'X-Qwen-Client-Id: curl-debug' \
  -H 'Last-Event-ID: 0' \
  'http://127.0.0.1:4170/session/<sid>/events'
 
# 8. Web Shell UI
open http://127.0.0.1:4170/

Quando a autenticação bearer está habilitada, adicione -H "Authorization: Bearer $QWEN_SERVER_TOKEN" a cada requisição.

8. Existe uma UI no navegador?

Sim — o Web Shell. resolveWebShellDir() localiza os assets compilados (empacotados ao lado do bundle da CLI em um release, packages/web-shell/dist em um checkout) e mountWebShellAssets() os serve em /, /assets e nas navegações de documento /session/:id (deep links do navegador — um curl /session/<id> simples recebe o 401/404 da API, não o shell). Quando os assets estão ausentes, o daemon degrada para apenas API em vez de quebrar; --no-web desativa explicitamente.

O shell estático é montado antes de bearerAuth em qualquer modo de inicialização — um navegador não pode anexar um header Authorization a uma navegação na barra de endereços ou a um sub-recurso <script src>, então protegê-lo simplesmente quebraria a UI. Toda rota de API que ele chama permanece protegida por token, e o front-end anexa o bearer por conta própria. Em um bind não-loopback, o shell é somente leitura, a menos que --allow-origin <origin> seja passado — POSTs same-origin carregam um header Origin que a barreira CORS rejeita (403) — então use --allow-origin para qualquer bind além do loopback.

A CSP é construída por buildWebShellCsp() e é deliberadamente mais permissiva que a de uma página estática ('unsafe-inline' para o patch inline performance.measure, workers eval/wasm/blob para shiki e mermaid, data: para fontes katex, connect-src 'self' para SSE). frame-ancestors 'none' mais X-Frame-Options: DENY bloqueiam clickjacking, exceto quando um origin de extensão é explicitamente permitido via --allow-origin para que a UI possa ser hospedada em um painel lateral do Chrome (#5626).

Para inspeção direta do protocolo, assine o stream SSE diretamente (routes/sse-events.ts) — veja as receitas com curl na seção 7.

9. Cadeia de chamadas do qwen serve até o servidor em escuta

qwen serve
   |
   v (process)
packages/cli/index.ts              main()
   |
   v
gemini.tsx                         main() - parseArguments()
   |
   v (yargs assembly)
config/config.ts                   import { serveCommand } ...
config/config.ts                   .command(serveCommand)
config/config.ts                   await yargsInstance.parse()
   |
   v (handler)
commands/serve.ts                  handler(argv) - boot pre-checks
commands/serve.ts                  const { runQwenServe } = await import('../serve/index.js')   # lazy load
commands/serve.ts                  await runQwenServe({...})
   |
   v
serve/run-qwen-serve.ts              runQwenServe(opts, deps)
   |  |- trim token
   |  |- hostname mismatch fallback
   |  |- auth preflight
   |  |- workspace validation + canonicalization
   |  |- MCP budget validation + childEnvOverrides
   |  |- loadSettings + validatePolicyConfig
   |  |- PermissionAuditRing + publisher
   |  |- resolveBridgeFsFactory
   |  `- createHttpAcpBridge({...})
   |
   v
serve/run-qwen-serve.ts              const app = createServeApp(opts, () => actualPort, {...})
   |
   v
serve/server.ts                    createServeApp() - builds Express app (**does not listen**)
   |  |- middleware chain (Host allowlist / CORS / bearerAuth / mutation gate / rate limit)
   |  |- route mounting (health / web-shell static / capabilities / workspace / session / SSE / ACP HTTP)
   |  `- return app
   |
   v
serve/run-qwen-serve.ts              server = createServer(app) / https.createServer(..., app)
   |  |- lifecycle.bindServer(server, { startupReady, drainHost })
   |  |- server.listen(port, hostname)
   |  |- server.maxConnections = cap
   |  |- actualPort = server.address().port
   |  |- write "qwen serve listening on ..."
   |  |- register SIGINT / SIGTERM (onSignal)
   |  `- resolve(handle: RunHandle)
   |
   v
commands/serve.ts                  await blockForever()    // block forever until signal

Pontos-chave:

• createServeApp apenas constrói; ele não inicia a escuta. Ele retorna uma instância express() com middlewares e rotas montadas. Embedders apenas ordinários podem continuar sendo donos do app.listen(). Embedders que usam Live/Conversations devem vincular o servidor Node real ao ciclo de vida do app exportado antes de ouvir (listen) e aguardar esse ciclo de vida durante o desligamento.
• () => actualPort é uma closure preguiçosa (lazy). actualPort é atribuído no callback do server.listen. O middleware hostAllowlist o lê sob demanda, então portas efêmeras (--port 0) ainda controlam o cabeçalho Host corretamente.
• await blockForever() é intencional. Se yargs.parse() for resolvido, o nível superior da CLI cai no ponto de entrada da TUI interativa (gemini.tsx). SIGINT / SIGTERM saem através do caminho onSignal do runQwenServe.

10. Divisão de arquivos de rotas HTTP

A montagem principal acontece em createServeApp() no server.ts, que conecta os middlewares e monta módulos de rotas focados:

Para a referência completa de rotas e protocolo de comunicação, consulte ../qwen-serve-protocol.md. Para a arquitetura, consulte 01-architecture.md.

11. Shutdown graceful vs hard shutdown

• Primeiro SIGINT / SIGTERM -> onSignal do runQwenServe -> shutdown graceful em duas fases:
  1. bridge.shutdown(): cada canal recebe KILL_HARD_DEADLINE_MS (10s), depois channel.kill().
  2. server.close(): requisições em andamento são drenadas, SHUTDOWN_FORCE_CLOSE_MS (5s) aciona closeAllConnections(), e então um segundo prazo de 2s se aplica.
• Segundo SIGINT / SIGTERM enquanto já está encerrando -> bridge.killAllSync() envia SIGKILL síncrono para todos os filhos ACP e chama process.exit(1) para evitar processos órfãos.

O RunHandle.close() retornado pelo runQwenServe é o equivalente programático para embedders e testes.

12. Invocação embutida (bypass da CLI)

import { runQwenServe } from '@qwen-code/qwen-code/serve';
 
const handle = await runQwenServe({
  port: 0, // ephemeral
  hostname: '127.0.0.1',
  mode: 'http-bridge',
  maxSessions: 20,
  workspace: '/abs/path/to/repo',
});
console.log(`Daemon at ${handle.url}`);
// ... call handle.bridge directly or access handle.server
await handle.close(); // programmatic shutdown

Ou obtenha o app Express diretamente e vincule o ciclo de vida do listener você mesmo. Essa forma é necessária quando o embed usa Live/Conversations:

import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import {
  createServeApp,
  getServeAppLifecycle,
} from '@qwen-code/qwen-code/serve';
 
let actualPort = 0;
const app = createServeApp(
  {
    port: 0,
    hostname: '127.0.0.1',
    mode: 'http-bridge',
    maxSessions: 20,
  },
  () => actualPort,
  {
    /* deps: bridge, fsFactory, ... */
  },
);
 
const lifecycle = getServeAppLifecycle(app);
const server = createServer(app);
lifecycle.bindServer(server);
await new Promise<void>((resolve, reject) => {
  server.once('error', reject);
  server.listen(0, '127.0.0.1', () => resolve());
});
actualPort = (server.address() as AddressInfo).port;
console.log('listening on', server.address());
 
// Stop admission, drain app work, close the listener, and release ownership.
await lifecycle.close();

Chamar server.close() diretamente também inicia a mesma limpeza orientada por eventos, mas é apenas melhor esforço a menos que o processo permaneça vivo; sempre aguarde lifecycle.close() para receber erros de desligamento. Se nenhum servidor estiver vinculado, as requisições de Live/Conversations falham com fail closed, enquanto o comportamento do app apenas ordinário permanece inalterado.

Nota: ao chamar createServeApp diretamente, o padrão é fsFactory.trusted = false. O writeTextFile do ACP no lado do agente é rejeitado como untrusted_workspace, e um aviso é impresso no stderr uma única vez. Injete deps.fsFactory com confiança explícita, injete deps.bridge ou aceite o comportamento padrão restrito por confiança.

13. Receitas de depuração

Consulte a seção de depuração em 19-observability.md. Os comandos comuns são:

# Is the daemon alive?
curl http://127.0.0.1:4170/health
 
# Which capabilities are advertised?
curl -s http://127.0.0.1:4170/capabilities | jq
 
# Daemon-host readiness
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# Tail live SSE
curl -N -H 'Accept: text/event-stream' \
     -H 'Last-Event-ID: 0' \
     'http://127.0.0.1:4170/session/<sid>/events'
 
# Verbose logs
QWEN_SERVE_DEBUG=1 qwen serve

Referências

• Entrada da CLI: packages/cli/src/commands/serve.ts
• Bootstrap: packages/cli/src/serve/run-qwen-serve.ts
• Factory do Express: packages/cli/src/serve/server.ts
• Middleware: packages/cli/src/serve/auth.ts
• Factory da bridge: packages/acp-bridge/src/bridge.ts
• Montagem estática do Web Shell: packages/cli/src/serve/web-shell-static.ts
• Docs do usuário: ../../users/qwen-serve.md
• Protocolo de comunicação: ../qwen-serve-protocol.md