クイックスタートと運用

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. 強化されたループバック開発（ループバックでもベアラ認証を強制）
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. ブラウザ Web 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 ディープヘルスチェック
curl -s 'http://127.0.0.1:4170/health?deep=1' | jq
 
# 2. ケーパビリティ
curl -s http://127.0.0.1:4170/capabilities | jq
 
# 3. プリフライト準備状況
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
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')   # 遅延ロード
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

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

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());
 
// 受け入れを停止し、アプリの作業を drain し、リスナーをクローズし、所有権を解放します。
await lifecycle.close();

# デーモンは生存しているか？
curl http://127.0.0.1:4170/health
 
# どのケーパビリティが公開されているか？
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