Skip to Content
开发者指南守护进程模式（开发者深入解析）配置参考

配置参考

概述

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

CLI 标志 (qwen serve)

参数类型默认值作用
--hostname <host>string127.0.0.1绑定地址。环回值：任意 127.0.0.0/8 地址、localhost、::1、[::1]；localhost 仅解析一次并固定，且 trusted mode 还会在启动完成前验证实际监听地址。非环回结果始终携带 bearer token：由操作员提供，或在 --token 和 QWEN_SERVER_TOKEN 均不存在时于启动时生成 — 生成取决于请求的主机名拼写，因此解析到非环回的 localhost 永远不会生成，且仅在 token 源已解析时才启动（拒绝信息会读取已解析的地址），而解析到环回的非字面名称会生成并打印其 bearer token。host:port 格式的输入会被拒绝，并提示使用 --port。
--port <n>number4170监听端口；0 表示临时端口。
--token <s>stringenvBearer token。覆盖 QWEN_SERVER_TOKEN 并在启动时进行 trim 处理。由于它会出现在进程命令行中，因此在部署时建议使用环境变量。当此参数和环境变量均不存在时，非环回绑定会生成临时的 128 位 base64url bearer（22 个字符）并在启动时打印一次；环回拼写不生成。显式为空的值是已提供的源，而非缺失的源：它会遮蔽环境变量，因此非环回绑定会拒绝启动，而在环回上则选择无 token 的可信模式（或在 --require-auth 下拒绝）。
--openbooleanfalse在 runtime 就绪后打开挂载的 Web Shell。已解析的 token（已配置或已生成）通过 URL fragment 传递。当浏览器启动不符合条件时，裸 --open 仍然是静默的无操作。
--open-with-authbooleanfalse在环回上以 bearer 认证打开 Web Shell。需要启用 Web Shell 和已构建的资源。复用已选择的 --token / QWEN_SERVER_TOKEN，或在监听前生成进程生命周期的 256 位 bearer — 该生成的值在启动前被安装到 options token 上，使此标志成为满足环回 --require-auth 的第三个 token 源。在浏览器不符合条件的环境中，启动并打印包含密钥的 fragment URL。不是 ServeOptions 或 SDK 设置。
--require-authbooleanfalse将 bearer 认证扩展到环回地址和 /health 端点。当没有 token 源可解析时，启动拒绝运行 — 在非环回生成步骤之后，这意味着环回绑定：在非环回绑定上，生成的临时 token 即可满足此标志，因此其「无已配置密钥则无守护进程」的快速失败行为仅限环回。环回 token 源包括 --token、QWEN_SERVER_TOKEN 和 --open-with-auth。
--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>number800, or derived at capacity 25 or less守护进程级别的活跃会话上限。省略时，在注册容量大于 25（包括默认值 256）时为 800，即使只有一个工作区也是如此。在容量为 25 或更少时，根据每个工作区的上限和启动/恢复的工作区数量派生一次，其中一个这样的工作区是无限制的。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 auth 或 trusted-loopback authority 下生效；每次调用都必须携带绑定到会话的 X-Qwen-Client-Id。
--event-ring-size <n>number8000每个会话的 SSE 重放 ring；软上限为 1_000_000。
--session-prompt-settled-close-grace-ms <n>non-negative integer0prompt 稳定后、空闲会话可被自动关闭前的宽限期（毫秒）。基于轮询的 SSE 客户端利用此窗口重连，而不会触发会话重建。0 = 立即关闭。
--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 拒绝策略。通配符和非环回 HTTP(S) origin 需要已解析的 token，因此在非环回绑定上，生成的临时 bearer 可同时满足两个守卫，拒绝行为仅限环回；无 token 的 HTTP(S) origin 必须是环回地址。
--allow-private-auth-base-urlbooleanfalse允许 /workspace/auth/provider 安装 localhost / 私有网络 auth provider 的 baseUrl；仅在受信任的本地开发环境中使用。
--web / --no-webbooleantrue在守护进程根路径提供构建好的 Web Shell SPA（GET /、/assets/* 以及 /session/:id 文档导航）。这些入口点在 bearerAuth 之前挂载；API 调用仍遵循已配置的 bearer auth 或 trusted-loopback authority。--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运行时工作 drain 后 ACP 子进程的自动回收延迟。首次使用前会保留普通预热。显式 keepalive 可延长已配置的延迟；以较长的剩余延迟为准。
--initialize-timeout-ms <n>positive integer10000ACP 子进程启动截止时间（channel factory + initialize 握手）及默认请求超时时间（毫秒）。
--session-restore-timeout-ms <n>positive integer60000ACP 会话 load/resume 超时时间（毫秒）。省略此参数时，显式提供的 initialize 超时时间会提高预算，但不会将其降低到默认值以下。
--permission-response-timeout-ms <n>non-negative integer0普通权限和 ask_user_question 响应的共享挂钟超时时间。0 或省略该标志时无限等待；正值启用计时器。
--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 处理。--token 优先级更高。显式为空的值视为已提供而非缺失，因此解析为无 token — --token '' 同样会遮蔽此处已设置的值。当此变量和 --token 均未设置时，非环回绑定会生成临时 bearer 并打印一次；守护进程永远不会将此变量写回环境中。
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_SERVE_SESSION_ATTACHMENTS_ROOT覆盖会话附件的存储位置；未命中已配置 root 的读取/删除操作会回退到默认运行时临时目录，以便切换前的附件仍可读取。接受绝对路径、相对于守护进程 cwd 的路径或 ~ / ~/…。参见 qwen-serve.md — 会话附件存储。
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 条目的空闲 drain 延迟；默认值为 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工作区内存文件名。qwen serve 通过 extractContextFilename() 对其进行快照，并作为 contextFilename 传递给工作区服务；POST /workspace/init 会写入该文件。
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 大小。
sessionPromptSettledCloseGraceMsprompt 稳定后、空闲会话可被自动关闭前的宽限期。0 = 立即关闭。
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 auth 或 trusted-loopback authority 以及绑定到会话的 client id 仍然是必需的。
promptDeadlineMsPrompt 绝对时间限制。
writerIdleTimeoutMsSSE writer 空闲超时时间。
channelIdleTimeoutMs运行时工作 drain 后 ACP 子进程的自动回收延迟。首次使用前会保留普通预热；活跃的 keepalive 窗口可延长延迟。
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。关键字段：

字段作用
boundWorkspace必需的规范工作区。
sessionScope'single'（默认）或 'thread'。
initializeTimeoutMs, sessionRestoreTimeoutMs, maxSessions, eventRingSize, permissionResponseTimeoutMs, maxPendingPermissionsPerSession资源上限约束。permissionResponseTimeoutMs 由普通权限和问题共享；0 或省略时禁用其计时器。
channelFactory可插拔的 ACP 子进程工厂；默认为 defaultSpawnChannelFactory。
fileSystemBridgeFileSystem 适配器。参见 07-workspace-filesystem.md。
permissionPolicy, permissionConsensusQuorum, permissionAudit中介器组件配置。
statusProvider守护进程宿主预检单元。
childEnvOverrides按句柄添加或移除环境变量。
externalToolGuard可选的守护进程侧处理器，用于私有的子进程到父进程的 prepare RPC。bridge 在调用处理器前后验证通道所有权和当前活跃的 Prompt。
channelIdleTimeoutMs运行时工作 drain 后 ACP 子进程的自动回收延迟。首次使用前会保留普通预热；活跃的 keepalive 窗口可延长延迟。

重要默认值

常量文件值含义
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.ts0共享权限和问题挂钟时间；0 禁用计时器。
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 守护进程适配器错误分类与修复