Skip to Content
开发者指南Daemon配置参考

配置参考

概述

本页面汇总了影响 qwen serve 守护进程及其适配器的所有设置：环境变量、CLI 参数、settings.json 键以及编程式选项。当特定功能页面需要跨领域的配置细节时，会链接回此处。

CLI 参数 (qwen serve)

参数类型默认值作用
--hostname <host>string127.0.0.1绑定地址。环回值：127.0.0.1、localhost、::1、[::1]。非环回地址需要在启动时提供 bearer token。拒绝 host:port 格式的输入，并提示使用 --port。
--port <n>number4170监听端口；0 表示临时端口。
--token <s>stringenvBearer token。覆盖 QWEN_SERVER_TOKEN 并在启动时进行 trim 处理。由于它会出现在进程命令行中，因此在部署时建议使用环境变量。
--require-authbooleanfalse将 bearer 认证扩展到环回地址和 /health 端点；如果没有 token，启动时将拒绝运行。
--workspace <dir>absolute path / repeatableprocess.cwd()启动时的工作区运行时；重复使用可注册额外的隔离运行时。第一个为主运行时。每个值必须是绝对路径且为目录；在启动时进行规范化处理。
--memory-project-scope <mode>git-root / workspaceworkspace项目内存分区。workspace 按精确的工作区目录隔离；git-root 是同一 Git root 下工作区共享的旧版兼容作用域。覆盖 QWEN_CODE_MEMORY_PROJECT_SCOPE。
--max-sessions <n>number32每个工作区的活跃会话上限。0 / Infinity 表示无限制；NaN 或负值会抛出异常。
--max-total-sessions <n>number多个启动/恢复的工作区时派生守护进程级别的活跃会话上限。省略时，根据每个工作区的上限和启动/恢复的工作区数量派生一个有限的默认值。0 / Infinity 表示无限制。
--max-pending-prompts-per-session <n>number5每个会话已接受但处于 pending/running 状态的 prompt 上限。超出的 prompt 将返回 503。0 / Infinity 表示无限制；负值或非整数值会抛出异常。
--max-connections <n>number256HTTP 监听器的 server.maxConnections；0 / Infinity 表示无限制。
--enable-session-shellbooleanfalse启用直接的 POST /session/:id/shell 执行。需要 bearer token，且每次调用都必须携带绑定到会话的 X-Qwen-Client-Id。
--event-ring-size <n>number8000每个会话的 SSE 重放 ring；软上限为 1_000_000。
--compacted-replay-max-bytes <n>positive integer4194304POST /session/:id/load 返回的有界内存重放快照的字节上限；硬上限为 268435456。
--max-journal-events <n>positive safe integer10000每个会话未完成的轮次的 liveJournal 重放条目的基线上限。自适应增长可以提高它（参见 --max-journal-bytes）；固定任一 journal 标志都会禁用增长。
--max-journal-bytes <n>positive safe integer8388608 (8 MiB)每个会话 liveJournal 的基线字节上限。当轮次超过它时，自适应增长会按需提高会话的上限，向双倍增长但受限于剩余 pool 余量，且不超过每会话 256 MiB 的硬上限 — 在有效的 --memory-budget-mb 的 5% 的守护进程级别 pool 内（上限为 1024 MB；当有效预算低于 1024 MB 最小值时为 0 — 增长禁用），由每个 workspace bridge 共享；没有余量时最旧的条目会被丢弃并标记 history_truncated。固定任一 journal 标志都会禁用增长。
--memory-budget-mb <n>integer in [1024, 1048576]受 cgroup 限制或主机内存的 50%，上限为参数最大值（1048576 MB）守护进程进程树的总内存预算，上限为解析后的可用内存。在守护进程状态的 limits.memory 中观察和报告；它不影响子进程的大小 — 当前的唯一消费者是自适应 live-journal 增长（参见 --max-journal-bytes）。启动时拒绝超出范围的值。
--memory-pressure-mode <mode>off | observeobserve守护进程是否根据自身 RSS 和 V8 堆派生内存压力级别。两种模式都会报告 runtime.memory.pressure；仅 observe 会触发 daemon_memory_pressure。仅限根进程；无自动修复措施。
--child-heap-mode <mode>off | observeobserve守护进程是否为预算中的每个子进程建模堆分区。observe 会报告该分区并统计超出分区的 spawn 次数；不应用任何限制。off 完全不发布分区 — maxConcurrentChildren 和 perChildCeilingMb 均为 null。
--http-bridgebooleantrueStage 1 bridge 模式。--no-http-bridge 仍会回退到 http-bridge 并将信息打印到 stderr。
--mcp-client-budget <n>positive integerunset设置 WorkspaceMcpBudget.clientBudget 并通过 childEnvOverrides 将其转发给 ACP 子进程。
--mcp-budget-mode <m>off / warn / enforce设置了 budget 时为 warn，否则为 off设置 WorkspaceMcpBudget.mode；enforce 需要配合 --mcp-client-budget 使用。
--external-tool-guard-mode <m>off / requiredoff启用托管 ACP 外部预执行 Guard。required 模式下，如果其环回 provider 未完成 v1 握手，则启动失败。
--external-tool-guard-endpoint <url>loopback HTTP(S) originunset仅在 required 模式下使用的 provider origin。必须是纯 origin 且使用 127.0.0.1、localhost 或 ::1；路径、凭据、重定向和代理路由会被拒绝。
--external-tool-guard-timeout-ms <n>integer 100..300003000每次握手和每次 prepare 的截止时间。超时在握手期间会导致启动失败，在轮次期间会 fail closed 该调用。
--allow-origin <pattern>repeatable stringunset跨域白名单，用于替换默认的 CORS 拒绝策略。* 允许任何 origin，但需要 token。
--allow-private-auth-base-urlbooleanfalse允许 /workspace/auth/provider 安装 localhost / 私有网络 auth provider 的 baseUrl；仅在受信任的本地开发环境中使用。
--web / --no-webbooleantrue在守护进程根路径提供构建好的 Web Shell SPA（GET /、/assets/* 以及 /session/:id 文档导航）。这些入口点在 bearerAuth 之前挂载；每个 API 路由仍受 token 门控。--no-web 使守护进程仅提供 API。
--prompt-deadline-ms <n>positive integerunset服务端 prompt 的绝对时间限制（毫秒）。超时将中止并返回错误。
--writer-idle-timeout-ms <n>positive integerunset每个 SSE 连接的空闲超时时间（毫秒）。如果在此时间内没有发送事件，守护进程将关闭 SSE 连接。
--channel-idle-timeout-ms <n>non-negative integer0在最后一个会话关闭后，保持 ACP 子进程存活的时间。0 表示立即回收。
--initialize-timeout-ms <n>positive integer10000ACP 子进程请求超时时间，包括 initialize 握手（毫秒）。
--session-restore-timeout-ms <n>positive integer60000ACP 会话 load/resume 超时时间（毫秒）。省略此参数时，显式提供的 initialize 超时时间会提高预算，但不会将其降低到默认值以下。
--session-reap-interval-ms <n>non-negative integer60000会话回收扫描间隔；0 表示禁用。
--session-idle-timeout-ms <n>non-negative integer1800000已断开连接会话的空闲回收时间；0 表示禁用。
--rate-limit / --no-rate-limitbooleanenv / off为 prompt、mutation 和 read 路由启用分层 HTTP 速率限制。
--rate-limit-prompt <n>positive integer10每个时间窗口内的 prompt 请求限制；需要启用速率限制。
--rate-limit-mutation <n>positive integer30每个时间窗口内的 mutation 请求限制；需要启用速率限制。
--rate-limit-read <n>positive integer120每个时间窗口内的 read 请求限制；需要启用速率限制。
--rate-limit-window-ms <n>integer >= 100060000速率限制时间窗口长度；需要启用速率限制。
无参数--QWEN_SERVE_NO_MCP_POOL=1 完全禁用 pool。

环境变量

由 runQwenServe / Express 中间件读取

环境变量作用
QWEN_SERVER_TOKENBearer token；在启动时进行 trim 处理。
QWEN_SERVE_DEBUG1 / true / on / yes（不区分大小写）启用详细的 stderr 日志。请参阅 19-observability.md。
QWEN_SERVE_NO_MCP_POOL1 禁用工作区 MCP transport pool 并回退到每个会话的 McpClientManager；capabilities 将停止广播 mcp_workspace_pool / mcp_pool_restart。
QWEN_SERVE_PROMPT_DEADLINE_MS--prompt-deadline-ms 的环境变量回退值。
QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS--writer-idle-timeout-ms 的环境变量回退值。
QWEN_SERVE_RATE_LIMIT1 / true 启用分层 HTTP 速率限制；CLI 参数 --rate-limit / --no-rate-limit 优先级更高。
QWEN_SERVE_RATE_LIMIT_PROMPT--rate-limit-prompt 的环境变量回退值。
QWEN_SERVE_RATE_LIMIT_MUTATION--rate-limit-mutation 的环境变量回退值。
QWEN_SERVE_RATE_LIMIT_READ--rate-limit-read 的环境变量回退值。
QWEN_SERVE_RATE_LIMIT_WINDOW_MS--rate-limit-window-ms 的环境变量回退值。
QWEN_SERVE_NEW_FILE_MODE守护进程文本写入的新文件权限模式策略：owner（默认值 — 新文件创建为 0600，不受 umask 影响）或 system（新文件遵循 0o666 & ~umask）。不区分大小写；字面值 0600 作为 owner 的别名被接受（不支持其他八进制模式），无法识别的值会在 stderr 警告并保持 0600 默认值。现有文件始终保留其权限模式。参见 qwen-serve.md — Agent 文本写入的新文件权限模式。
QWEN_CODE_MEMORY_PROJECT_SCOPEworkspace 按精确的工作区目录键控项目内存；git-root 选择旧版共享作用域。未设置时，守护进程注入 workspace；无法识别的值警告一次并保留旧版 git-root 行为。通过运行时 base env 传播，而非 childEnvOverrides；--memory-project-scope 优先级更高。每个工作区的 remember/forget/dream lane 将 pending 任务上限设为 MAX_PENDING = 16；N 个工作区最多允许 16·N 个排队任务，无守护进程级别上限。

空白的 QWEN_CODE_MEMORY_PROJECT_SCOPE 值被视为未设置，因此默认为 workspace；无法识别的非空值仍然警告一次并保留旧版 git-root 行为。

由 qwen serve CLI 包装器读取

环境变量作用
QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN非空 bearer token，最多 8192 个 UTF-16 编码单元，不含控制字符，仅在 required 模式下复制到 ServeOptions.externalToolGuard。然后 CLI 在运行时环境被冻结之前删除环境变量；ACP 子进程、channel worker 和执行器环境也会防御性地清除它。

通过 BridgeOptions.childEnvOverrides 转发给 ACP 子进程

runQwenServe 会为每个 handle 构建这些变量，因此同一进程中的两个守护进程不会在 process.env 上产生竞争。budget 变量不是 qwen serve 父进程的环境变量回退值；CLI 路径必须从 --mcp-client-budget / --mcp-budget-mode 生成它们。

环境变量作用
QWEN_SERVE_MCP_CLIENT_BUDGET正整数字符串，由 ACP 子进程的 readBudgetFromEnv() 消费。
QWEN_SERVE_MCP_BUDGET_MODEoff / warn / enforce。
QWEN_SERVE_MCP_POOL_TRANSPORTS逗号分隔的 transport 白名单；默认的 pooled transports 为 stdio,websocket；可以显式包含 http,sse。
QWEN_SERVE_MCP_POOL_DRAIN_MSPool 条目的空闲排空延迟；默认值为 30000，限制在 1000..600000 毫秒之间。

由 SDK / 适配器读取

环境变量作用
QWEN_DAEMON_URLCLI TUI 适配器、channels 和 IDE companion 的守护进程 base URL。
QWEN_DAEMON_TOKENBearer token。
QWEN_DAEMON_WORKSPACE覆盖发送给 POST /session 的 cwd。

settings.json 键

守护进程从每个工作区合并后的设置和环境覆盖构建该工作区的运行时。进程全局的监听器/认证选项只解析一次，而运行时特定的服务和 ACP 子进程接收所属运行时的快照。格式错误的设置遵循受影响运行时的已文档化启动回退或失败行为；它们不得导致另一个工作区的设置被复用。

键类型作用
policy.permissionStrategy'first-responder' | 'designated' | 'consensus' | 'local-only'设置 BridgeOptions.permissionPolicy；当前生效的值会作为 policy.permission 出现在 /capabilities 中。启动时会通过 validatePolicyConfig() 对照 SERVE_CAPABILITY_REGISTRY.permission_mediation.modes 进行验证。未知的字面量会抛出 InvalidPolicyConfigError 并明确导致启动失败。
policy.consensusQuorumpositive integerconsensus 策略的 N 值。默认值为 votersAtIssue.size 的 floor(M/2) + 1（M=2 表示一致同意；更大的偶数 M 表示超过半数）。如果在非 consensus 策略下设置，它将被忽略，并且启动时会在 stderr 打印警告。非正整数会抛出 InvalidPolicyConfigError。请参阅 04-permission-mediation.md。
context.fileNamestring通过 BridgeOptions.contextFilename 覆盖 getCurrentGeminiMdFilename()。
tools.disabledstring[]在下次生成 ACP 子进程时禁用的工具。通过 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 会写入此处。
telemetryobjectOTel 配置。键包括 enabled、otlpEndpoint、otlpProtocol、otlpTracesEndpoint、otlpLogsEndpoint、otlpMetricsEndpoint、target、outfile、userId、includeSensitiveSpanAttributes、sensitiveSpanAttributeMaxLength、resourceAttributes 和 metrics.includeSessionId。resolveTelemetrySettings() 在启动时读取它并初始化 initializeTelemetry()。userId 是进程级别的，当守护进程服务多个用户时，不得将其配置为终端用户身份。

ServeOptions（编程式嵌入）

packages/cli/src/serve/types.ts 定义了通过公开 serve API 传递的类型化选项。它映射了上述 CLI 参数并增加了以下内容：

字段作用
eventRingSize覆盖默认的每个会话 ring 大小。
memoryProjectScope仅限 runQwenServe；优先级为选项、启动时环境变量，然后回退到 workspace。直接调用 createServeApp 的使用 deps.daemonEnv。
maxPendingPromptsPerSession每个会话的 pending prompt 上限；0 / Infinity 表示无限制。
mcpPoolActive编程式开关，默认值来自 QWEN_SERVE_NO_MCP_POOL。
externalToolGuard可选的 {mode:'required', endpoint, token, timeoutMs?}。省略表示完全关闭；required 模式在监听前执行 provider 握手。
allowOrigins跨域白名单（string[]），对应 --allow-origin。
allowPrivateAuthBaseUrl允许安装私有 / localhost auth provider 的 baseUrl。
serveWebShell在守护进程根路径提供构建好的 Web Shell SPA（默认 true）；false（CLI 的 --no-web）使守护进程仅提供 API。当构建产物不包含 shell 资源时无效。
enableSessionShell启用会话 shell 执行；仍然需要 bearer token 和绑定到会话的 client id。
promptDeadlineMsPrompt 绝对时间限制。
writerIdleTimeoutMsSSE writer 空闲超时时间。
channelIdleTimeoutMs在最后一个会话关闭后，保持 ACP 子进程预热状态的时间。
initializeTimeoutMsACP 子进程请求超时时间，包括 initialize 握手。
sessionRestoreTimeoutMsACP 会话 load/resume 超时时间。优先级：显式的 restore 值；否则显式的 initialize 值会提高 60000 默认值但不会降低它；否则为 60000。
sessionReapIntervalMs会话回收扫描间隔。
sessionIdleTimeoutMs已断开连接会话的空闲回收时间。
rateLimit*分层 HTTP 速率限制开关、阈值和时间窗口。

BridgeOptions（编程式 bridge 嵌入）

packages/acp-bridge/src/bridgeOptions.ts 定义了 bridge 选项。完整表格请参见 03-acp-bridge.md。关键字段如下：

FieldEffect
boundWorkspace必需的规范工作区。
sessionScope'single'（默认）或 'thread'。
initializeTimeoutMs, sessionRestoreTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession资源上限约束。
channelFactory可插拔的 ACP 子进程工厂；默认为 defaultSpawnChannelFactory。
fileSystemBridgeFileSystem 适配器。参见 07-workspace-filesystem.md。
permissionPolicy, permissionConsensusQuorum, permissionAudit中介器组件配置。
statusProvider守护进程宿主预检单元。
childEnvOverrides按句柄添加或移除环境变量。
externalToolGuard可选的守护进程侧处理器，用于私有的子进程到父进程的 prepare RPC。bridge 在调用处理器前后验证通道所有权和当前活跃的 Prompt。
contextFilename覆盖 getCurrentGeminiMdFilename()。
channelIdleTimeoutMs最后一个会话关闭后，保持 ACP 子进程存活的时长（毫秒）；默认为 0。

重要默认值

ConstantFileValueMeaning
DEFAULT_MAX_SESSIONSbridge.ts32触发 SessionLimitExceededError 前的会话上限。
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 的 bridge 超时时间。
DEFAULT_PERMISSION_TIMEOUT_MSbridge.ts5 * 60_000每个权限请求的实际时间上限。
DEFAULT_MAX_PENDING_PER_SESSIONbridge.ts64与 DEFAULT_MAX_SUBSCRIBERS 对齐。
MAX_RESOLVED_PERMISSION_RECORDSpermissionMediator.ts512近期已解决权限的 FIFO 队列。
KILL_HARD_DEADLINE_MSspawnChannel.ts10_000每个通道的优雅关闭时间窗口。
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
VS Code IDE 守护进程适配器错误分类与修复