퀵스타트 & 운영

qwen serve

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.

# 1. 로컬 개발 기본값 (루프백, 토큰 없음)
qwen serve
 
# 2. 명시적 워크스페이스 + 임시 포트
qwen serve --workspace /path/to/repo --port 0
 
# 3. 강화된 루프백 개발 (루프백에서도 bearer 강제)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) qwen serve --require-auth
 
# 4. LAN에 노출 (비루프백은 토큰 필수)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) \
  qwen serve --hostname 0.0.0.0 --port 4170
 
# 5. 다중 세션 및 더 큰 리플레이 링 튜닝
qwen serve --max-sessions 0 --event-ring-size 32000
 
# 6. 다중 클라이언트 협업 + 엄격한 MCP 예산
QWEN_SERVER_TOKEN=secret \
  qwen serve --require-auth \
             --mcp-client-budget 10 \
             --mcp-budget-mode enforce
 
# 7. settings.json에 합의 정책 설정 후 시작
# settings.json: { "policy": { "permissionStrategy": "consensus", "consensusQuorum": 2 } }
qwen serve
 
# 8. 디버그 로깅
QWEN_SERVE_DEBUG=1 qwen serve
 
# 9. F2 풀 비활성화 (세션별 MCP 클라이언트로 폴백)
QWEN_SERVE_NO_MCP_POOL=1 qwen serve
 
# 10. 브라우저 웹 UI 교차 출처 접근 허용
QWEN_SERVER_TOKEN=secret \
  qwen serve --allow-origin 'http://localhost:3000'
 
# 11. 프롬프트 기한 + SSE 유휴 타임아웃
qwen serve --prompt-deadline-ms 300000 --writer-idle-timeout-ms 600000
 
# 12. 마지막 세션 종료 후 ACP 자식을 웜 상태로 유지
qwen serve --channel-idle-timeout-ms 60000
 
# 13. HTTP 속도 제한 활성화
QWEN_SERVE_RATE_LIMIT=1 qwen serve

# 1. 활성 상태
curl http://127.0.0.1:4170/health
# -> {"status":"ok"}
 
# 1.1 Deep 헬스
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 준비 상태
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# 4. 환경 스냅샷 (비밀은 존재 여부만 보고)
curl -s http://127.0.0.1:4170/workspace/env | jq
 
# 5. MCP 풀 / 예산 스냅샷
curl -s http://127.0.0.1:4170/workspace/mcp | jq
 
# 6. 세션 생성
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. SSE 테일 (<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/

qwen serve
   |
   v (process)
packages/cli/index.ts              main()
   |
   v
llm.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) - 부트 사전 검사
commands/serve.ts                  const { runQwenServe } = await import('../serve/index.js')   # 지연 로드
commands/serve.ts                  await runQwenServe({...})
   |
   v
serve/run-qwen-serve.ts              runQwenServe(opts, deps)
   |  |- 토큰 trim
   |  |- hostname 불일치 폴백
   |  |- auth 사전 검사
   |  |- 워크스페이스 검증 + 표준화
   |  |- MCP 예산 검증 + childEnvOverrides
   |  |- loadSettings + validatePolicyConfig
   |  |- PermissionAuditRing + publisher
   |  |- resolveBridgeFsFactory
   |  `- createHttpAcpBridge({...})
   |
   v
serve/run-qwen-serve.ts              const app = createServeApp(opts, () => actualPort, {...})
   |
   v
serve/server.ts                    createServeApp() - Express 앱 빌드 (**리스닝하지 않음**)
   |  |- 미들웨어 체인 (Host 허용 목록 / CORS / bearerAuth / mutation gate / 속도 제한)
   |  |- 라우트 마운팅 (health / web-shell 정적 / 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
   |  |- "qwen serve listening on ..." 출력
   |  |- SIGINT / SIGTERM 등록 (onSignal)
   |  `- resolve(handle: RunHandle)
   |
   v
commands/serve.ts                  await blockForever()    // 시그널까지 무한 차단

import { runQwenServe } from '@qwen-code/qwen-code/serve';
 
const handle = await runQwenServe({
  port: 0, // 임시 포트
  hostname: '127.0.0.1',
  mode: 'http-bridge',
  maxSessions: 20,
  workspace: '/abs/path/to/repo',
});
console.log(`Daemon at ${handle.url}`);
// ... handle.bridge를 직접 호출하거나 handle.server에 접근
await handle.close(); // 프로그래밍적 종료

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());
 
// 수용을 중지하고, 앱 작업을 드레인하고, 리스너를 종료하고, 소유권을 해제합니다.
await lifecycle.close();

# 데몬이 살아 있는가?
curl http://127.0.0.1:4170/health
 
# 어떤 capabilities가 광고되는가?
curl -s http://127.0.0.1:4170/capabilities | jq
 
# 데몬-호스트 준비 상태
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# 라이브 SSE 테일
curl -N -H 'Accept: text/event-stream' \
     -H 'Last-Event-ID: 0' \
     'http://127.0.0.1:4170/session/<sid>/events'
 
# 상세 로그
QWEN_SERVE_DEBUG=1 qwen serve