How to use Qwen Code: a step-by-step guide

To use Qwen Code, install the qwen CLI with the official script, npm or Homebrew, run qwen in a project folder, choose a model provider with /auth, and describe what you want. Qwen Code reads your code, edits files and runs commands, asking for approval according to the approval mode you pick. Since the free Qwen OAuth tier ended on April 15, 2026, you need an API key or plan from a provider, or a local model.

That’s the core loop. This guide covers the rest: the sign-in options and what replaced the free tier, OpenAI-compatible keys and local models, choosing a model, approval modes, QWEN.md, MCP servers, headless mode for scripts, and running Qwen Code next to other agents. Everything here follows the official Qwen Code repository and documentation as of October 2026.

What Qwen Code is

Qwen Code is a terminal coding agent from the Qwen team at Alibaba, released under the Apache-2.0 license. It started from Gemini CLI, so its layout will feel familiar if you’ve used Google’s agent, but it has been developed independently for a long time now. It is tuned for Qwen’s own coding models, yet it isn’t locked to them: it speaks the OpenAI, Anthropic and Gemini API formats and works with local models.

Besides the terminal, the project offers a desktop app, IDE integrations for VS Code, Zed and JetBrains, and SDKs for TypeScript, Python and Java. This guide sticks to the CLI.

Step 1: install Qwen Code

After the script install, restart your terminal so the qwen command is on your PATH. The npm package needs Node.js 22 or newer. To update later, run the same npm or Homebrew command again.

Step 2: sign in with /auth

Move into a project and start Qwen Code:

cd my-project
qwen

On first run, and any time later with /auth, Qwen Code shows four ways to connect a model:

Run /doctor inside a session to see which authentication is active. The old qwen auth shell command has been removed, so /auth is the place to change providers.

What happened to the free Qwen OAuth tier

For a long time the easy start was signing in with a qwen.ai account through Qwen OAuth and getting a free daily quota. The docs now say that the Qwen OAuth free tier was discontinued on April 15, 2026. It no longer appears in /auth, and new requests through it are rejected even if an old token is still cached. If you followed an older tutorial and the agent suddenly stopped answering, this is why. Pick one of the options above instead. Our roundup of the best free AI coding tools covers what still costs nothing in 2026.

Use any OpenAI-compatible API key

The quickest setup for scripts and servers is three environment variables:

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="your-model-id"
qwen

These are the variables of the OpenAI-compatible protocol, which covers most providers. The Anthropic and Gemini formats have their own (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL and GEMINI_API_KEY, GEMINI_MODEL).

Rather than exporting keys in every shell, you can keep them in a .env file. Qwen Code looks for .qwen/.env and .env in the project and its parent folders, then ~/.qwen/.env and ~/.env, and loads only the first one it finds. Command-line flags beat shell variables, shell variables beat .env, and .env beats the env block in settings.json.

For a permanent setup, define the provider in ~/.qwen/settings.json. The envKey names the variable that holds the key:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

The file also accepts an env block with the key itself, but that stores it in plain text. The docs suggest .qwen/.env for project secrets, kept out of Git.

Local models with Ollama

Ollama, vLLM and LM Studio all expose an OpenAI-compatible API, so a local model is just another openai provider with a local baseUrl. Ollama needs no real key, so any placeholder works:

{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": { "contextWindowSize": 32768 }
      }
    ]
  }
}

The id must match the model name in Ollama. A small local model will struggle with long agent sessions; our guide to a local LLM coding agent covers which models and how much memory make it workable.

Step 3: pick a model

Inside a session, /model opens a picker with the models your providers offer, and /model <model-id> switches straight away. From the shell, qwen --model qwen3-coder-plus (or -m) sets the model for one run. For thinking models, /effort sets the reasoning level where the provider supports it.

Which models you get depends on the provider. As of October 2026, the Alibaba Coding Plan lists Qwen models such as qwen3-coder-plus, qwen3-coder-next and qwen3.7-plus, plus third-party models such as GLM, Kimi and MiniMax. A pay-as-you-go key gives you whatever that provider’s API exposes.

Step 4: the basics of a session

The Qwen Code screen is a chat with your project. A few things you’ll use constantly:

• @path adds a file to your message, and @folder/ reads the text files in a folder.
• !command runs a shell command, for example !git status. A lone ! switches to shell mode until you type ! again.
• Shift+Tab (Tab on Windows) cycles through approval modes.

From the shell, qwen --continue reopens the latest session for the current project and qwen --resume <id> opens a specific one.

Step 5: approval modes

Qwen Code has five approval modes that decide what it may do without asking:

Out of the box, Qwen Code starts in Auto: a model-based classifier approves safe actions and blocks risky ones. Use /approval-mode plan or Shift+Tab to switch, or start with qwen --approval-mode plan. A good habit for anything non-trivial is to start in Plan, agree on an approach, then switch to Auto-Edit or Auto to carry it out. Keep YOLO for containers or throwaway machines, where a wrong command can’t do lasting damage.

Step 6: QWEN.md and project context

QWEN.md is the briefing Qwen Code loads at the start of every session: build and test commands, conventions, folders to stay out of. It can live in three places, and all of them are loaded:

Run /init and Qwen Code scans the project and writes a starter QWEN.md; if one exists, it suggests additions instead of overwriting it. If the repository already has an AGENTS.md for other tools, Qwen Code reads that too. Inside QWEN.md, @docs/git-workflow.md pulls in another file.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.
- Git workflow: @docs/git-workflow.md

Keep it short; the docs note that a longer file is followed less reliably. Qwen Code also keeps an auto-memory of its own in ~/.qwen/projects/<project>/memory/, plain Markdown you can edit or switch off in /memory. For rules that only matter for some files, .qwen/rules/ takes Markdown files with a paths: field. How to write CLAUDE.md and AGENTS.md covers what belongs in such a file, and it applies to QWEN.md as well.

Step 7: MCP servers

MCP servers give Qwen Code new tools such as a browser, an issue tracker or documentation search. The fastest way to add one is the qwen mcp command:

# a remote server over HTTP
qwen mcp add --transport http my-server http://localhost:3000/mcp

# a local server started as a process (stdio is the default transport)
qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING python -m my_mcp_server

# remove it again
qwen mcp remove my-server

Servers land in the mcpServers block of ~/.qwen/settings.json (the default user scope) or, with --scope project, in .qwen/settings.json. You can also edit that block by hand: command and args for a local process, httpUrl for an HTTP server. --include-tools and --exclude-tools limit which tools a server exposes. If Qwen Code was already running, restart it, then type /mcp to check that the server connected and see its tools.

Step 8: headless mode for scripts and CI

-p (or --prompt) runs a single task without the interactive UI, and stdin works too:

qwen -p "Summarize what changed in src/ since the last tag"
cat error.log | qwen -p "Explain this stack trace"
qwen -p "List the TODOs in this repo" --output-format json > todos.json

--output-format takes text, json or stream-json. qwen --continue -p "..." carries on the latest session, so a script can work in several steps. To let a headless run edit files, set an approval mode such as --approval-mode auto-edit, or --yolo on an isolated runner. The docs are explicit that --yolo does not turn on a sandbox: shell commands run with your user’s permissions. Budgets keep an unattended run from running away:

qwen -p "Fix the failing unit tests" --yolo \
  --max-session-turns 30 --max-wall-time 10m --output-format json

A run that exceeds --max-wall-time or --max-tool-calls exits with code 55, and one that exceeds --max-session-turns exits with 53, so CI can tell the cases apart. For real isolation, qwen -s runs tools in a sandbox (Seatbelt on macOS, Docker or Podman elsewhere).

Common pitfalls

• The agent stopped working after April 2026. You were on the discontinued Qwen OAuth free tier. Run /auth and pick another provider.
• “qwen auth” prints a removal notice. The command is gone; use /auth in a session and /doctor to check.
• A key in QWENCLOUD_API_KEY or DASHSCOPE_API_KEY is ignored. Provider-specific variables only work when a settings.json provider names them as envKey. Otherwise use OPENAI_API_KEY.
• A new MCP server doesn’t show up. It was added while Qwen Code was running. Restart it in the same project.
• Long sessions get slow and expensive. Use /compress or /clear, keep QWEN.md short and turn off MCP servers you don’t need.

Running Qwen Code next to other CLIs

Qwen Code has its own subagents and worktree support, but they stay inside Qwen Code. If you want Qwen Code on one task, Claude Code on another and Gemini CLI on a third, you are back to juggling terminal tabs. AgentVera is a desktop app that runs these CLIs side by side in real terminals, using your own installs and logins. Its Qwen Code support works like this:

• Your login. Qwen Code keeps its own sign-in, and the agent’s terminal asks on first launch. If qwen isn’t installed, AgentVera installs it with npm i -g @qwen-code/qwen-code.
• One session per agent. Each agent starts with its own session id (--session-id), and a saved session reopens with --resume.
• Role and model. The agent’s role is appended to Qwen Code’s system prompt with --append-system-prompt. Leave the Model field empty to use Qwen Code’s default, or pick a model and AgentVera passes it with --model.
• MCP on every launch. The servers in AgentVera’s MCP manager and AgentVera’s browser are passed with --mcp-config, so your own settings.json stays as it is.
• Panes, review and flows. Run Qwen Code next to Claude Code in the workspace grid, each agent in its own git worktree, with automatic code review when a turn ends. Qwen Code agents also work in broadcasts, scheduled tasks and flows (Pro and Team), where one agent’s answer goes to the next.
• More than one account. Under Settings → Accounts → Accounts of other agents you can add extra Qwen accounts, which run on API keys, and set a fallback order (Pro and Team).

To be fair about the trade-offs: if you only want a free hosted model, Qwen Code no longer offers one, and the free tools in the roundup linked above are a better start. If you want a provider-agnostic agent with a different workflow, opencode is the closest alternative. The grid, worktrees, code review and MCP manager are on AgentVera’s free plan. Download AgentVera to try it.

Wrapping up

To use Qwen Code, install it, run qwen in a project and pick a provider with /auth, now that the free Qwen OAuth tier is gone. Any OpenAI-compatible key works through OPENAI_* variables or settings.json, local models included. Start risky work in Plan mode, put your project rules in QWEN.md, add tools with qwen mcp add, and use qwen -p with budgets when a script or CI job needs the agent. After that, the main decision is which provider and model fit your budget, and Qwen Code lets you change both whenever you like.