Settings and environment

Use /settings to inspect the interactive settings dialog. File-based settings support JSON with comments (JSONC). Keep credentials out of shared project configuration.

Configuration files and precedence

The merge order is defaults → user → trusted project → trusted local → flag. Higher layers take precedence according to each field’s merge rule; arrays and nested objects do not all use the same replacement behavior.

Project and local settings are excluded when the project is not trusted. A project cannot grant itself trust through its own settings. Explicit --settings input still applies. See Permissions.

Non-interactive runs skip the trust check: with -p, piped or redirected input or output, CI=true, or GITHUB_ACTIONS=true, the working directory is treated as trusted and its project and local settings load. In automation against a repository whose configuration you have not reviewed, pass --setting-sources user.

Add local settings and files containing secrets to your project’s ignore rules as appropriate. A filename containing “local” is not by itself a Git exclusion.

Start with a small configuration

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

Use Models and providers to add a custom endpoint. Do not replace a complete existing settings file with a small example: merge the relevant keys.

Select configuration sources

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

The first command loads user and project disk settings, excluding the local layer. An empty source list excludes all three disk layers; built-in defaults and explicit flag settings still apply. Unknown source names are ignored, so check spelling.

Override a setting for one run:

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

The inline example uses POSIX-shell quoting. Relative settings-file paths resolve against the project path. Explicit flag settings are independent of --setting-sources and project trust; review files you pass this way.

Use a separate user configuration root

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

This changes the user-level configuration root for the run. It does not rename the project’s .qwen directory. Use an explicit path and check which configuration root is active when diagnosing missing credentials or settings.

Environment variables

Settings values can reference environment variables, for example "${MODEL_API_KEY}". Export these variables in the shell before starting Qwen Code.

Settings expansion occurs before the settings service loads a .env file. Therefore, do not rely on a variable defined only in a newly loaded .env file to resolve a settings placeholder during that load. Hook placeholders are preserved for hook-specific handling.

Qwen Code loads one environment file per session:

• If <project>/.qwen/.env exists, it is loaded. This does not depend on project trust or --setting-sources.
• Otherwise, the user configuration directory’s .env is loaded.
• Parent directories and ordinary project-root .env files are not searched.
• Existing environment variables take precedence.
• In an untrusted project, the project .env cannot set variables that change which programs run: the shell prefix and Git Bash path, and on Windows also PATH, BASH_PATH, GIT_BASH, GIT_HOME, and SYSTEMROOT. Other variables in the file still load.

Disabling all disk setting sources does not disable environment-file loading. Do not put values in a project .env that you would not want applied in every session in that directory.

Apply and diagnose changes

Some settings apply during a session; others require restarting. Provider definitions require restart. If the expected value is not effective, check source selection, project trust, higher-priority overrides, and the active configuration root.

Ordinary settings-file problems can produce warnings while preserving usable configuration. Invalid explicitly requested flag settings can stop startup. Fix the reported field instead of deleting all configuration. See Troubleshooting.