Configuration System

Qwen Code uses a sophisticated hierarchical configuration system that allows customization at multiple levels with clear precedence rules.

Overview

The configuration system provides:

Hierarchical Loading: Multiple configuration sources with defined precedence
Type Safety: Full TypeScript type definitions
Validation: Automatic validation of configuration values
Dynamic Updates: Some settings can be changed at runtime
Environment Integration: Seamless environment variable support

Configuration Hierarchy

Configuration is loaded from multiple sources with this precedence (highest to lowest):

1. CLI Arguments (--model, --temperature, etc.)
   ↓
2. Environment Variables (QWEN_*, OPENAI_*)
   ↓
3. Project Settings (.qwen/settings.json)
   ↓
4. User Settings (~/.qwen/settings.json)
   ↓
5. System Settings
   ↓
6. Built-in Defaults

Example:

# User settings (~/.qwen/settings.json)
{ "model": "qwen-coder-plus" }

# Project settings (.qwen/settings.json)
{ "model": "gpt-4o" }

# Environment variable
export QWEN_MODEL="claude-3-5-sonnet"

# CLI argument
qwen-code --model qwen-turbo

# Result: Uses "qwen-turbo" (CLI has highest priority)

Configuration File Format

User Settings

Location: ~/.qwen/settings.json Purpose: Global settings across all projects

{
  "model": "qwen-coder-plus",
  "temperature": 1.0,
  "vimMode": true,
  "theme": "dark",
  "telemetry": {
    "enabled": false
  },
  "editor": {
    "preferredEditor": "code"
  }
}

Project Settings

Location: .qwen/settings.json in project root Purpose: Project-specific overrides

{
  "model": "gpt-4o",
  "context": {
    "contextFileNames": ["QWEN.md", "PROJECT.md"],
    "directories": ["src", "lib"]
  },
  "tools": {
    "core": ["read_file", "write_file", "edit"],
    "exclude": ["run_shell_command(rm)"]
  }
}

Configuration Categories

General Settings

interface GeneralSettings {
  model?: string;                    // Model name
  temperature?: number;              // 0.0-2.0
  topP?: number;                     // 0.0-1.0
  vimMode?: boolean;                 // Enable vim keybindings
  autoUpdate?: boolean;              // Auto-update CLI
  editor?: {
    preferredEditor?: string;        // 'code', 'vim', 'nano'
  };
}

UI Settings

interface UISettings {
  theme?: string;                    // 'dark', 'light', 'auto'
  showBanner?: boolean;              // Show welcome banner
  showFooter?: boolean;              // Show status footer
  colorScheme?: {
    primary?: string;
    secondary?: string;
    // ...
  };
}

Model Settings

interface ModelSettings {
  model?: string;                    // Model identifier
  temperature?: number;              // Sampling temperature
  topP?: number;                     // Nucleus sampling
  maxTokens?: number;                // Max output tokens
  sessionTurnLimit?: number;         // Max turns per session
  compressionSettings?: {
    enabled?: boolean;
    triggerTokens?: number;
    targetTokens?: number;
  };
}

Context Settings

interface ContextSettings {
  contextFileNames?: string[];       // Context file names
  directories?: string[];            // Directories to include
  fileFiltering?: {
    maxFileSize?: number;
    excludePatterns?: string[];
    includePatterns?: string[];
  };
}

Tool Settings

interface ToolSettings {
  core?: string[];                   // Allowed tools
  exclude?: string[];                // Blocked tools
  approvalMode?: ApprovalMode;       // Confirmation behavior
  shell?: {
    enableInteractiveShell?: boolean;
    showColor?: boolean;
    pager?: string;
  };
  sandbox?: {
    enabled?: boolean;
    provider?: 'docker' | 'podman' | 'macos';
  };
}

Privacy Settings

interface PrivacySettings {
  telemetry?: {
    enabled?: boolean;
    endpoint?: string;
  };
  crashReporting?: boolean;
}

Advanced Settings

interface AdvancedSettings {
  debug?: boolean;                   // Enable debug mode
  verbose?: boolean;                 // Verbose logging
  logLevel?: 'error' | 'warn' | 'info' | 'debug';
  bugReportCommand?: string;         // Custom bug report command
}

Environment Variables

Core Variables

# Model Configuration
export QWEN_MODEL="qwen-coder-plus"
export QWEN_TEMPERATURE="0.7"
export QWEN_TOP_P="0.95"

# OpenAI-compatible API
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-4o"

# Sandboxing
export QWEN_SANDBOX="docker"  # or 'podman', 'false'

# Debug
export DEBUG="1"
export VERBOSE="true"

# Privacy
export QWEN_TELEMETRY="false"

Variable Naming Convention

Qwen-specific: QWEN_*
OpenAI compatibility: OPENAI_*
Development: DEBUG, DEV, VERBOSE

CLI Arguments

Override any setting via command-line arguments:

# Model configuration
qwen-code --model qwen-coder-plus --temperature 0.8

# UI settings
qwen-code --theme dark --vim-mode

# Tool restrictions
qwen-code --core-tools read_file,write_file

# Debug mode
qwen-code --debug --verbose

Configuration API

Access configuration programmatically:

import { Config } from '@qwen-code/qwen-code-core';

// Get configuration instance
const config = new Config();

// Read settings
const model = config.getModel();
const temperature = config.getTemperature();
const isVimMode = config.getVimMode();

// Update settings (runtime)
config.setModel('gpt-4o');
config.setTemperature(0.7);
config.setApprovalMode(ApprovalMode.AUTO_EDIT);

// Access subsystems
const toolRegistry = config.getToolRegistry();
const fileService = config.getFileService();
const subagentManager = config.getSubagentManager();

Storage System

The Storage class manages file paths:

import { Storage } from '@qwen-code/qwen-code-core';

// Global directories
const qwenDir = Storage.getGlobalQwenDir();
// Returns: ~/.qwen

const tempDir = Storage.getGlobalTempDir();
// Returns: ~/.qwen/tmp

const skillsDir = config.storage.getUserSkillsDir();
// Returns: ~/.qwen/skills

// Project directories
const projectConfig = config.storage.getProjectConfigDir();
// Returns: ./.qwen

const projectTemp = config.storage.getProjectTempDir();
// Returns: ./.qwen/tmp

Approval Modes

Control when user confirmation is required:

export enum ApprovalMode {
  PLAN = 'plan',           // Review all actions before execution
  DEFAULT = 'default',     // Confirm modifying operations
  AUTO_EDIT = 'auto-edit', // Auto-approve edits, confirm others
  YOLO = 'yolo',          // Auto-approve everything (dangerous!)
}

Setting Approval Mode:

# Via CLI
qwen-code --approval-mode plan

# Via settings.json
{ "approvalMode": "plan" }

# Via environment
export QWEN_APPROVAL_MODE="auto-edit"

# At runtime
/settings set approvalMode auto-edit

File Filtering

Control which files are accessible:

export interface FileFilteringOptions {
  maxFileSize: number;               // Max file size in bytes
  excludePatterns: string[];         // Glob patterns to exclude
  includePatterns: string[];         // Glob patterns to include
  respectGitignore: boolean;         // Respect .gitignore
  respectQwenignore: boolean;        // Respect .qwenignore
}

// Default filtering
export const DEFAULT_FILE_FILTERING_OPTIONS: FileFilteringOptions = {
  maxFileSize: 1024 * 1024,          // 1 MB
  excludePatterns: [
    '**/node_modules/**',
    '**/.git/**',
    '**/dist/**',
    '**/build/**',
  ],
  includePatterns: ['**/*'],
  respectGitignore: true,
  respectQwenignore: true,
};

Tool Restrictions

Core Tools (Allowlist)

Restrict to specific tools:

{
  "tools": {
    "core": [
      "read_file",
      "write_file",
      "edit",
      "glob",
      "grep_search",
      "run_shell_command(git)",
      "run_shell_command(npm)"
    ]
  }
}

Exclude Tools (Blocklist)

Block specific tools or commands:

{
  "tools": {
    "exclude": [
      "run_shell_command(rm)",
      "run_shell_command(sudo)",
      "write_file"
    ]
  }
}

Validation

Configuration is validated on load:

// Automatic validation
const config = new Config();
// Throws error if invalid

// Manual validation
import { validateConfig } from '@qwen-code/qwen-code-core';

const errors = validateConfig(configObject);
if (errors.length > 0) {
  console.error('Invalid configuration:', errors);
}

Common Validation Rules:

Temperature: 0.0 ≤ value ≤ 2.0
Top P: 0.0 ≤ value ≤ 1.0
Max tokens: value > 0
File size: value > 0
Model: non-empty string

Context Files

Special markdown files for persistent context:

{
  "context": {
    "contextFileNames": [
      "QWEN.md",      // Primary context file
      "AGENTS.md",    // Agent-specific context
      "PROJECT.md"    // Project description
    ]
  }
}

These files are automatically included in model context:

QWEN.md: User preferences, project info, saved memories
AGENTS.md: Agent configurations and instructions
PROJECT.md: Project overview and guidelines

Best Practices

User Settings

Use for personal preferences:

{
  "vimMode": true,
  "theme": "dark",
  "editor": { "preferredEditor": "code" },
  "telemetry": { "enabled": false }
}

Project Settings

Use for project-specific configuration:

{
  "model": "gpt-4o",
  "context": {
    "contextFileNames": ["QWEN.md", "CODING_STANDARDS.md"],
    "directories": ["src", "tests"]
  },
  "tools": {
    "core": ["read_file", "write_file", "edit", "run_shell_command"]
  }
}

Environment Variables

Use for sensitive data or environment-specific settings:

# In CI/CD
export OPENAI_API_KEY="$SECRET_KEY"
export QWEN_TELEMETRY="false"
export QWEN_SANDBOX="docker"

CLI Arguments

Use for one-off overrides:

# Quick test with different model
qwen-code --model qwen-turbo --temperature 0.5

# Debug session
qwen-code --debug --verbose

Troubleshooting

View Effective Configuration

# In Qwen Code CLI
/settings

# Or view specific setting
/settings get model

Configuration Validation Errors

If you see validation errors:

Check for typos in setting names
Verify value types (number vs string)
Ensure values are within valid ranges
Check for syntax errors in JSON files

Precedence Issues

If settings aren’t taking effect:

Check for overrides in higher-priority sources
Use /settings to see effective values
Use --debug to see configuration loading

Next Steps

Testing Guide - Testing with different configurations
Tools System - Configuring tool access
Subagents System - Agent configurations

Contributing

Core Concepts

Tools Reference

​Configuration System

​Overview

​Configuration Hierarchy

​Example:

​Configuration File Format

​User Settings

​Project Settings

​Configuration Categories

​General Settings

​UI Settings

​Model Settings

​Context Settings

​Tool Settings

​Privacy Settings

​Advanced Settings

​Environment Variables

​Core Variables

​Variable Naming Convention

​CLI Arguments

​Configuration API

​Storage System

​Approval Modes

​File Filtering

​Tool Restrictions

​Core Tools (Allowlist)

​Exclude Tools (Blocklist)

​Validation

​Context Files

​Best Practices

​User Settings

​Project Settings

​Environment Variables

​CLI Arguments

​Troubleshooting

​View Effective Configuration

​Configuration Validation Errors

​Precedence Issues

​Next Steps

Configuration System

Overview

Configuration Hierarchy

Example:

Configuration File Format

User Settings

Project Settings

Configuration Categories

General Settings

UI Settings

Model Settings

Context Settings

Tool Settings

Privacy Settings

Advanced Settings

Environment Variables

Core Variables

Variable Naming Convention

CLI Arguments

Configuration API

Storage System

Approval Modes

File Filtering

Tool Restrictions

Core Tools (Allowlist)

Exclude Tools (Blocklist)

Validation

Context Files

Best Practices

User Settings

Project Settings

Environment Variables

CLI Arguments

Troubleshooting

View Effective Configuration

Configuration Validation Errors

Precedence Issues

Next Steps