Qwen Code CLI: Architecture, Tool Definitions, and Technical Deep Dive

Quick Verdict

Qwen Code is a production-grade terminal agent that exposes a defined set of tools to the LLM through OpenAI-compatible function calling. The architecture is a ReAct loop: the model receives tool schemas on every turn, requests tool executions in its response, and receives structured results back. This is the same pattern as Claude Code and Gemini CLI, but Qwen Code is the only one of the three that lets you swap the backing model at runtime to any OpenAI-compatible endpoint.

The underlying Qwen3-Coder-480B model was trained with long-horizon reinforcement learning on 20,000 parallel environments, each running full GitHub issue resolution tasks. The RL training specifically targets multi-turn tool use, which is why the SWE-bench score (69.6%) is meaningfully higher than models trained only on code generation.

Agent Loop Architecture

Qwen Code is a TypeScript/Node.js application structured around a layered ReAct loop. Three core classes handle the lifecycle:

• GeminiClient — manages session lifecycle and API connections
• GeminiChat — owns conversation history and compression logic
• Turn — processes individual LLM response streams, extracts function_calls

The execution path per turn:

1. User input enters through InputPrompt with tab completion
2. AppContainer prepares React context and UI state
3. GeminiClient sends the conversation history plus all registered tool schemas (getFunctionDeclarations()) to the model API
4. The model responds with text, one or more function_calls, or both
5. Turn extracts function calls from the streaming response
6. ToolScheduler validates parameters with Zod schemas, checks approval mode, runs tools (potentially in parallel), and returns ToolResult objects
7. Results feed back into GeminiChat as tool response messages for the next turn

Tool results have two fields: llmContent (detailed output for the model, including exit codes and PIDs) and returnDisplay (formatted output for the terminal UI). This separation prevents the model's context from being polluted by display formatting.

Built-in Tool Registry

Every tool is a subclass of BaseDeclarativeTool, registered in ToolRegistry, and exported to the LLM via getFunctionDeclarations(). The LLM sees the same JSON Schema definitions you would see if you called /tools --verbose in a session.

Tool Schema Format

Tools are exposed to the model as standard OpenAI function definitions. The getFunctionDeclarations() method on ToolRegistry returns an array sorted alphabetically. Here is the schema for edit:

{
  "type": "function",
  "function": {
    "name": "edit",
    "description": "Replaces text in a file. Requires old_string to match exactly once in the file unless replace_all is set to true.",
    "parameters": {
      "type": "object",
      "properties": {
        "file_path": {
          "type": "string",
          "description": "Absolute path to the file to modify."
        },
        "old_string": {
          "type": "string",
          "description": "Exact text to find. Must be unique in the file."
        },
        "new_string": {
          "type": "string",
          "description": "Text to replace old_string with."
        },
        "replace_all": {
          "type": "boolean",
          "description": "If true, replace all occurrences. Default: false."
        }
      },
      "required": ["file_path", "old_string", "new_string"]
    }
  }
}

{
  "type": "function",
  "function": {
    "name": "run_shell_command",
    "description": "Execute a shell command in a persistent session. Commands that modify the filesystem require user approval in DEFAULT mode.",
    "parameters": {
      "type": "object",
      "properties": {
        "command": {
          "type": "string",
          "description": "Shell command to execute."
        },
        "is_background": {
          "type": "boolean",
          "description": "If true, run asynchronously. Default: false."
        },
        "timeout_ms": {
          "type": "number",
          "description": "Maximum execution time in milliseconds."
        }
      },
      "required": ["command"]
    }
  }
}

read_many_files (@ command)

The @path syntax is a shortcut that triggers read_many_files, a specialized batch read tool. It injects directory contents into the prompt with git-aware filtering: files matching .gitignore and .qwenignore patterns are excluded. This is how you efficiently pull an entire module into context without manually listing files.

File Edit Format

Qwen Code uses a search-and-replace format for file edits, not unified diffs. The model calls the edit tool with old_string and new_string. The tool validates that old_string appears exactly once in the target file, then replaces it.

The search-and-replace approach has a known failure mode: if the model specifies an old_string that matches zero or multiple locations, the edit fails. Qwen Code includes a multi-stage correction mechanism to handle this: if the initial match fails, the tool calls the model again with the file content and asks it to refine the old_string to be more specific. This loop runs up to a configured number of retries before giving up.

// Model output (function call in response stream)
{
  "name": "edit",
  "arguments": {
    "file_path": "/home/user/project/src/api.ts",
    "old_string": "  const timeout = 5000;",
    "new_string": "  const timeout = 30000;"
  }
}

// Tool result returned to model
{
  "llmContent": "Successfully replaced 1 occurrence in /home/user/project/src/api.ts",
  "returnDisplay": "✓ Edited src/api.ts (1 change)"
}

Context Management

QWEN.md Project Files

Project context loads from QWEN.md files in a hierarchy: global user (~/.qwen/QWEN.md), then project root, then subdirectories. Run /init inside a session to generate a starter QWEN.md from your current project structure. The context.fileName setting lets you override the filename.

Context Compression

When conversation history grows large, two mechanisms kick in:

• Manual: /compress summarizes the current chat history into a condensed form. Useful before starting a new sub-task that does not need full prior context.
• Automatic: model.chatCompression.contextPercentageThreshold triggers compression when history exceeds a set percentage of the model's context window. Default is typically 70-80%.

Context Window Limits

Qwen Code determines the effective context window from built-in defaults per model name. If your provider's actual limit differs (for example, you're using an older API version or a quantized local model), override it with contextWindowSize in generationConfig:

{
  "model": {
    "name": "qwen3-coder-plus",
    "generationConfig": {
      "contextWindowSize": 131072,
      "enableCacheControl": true,
      "samplingParams": {
        "temperature": 0.1,
        "top_p": 0.95,
        "max_tokens": 8192
      }
    }
  }
}

Token Caching

For API key authentication (not OAuth), Qwen Code activates prompt caching when the provider supports it. System instructions and stable QWEN.md context are cached, so repeated turns in the same session do not re-process the full system prompt. Set enableCacheControl: true in generationConfig to enable. DashScope and OpenRouter support cache pricing for Qwen models.

MCP Integration

MCP (Model Context Protocol) servers register additional tools into the ToolRegistry at startup. From the model's perspective, MCP tools are indistinguishable from built-in tools — they appear in the same getFunctionDeclarations() array.

Discovery Process

On startup, discoverMcpTools() iterates the mcpServers config, establishes transport connections, calls each server's tool listing endpoint, sanitizes schemas (removes $schema and additionalProperties for compatibility), and registers tools. Name conflicts use first-registration-wins with prefixing: if two servers both expose a tool named search, the second becomes serverName__search.

Transport Types

• Stdio: Spawns a subprocess, communicates via stdin/stdout. Best for local Python or Node.js servers.
• SSE: Connects to a Server-Sent Events endpoint. For persistent remote servers.
• Streamable HTTP: HTTP streaming. For cloud-hosted MCP services.

{
  "mcpServers": {
    "warpgrep": {
      "command": "npx",
      "args": ["-y", "@morphllm/warpgrep-mcp"],
      "env": {
        "WARPGREP_API_KEY": "$WARPGREP_API_KEY"
      },
      "timeout": 10000
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "trust": false
    },
    "remote-tools": {
      "httpUrl": "https://my-mcp-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer $REMOTE_MCP_TOKEN"
      },
      "timeout": 5000,
      "includeTools": ["search", "fetch"],
      "excludeTools": ["dangerous_tool"]
    },
    "google-drive": {
      "url": "https://mcp.googleapis.com/sse",
      "authProviderType": "google_credentials"
    }
  }
}

Tool Wrapping

Each discovered MCP tool is wrapped in a DiscoveredMCPTool instance. This wrapper handles:

• Confirmation dialogs (bypassed when trust: true on the server config)
• Per-tool include/exclude filtering via includeTools and excludeTools
• Execution routing: the tool JSON parameters are passed to the MCP server via stdin (Stdio) or POST (HTTP)
• Response normalization: MCP responses are mapped to the standard ToolResult format

OAuth for Remote MCP Servers

Remote SSE/HTTP servers that require authentication trigger a browser-based OAuth flow. The token is stored in ~/.qwen/mcp-oauth-tokens.json. Three provider types are supported: dynamic_discovery (server advertises its OAuth config), google_credentials (Application Default Credentials), and service_account_impersonation (Google Cloud service accounts).

Multi-Provider Configuration

Qwen Code is provider-agnostic. The modelProviders array in ~/.qwen/settings.json defines available models. Switch at runtime with /model. Each provider entry specifies a protocol, base URL, model ID, and environment variable for the API key.

{
  "modelProviders": [
    {
      "protocol": "openai",
      "id": "qwen3-coder-plus",
      "displayName": "Qwen3-Coder (DashScope)",
      "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "envKey": "QWEN_API_KEY"
    },
    {
      "protocol": "openai",
      "id": "qwen3-coder-480b-a35b-instruct",
      "displayName": "Qwen3-Coder-480B (OpenRouter)",
      "baseURL": "https://openrouter.ai/api/v1",
      "envKey": "OPENROUTER_API_KEY",
      "generationConfig": {
        "contextWindowSize": 262144
      }
    },
    {
      "protocol": "anthropic",
      "id": "claude-sonnet-4-5-20251022",
      "displayName": "Claude Sonnet 4.5",
      "envKey": "ANTHROPIC_API_KEY"
    },
    {
      "protocol": "openai",
      "id": "gpt-5.4",
      "displayName": "GPT-5.4 (OpenAI)",
      "envKey": "OPENAI_API_KEY"
    },
    {
      "protocol": "openai",
      "id": "qwen3-coder",
      "displayName": "Qwen3-Coder (Ollama local)",
      "baseURL": "http://localhost:11434/v1",
      "envKey": ""
    }
  ],
  "model": {
    "name": "qwen3-coder-plus"
  }
}

# DashScope (Alibaba Cloud — direct Qwen API)
export QWEN_API_KEY=sk-...

# OpenRouter (multi-model routing, same endpoint)
export OPENROUTER_API_KEY=sk-or-...

# Anthropic (for Claude models via Qwen Code)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI (for GPT-5.4)
export OPENAI_API_KEY=sk-...

# Tavily (web_search tool — required for web search)
export TAVILY_API_KEY=tvly-...

# Launch with a specific model
qwen --model qwen3-coder-480b-a35b-instruct

Switching providers mid-session with /model creates a new ContentGenerator instance for the selected provider but preserves conversation history. The model receives the full prior context on the first turn after switching.

Permission and Sandbox Model

Four Approval Modes

Every tool call routes through the approval system before execution. Four modes control the behavior:

Per-tool overrides are available through tools.allowed (whitelist specific tools that bypass confirmation regardless of mode) and tools.exclude (remove tools from the registry entirely).

Sandboxing

The --sandbox flag enables container isolation for run_shell_command. Three backends:

• Docker/Podman (Linux): Uses the qwen-code-sandbox image. Drop in a custom .qwen/sandbox.Dockerfile for project-specific toolchains.
• Seatbelt (macOS): sandbox-exec profiles restrict filesystem and network access. Configured via SEATBELT_PROFILE.
• No sandbox: Default. All shell commands run in the host environment with workspace boundary enforcement only.

Workspace Boundary Enforcement

Independent of approval mode, all file tools (read_file, write_file, edit) validate that paths are absolute and within the registered workspace directories. Commands cannot access files outside the project root. The /directory add slash command extends the workspace to additional directories.

{
  "tools": {
    "approvalMode": "auto-edit",
    "allowed": ["read_file", "grep_search", "glob", "list_directory"],
    "exclude": ["web_search"],
    "sandbox": false,
    "shell": {
      "enableInteractiveShell": true
    },
    "enableToolOutputTruncation": true,
    "truncateToolOutputThreshold": 50000,
    "truncateToolOutputLines": 500
  }
}

Setup and Installation

Requires Node.js 20+. Install takes under a minute.

# npm (recommended)
npm install -g @qwen-code/qwen-code@latest

# Homebrew (macOS/Linux)
brew install qwen-code

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

# Verify
qwen --version

# Launch — select "Qwen OAuth" on first run
qwen

# Headless mode (CI, scripts)
qwen -p "Add error handling to src/api.ts"

# Pipe mode
git diff HEAD~1 | qwen -p "Summarize these changes"
tail -f app.log | qwen -p "Alert me when you see an error"

# Launch in auto-edit mode (no confirmation for file edits)
qwen --approval-mode auto-edit

# Launch with sandboxing enabled
qwen --sandbox

# In your project root, generate QWEN.md
qwen
/init

# QWEN.md structure (customize for your project)
# ---
# Project: my-api
# Stack: TypeScript, Node.js 20, PostgreSQL
# Test command: bun test
# Lint command: bun run lint
# Build command: bun run build
# Key directories: src/api, src/db, tests/
# ---

Qwen Code vs Claude Code vs Gemini CLI

Model Support and Token Costs

Qwen Code works with any OpenAI-compatible provider. These are the models and costs most relevant to Qwen Code deployments as of March 2026:

Benchmarks

Qwen3-Coder-480B was trained with long-horizon RL on 20,000 parallel environments. The RL loop specifically targets SWE-bench-style tasks: given a GitHub issue and a repository, resolve the issue through multi-turn tool use. This training approach directly optimizes for the benchmark, which is why the score (69.6%) is meaningful rather than an artifact of overfitting.

The 11-point gap between Qwen3-Coder-480B (69.6%) and Claude Opus 4.6 (80.8%) on SWE-bench is not uniform across task types. Simple single-file bugs: gap is small. Complex multi-file refactors requiring deep dependency understanding: gap is large. For a free model, 69.6% is a high floor. For production critical paths where failing 1 in 10 tasks has real cost, Claude Code's accuracy advantage justifies the subscription.

What Developers Are Saying

Limitations

When to Use Qwen Code

Frequently Asked Questions

What file edit format does Qwen Code use?

Search-and-replace. The edit tool takes old_string (must match exactly once) and new_string. A multi-stage correction mechanism retries with fuzzy matching if the exact string is not found. For full file overwrites, write_file is used instead. Both tools show a diff before writing and require confirmation in DEFAULT mode.

What tools does the LLM actually see?

Thirteen built-in tools as OpenAI function definitions: read_file, write_file, edit, list_directory, glob, grep_search, run_shell_command, web_fetch, web_search, save_memory, todo_write, task, and skill. MCP servers add additional tools to the same registry. Run /tools --verbose to see the full JSON schemas for every registered tool.

How does Qwen Code manage context on large codebases?

Project context loads from hierarchical QWEN.md files. /compress summarizes history manually. chatCompression.contextPercentageThreshold triggers automatic compression. The @path syntax batch-reads files with git-aware filtering. For models with smaller effective context, override with contextWindowSize in generationConfig.

How does MCP integration work technically?

discoverMcpTools() runs at startup, connects to configured servers via Stdio/SSE/HTTP, fetches tool schemas, sanitizes them (removes $schema and additionalProperties), and registers tools in ToolRegistry. MCP tools are wrapped in DiscoveredMCPTool for confirmation logic. Tool name conflicts get server-prefix namespacing.

What approval modes exist and how do they differ?

PLAN: no modifications allowed. DEFAULT: approval required for all edit/write/exec tools. AUTO-EDIT: file edits auto-approved, shell commands need approval. YOLO: everything auto-approved. Set via --approval-mode flag or tools.approvalMode in settings.json. Individual tools can be permanently whitelisted with tools.allowed.

Can I run Qwen Code in CI without interactive auth?

Yes, but not with the free OAuth tier — OAuth requires a browser. Use a QWEN_API_KEY (DashScope) or any other provider API key. Set the key as a CI secret, configure it in settings.json or as an environment variable, and run with qwen -p "prompt" for headless execution.

How does Qwen3-Coder handle function calling differently from standard models?

Qwen3-Coder was specifically RL-trained on tool use tasks, which means it's more reliable than fine-tuned-only models at knowing when to call tools vs. when to respond directly. The model uses a Hermes-style tool calling format and was deployed with --tool-call-parser qwen3_coder on vLLM. It runs exclusively in non-thinking mode (no extended reasoning blocks), which keeps tool call latency low and outputs immediately deployable.

How does Qwen Code compare to Gemini CLI architecturally?

They share the same base architecture (Qwen Code is a fork of Gemini CLI). Divergences: Qwen Code adds enhanced parser support for Qwen models, broader provider backend support (Anthropic, Google, OpenAI all in one config), JetBrains integration, and Docker/Podman sandboxing. Gemini CLI adds native Google Search grounding, which Qwen Code replaces with the Tavily-powered web_search tool. The agent loop, tool dispatch, and MCP integration patterns are nearly identical.

Related

• Gemini CLI vs Claude Code — Full Comparison
• Claude Code vs GitHub Copilot
• Cline vs Cursor
• Best AI Coding Tools 2026
• Claude Code MCP Servers Guide

Sources

• Qwen Code GitHub Repository
• Qwen Code File System Tools Documentation
• MCP Servers with Qwen Code
• Qwen Code Configuration Reference
• Core Tools Reference (DeepWiki)
• Qwen3-Coder: Agentic Coding in the World (Qwen Blog)
• I Ditched Claude Code and Now Using Open Source Qwen AI (It's FOSS)
• Qwen Code is Good But Not Great (InfoWorld)
• Qwen Code Launch Discussion (Hacker News)
• Qwen3 Coder vs Kimi K2 vs Claude 4 Sonnet (Composio)