Configure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modes

Install with the standalone script, npm (Node.js 22 or later) or Homebrew, then run qwen and follow the authentication prompt.

# Linux / macOS
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

# npm
npm install -g @qwen-code/qwen-code@latest

# Homebrew
brew install qwen-code

• User settings: ~/.qwen/settings.json, applied to all your sessions.
• Project settings: .qwen/settings.json in the project root, overriding user settings.
• System defaults file, for example /etc/qwen-code/system-defaults.json on Linux, which has the lowest file precedence.
• System settings file, for example /etc/qwen-code/settings.json on Linux, which overrides user and project settings.
• Environment variables and then command line arguments override all settings files.
• String values can reference environment variables with $VAR_NAME or ${VAR_NAME}.

Run /auth inside qwen to pick Alibaba ModelStudio, a third party provider or a custom provider. The Qwen OAuth free tier was discontinued on 2026-04-15. For scripted setup with any OpenAI-compatible endpoint, export the three OpenAI variables. QWEN_MODEL is an alias for OPENAI_MODEL.

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://YOUR_PROVIDER/v1"
export OPENAI_MODEL="YOUR_MODEL_ID"
qwen

For a persistent setup, define modelProviders in ~/.qwen/settings.json, set security.auth.selectedType so no interactive /auth is needed, and set model.name to one of the model ids. Keys are read from the variable named in envKey. Shell exports beat .env files, which beat the env block in settings.json, so prefer .qwen/.env or exports for secrets. Switch models later with /model.

{
  "modelProviders": {
    "openai": [
      {
        "id": "YOUR_MODEL_ID",
        "name": "My model",
        "baseUrl": "https://YOUR_PROVIDER/v1",
        "envKey": "OPENAI_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "YOUR_MODEL_ID"
  }
}

Context files default to QWEN.md. Qwen Code loads a global file from ~/.qwen/QWEN.md, then searches the current directory and each parent up to the project root (the folder with .git) or your home directory. All found files are concatenated into the system prompt, and the footer shows how many were loaded. You can import other Markdown files with @path/to/file.md and manage loaded context with the /memory command.

Set context.fileName to a string or an array of strings to use different file names.

{
  "context": {
    "fileName": ["AGENTS.md", "QWEN.md"]
  }
}

MCP servers live under mcpServers in settings.json. Use command for stdio, httpUrl for streamable HTTP or url for SSE. The qwen mcp add command writes to user scope by default; pass --scope project to write .qwen/settings.json instead. Use /mcp inside qwen to view servers, and restart qwen if it was already running.

# Remote HTTP server, user scope
qwen mcp add --transport http my-server http://localhost:3000/mcp

# Local stdio server, project scope, with an env var
qwen mcp add --scope project -e API_KEY=YOUR_VALUE pythonTools python -m my_mcp_server

# Remove
qwen mcp remove my-server

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": { "API_KEY": "$EXTERNAL_API_KEY" },
      "timeout": 15000
    },
    "remoteTools": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

tools.approvalMode sets the default approval mode, and auto is the default. Cycle modes in a session with Shift+Tab (Tab on Windows), or use /approval-mode. On the command line, use --approval-mode or --yolo. YOLO does not turn on a sandbox by itself.

• plan: read only analysis, no edits or shell commands.
• default (shown as Ask Permissions): manual approval for file edits and shell commands.
• auto-edit: file edits are auto approved, shell commands still need approval.
• auto: an LLM classifier approves safe actions and blocks risky ones.
• yolo: every tool call is auto approved; use only in trusted, controlled environments.

{
  "tools": {
    "approvalMode": "auto-edit"
  }
}