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 /* */):

{
  "$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

modelProviders · object · required

Model providers configuration grouped by authentication type. Each auth type contains an array of model configurations.

See Model Providers for detailed configuration.

Environment Variables

env · object

Fallback environment variables (e.g., API keys). Lower priority than shell export and .env files.

{
  "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.

MCP Servers

mcpServers · object

Configuration for Model Context Protocol (MCP) servers.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

Model Settings

model.name · string

The default model to use when Qwen Code starts.

{
  "model": {
    "name": "qwen3-coder-plus"
  }
}

model.maxSessionTurns · number · default: "-1"

Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.

model.sessionTokenLimit · number

The maximum number of tokens allowed in a session before automatic compression or truncation.

model.skipStartupContext · boolean · default: "false"

Avoid sending the workspace startup context at the beginning of each session. Useful for large projects.

model.generationConfig · object

Generation configuration settings for API requests.

model.generationConfig.timeout · number

Request timeout in milliseconds.

model.generationConfig.maxRetries · number

Maximum number of retries for failed requests.

model.generationConfig.enableCacheControl · boolean · default: "true"

Enable cache control for DashScope providers.

model.generationConfig.contextWindowSize · 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.

General Settings

general.vimMode · boolean · default: "false"

Enable Vim keybindings in the terminal UI.

general.enableAutoUpdate · boolean · default: "true"

Enable automatic update checks and installations on startup.

general.gitCoAuthor · boolean · default: "true"

Automatically add a Co-authored-by trailer to git commit messages when commits are made through Qwen Code.

general.language · 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"

general.outputLanguage · string · default: "auto"

The language for LLM output. Use "auto" to detect from system settings, or set a specific language.

general.chatRecording · boolean · default: "true"

Enable saving chat history to disk. Disabling this will prevent --continue and --resume from working.

general.defaultFileEncoding · string · default: "utf-8"

Default encoding for new files.

Options: "utf-8" (without BOM), "utf-8-bom" (with BOM)

UI Settings

ui.theme · string · default: "Qwen Dark"

The color theme for the UI.

ui.hideTips · boolean · default: "false"

Hide helpful tips in the UI.

ui.showLineNumbers · boolean · default: "true"

Show line numbers in code output.

ui.enableWelcomeBack · boolean · default: "true"

Show welcome back dialog when returning to a project with conversation history.

ui.accessibility.enableLoadingPhrases · boolean · default: "true"

Enable loading phrases (disable for accessibility).

ui.accessibility.screenReader · boolean

Render output in plain-text to be more screen reader accessible.

Security Settings

security.auth.selectedType · string

The protocol to use on startup.

Options: "openai", "anthropic", "gemini", "vertex-ai", "qwen-oauth"

security.auth.apiKey · string

API key for OpenAI compatible authentication (only used when selectedType is "openai").

security.auth.baseUrl · string

Base URL for OpenAI compatible API.

security.folderTrust.enabled · boolean · default: "false"

Enable folder trust security feature. See Trusted Folders.

Context Settings

context.includeDirectories · array

Additional directories to include in the workspace context. Missing directories will be skipped with a warning.

{
  "context": {
    "includeDirectories": [
      "/path/to/directory1",
      "/path/to/directory2"
    ]
  }
}

context.fileFiltering.respectGitIgnore · boolean · default: "true"

Respect .gitignore files when searching.

context.fileFiltering.respectQwenIgnore · boolean · default: "true"

Respect .qwenignore files when searching. See .qwenignore.

context.fileFiltering.enableFuzzySearch · boolean · default: "true"

Enable fuzzy search when searching for files.

Tools Settings

tools.approvalMode · 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

tools.allowed · array

A list of tool names that will bypass the confirmation dialog.

{
  "tools": {
    "allowed": ["read", "glob", "grep"]
  }
}

tools.exclude · array

Tool names to exclude from discovery.

{
  "tools": {
    "exclude": ["write_file", "edit"]
  }
}

tools.shell.enableInteractiveShell · boolean · default: "true"

Use node-pty for an interactive shell experience. Falls back to child_process if PTY is unavailable.

tools.useRipgrep · boolean · default: "true"

Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.

tools.useBuiltinRipgrep · boolean · default: "true"

Use the bundled ripgrep binary. When set to false, the system-level rg command will be used instead.

MCP Settings

mcp.allowed · array

A list of MCP servers to allow.

{
  "mcp": {
    "allowed": ["filesystem", "github"]
  }
}

mcp.excluded · array

A list of MCP servers to exclude.

Privacy Settings

privacy.usageStatisticsEnabled · boolean · default: "true"

Enable collection of usage statistics.

Advanced Settings

advanced.excludedEnvVars · array

Environment variables to exclude from project context. Default: ["DEBUG", "DEBUG_MODE"]

webSearch · object

Configuration for web search providers.

{
  "webSearch": {
    "provider": [
      {
        "type": "tavily",
        "apiKey": "tvly-xxxxxxxxxxxxx"
      },
      {
        "type": "google",
        "apiKey": "AIzaxxxxxxxxxxxxx",
        "searchEngineId": "xxxxxxxxxxxxx"
      }
    ],
    "default": "tavily"
  }
}

Complete Example

{
  "$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
• Environment Variables
• Trusted Folders
• .qwenignore File