Skip to main content
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:
FileScopeDescription
~/.qwen/settings.jsonUser (global)Applies to all your Qwen Code sessions. Recommended for modelProviders and env.
.qwen/settings.jsonProjectApplies only when running Qwen Code in this project. Overrides user settings.
System settingsSystemAdministrator-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