Skip to Content

설정 참조

개요

이 페이지는 qwen serve daemon과 adapter에 영향을 미치는 모든 설정을 수집합니다: 환경 변수, CLI 플래그, settings.json 키, 프로그래밍 옵션. 기능별 페이지는 교차 설정 정보가 필요할 때 여기로 링크합니다.

CLI 플래그 (qwen serve)

플래그타입기본값효과
--hostname <host>string127.0.0.1바인드 주소. 루프백 값: 127.0.0.1, localhost, ::1, [::1]. 루프백이 아닌 값은 부팅 시 bearer 토큰 필요. host:port 입력은 --port 사용을 안내하며 거부.
--port <n>number4170수신 포트. 0은 임시 포트를 의미.
--token <s>stringenvBearer 토큰. QWEN_SERVER_TOKEN을 오버라이드하며 부팅 시 트리밍됩니다. 프로세스 명령줄에 표시되므로, 배포에서는 env를 권장.
--openbooleanfalse런타임 준비 후 마운트된 Web Shell을 엽니다. 설정된 토큰은 URL 프래그먼트로 전달됩니다. 브라우저 실행 대상이 아닌 경우 순수 --open은 조용한 no-op입니다.
--open-with-authbooleanfalse루프백에서 베어러 인증과 함께 Web Shell을 엽니다. 활성화된 Web Shell과 빌드된 애셋이 필요합니다. 선택된 --token / QWEN_SERVER_TOKEN을 재사용하거나, listen 전에 프로세스 수명의 256비트 베어러를 생성합니다. 브라우저 대상이 아닌 환경에서는 시작하고 비밀 포함 프래그먼트 URL을 출력합니다. ServeOptions 또는 SDK 설정이 아닙니다.
--require-authbooleanfalseBearer 인증을 루프백과 /health로 확장. 토큰 없이는 부팅 거부.
--workspace <dir>절대 경로 / 반복 가능process.cwd()시작 워크스페이스 런타임. 반복하면 추가 격리 런타임 등록. 첫 번째가 primary. 모든 값은 절대 경로이고 디렉토리여야 하며, 부팅 시 표준화.
--memory-project-scope <mode>git-root / workspaceworkspace프로젝트 메모리 분할. workspace는 정확한 워크스페이스 디렉토리별로 격리. git-root는 동일한 Git 루트의 워크스페이스가 공유하는 레거시 호환 스코프. QWEN_CODE_MEMORY_PROJECT_SCOPE 오버라이드.
--max-sessions <n>number32워크스페이스당 활성 세션 상한. 0 / Infinity는 무제한. NaN / 음수 값은 예외 발생.
--max-total-sessions <n>number여러 시작/복원 워크스페이스에 대해 파생Daemon 전체 활성 세션 상한. 생략 시 워크스페이스당 상한과 시작/복원 워크스페이스 수에서 유한 기본값이 한 번 파생. 0 / Infinity는 무제한.
--max-pending-prompts-per-session <n>number5세션당 수락되었지만 대기 중/실행 중인 프롬프트 상한. 초과 시 503 반환. 0 / Infinity는 무제한. 음수 또는 비정수 값은 예외 발생.
--max-connections <n>number256HTTP 리스너 server.maxConnections. 0 / Infinity는 무제한.
--enable-session-shellbooleanfalse직접 POST /session/:id/shell 실행 활성화. Bearer 토큰 필요하며, 모든 호출은 세션 바인딩된 X-Qwen-Client-Id를 포함해야.
--event-ring-size <n>number8000세션당 SSE 리플레이 링. 소프트 상한은 1_000_000.
--compacted-replay-max-bytes <n>양의 정수4194304POST /session/:id/load가 반환하는 경계된 인메모리 리플레이 스냅샷의 바이트 상한. 하드 상한은 268435456.
--max-journal-events <n>양의 안전 정수10000미완료 턴에 대한 인플라이트 liveJournal 리플레이 엔트리의 세션당 기본 상한. 적응적 성장으로 상승 가능(--max-journal-bytes 참조). 어느 쪽의 journal 플래그라도 고정하면 성장 비활성화.
--max-journal-bytes <n>양의 안전 정수8388608(8 MiB)인플라이트 liveJournal의 세션당 기본 바이트 상한. 턴이 이를 초과하면 적응적 성장이 세션의 상한을 필요에 따라 상승시키며, 2배까지 가능하지만 남은 풀 헤드룸으로 제한되며 세션당 256 MiB 하드 상한을 초과하지 않음 — 유효 --memory-budget-mb의 5%인 daemon 전체 풀 내(최대 1024 MB로 제한; 유효 예산이 1024 MB 최소값 미만이면 0 — 성장 비활성화), 모든 workspace bridge가 공유; 헤드룸이 없으면 가장 오래된 엔트리가 history_truncated 마커와 함께 삭제. 어느 쪽의 journal 플래그라도 고정하면 성장 비활성화.
--memory-budget-mb <n>[1024, 1048576] 범위의 정수cgroup 제약 또는 호스트 메모리의 50%, 플래그 최대값(1048576 MB)으로 제한Daemon 프로세스 트리의 총 메모리 예산. 해석된 사용 가능 메모리로 제한. Daemon 상태의 limits.memory에서 보고되며, 자식 프로세스 크기를 결정하지 않음 — 현재 유일한 소비자는 적응적 live-journal 성장(--max-journal-bytes 참조). 부팅은 범위를 벗어난 값을 거부.
--memory-pressure-mode <mode>off | observeobserveDaemon이 자체 RSS와 V8 힙에서 메모리 압박 수준을 도출하는지 여부. 두 모드 모두 runtime.memory.pressure를 보고하며, observedaemon_memory_pressure를 발생. 루트 프로세스 전용. 조치 없음.
--child-heap-mode <mode>off | observeobserveDaemon이 예산의 자식별 힙 분할을 모델링하는지 여부. observe는 이를 보고하고 이를 초과하는 spawn을 카운트. 적용되는 것 없음. off는 분할을 전혀 공개하지 않음 — maxConcurrentChildrenperChildCeilingMb 모두 null.
--http-bridgebooleantrueStage 1 브리지 모드. --no-http-bridge도 http-bridge로 폴백하며 stderr에 출력.
--mcp-client-budget <n>양의 정수미설정WorkspaceMcpBudget.clientBudget을 설정하고 childEnvOverrides를 통해 ACP 자식으로 전달.
--mcp-budget-mode <m>off / warn / enforce예산이 설정되면 warn, 그렇지 않으면 offWorkspaceMcpBudget.mode 설정. enforce--mcp-client-budget 필요.
--external-tool-guard-mode <m>off / requiredoff관리되는 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-urlbooleanfalse/workspace/auth/provider가 localhost / 사설 네트워크 인증 프로바이더 baseUrl을 설치하도록 허용. 신뢰할 수 있는 로컬 개발에서만 사용.
--web / --no-webbooleantrue데몬 루트에서 빌드된 Web Shell SPA를 제공(GET /, /assets/*, /session/:id 문서 내비게이션). 이 진입점은 bearerAuth 이전에 마운트됩니다. 모든 API 라우트는 토큰 게이트 상태입니다. --no-web은 데몬을 API 전용으로 남깁니다.
--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>양의 정수10000initialize 핸드셰이크를 포함한 ACP 자식 요청 타임아웃(ms).
--session-restore-timeout-ms <n>양의 정수60000ACP 세션 로드/재개 타임아웃(ms). 이 플래그를 생략하면 명시적으로 제공된 initialize 타임아웃이 기본값을 높이되 낮추지는 않습니다.
--permission-response-timeout-ms <n>음이 아닌 정수0일반 권한 및 ask_user_question 응답에 대한 공유 월클럭 타임아웃. 0 또는 플래그 생략 시 무제한 대기. 양수 값은 타이머를 활성화.
--session-reap-interval-ms <n>음이 아닌 정수60000세션 리퍼 스캔 간격. 0은 비활성화.
--session-idle-timeout-ms <n>음이 아닌 정수1800000연결 해제된 세션의 유휴 회수 시간. 0은 비활성화.
--rate-limit / --no-rate-limitbooleanenv / 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_TOKENBearer 토큰. 부팅 시 트리밍.
QWEN_SERVE_DEBUG1 / true / on / yes(대소문자 무관)는 상세 stderr 로그를 활성화. 19-observability.md 참조.
QWEN_SERVE_NO_MCP_POOL1은 워크스페이스 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_LIMIT1 / 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_SERVE_NEW_FILE_MODE데몬 텍스트 쓰기에 대한 새 파일 모드 정책: owner(기본값 — 새 파일이 0600으로 생성되며 umask와 무관) 또는 system(새 파일은 0o666 & ~umask를 따름). 대소문자 무관. 리터럴 0600owner의 별칭으로 허용됨(다른 8진 모드는 지원되지 않음). 인식할 수 없는 값은 stderr에 경고하고 기본 0600을 유지. 기존 파일은 항상 모드를 유지. qwen-serve.md — 에이전트 텍스트 쓰기의 새 파일 모드 참조.
QWEN_CODE_MEMORY_PROJECT_SCOPEworkspace는 프로젝트 메모리를 정확한 워크스페이스 디렉토리로 키잉. git-root는 레거시 공유 스코프. 미설정 시 daemon이 workspace를 주입. 인식 불가능한 값은 한 번 경고하고 레거시 git-root 동작을 유지. 런타임 기본 env를 통해 전파되며 childEnvOverrides가 아님. --memory-project-scope가 우선. 각 워크스페이스의 remember/forget/dream 레인은 대기 작업을 MAX_PENDING = 16으로 제한. N개 워크스페이스는 daemon 전체 상한 없이 최대 16·N개의 대기 작업을 허용.

QWEN_CODE_MEMORY_PROJECT_SCOPE 값은 설정되지 않은 것으로 처리되어 기본값 workspace를 사용하며, 인식할 수 없는 비어 있지 않은 값은 여전히 한 번 경고하고 레거시 git-root 동작을 유지합니다.

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_BUDGETACP 자식의 readBudgetFromEnv()에서 소비하는 양의 정수 문자열.
QWEN_SERVE_MCP_BUDGET_MODEoff / warn / enforce.
QWEN_SERVE_MCP_POOL_TRANSPORTS쉼표로 구분된 전송 허용 목록. 기본 풀 전송은 stdio,websocket. http,sse를 명시적으로 포함 가능.
QWEN_SERVE_MCP_POOL_DRAIN_MS풀 엔트리 유휴 드레인 지연. 기본값 30000, 1000..600000ms 범위로 제한.

SDK / adapter에서 읽는 변수

환경 변수효과
QWEN_DAEMON_URLCLI TUI adapter, 채널 및 IDE companion용 데몬 기본 URL.
QWEN_DAEMON_TOKENBearer 토큰.
QWEN_DAEMON_WORKSPACEPOST /session에 전송되는 cwd를 오버라이드.

settings.json

daemon은 각 워크스페이스의 병합된 설정과 환경 오버레이에서 각 워크스페이스 런타임을 구성합니다. 프로세스 전역 리스너/인증 옵션은 한 번 해석되며, 런타임별 서비스와 ACP 자식은 소유 런타임 스냅샷을 받습니다. 잘못된 설정은 영향을 받는 런타임에 대해 문서화된 시작 폴백 또는 실패 동작을 따릅니다. 다른 워크스페이스의 설정이 재사용되게 해서는 안 됩니다.

타입효과
policy.permissionStrategy'first-responder' | 'designated' | 'consensus' | 'local-only'BridgeOptions.permissionPolicy 설정. 활성 값은 /capabilitiespolicy.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.fileNamestring워크스페이스 메모리 파일명. qwen serveextractContextFilename()을 통해 스냅샷을 찍고 contextFilename으로 워크스페이스 서비스에 전달. POST /workspace/init이 해당 파일을 씁니다.
tools.disabledstring[]다음 ACP 자식 spawn에 대해 비활성화되는 도구. normalizeDisabledToolList()를 통해 정규화(packages/cli/src/config/normalizeDisabledTools.ts): 비배열은 []가 되고, 비문자열 항목은 건너뛰며, 공백이 트리밍되고, 빈 항목은 삭제되며, 첫 번째 항목을 유지하면서 중복이 제거. 부팅과 restartMcpServer 설정 새로고침 모두 이 함수를 통과. ToolRegistry.has(name)은 정확하고 대소문자를 구분. POST /workspace/tools/:name/enabletool_toggled가 이 키를 업데이트.
tools.approvalMode'default' | 'auto' | ...기본 세션 승인 모드. persist: true일 때 POST /session/:id/approval-mode가 여기에 기록.
telemetryobjectOTel 설정. 키는 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는 공개 serve API를 통해 전달되는 타입화된 옵션을 정의합니다. 위의 CLI 플래그를 미러링하며 다음을 추가합니다:

필드효과
eventRingSize기본 세션당 링 크기를 오버라이드.
memoryProjectScoperunQwenServe 전용. 우선순위: 옵션, 런치 env, 그다음 workspace. 직접 createServeApp 호출자는 deps.daemonEnv를 사용.
maxPendingPromptsPerSession세션당 대기 프롬프트 상한. 0 / Infinity는 무제한.
mcpPoolActive프로그래밍 스위치. QWEN_SERVE_NO_MCP_POOL에서 기본값 결정.
externalToolGuard선택적 {mode:'required', endpoint, token, timeoutMs?}. 생략하면 완전히 비활성화. required 모드는 수신 전에 프로바이더 핸드셰이크 수행.
allowOrigins교차 origin 허용 목록(string[]). --allow-origin에 해당.
allowPrivateAuthBaseUrl사설 / localhost 인증 프로바이더 baseUrl 설치를 허용.
serveWebShell데몬 루트에서 빌드된 Web Shell SPA를 제공(기본 true). false(CLI의 --no-web)는 데몬을 API 전용으로 남깁니다. 빌드에 셸 애셋이 없으면 효과 없음.
enableSessionShell세션 셸 실행 활성화. Bearer 토큰과 세션 바인딩 클라이언트 id는 여전히 필요.
promptDeadlineMs프롬프트 월클럭 제한.
writerIdleTimeoutMsSSE 라이터 유휴 타임아웃.
channelIdleTimeoutMs마지막 세션이 닫힌 후 ACP 자식을 웜 상태로 유지하는 시간.
initializeTimeoutMsinitialize 핸드셰이크를 포함한 ACP 자식 요청 타임아웃.
sessionRestoreTimeoutMsACP 세션 로드/재개 타임아웃. 우선순위: 명시적 복원 값. 그렇지 않으면 명시적 initialize 값이 60000 기본값을 높이되 낮추지는 않음. 그렇지 않으면 60000.
sessionReapIntervalMs세션 리퍼 스캔 간격.
sessionIdleTimeoutMs연결 해제된 세션의 유휴 회수 시간.
rateLimit*티어별 HTTP 속도 제한 스위치, 임계값 및 윈도우.

BridgeOptions (프로그래밍 브리지 임베딩)

packages/acp-bridge/src/bridgeOptions.ts는 브리지 옵션을 정의합니다. 전체 표는 03-acp-bridge.md를 참조하세요. 주요 필드:

필드효과
boundWorkspace필수 표준 워크스페이스.
sessionScope'single'(기본) vs 'thread'.
initializeTimeoutMs, sessionRestoreTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession경계된 리소스 상한. permissionResponseTimeoutMs는 일반 권한 및 질문이 공유하며, 0 또는 생략 시 타이머가 비활성화됩니다.
channelFactory플러그 가능한 ACP 자식 팩토리. 기본값은 defaultSpawnChannelFactory.
fileSystemBridgeFileSystem adapter. 07-workspace-filesystem.md 참조.
permissionPolicy, permissionConsensusQuorum, permissionAudit중재자 연결.
statusProviderDaemon 호스트 프리플라이트 셀.
childEnvOverrides핸들별 환경 추가 또는 제거.
externalToolGuard선택적 daemon 측 비공개 자식→부모 prepare RPC 핸들러. 브릿지는 핸들러 호출 전후에 channel 소유권과 활성 프롬프트를 검증.
channelIdleTimeoutMs마지막 세션이 닫힌 후 ACP 자식을 유지하는 시간(ms). 기본값 0.

주요 기본값

상수파일의미
DEFAULT_MAX_SESSIONSbridge.ts32SessionLimitExceededError 전 세션 상한.
MAX_EVENT_RING_SIZEbridge.ts1_000_000BridgeOptions.eventRingSize의 소프트 상한. 오타 방지.
DEFAULT_RING_SIZEeventBus.ts8000세션당 SSE 리플레이 링 깊이.
DEFAULT_MAX_QUEUEDeventBus.ts256구독자당 큐 상한.
DEFAULT_MAX_SUBSCRIBERSeventBus.ts64버스당 구독자 상한.
WARN_THRESHOLD_RATIOeventBus.ts0.75slow_client_warning 트리거.
WARN_RESET_RATIOeventBus.ts0.375히스테리시스 재설정 임계값.
DEFAULT_INIT_TIMEOUT_MSbridge.ts10_000ACP initialize 핸드셰이크 타임아웃.
MCP_RESTART_TIMEOUT_MSbridge.ts300_000/workspace/mcp/:server/restart의 브리지 타임아웃.
DEFAULT_PERMISSION_TIMEOUT_MSbridge.ts0공유 권한 및 질문 월클럭. 0은 타이머를 비활성화.
DEFAULT_MAX_PENDING_PER_SESSIONbridge.ts64DEFAULT_MAX_SUBSCRIBERS와 정렬.
MAX_RESOLVED_PERMISSION_RECORDSpermissionMediator.ts512최근 해석된 권한의 FIFO.
KILL_HARD_DEADLINE_MSspawnChannel.ts10_000Channel별 정상 종료 윈도우.
SHUTDOWN_FORCE_CLOSE_MSrun-qwen-serve.ts5_000HTTP 서버 강제 종료 타이머.
MAX_READ_BYTESfs/policy.ts256 * 1024전체 스냅샷 및 반환 텍스트 상한. 더 큰 UTF-8 텍스트는 유한 행 제한 필요.
MAX_WRITE_BYTESfs/policy.ts5 * 1024 * 1024쓰기 상한.
MAX_DISPLAY_NAME_LENGTHbridge.ts256세션 displayName 상한.

교차 참조

Last updated on