Démarrage rapide et opérations

Cette page se concentre sur comment démarrer qwen serve, comment vérifier qu’il fonctionne, et à quoi ressemble la chaîne d’appels interne de qwen serve au serveur en écoute. Les détails sur l’architecture, les composants et le protocole de communication se trouvent dans les autres pages d’exploration approfondie du démon.

1. Chemin le plus court

qwen serve

Output:

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.

Ouvrez http://127.0.0.1:4170/ dans un navigateur pour obtenir l’interface Web Shell : chat, liste de sessions et inspection du workspace. createServeApp() monte les assets Web Shell bundled (packages/cli/src/serve/web-shell-static.ts) avant bearerAuth, donc le shell lui-même se charge sans token ; ses propres appels API portent le bearer lorsqu’un token est configuré — démarrez le démon avec --open (qui place le token dans le fragment d’URL, jamais envoyé au serveur) ou ajoutez #token=… manuellement lorsque l’authentification est activée. --no-web désactive et laisse le démon en API-only.

2. Recettes de lancement

# 1. Dév local par défaut (loopback, pas de token)
qwen serve
 
# 2. Workspace explicite + port éphémère
qwen serve --workspace /path/to/repo --port 0
 
# 3. Développement loopback renforcé (force le bearer même sur loopback)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) qwen serve --require-auth
 
# 4. Exposition au LAN (le non-loopback requiert un token)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) \
  qwen serve --hostname 0.0.0.0 --port 4170
 
# 5. Ajustement pour de nombreuses sessions et un ring de replay plus grand
qwen serve --max-sessions 0 --event-ring-size 32000
 
# 6. Collaboration multi-clients + budget MCP strict
QWEN_SERVER_TOKEN=secret \
  qwen serve --require-auth \
             --mcp-client-budget 10 \
             --mcp-budget-mode enforce
 
# 7. Démarrage avec une politique de consensus configurée dans settings.json
# settings.json: { "policy": { "permissionStrategy": "consensus", "consensusQuorum": 2 } }
qwen serve
 
# 8. Logs de débogage
QWEN_SERVE_DEBUG=1 qwen serve
 
# 9. Désactivation du pool F2 (fallback sur les clients MCP par session)
QWEN_SERVE_NO_MCP_POOL=1 qwen serve
 
# 10. Autorisation de l'accès cross-origin pour l'interface web du navigateur
QWEN_SERVER_TOKEN=secret \
  qwen serve --allow-origin 'http://localhost:3000'
 
# 11. Deadline du prompt + timeout d'inactivité SSE
qwen serve --prompt-deadline-ms 300000 --writer-idle-timeout-ms 600000
 
# 12. Maintenir le child ACP actif après la fermeture de la dernière session
qwen serve --channel-idle-timeout-ms 60000
 
# 13. Activation du rate limiting HTTP
QWEN_SERVE_RATE_LIMIT=1 qwen serve

Avec la recette loopback renforcée (3), /health est enregistré après bearerAuth, donc les sondes doivent porter le token comme toute autre route API (la surface statique du Web Shell reste pre-auth par conception ; passez --no-web pour un démon API-only).

3. Flags de démarrage complets

La CLI est définie dans packages/cli/src/commands/serve.ts :

4. Variables d’environnement

Les overrides d’env par handle sont intentionnels : deux démons s’exécutant dans le même processus n’entrent pas en compétition sur process.env. defaultSpawnChannelFactory prend un snapshot de l’env au moment du spawn.

5. settings.json est également lu

Le démarrage appelle loadSettings(boundWorkspace) une seule fois :

Une erreur d’E/S des paramètres, comme un JSON malformé, fallback sur les valeurs par défaut. InvalidPolicyConfigError est l’exception : une mauvaise configuration de la politique fait échouer le démarrage explicitement.

6. Scénarios de refus de démarrage (échecs explicites)

run-qwen-serve.ts lève intentionnellement une erreur au lieu de fallback dans ces cas :

7. Checklist de vérification avec 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/

Lorsque l’authentification bearer est activée, ajoutez -H "Authorization: Bearer $QWEN_SERVER_TOKEN" à chaque requête.

8. Y a-t-il une interface navigateur ?

Oui — le Web Shell. resolveWebShellDir() trouve les assets construits (bundlés à côté du bundle CLI dans une release, packages/web-shell/dist dans un checkout) et mountWebShellAssets() les sert à /, /assets et /session/:id pour les navigations de documents (liens profonds du navigateur — un simple curl /session/<id> obtient le 401/404 de l’API, pas le shell). Lorsque les assets sont absents, le démon dégrade vers API-only au lieu de planter ; --no-web désactive explicitement.

Le shell statique est monté avant bearerAuth dans tous les modes de lancement — un navigateur ne peut pas attacher un en-tête Authorization à une navigation dans la barre d’adresse ou à une sous-ressource <script src>, donc le conditionner casserait simplement l’UI. Chaque route API qu’il appelle reste conditionnée par le token, et le front-end attache le bearer lui-même. Sur un bind non-loopback, le shell est en lecture seule sauf si --allow-origin <origin> est passé — les POST same-origin portent un en-tête Origin que le mur CORS rejette (403) — donc passez --allow-origin pour tout bind au-delà du loopback.

La CSP est construite par buildWebShellCsp() et est délibérément plus souple que celle d’une page statique ('unsafe-inline' pour le patch inline performance.measure, eval/wasm/blob workers pour shiki et mermaid, data: pour les polices katex, connect-src 'self' pour le SSE). frame-ancestors 'none' plus X-Frame-Options: DENY bloquent le clickjacking, sauf lorsqu’une origin d’extension est explicitement autorisée via --allow-origin pour que l’UI puisse être hébergée dans un panneau latéral Chrome (#5626).

Pour l’inspection brute du protocole, abonnez-vous au flux SSE directement (routes/sse-events.ts) — voir les recettes curl de la section 7.

9. Chaîne d’appel de qwen serve au serveur en écoute

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

Points clés :

• createServeApp se contente de construire ; il ne met pas le serveur en écoute. Il retourne une instance express() avec les middlewares et les routes montés. Les intégrateurs à usage ordinaire peuvent continuer à posséder app.listen(). Les intégrateurs qui utilisent Live/Conversations doivent lier le serveur Node réel au cycle de vie exporté de l’application avant l’écoute et attendre ce cycle de vie pendant l’arrêt.
• () => actualPort est une closure paresseuse (lazy closure). actualPort est assigné dans le callback de app.listen. Le middleware hostAllowlist le lit à la demande, de sorte que les ports éphémères (--port 0) filtrent toujours correctement l’en-tête Host.
• await blockForever() est intentionnel. Si yargs.parse() résout, le niveau supérieur du CLI passe au point d’entrée de l’interface TUI interactive (gemini.tsx). SIGINT / SIGTERM quittent via le chemin onSignal de runQwenServe.

10. Répartition des fichiers de routes HTTP

L’assemblage principal a lieu dans createServeApp() dans server.ts, qui connecte les middlewares et monte des modules de routes spécifiques :

Pour la référence complète des routes et du protocole de communication (wire protocol), consultez ../qwen-serve-protocol.md. Pour l’architecture, consultez 01-architecture.md.

11. Arrêt gracieux (graceful) vs arrêt forcé (hard)

• Premier SIGINT / SIGTERM -> onSignal de runQwenServe -> arrêt gracieux en deux phases :
  1. bridge.shutdown() : chaque canal dispose de KILL_HARD_DEADLINE_MS (10s), puis channel.kill() est appelé.
  2. server.close() : les requêtes en cours se terminent (drain), SHUTDOWN_FORCE_CLOSE_MS (5s) déclenche closeAllConnections(), puis un second délai de 2s s’applique.
• Second SIGINT / SIGTERM alors que le processus est déjà en cours d’arrêt -> bridge.killAllSync() envoie un SIGKILL synchrone à tous les processus enfants ACP et appelle process.exit(1) pour éviter les processus orphelins.

RunHandle.close() retourné par runQwenServe est l’équivalent programmatique pour les intégrateurs (embedders) et les tests.

12. Invocation intégrée (contournement du 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 obtenez l’application Express directement et liez vous-même le cycle de vie de l’écouteur. Cette forme est requise lorsque l’intégrateur utilise 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();

Appeler server.close() brut déclenche également le même nettoyage piloté par les événements, mais ce n’est que du best-effort sauf si le processus reste en vie ; attendez toujours lifecycle.close() pour recevoir les erreurs d’arrêt. Si aucun serveur n’est lié, les requêtes Live/Conversations échouent fermement tandis que le comportement applicatif à usage ordinaire reste inchangé.

Remarque : lors de l’appel direct à createServeApp, la valeur par défaut est fsFactory.trusted = false. L’ACP côté agent writeTextFile est rejeté en tant que untrusted_workspace, et un avertissement est affiché une fois sur stderr. Vous pouvez soit injecter deps.fsFactory avec une confiance explicite, injecter deps.bridge, soit accepter le comportement par défaut conditionné par la confiance (trust-gated).

13. Recettes de débogage

Consultez la section de débogage dans 19-observability.md. Les commandes courantes sont :

# 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

Références

• Point d’entrée CLI : packages/cli/src/commands/serve.ts
• Amorçage (Bootstrap) : packages/cli/src/serve/run-qwen-serve.ts
• Factory Express : packages/cli/src/serve/server.ts
• Middleware : packages/cli/src/serve/auth.ts
• Factory de bridge : packages/acp-bridge/src/bridge.ts
• Montage statique Web Shell : packages/cli/src/serve/web-shell-static.ts
• Documentation utilisateur : ../../users/qwen-serve.md
• Protocole de communication (Wire protocol) : ../qwen-serve-protocol.md