> ## 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.

# 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:

```bash theme={null}
# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```typescript theme={null}
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

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

### Model Settings

```typescript theme={null}
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

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

### Tool Settings

```typescript theme={null}
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

```typescript theme={null}
interface PrivacySettings {
  telemetry?: {
    enabled?: boolean;
    endpoint?: string;
  };
  crashReporting?: boolean;
}
```

### Advanced Settings

```typescript theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:**

```bash theme={null}
# 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:

```typescript theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "tools": {
    "exclude": [
      "run_shell_command(rm)",
      "run_shell_command(sudo)",
      "write_file"
    ]
  }
}
```

## Validation

Configuration is validated on load:

```typescript theme={null}
// 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "vimMode": true,
  "theme": "dark",
  "editor": { "preferredEditor": "code" },
  "telemetry": { "enabled": false }
}
```

### Project Settings

Use for project-specific configuration:

```json theme={null}
{
  "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:

```bash theme={null}
# In CI/CD
export OPENAI_API_KEY="$SECRET_KEY"
export QWEN_TELEMETRY="false"
export QWEN_SANDBOX="docker"
```

### CLI Arguments

Use for one-off overrides:

```bash theme={null}
# Quick test with different model
qwen-code --model qwen-turbo --temperature 0.5

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

## Troubleshooting

### View Effective Configuration

```bash theme={null}
# 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.mdx) - Testing with different configurations
* [Tools System](./tools-system.mdx) - Configuring tool access
* [Subagents System](./subagents-system.mdx) - Agent configurations