> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings.json Reference

> Complete reference for Qwen Code settings.json configuration

Qwen Code can be configured via `settings.json` files that control behavior, UI preferences, model settings, and more.

## Configuration Files

Qwen Code supports multiple settings files with different scopes:

| File                    | Scope         | Description                                                                             |
| ----------------------- | ------------- | --------------------------------------------------------------------------------------- |
| `~/.qwen/settings.json` | User (global) | Applies to all your Qwen Code sessions. **Recommended for `modelProviders` and `env`.** |
| `.qwen/settings.json`   | Project       | Applies only when running Qwen Code in this project. Overrides user settings.           |
| System settings         | System        | Administrator-level settings (platform-specific paths)                                  |

### Settings Priority

Settings are merged with the following precedence (later values override earlier ones):

1. System Defaults
2. User Settings (`~/.qwen/settings.json`)
3. Workspace Settings (`.qwen/settings.json`)
4. System Settings (as overrides)

## File Format

Settings files are JSON files with optional comments (using `//` or `/* */`):

```json theme={null}
{
  "$version": 3,
  // Model configuration
  "model": {
    "name": "qwen3-coder-plus"
  },
  "modelProviders": {
    // OpenAI-compatible providers
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "Qwen3 Coder Plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  }
}
```

## Top-Level Configuration

### Model Providers

<ParamField path="modelProviders" type="object" required>
  Model providers configuration grouped by authentication type. Each auth type contains an array of model configurations.

  See [Model Providers](/configuration/model-providers) for detailed configuration.
</ParamField>

### Environment Variables

<ParamField path="env" type="object">
  Fallback environment variables (e.g., API keys). Lower priority than shell `export` and `.env` files.

  ```json theme={null}
  {
    "env": {
      "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx",
      "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxxx"
    }
  }
  ```

  **Security Note:** Never commit API keys to version control. Consider using `.env` files instead.
</ParamField>

### MCP Servers

<ParamField path="mcpServers" type="object">
  Configuration for Model Context Protocol (MCP) servers.

  ```json theme={null}
  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
      }
    }
  }
  ```
</ParamField>

## Model Settings

<ParamField path="model.name" type="string">
  The default model to use when Qwen Code starts.

  ```json theme={null}
  {
    "model": {
      "name": "qwen3-coder-plus"
    }
  }
  ```
</ParamField>

<ParamField path="model.maxSessionTurns" type="number" default="-1">
  Maximum number of user/model/tool turns to keep in a session. `-1` means unlimited.
</ParamField>

<ParamField path="model.sessionTokenLimit" type="number">
  The maximum number of tokens allowed in a session before automatic compression or truncation.
</ParamField>

<ParamField path="model.skipStartupContext" type="boolean" default="false">
  Avoid sending the workspace startup context at the beginning of each session. Useful for large projects.
</ParamField>

<ParamField path="model.generationConfig" type="object">
  Generation configuration settings for API requests.

  <ParamField path="model.generationConfig.timeout" type="number">
    Request timeout in milliseconds.
  </ParamField>

  <ParamField path="model.generationConfig.maxRetries" type="number">
    Maximum number of retries for failed requests.
  </ParamField>

  <ParamField path="model.generationConfig.enableCacheControl" type="boolean" default="true">
    Enable cache control for DashScope providers.
  </ParamField>

  <ParamField path="model.generationConfig.contextWindowSize" type="number">
    Overrides the default context window size for the selected model. Use when a provider's effective context limit differs from Qwen Code's default.
  </ParamField>
</ParamField>

## General Settings

<ParamField path="general.vimMode" type="boolean" default="false">
  Enable Vim keybindings in the terminal UI.
</ParamField>

<ParamField path="general.enableAutoUpdate" type="boolean" default="true">
  Enable automatic update checks and installations on startup.
</ParamField>

<ParamField path="general.gitCoAuthor" type="boolean" default="true">
  Automatically add a Co-authored-by trailer to git commit messages when commits are made through Qwen Code.
</ParamField>

<ParamField path="general.language" type="string" default="auto">
  The language for the user interface. Use `"auto"` to detect from system settings.

  Options: `"auto"`, `"en"`, `"zh"`, `"ja"`, `"de"`, `"fr"`, `"ru"`, `"pt-BR"`
</ParamField>

<ParamField path="general.outputLanguage" type="string" default="auto">
  The language for LLM output. Use `"auto"` to detect from system settings, or set a specific language.
</ParamField>

<ParamField path="general.chatRecording" type="boolean" default="true">
  Enable saving chat history to disk. Disabling this will prevent `--continue` and `--resume` from working.
</ParamField>

<ParamField path="general.defaultFileEncoding" type="string" default="utf-8">
  Default encoding for new files.

  Options: `"utf-8"` (without BOM), `"utf-8-bom"` (with BOM)
</ParamField>

## UI Settings

<ParamField path="ui.theme" type="string" default="Qwen Dark">
  The color theme for the UI.
</ParamField>

<ParamField path="ui.hideTips" type="boolean" default="false">
  Hide helpful tips in the UI.
</ParamField>

<ParamField path="ui.showLineNumbers" type="boolean" default="true">
  Show line numbers in code output.
</ParamField>

<ParamField path="ui.enableWelcomeBack" type="boolean" default="true">
  Show welcome back dialog when returning to a project with conversation history.
</ParamField>

<ParamField path="ui.accessibility.enableLoadingPhrases" type="boolean" default="true">
  Enable loading phrases (disable for accessibility).
</ParamField>

<ParamField path="ui.accessibility.screenReader" type="boolean">
  Render output in plain-text to be more screen reader accessible.
</ParamField>

## Security Settings

<ParamField path="security.auth.selectedType" type="string">
  The protocol to use on startup.

  Options: `"openai"`, `"anthropic"`, `"gemini"`, `"vertex-ai"`, `"qwen-oauth"`
</ParamField>

<ParamField path="security.auth.apiKey" type="string">
  API key for OpenAI compatible authentication (only used when `selectedType` is `"openai"`).
</ParamField>

<ParamField path="security.auth.baseUrl" type="string">
  Base URL for OpenAI compatible API.
</ParamField>

<ParamField path="security.folderTrust.enabled" type="boolean" default="false">
  Enable folder trust security feature. See [Trusted Folders](/configuration/trusted-folders).
</ParamField>

## Context Settings

<ParamField path="context.includeDirectories" type="array">
  Additional directories to include in the workspace context. Missing directories will be skipped with a warning.

  ```json theme={null}
  {
    "context": {
      "includeDirectories": [
        "/path/to/directory1",
        "/path/to/directory2"
      ]
    }
  }
  ```
</ParamField>

<ParamField path="context.fileFiltering.respectGitIgnore" type="boolean" default="true">
  Respect `.gitignore` files when searching.
</ParamField>

<ParamField path="context.fileFiltering.respectQwenIgnore" type="boolean" default="true">
  Respect `.qwenignore` files when searching. See [.qwenignore](/configuration/qwenignore).
</ParamField>

<ParamField path="context.fileFiltering.enableFuzzySearch" type="boolean" default="true">
  Enable fuzzy search when searching for files.
</ParamField>

## Tools Settings

<ParamField path="tools.approvalMode" type="string" default="default">
  Approval mode for tool usage. Controls how tools are approved before execution.

  Options:

  * `"plan"`: Show execution plan only, don't execute
  * `"default"`: Prompt for approval before execution
  * `"auto-edit"`: Auto-approve edit tools, prompt for others
  * `"yolo"`: Auto-approve all tools
</ParamField>

<ParamField path="tools.allowed" type="array">
  A list of tool names that will bypass the confirmation dialog.

  ```json theme={null}
  {
    "tools": {
      "allowed": ["read", "glob", "grep"]
    }
  }
  ```
</ParamField>

<ParamField path="tools.exclude" type="array">
  Tool names to exclude from discovery.

  ```json theme={null}
  {
    "tools": {
      "exclude": ["write_file", "edit"]
    }
  }
  ```
</ParamField>

<ParamField path="tools.shell.enableInteractiveShell" type="boolean" default="true">
  Use node-pty for an interactive shell experience. Falls back to child\_process if PTY is unavailable.
</ParamField>

<ParamField path="tools.useRipgrep" type="boolean" default="true">
  Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.
</ParamField>

<ParamField path="tools.useBuiltinRipgrep" type="boolean" default="true">
  Use the bundled ripgrep binary. When set to false, the system-level `rg` command will be used instead.
</ParamField>

## MCP Settings

<ParamField path="mcp.allowed" type="array">
  A list of MCP servers to allow.

  ```json theme={null}
  {
    "mcp": {
      "allowed": ["filesystem", "github"]
    }
  }
  ```
</ParamField>

<ParamField path="mcp.excluded" type="array">
  A list of MCP servers to exclude.
</ParamField>

## Privacy Settings

<ParamField path="privacy.usageStatisticsEnabled" type="boolean" default="true">
  Enable collection of usage statistics.
</ParamField>

## Advanced Settings

<ParamField path="advanced.excludedEnvVars" type="array">
  Environment variables to exclude from project context. Default: `["DEBUG", "DEBUG_MODE"]`
</ParamField>

<ParamField path="webSearch" type="object">
  Configuration for web search providers.

  ```json theme={null}
  {
    "webSearch": {
      "provider": [
        {
          "type": "tavily",
          "apiKey": "tvly-xxxxxxxxxxxxx"
        },
        {
          "type": "google",
          "apiKey": "AIzaxxxxxxxxxxxxx",
          "searchEngineId": "xxxxxxxxxxxxx"
        }
      ],
      "default": "tavily"
    }
  }
  ```
</ParamField>

## Complete Example

```json theme={null}
{
  "$version": 3,
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "Qwen3 Coder Plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      },
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "baseUrl": "https://api.openai.com/v1",
        "envKey": "OPENAI_API_KEY"
      }
    ],
    "anthropic": [
      {
        "id": "claude-sonnet-4-20250514",
        "name": "Claude Sonnet 4",
        "envKey": "ANTHROPIC_API_KEY"
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": -1,
    "generationConfig": {
      "timeout": 120000,
      "enableCacheControl": true
    }
  },
  "general": {
    "vimMode": false,
    "enableAutoUpdate": true,
    "language": "auto",
    "gitCoAuthor": true
  },
  "ui": {
    "theme": "Qwen Dark",
    "showLineNumbers": true,
    "hideTips": false
  },
  "context": {
    "fileFiltering": {
      "respectGitIgnore": true,
      "respectQwenIgnore": true,
      "enableFuzzySearch": true
    }
  },
  "tools": {
    "approvalMode": "default",
    "useRipgrep": true,
    "shell": {
      "enableInteractiveShell": true
    }
  }
}
```

## Migration

Qwen Code automatically migrates settings files from older versions. The `$version` field tracks the schema version.

Current version: `3`

## See Also

* [Model Providers Configuration](/configuration/model-providers)
* [Environment Variables](/configuration/environment-variables)
* [Trusted Folders](/configuration/trusted-folders)
* [.qwenignore File](/configuration/qwenignore)