Configuration System

Understanding Qwen Code’s hierarchical configuration system

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:

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

Precedence Issues

If settings aren’t taking effect:

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

Next Steps

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