설정 참조
개요
이 페이지는 qwen serve daemon과 adapter에 영향을 미치는 모든 설정을 수집합니다: 환경 변수, CLI 플래그, settings.json 키, 프로그래밍 옵션. 기능별 페이지는 교차 설정 정보가 필요할 때 여기로 링크합니다.
CLI 플래그 (qwen serve)
| 플래그 | 타입 | 기본값 | 효과 |
|---|---|---|---|
--hostname <host> | string | 127.0.0.1 | 바인드 주소. 루프백 값: 127.0.0.1, localhost, ::1, [::1]. 루프백이 아닌 값은 부팅 시 bearer 토큰 필요. host:port 입력은 --port 사용을 안내하며 거부. |
--port <n> | number | 4170 | 수신 포트. 0은 임시 포트를 의미. |
--token <s> | string | env | Bearer 토큰. QWEN_SERVER_TOKEN을 오버라이드하며 부팅 시 트리밍됩니다. 프로세스 명령줄에 표시되므로, 배포에서는 env를 권장. |
--require-auth | boolean | false | Bearer 인증을 루프백과 /health로 확장. 토큰 없이는 부팅 거부. |
--workspace <dir> | 절대 경로 / 반복 가능 | process.cwd() | 시작 워크스페이스 런타임. 반복하면 추가 격리 런타임 등록. 첫 번째가 primary. 모든 값은 절대 경로이고 디렉토리여야 하며, 부팅 시 표준화. |
--memory-project-scope <mode> | git-root / workspace | git-root | 프로젝트 메모리 분할. git-root는 동일한 Git 루트의 워크스페이스 간 메모리 공유. workspace는 정확한 워크스페이스 디렉토리별 격리. QWEN_CODE_MEMORY_PROJECT_SCOPE 오버라이드. |
--max-sessions <n> | number | 32 | 워크스페이스당 활성 세션 상한. 0 / Infinity는 무제한. NaN / 음수 값은 예외 발생. |
--max-total-sessions <n> | number | 여러 시작/복원 워크스페이스에 대해 파생 | Daemon 전체 활성 세션 상한. 생략 시 워크스페이스당 상한과 시작/복원 워크스페이스 수에서 유한 기본값이 한 번 파생. 0 / Infinity는 무제한. |
--max-pending-prompts-per-session <n> | number | 5 | 세션당 수락되었지만 대기 중/실행 중인 프롬프트 상한. 초과 시 503 반환. 0 / Infinity는 무제한. 음수 또는 비정수 값은 예외 발생. |
--max-connections <n> | number | 256 | HTTP 리스너 server.maxConnections. 0 / Infinity는 무제한. |
--enable-session-shell | boolean | false | 직접 POST /session/:id/shell 실행 활성화. Bearer 토큰 필요하며, 모든 호출은 세션 바인딩된 X-Qwen-Client-Id를 포함해야. |
--event-ring-size <n> | number | 8000 | 세션당 SSE 리플레이 링. 소프트 상한은 1_000_000. |
--compacted-replay-max-bytes <n> | 양의 정수 | 4194304 | POST /session/:id/load가 반환하는 경계된 인메모리 리플레이 스냅샷의 바이트 상한. 하드 상한은 268435456. |
--memory-budget-mb <n> | [1024, 1048576] 범위의 정수 | cgroup 제약 또는 호스트 메모리의 50%, 플래그 최대값(1048576 MB)으로 제한 | Daemon 프로세스 트리의 총 메모리 예산. 해석된 사용 가능 메모리로 제한. Daemon 상태의 limits.memory에서 관찰 및 보고되며, 자식 프로세스 크기를 결정하지 않음. 부팅은 범위를 벗어난 값을 거부. |
--memory-pressure-mode <mode> | off | observe | observe | Daemon이 자체 RSS와 V8 힙에서 메모리 압박 수준을 도출하는지 여부. 두 모드 모두 runtime.memory.pressure를 보고하며, observe만 daemon_memory_pressure를 발생. 루트 프로세스 전용. 조치 없음. |
--child-heap-mode <mode> | off | observe | observe | Daemon이 예산의 자식별 힙 분할을 모델링하는지 여부. observe는 이를 보고하고 이를 초과하는 spawn을 카운트. 적용되는 것 없음. off는 분할을 전혀 공개하지 않음 — maxConcurrentChildren과 perChildCeilingMb 모두 null. |
--http-bridge | boolean | true | Stage 1 브리지 모드. --no-http-bridge도 http-bridge로 폴백하며 stderr에 출력. |
--mcp-client-budget <n> | 양의 정수 | 미설정 | WorkspaceMcpBudget.clientBudget을 설정하고 childEnvOverrides를 통해 ACP 자식으로 전달. |
--mcp-budget-mode <m> | off / warn / enforce | 예산이 설정되면 warn, 그렇지 않으면 off | WorkspaceMcpBudget.mode 설정. enforce는 --mcp-client-budget 필요. |
--external-tool-guard-mode <m> | off / required | off | 관리되는 ACP 외부 사전 실행 Guard 활성화. required는 루프백 프로바이더가 v1 핸드셰이크를 완료하지 않으면 시작 거부. |
--external-tool-guard-endpoint <url> | 루프백 HTTP(S) origin | 미설정 | required 모드에서만 사용되는 프로바이더 origin. origin 전용이어야 하며 127.0.0.1, localhost, 또는 ::1 사용. 경로, 자격 증명, 리다이렉트, 프록시 라우팅은 거부. |
--external-tool-guard-timeout-ms <n> | 100..30000 범위의 정수 | 3000 | 핸드셰이크 및 prepare당 데드라인. 타임아웃은 핸드셰이크 중 시작을 실패시키거나, 턴 중에 호출을 차단하고 실패. |
--allow-origin <pattern> | 반복 가능 string | 미설정 | 기본 CORS 거부를 대체하는 교차 origin 허용 목록. *는 모든 origin을 허용하지만 토큰 필요. |
--allow-private-auth-base-url | boolean | false | /workspace/auth/provider가 localhost / 사설 네트워크 인증 프로바이더 baseUrl을 설치하도록 허용. 신뢰할 수 있는 로컬 개발에서만 사용. |
--prompt-deadline-ms <n> | 양의 정수 | 미설정 | 서버 측 프롬프트 월클럭 제한(ms). 타임아웃 시 abort 후 에러 반환. |
--writer-idle-timeout-ms <n> | 양의 정수 | 미설정 | SSE 연결당 유휴 타임아웃(ms). 이 시간 동안 이벤트가 전송되지 않으면 daemon이 SSE 연결을 닫음. |
--channel-idle-timeout-ms <n> | 음이 아닌 정수 | 0 | 마지막 세션이 닫힌 후 ACP 자식을 유지하는 시간. 0은 즉시 회수. |
--initialize-timeout-ms <n> | 양의 정수 | 10000 | initialize 핸드셰이크를 포함한 ACP 자식 요청 타임아웃(ms). |
--session-reap-interval-ms <n> | 음이 아닌 정수 | 60000 | 세션 리퍼 스캔 간격. 0은 비활성화. |
--session-idle-timeout-ms <n> | 음이 아닌 정수 | 1800000 | 연결 해제된 세션의 유휴 회수 시간. 0은 비활성화. |
--rate-limit / --no-rate-limit | boolean | env / off | 프롬프트, 변경, 읽기 라우트에 대한 티어별 HTTP 속도 제한 활성화. |
--rate-limit-prompt <n> | 양의 정수 | 10 | 윈도우당 프롬프트 요청 제한. 속도 제한 활성화 필요. |
--rate-limit-mutation <n> | 양의 정수 | 30 | 윈도우당 변경 요청 제한. 속도 제한 활성화 필요. |
--rate-limit-read <n> | 양의 정수 | 120 | 윈도우당 읽기 요청 제한. 속도 제한 활성화 필요. |
--rate-limit-window-ms <n> | >= 1000 범위의 정수 | 60000 | 속도 제한 윈도우 길이. 속도 제한 활성화 필요. |
| 플래그 없음 | - | - | QWEN_SERVE_NO_MCP_POOL=1은 풀을 완전히 비활성화. |
환경 변수
runQwenServe / Express 미들웨어에서 읽는 변수
| 환경 변수 | 효과 |
|---|---|
QWEN_SERVER_TOKEN | Bearer 토큰. 부팅 시 트리밍. |
QWEN_SERVE_DEBUG | 1 / true / on / yes(대소문자 무관)는 상세 stderr 로그를 활성화. 19-observability.md 참조. |
QWEN_SERVE_NO_MCP_POOL | 1은 워크스페이스 MCP 전송 풀을 비활성화하고 세션별 McpClientManager로 폴백. mcp_workspace_pool / mcp_pool_restart 기능 광고 중단. |
QWEN_SERVE_PROMPT_DEADLINE_MS | --prompt-deadline-ms의 env 폴백. |
QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS | --writer-idle-timeout-ms의 env 폴백. |
QWEN_SERVE_RATE_LIMIT | 1 / true는 티어별 HTTP 속도 제한 활성화. CLI --rate-limit / --no-rate-limit이 우선. |
QWEN_SERVE_RATE_LIMIT_PROMPT | --rate-limit-prompt의 env 폴백. |
QWEN_SERVE_RATE_LIMIT_MUTATION | --rate-limit-mutation의 env 폴백. |
QWEN_SERVE_RATE_LIMIT_READ | --rate-limit-read의 env 폴백. |
QWEN_SERVE_RATE_LIMIT_WINDOW_MS | --rate-limit-window-ms의 env 폴백. |
QWEN_CODE_MEMORY_PROJECT_SCOPE | workspace는 프로젝트 메모리를 정확한 워크스페이스 디렉토리 기준으로 키잉. 다른 값은 git-root 스코프 유지(인식 불가능한 값은 한 번 경고). 런타임 기본 env를 통해 전파되며 childEnvOverrides가 아님. --memory-project-scope가 우선. 각 워크스페이스의 remember/forget/dream 레인은 대기 작업을 MAX_PENDING = 16으로 제한. N개 워크스페이스는 daemon 전체 상한 없이 최대 16·N개의 대기 작업을 허용. |
qwen serve CLI 래퍼에서 읽는 변수
| 환경 변수 | 효과 |
|---|---|
QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN | 제어 문자를 포함하지 않는 최대 8192 UTF-16 코드 유닛의 비어 있지 않은 bearer 토큰. required 모드에서만 ServeOptions.externalToolGuard에 복사. CLI는 런타임 환경이 고정되기 전에 환경 값을 삭제. ACP 자식, channel 워커, 실행자 환경도 방어적으로 삭제. |
BridgeOptions.childEnvOverrides를 통해 ACP 자식으로 전달
runQwenServe는 핸들별로 이를 구성하므로, 한 프로세스의 두 daemon이 process.env에서 경주하지 않습니다. 예산 변수는 qwen serve의 부모 프로세스 env 폴백이 아닙니다. CLI 경로는 --mcp-client-budget / --mcp-budget-mode에서 이를 생성해야 합니다.
| 환경 변수 | 효과 |
|---|---|
QWEN_SERVE_MCP_CLIENT_BUDGET | ACP 자식의 readBudgetFromEnv()에서 소비하는 양의 정수 문자열. |
QWEN_SERVE_MCP_BUDGET_MODE | off / warn / enforce. |
QWEN_SERVE_MCP_POOL_TRANSPORTS | 쉼표로 구분된 전송 허용 목록. 기본 풀 전송은 stdio,websocket. http,sse를 명시적으로 포함 가능. |
QWEN_SERVE_MCP_POOL_DRAIN_MS | 풀 엔트리 유휴 드레인 지연. 기본값 30000, 1000..600000ms 범위로 제한. |
SDK / adapter에서 읽는 변수
| 환경 변수 | 효과 |
|---|---|
QWEN_DAEMON_URL | CLI TUI adapter, channel, IDE companion용 daemon 기본 URL. |
QWEN_DAEMON_TOKEN | Bearer 토큰. |
QWEN_DAEMON_WORKSPACE | POST /session에 전송되는 cwd를 오버라이드. |
settings.json 키
daemon은 각 워크스페이스의 병합된 설정과 환경 오버레이에서 각 워크스페이스 런타임을 구성합니다. 프로세스 전역 리스너/인증 옵션은 한 번 해석되며, 런타임별 서비스와 ACP 자식은 소유 런타임 스냅샷을 받습니다. 잘못된 설정은 영향을 받는 런타임에 대해 문서화된 시작 폴백 또는 실패 동작을 따릅니다. 다른 워크스페이스의 설정이 재사용되게 해서는 안 됩니다.
| 키 | 타입 | 효과 |
|---|---|---|
policy.permissionStrategy | 'first-responder' | 'designated' | 'consensus' | 'local-only' | BridgeOptions.permissionPolicy 설정. 활성 값은 /capabilities에 policy.permission으로 표시. 부팅 시 SERVE_CAPABILITY_REGISTRY.permission_mediation.modes에 대해 validatePolicyConfig()를 통해 검증. 알 수 없는 리터럴은 InvalidPolicyConfigError를 발생시키고 부팅을 명시적으로 실패. |
policy.consensusQuorum | 양의 정수 | consensus 정책의 N. 기본값은 votersAtIssue.size에 대해 floor(M/2) + 1(M=2는 만장일치; 더 큰 짝수 M은 과반 이상). consensus가 아닌 정책에서 설정하면 무시되며 부팅 시 stderr 경고를 출력. 양이 아닌 정수는 InvalidPolicyConfigError를 발생. 04-permission-mediation.md 참조. |
context.fileName | string | BridgeOptions.contextFilename을 통해 getCurrentGeminiMdFilename() 오버라이드. |
tools.disabled | string[] | 다음 ACP 자식 spawn에 대해 비활성화되는 도구. normalizeDisabledToolList()를 통해 정규화(packages/cli/src/config/normalizeDisabledTools.ts): 비배열은 []가 되고, 비문자열 항목은 건너뛰며, 공백이 트리밍되고, 빈 항목은 삭제되며, 첫 번째 항목을 유지하면서 중복이 제거. 부팅과 restartMcpServer 설정 새로고침 모두 이 함수를 통과. ToolRegistry.has(name)은 정확하고 대소문자를 구분. POST /workspace/tools/:name/enable 및 tool_toggled가 이 키를 업데이트. |
tools.approvalMode | 'default' | 'auto' | ... | 기본 세션 승인 모드. persist: true일 때 POST /session/:id/approval-mode가 여기에 기록. |
telemetry | object | OTel 설정. 키는 enabled, otlpEndpoint, otlpProtocol, otlpTracesEndpoint, otlpLogsEndpoint, otlpMetricsEndpoint, target, outfile, userId, includeSensitiveSpanAttributes, sensitiveSpanAttributeMaxLength, resourceAttributes, metrics.includeSessionId를 포함. resolveTelemetrySettings()가 부팅 시 읽고 initializeTelemetry()를 초기화. userId는 프로세스 전체이며 daemon이 여러 사용자에게 서비스할 때 최종 사용자 정체성으로 설정하면 안 됨. |
ServeOptions (프로그래밍 임베딩)
packages/cli/src/serve/types.ts는 runQwenServe와 createServeApp 모두에서 허용되는 타입화된 옵션 객체를 정의합니다. 위의 CLI 플래그를 미러링하며 다음을 추가합니다:
| 필드 | 효과 |
|---|---|
eventRingSize | 기본 세션당 링 크기를 오버라이드. |
memoryProjectScope | 'git-root' | 'workspace' 프로젝트 메모리 분할. QWEN_CODE_MEMORY_PROJECT_SCOPE로 폴백. |
maxPendingPromptsPerSession | 세션당 대기 프롬프트 상한. 0 / Infinity는 무제한. |
mcpPoolActive | 프로그래밍 스위치. QWEN_SERVE_NO_MCP_POOL에서 기본값 결정. |
externalToolGuard | 선택적 {mode:'required', endpoint, token, timeoutMs?}. 생략하면 완전히 비활성화. required 모드는 수신 전에 프로바이더 핸드셰이크 수행. |
allowOrigins | 교차 origin 허용 목록(string[]). --allow-origin에 해당. |
allowPrivateAuthBaseUrl | 사설 / localhost 인증 프로바이더 baseUrl 설치를 허용. |
enableSessionShell | 세션 셸 실행 활성화. Bearer 토큰과 세션 바인딩 클라이언트 id는 여전히 필요. |
promptDeadlineMs | 프롬프트 월클럭 제한. |
writerIdleTimeoutMs | SSE 라이터 유휴 타임아웃. |
channelIdleTimeoutMs | 마지막 세션이 닫힌 후 ACP 자식을 웜 상태로 유지하는 시간. |
initializeTimeoutMs | initialize 핸드셰이크를 포함한 ACP 자식 요청 타임아웃. |
sessionReapIntervalMs | 세션 리퍼 스캔 간격. |
sessionIdleTimeoutMs | 연결 해제된 세션의 유휴 회수 시간. |
rateLimit* | 티어별 HTTP 속도 제한 스위치, 임계값 및 윈도우. |
BridgeOptions (프로그래밍 브리지 임베딩)
packages/acp-bridge/src/bridgeOptions.ts는 브리지 옵션을 정의합니다. 전체 표는 03-acp-bridge.md를 참조하세요. 주요 필드:
| 필드 | 효과 |
|---|---|
boundWorkspace | 필수 표준 워크스페이스. |
sessionScope | 'single'(기본) vs 'thread'. |
initializeTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession | 경계된 리소스 상한. |
channelFactory | 플러그 가능한 ACP 자식 팩토리. 기본값은 defaultSpawnChannelFactory. |
fileSystem | BridgeFileSystem adapter. 07-workspace-filesystem.md 참조. |
permissionPolicy, permissionConsensusQuorum, permissionAudit | 중재자 연결. |
statusProvider | Daemon 호스트 프리플라이트 셀. |
childEnvOverrides | 핸들별 환경 추가 또는 제거. |
externalToolGuard | 선택적 daemon 측 비공개 자식→부모 prepare RPC 핸들러. 브릿지는 핸들러 호출 전후에 channel 소유권과 활성 프롬프트를 검증. |
contextFilename | getCurrentGeminiMdFilename() 오버라이드. |
channelIdleTimeoutMs | 마지막 세션이 닫힌 후 ACP 자식을 유지하는 시간(ms). 기본값 0. |
주요 기본값
| 상수 | 파일 | 값 | 의미 |
|---|---|---|---|
DEFAULT_MAX_SESSIONS | bridge.ts | 32 | SessionLimitExceededError 전 세션 상한. |
MAX_EVENT_RING_SIZE | bridge.ts | 1_000_000 | BridgeOptions.eventRingSize의 소프트 상한. 오타 방지. |
DEFAULT_RING_SIZE | eventBus.ts | 8000 | 세션당 SSE 리플레이 링 깊이. |
DEFAULT_MAX_QUEUED | eventBus.ts | 256 | 구독자당 큐 상한. |
DEFAULT_MAX_SUBSCRIBERS | eventBus.ts | 64 | 버스당 구독자 상한. |
WARN_THRESHOLD_RATIO | eventBus.ts | 0.75 | slow_client_warning 트리거. |
WARN_RESET_RATIO | eventBus.ts | 0.375 | 히스테리시스 재설정 임계값. |
DEFAULT_INIT_TIMEOUT_MS | bridge.ts | 10_000 | ACP initialize 핸드셰이크 타임아웃. |
MCP_RESTART_TIMEOUT_MS | bridge.ts | 300_000 | /workspace/mcp/:server/restart의 브리지 타임아웃. |
DEFAULT_PERMISSION_TIMEOUT_MS | bridge.ts | 5 * 60_000 | 권한 요청당 월클럭. |
DEFAULT_MAX_PENDING_PER_SESSION | bridge.ts | 64 | DEFAULT_MAX_SUBSCRIBERS와 정렬. |
MAX_RESOLVED_PERMISSION_RECORDS | permissionMediator.ts | 512 | 최근 해석된 권한의 FIFO. |
KILL_HARD_DEADLINE_MS | spawnChannel.ts | 10_000 | Channel별 정상 종료 윈도우. |
SHUTDOWN_FORCE_CLOSE_MS | run-qwen-serve.ts | 5_000 | HTTP 서버 강제 종료 타이머. |
MAX_READ_BYTES | fs/policy.ts | 256 * 1024 | 전체 스냅샷 및 반환 텍스트 상한. 더 큰 UTF-8 텍스트는 유한 행 제한 필요. |
MAX_WRITE_BYTES | fs/policy.ts | 5 * 1024 * 1024 | 쓰기 상한. |
MAX_DISPLAY_NAME_LENGTH | bridge.ts | 256 | 세션 displayName 상한. |
교차 참조
- 인증 설정:
12-auth-security.md - 기능 및 프로토콜 버전:
11-capabilities-versioning.md - 이벤트 링 및 배압 조정:
10-event-bus.md - MCP 풀 / 예산:
05-mcp-transport-pool.md및06-mcp-budget-guardrails.md - 권한 정책:
04-permission-mediation.md - 사용자 운영 가이드:
../../users/qwen-serve.md
Last updated on