环境变量与更新来源

按当前加载实现配置 .env、存储目录、运行开关和独立更新镜像。

This page has not been translated into English yet. The original Chinese version is shown below.

非空的启动进程环境优先于 .env，后者再优先于顶层 settings.env。CLI 参数是否覆盖某个模型字段还取决于选中 provider，见凭据与解析。

当前 .env 加载顺序

Authentication 页仍写“只加载首个文件”；当前 findEnvFiles / loadEnvironment 实现则是：

从工作目录向上，找到第一份允许加载的项目文件，每一级优先 .qwen/.env，其次 .env；不会沿途累积多个项目文件。
随后追加用户文件：全局 Qwen 目录的 .env；QWEN_HOME 改到其他目录时再考虑旧 ~/.qwen/.env；最后 ~/.env。重复路径去重。
依次补充变量，已有非空值不覆盖；空字符串视为未有效设置，后层可补齐。
最后用顶层 settings.env 补充仍未有效设置的字符串值。

启用信任功能且工作区不受信任时，只加载允许的用户级文件。受信任工作区可以使用祖先文件，但祖先自身明确 DO_NOT_TRUST 时仍跳过该文件。

三类变量限制

advanced.excludedEnvVars 默认 DEBUG、DEBUG_MODE，只作用于普通项目 .env；.qwen/.env 不受这份可配置列表排除。

加载器执行相关变量，例如 NODE_OPTIONS、NODE_PATH、LD_PRELOAD、DYLD_INSERT_LIBRARIES、BASH_ENV、ZDOTDIR 和 BASH_FUNC_*，在任何 .env 与顶层 settings.env 都拒绝。需要它们时由操作者启动环境提供；daemon 会进一步清理传给会话子进程的继承值，普通 CLI 与直接 ACP 的处理不同。

另一组只允许操作者控制的变量不能由项目 .env 设置，包括 CA/证书来源、Git/编辑器/浏览器命令、沙箱选择、QWEN_CLI_ENTRY、QWEN_CDP_MCP_COMMAND、TMPDIR/TMP/TEMP 等。它们可由 shell 或允许的用户文件在启动时设置，重载不会应用其变化或移除。

限制列表以官方配置章节和源码为准。.qwen/.env 仅豁免可配置的 DEBUG 排除列表，不豁免上述强制限制。per-server MCP env 与 per-hook env 属于各自范围，不能据此推断顶层 env 的限制也自动适用于它们。

存储与显示

变量	用途
QWEN_HOME	全局设置、凭据、记忆和 Skills 目录，默认 ~/.qwen；支持相对路径与 ~，不改变项目 .qwen
QWEN_RUNTIME_DIR	会话、日志、Todo 等运行输出目录，默认跟随 QWEN_HOME
NO_COLOR	任意值关闭颜色
QWEN_DISABLE_HYPERLINKS	1 强制关闭 OSC 8，回退普通链接文本
FORCE_HYPERLINK	非零整数或空字符串强制开启，0 或非数字关闭；仍受上述 opt-out 限制
CLI_TITLE	自定义终端标题

QWEN_HOME 与 QWEN_RUNTIME_DIR 在读取存储/设置路径前从允许的用户文件预解析，避免同一进程将状态分散到新旧目录。shell 历史默认按项目存于 ~/.qwen/tmp/<project_hash>/shell_history。

模型目录与运行诊断

QWEN_CODE_MODELS_DEV=off 忽略 models.dev 目录，仅使用内置表，同时停止刷新；QWEN_CODE_MODELS_DEV_REFRESH=off 只停止每日下载，已有比内置快照新的 model-registry.json 仍可使用。运行中保持选中目录，新进程才读取刷新结果。

QWEN_CODE_MODELS_DEV_URL 可指定完整 api.json 镜像；局部模型修正更适合 modelProviders。上述变量不能来自项目文件或顶层 settings.env，且不在重载时改变。

QWEN_CODE_UNATTENDED_RETRY=true/1 为 429、529 开启无限退避重试，单次等待最多 5 分钟，stderr 每 30 秒心跳；CI=true 本身不启用它。它不同于运行时长预算。

QWEN_CODE_PROFILE_STARTUP=1 记录启动阶段到 ~/.qwen/startup-perf/，默认只在沙箱子进程生效；加 PROFILE_STARTUP_OUTER=1（完整变量为 QWEN_CODE_PROFILE_STARTUP_OUTER）记录外层，加 QWEN_CODE_PROFILE_STARTUP_NO_HEAP=1 跳过内存快照。

QWEN_CODE_LEGACY_MCP_BLOCKING=1 恢复等待所有 MCP 握手的旧初始化方式；默认逐步后台发现。QWEN_CODE_LEGACY_ERASE_LINES=1 禁用终端重绘优化，0 强制启用；WSL 默认跳过该优化。

独立安装的更新镜像

export QWEN_UPDATE_BASE_URL="https://downloads.example.com/qwen-code"
qwen update

域名是示例。镜像根下按 v/ 放平台归档、SHA256SUMS 和 SHA256SUMS.sig，现有校验仍执行；QWEN_REQUIRE_SIGNATURE=1 可要求签名。

必须是无凭据、query 或 fragment 的 HTTPS URL。空值保留内置源；指定镜像后失败不会再回退内置源。仅从启动 shell 或用户 .env 配置，项目文件及任何范围的顶层 settings.env 都拒绝，变更需重启。

此变量适用于 qwen update、/update 与自动独立更新，不改变 npm registry 查询，也不同于安装器指向具体版本目录的 QWEN_INSTALL_BASE_URL。