Qwen Code: How to Install, Set Up, and Use the AI Coding Agent

Qwen Code is an open-source AI coding agent that works with your project files and development tools. It can help explain a codebase, propose changes, edit files, and run commands, depending on the model you connect and the permissions you allow. To start, install the CLI, configure a model provider, and give it a small task whose result you can review and test. The official Qwen Code repository is the starting point for downloads and documentation.

Documentation checked: October 5, 2026. The CLI release checked for this guide is Qwen Code v0.25.0. CLI, Desktop, extension, and SDK versions are separate components; a version number for one does not establish which version another is running.

What Qwen Code does—and how it differs from a coding model

Qwen Code provides the agent workflow around a model: it gathers relevant project context, sends requests, and handles tool actions. A model such as one from the Qwen3-Coder family supplies the language and coding capabilities. Installing the agent does not mean you have downloaded that model’s weights.

The distinction matters when comparing capabilities. Changing the connected model can change the quality of explanations, tool use, supported inputs, and cost without changing your Qwen Code installation. There is no single context-window size or hardware requirement that describes every possible configuration.

Useful starting tasks include explaining where a feature is implemented, investigating a failing test, making a limited refactor, and updating documentation to match an actual change. These fit the workflows in the official quickstart. Ask for file references and a way to verify the answer, rather than accepting a confident explanation as proof.

The terminal is not the only interface. The project also provides editor integrations and a Desktop application. This walkthrough uses the CLI so you can distinguish terminal commands, agent instructions, permission changes, and independent verification.

Is Qwen Code free?

The Qwen Code software is open source under the Apache 2.0 license, but using a connected model is not automatically free. Your costs depend on the service or local inference setup behind the agent.

Connection route	What you need to check
Standard hosted API	The selected model’s rates, account billing status, and usage limits.
Alibaba Cloud Coding Plan or Token Plan	The plan’s subscription or credit terms, supported models, dedicated credentials, and applicable limits.
Another model provider	That provider’s own pricing and restrictions. A free offer from one provider is not a universal Qwen Code allowance.
Self-hosted model	Hardware, electricity, or server costs, even when there is no external model API bill.

Alibaba Cloud documents the distinctions between pay-as-you-go access, Coding Plan, and Token Plan in its Qwen Code connection guide. Under Coding Plan, usage is metered by model calls: one user task can trigger several calls as the agent reads, edits, and checks its work. Review the current plan terms instead of treating one prompt as one billable unit.

Do not follow old free-OAuth onboarding instructions. The official authentication documentation states that the Qwen OAuth free tier was discontinued on April 15, 2026, and it is no longer a selectable entry in the authentication dialog. Use one of the currently supported connection methods.

Install Qwen Code on Windows, macOS, or Linux

Choose one installation method. The recommended installer uses a standalone archive when one is available for your platform. If it falls back to npm, Node.js 22 or newer and npm must be available on your system’s PATH.

The commands below download and execute an installation script. Review the script linked in the command before running it, particularly on a work computer. Follow your organization’s installation policy rather than bypassing restrictions or switching to administrator privileges as a first response to an error.

Windows: use PowerShell

Open PowerShell and run the Windows installer. This is a PowerShell command, not a Command Prompt command.

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

macOS or Linux: use the terminal

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

Alternative: install through npm

Use this route instead of the standalone installer when you already manage Node.js and global npm packages. The v0.25.0 package requirements specify Node.js 22 or newer. Check your environment first:

node --version
npm --version

Then install the package:

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

Verify the installation

Reopen your terminal if the new command is not available, then run:

qwen --version
qwen --help

A version number confirms that the terminal can find and launch the CLI. It does not confirm that your API credentials work, your account has usable quota, or the agent can complete a coding task.

Connecting this installation to a hosted provider does not require you to run the model on your own GPU. Running model inference locally is a separate setup, covered later.

Connect Qwen Code to a model provider

The current authentication menu groups connections under Alibaba ModelStudio, Third-party Providers, and Custom Provider. The last option is for configurations such as a local server or an unsupported provider. Choose the route matching credentials you actually have; similarly named keys and plans are not interchangeable.

Prepare a standard Model Studio API key

For a standard pay-as-you-go connection, follow Alibaba Cloud’s API key creation instructions. Open the API Key page, select your region, and choose Create API Key. Select the intended workspace and appropriate access permissions.

Save the key securely when it is shown. Where the creation dialog also provides an API Host, preserve that connection information too. Alibaba Cloud’s current documentation warns that the full key cannot be retrieved again after the creation dialog closes.

Your key, endpoint, and permitted models must belong to the appropriate region and workspace. The regional endpoint documentation distinguishes workspace-dedicated and DashScope endpoints; do not reuse an endpoint from an unrelated tutorial or another billing plan.

Configure the connection inside the CLI

From a directory where you keep practice projects, create a new, empty folder. Use another name if this folder already exists:

mkdir qwen-code-demo
cd qwen-code-demo
qwen --approval-mode plan

Starting explicitly in Plan mode avoids relying on a previously saved approval setting. Inside the Qwen Code session, enter:

/auth

1. Select Alibaba ModelStudio, then Standard API Key for the pay-as-you-go key prepared above.
2. Choose the matching region and enter the key in the authentication flow—not in an ordinary chat message.
3. After configuration, enter /model and select an available coding-capable model that your account is permitted to use.
4. Run /doctor to inspect the installation, authentication, and environment checks before starting a task.

The standard-key connection is documented in Alibaba Cloud’s Qwen Code setup guide; use the current CLI authentication documentation for the current top-level menu names. An existing Coding Plan or Token Plan subscription requires its corresponding option and credentials instead.

/auth, /model, and /doctor are commands entered inside Qwen Code. They are not operating-system commands. The standalone qwen auth command has been removed, according to the command reference.

Do not share credentials, unredacted settings files, or diagnostic output without inspecting them. A successful configuration check is also not a completed model task. Review your provider’s billing terms before sending prompts that request model responses.

Set permissions before asking it to change files

Do not assume Qwen Code always asks before editing or running a command. The v0.25.0 settings schema selects Auto as the default approval mode. Auto mode can approve actions through a classifier, so a cautious first task should use an explicitly selected mode.

For the walkthrough, use Plan while inspecting the problem, then switch to Ask Permissions before applying the fix. The latter retains the command value default, despite its user-facing name. The approval-mode documentation explains the distinction.

Inspect your existing rules with:

/permissions

Review broad allow rules before proceeding. The permissions reference gives explicit deny rules priority over ask rules, and ask rules priority over allow rules. Previously granted permissions can therefore affect what prompts you see.

Keep the first exercise in a disposable directory without credentials, customer data, or production configuration. If a folder-trust prompt appears, review the folder before trusting it; workspace trust affects which project settings and environment files load.

A prompt saying “do not edit files” expresses your intent, but it is not an operating-system security boundary. Approval settings and sandbox restrictions are separate controls. Likewise, enabling YOLO does not automatically enable a sandbox. Neither YOLO nor automatic approval is needed for this exercise.

Complete your first coding task with an independently checked test

This exercise fixes a small boundary bug. It demonstrates the full workflow: inspect the code, understand the failure, approve a limited change, review the actual diff, and rerun the tests yourself.

You need Node.js 22 or newer for this particular exercise, even if you installed Qwen Code through a standalone package. Git is used to record and compare the starting files. No third-party JavaScript dependencies are required.

1. Create the deliberately broken example

Exit the Qwen Code session with /quit. In the qwen-code-demo folder, use your editor to create a file named clamp.mjs:

export function clamp(value, min, max) {
  return Math.min(value, max);
}

The intended function keeps a number inside an inclusive range. For example, with a range from 0 to 10, it should return 0 for an input below 0 and 10 for an input above 10. For this exercise, inputs are finite numbers and min <= max; handling invalid inputs is outside the task.

Create a second file, clamp.test.mjs, containing:

import test from 'node:test';
import assert from 'node:assert/strict';
import { clamp } from './clamp.mjs';

test('keeps a value inside the range', () => {
  assert.equal(clamp(5, 0, 10), 5);
});

test('caps a value above the maximum', () => {
  assert.equal(clamp(12, 0, 10), 10);
});

test('raises a value below the minimum', () => {
  assert.equal(clamp(-3, 0, 10), 0);
});

Run the tests from your normal terminal, not from the agent’s chat input. The command uses Node.js’s built-in test runner:

node --test clamp.test.mjs

The first two tests should pass and the third should fail: the function returns -3 where the test expects 0. That failure is intentional. It is the defect you will ask the agent to investigate, not an installation or authentication error.

2. Record the starting files in Git

In this new practice directory, record the two files before the agent changes anything:

git init
git add clamp.mjs clamp.test.mjs
git -c user.name="Qwen Code Demo" -c user.email="[email protected]" commit -m "Add clamp test fixture"
git status --short

The example identity is supplied for this demonstration commit, not as a global Git configuration change. Review any additional files shown by the status command; do not replace the explicit file list with a blanket command that stages everything.

For real projects, preserve existing work before introducing an agent. Creating a branch alone does not back up untracked files, credentials, or files outside the repository.

3. Ask Qwen Code to explain the failure first

Start the CLI again from the same directory:

qwen --approval-mode plan

Then send this task instruction:

Read @clamp.mjs and @clamp.test.mjs.

Explain why the lower-bound test fails.
Assume all inputs are finite numbers and min is less than or equal to max.

Do not edit files, run commands, install packages, or use web tools.
Propose the smallest fix that preserves the exported function signature
and every existing test assertion.

Do not claim that you ran the tests.

The @ references supply specific files as context; they do not establish an access-control boundary. A correct explanation should identify that the existing implementation enforces the upper limit but ignores the lower limit. Ask for clarification if the response discusses unrelated changes or fails to explain that specific defect.

4. Approve a narrow implementation change

After reviewing the proposed fix, change the session to Ask Permissions:

/approval-mode default

Submit a separate implementation instruction:

Apply the approved fix to clamp.mjs only.

Keep clamp.test.mjs unchanged.
Do not add dependencies, change configuration, or create other source files.
Do not commit or push anything.

Run node --test clamp.test.mjs only after I approve the command.
Report the actual test result, or clearly state that the tests were not run.

Read the proposed edit before allowing it. If the agent requests an unrelated installation, a broad shell command, or changes to the test assertions, decline that action and restate the scope.

5. Verify the diff and run the tests yourself

Exit with /quit, then inspect the repository and execute the test command in your own terminal:

git status --short
git diff HEAD -- clamp.mjs clamp.test.mjs
node --test clamp.test.mjs

The comparison against HEAD lets you review changes to the recorded files, including changes that may have been staged. Check the status output as well, since the selected-file diff is not a complete inventory of new files.

A minimal reference implementation is:

export function clamp(value, min, max) {
  return Math.min(max, Math.max(min, value));
}

Accept the result only after confirming that the function handles both bounds, the test assertions remain unchanged, and all three tests pass. Those tests verify the supplied cases; they are not evidence that every possible input or production integration has been covered.

Example validation: This fixture was executed locally using Node.js v22.16.0. The original implementation produced two passing tests and one failure; the reference implementation passed all three. These are local fixture results, not a claimed Qwen Code session. No paid model request, agent-generated patch, response time, or token-cost measurement is presented as tested here.

Use a small set of commands for everyday work

After authentication and your first task, these session commands help manage longer work without memorizing the entire command reference.

Command	Practical use
/help	Check the commands available in your installed version.
/context	Inspect how the session’s context window is being used.
/compress	Replace conversation history with a summary. Keep essential requirements somewhere durable rather than assuming every detail survives compression.
/clear	Start a fresh conversation context. This is not a command for undoing file changes.
/resume	Return to a previous conversation. Check the current working files before continuing an old task.

Keep your requests bounded: name the relevant files, describe the required behavior, state what must remain unchanged, and give an acceptance test. “Fix everything” provides neither a useful scope nor a clear stopping condition.

Keep recurring project instructions in QWEN.md

A project-root QWEN.md file supplies instructions that Qwen Code loads for later sessions. The memory documentation recommends concise, specific information such as test commands and project conventions—not a duplicate of the entire codebase.

For the practice project, a short file could contain:

Use Node.js's built-in test runner.
Run tests with: node --test clamp.test.mjs
Do not add dependencies without approval.
Do not change test assertions merely to make a failure disappear.
Report which checks were actually executed.

Create this after completing the first exercise, so it does not become an unexplained extra file in that task’s diff. Keep secrets out of instruction files, and remember that written instructions do not replace permission controls.

Once single-agent tasks are repeatable, the next step may be delegation rather than a larger prompt. Our Qwen Code subagents guide covers that separate workflow. It is not required for the installation or first task above.

Use Qwen Code in VS Code

The official Qwen Code Companion extension, published under qwenlm, provides a chat interface and native diff review in VS Code. Its documentation lists VS Code 1.96.0 or newer, and the extension is marked as a preview/beta.

Install it through the official Marketplace entry, open your practice project, and use the Command Palette to run Qwen Code: Open. Open the palette with Ctrl+Shift+P on Windows or Linux, or Cmd+Shift+P on macOS.

The extension bundles its runtime, so its basic installation does not require a separate global CLI installation. Provider access and possible model charges still need to be configured. Review changes in the editor’s diff view rather than enabling automatic acceptance for an unfamiliar task.

When diagnosing a problem, check the extension as well as the terminal installation. Updating a global qwen executable does not establish that the extension’s bundled runtime was updated.

Can Qwen Code run with local models?

Yes. The model-provider documentation describes connections to local inference servers such as Ollama, vLLM, and LM Studio through compatible API endpoints. The agent and the inference server remain separate components.

A local setup needs a running server, an explicitly selected model, and the correct API base URL. For example, the documentation shows http://localhost:11434/v1 for a local Ollama connection. Use the actual model identifier served by your installation rather than copying an old model name from a configuration example.

Test agent behavior as well as ordinary text generation. A model producing a chat response does not demonstrate that your setup can reliably complete a file-reading, editing, and verification workflow. Memory requirements and speed also depend on the model, quantization, context, and runtime; there is no useful single hardware figure for every local configuration.

For the model-installation side, follow our separate guide to running and verifying Qwen with Ollama. Confirm the model deployment first, then connect it to the coding agent.

Local software does not automatically mean private or offline inference

Running the CLI on your computer does not prevent a configured cloud provider from receiving task context. The Qwen Code privacy notice distinguishes the policies of the underlying model providers, including their data-use and retention terms.

Before using private code, check the actual provider and endpoint, your organization’s rules, and any external tools you have enabled. Treat credentials and saved conversations as sensitive. Do not assume an ignore file, a local interface, or a localhost address by itself proves that every part of a workflow stays on your machine.

Troubleshoot the failing layer before reinstalling

Start with the last step that definitely worked. A CLI that does not launch, a rejected API key, and an agent that refuses to edit a file are different problems.

Symptom	First checks
qwen is not found	Reopen the terminal and check the installation method and PATH. For npm installations, confirm Node.js and npm are available in that same shell.
Authentication fails	Check the selected provider, key validity, region, and billing-plan type. Use /auth when the interactive session is available.
The model is unavailable	Check the exact model ID, endpoint, regional availability, and the key’s model permissions.
A quota or rate-limit error appears	Read the provider’s error and usage dashboard. Distinguish an exhausted allowance from a temporary request-rate restriction before retrying.
The agent will not edit files	Inspect the current approval mode, permission rules, and workspace trust. Plan mode is not the mode for applying the implementation change.

For a certificate error on a managed network, use your organization’s approved certificate setup rather than disabling TLS verification. Qwen’s official troubleshooting guide covers certificate configuration and other startup issues.

Update through the same route you used to install: rerun the standalone installer for a standalone installation, or the npm installation command for a global npm installation. Reopen the CLI and check the version afterward. Do not install another copy merely to avoid identifying which executable currently runs.

Preserve your project and settings before changing configuration. For deeper startup, provider, and editor problems, use the dedicated Qwen Code troubleshooting guide rather than deleting the entire .qwen directory as a first step.

Decide whether Qwen Code fits your workflow

Evaluate it on a task you can judge independently: one failing test, one limited refactor, or one documentation correction. Check how much explanation, correction, and diff review you need—not just whether the agent eventually reports success.

When comparing it with another coding assistant, keep the repository and acceptance criteria constant, and record the provider, model, permissions, and actual charges used by each setup. Our Qwen Code vs Claude Code comparison addresses the broader product decision separately.

A useful first success is a small change you understand, with an unchanged test that now passes. Build from that point before adding larger tasks, additional tools, or more autonomous permissions.