配置与环境变量

使用 /settings 打开交互式配置界面。配置文件支持带注释的 JSON（JSONC）。不要将凭据写入共享项目配置。

配置文件与优先级

合并顺序为：默认值 → 用户 → 可信项目 → 可信本地 → 参数。高优先级配置按字段自身的合并规则生效；数组和嵌套对象并非全部采用相同的替换方式。

项目未受信任时，不合并项目和本地配置。项目不能通过自己的配置授予自己信任。显式传入的 --settings 仍然生效。详见权限。

非交互运行不做信任检查：使用 -p、输入或输出被管道或重定向、CI=true 或 GITHUB_ACTIONS=true 时，当前目录视为可信，项目和本地配置都会加载。在未审阅过配置的仓库上做自动化时，请传入 --setting-sources user。

根据需要将本地配置和含密钥的文件加入项目忽略规则。文件名带有“local”并不意味着 Git 会自动忽略它。

从小配置开始

{
  "general": {
    "vimMode": false,
    "defaultPermissionMode": "default",
    "enableAutoUpdate": false
  }
}

配置自定义端点见模型与服务商。不要用小示例替换完整的已有配置文件，应合并所需字段。

选择配置来源

qwen --setting-sources user,project
qwen --setting-sources ""

第一条命令加载用户和项目配置，排除本地层。空来源列表排除三个磁盘配置层，但内置默认值和显式参数配置仍然生效。未知来源名会被忽略，因此要检查拼写。

仅覆盖本次运行的配置：

qwen --settings '{"general":{"vimMode":true}}'
qwen --settings ./preview-settings.json

内联示例采用 POSIX shell 引号语法。相对配置文件路径以项目路径为基准。显式参数配置独立于 --setting-sources 和项目是否可信，因此应先检查通过此方式加载的文件。

使用独立用户配置根目录

qwen --config-dir /path/to/qwen-profile

此参数改变本次运行的用户配置根目录，不会重命名项目的 .qwen 目录。排查凭据或配置缺失时，请使用明确路径，并确认当前使用的配置根目录。

环境变量

配置值可以引用环境变量，例如 "${MODEL_API_KEY}"。应在启动 Qwen Code 前，在 shell 中导出这些变量。

配置中的变量展开发生在配置服务加载 .env 文件之前。因此，不要依赖仅在新加载的 .env 中定义的变量，来解析同一次加载中的配置占位符。Hook 占位符会保留，交由 Hook 流程处理。

每个会话只加载一个环境文件：

• 如果存在 <project>/.qwen/.env，加载该文件。这与项目是否可信、--setting-sources 均无关。
• 否则加载用户配置目录中的 .env。
• 不搜索父目录，也不搜索普通的项目根目录 .env。
• 已存在的环境变量优先。
• 项目未受信任时，项目 .env 不能设置会改变执行程序的变量：shell 前缀、Git Bash 路径，Windows 上还包括 PATH、BASH_PATH、GIT_BASH、GIT_HOME 和 SYSTEMROOT。文件中的其他变量照常加载。

排除所有磁盘配置来源，并不会关闭环境文件加载。不要在项目 .env 中放入你不希望在该目录每个会话中生效的值。

应用与排查配置变更

部分配置可在会话中生效，部分需要重启；服务商定义需要重启。设置未按预期生效时，依次检查配置来源选择、项目是否可信、更高优先级覆盖和当前配置根目录。

普通配置文件问题可能产生警告，并尽量保留可用配置。显式请求加载的参数配置无效时，可能阻止启动。应修复报错字段，不要直接删除全部配置。详见故障排查。