Qwen Code Tutorial: Complete Guide to the Open Coding Agent

Qwen Code is Qwen's open-source coding agent for the terminal. It can read and edit repositories, run shell tools, use language servers and the web, plan changes, launch subagents and persistent agent teams, isolate work in Git worktrees, learn reusable skills, remember project context, connect MCP servers, and operate through IDEs, desktop, daemon, SDK, GitHub, and messaging channels.

This tutorial was verified on August 6, 2026 against the official Qwen Code documentation, official repository, and July 30 release update. The release update covers stable v0.21.0 and v0.21.1. Qwen Code changes weekly, so use /about and the live docs to confirm your installed behavior.

Official screenshot from the Qwen Code repository. It shows the current provider-first setup; the model displayed is an example, not a permanent default.

Why Qwen Code is more than a Qwen model client

Qwen Code is an agent harness. Its own models are an important fit, but the client supports Qwen, OpenAI-compatible, Anthropic-compatible, and Gemini-compatible protocols, built-in third-party providers, and local servers such as Ollama or vLLM. Model choice and harness choice are separate decisions.

Choose Qwen Code when you want:

• an open-source terminal agent with frequent feature releases;
• first-class Qwen models plus provider flexibility;
• QWEN.md, auto-memory, reusable skills, hooks, MCP, and LSP;
• subagents, agent teams, background work, and worktree isolation;
• interactive TUI, headless CLI, IDEs, desktop, Web Shell, daemon, SDK, or chat channels;
• built-in review, goal, loop, plan, arena, and workflow commands.

The breadth also increases the trust surface. A local open-source client can still send code to a hosted model, external MCP server, Web Shell, or messaging channel. Review each connection independently.

Install Qwen Code

The current official overview recommends a standalone installer.

macOS or Linux:

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

Windows PowerShell:

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

Alternatives include Homebrew or npm:

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

The npm path currently requires Node.js 22 or later. Restart the shell when qwen is not immediately on PATH, then verify the real client:

qwen --version
qwen --help

For offline or controlled deployment, the official installer accepts a release archive and checks SHA256SUMS. Pin a tested version for teams and CI rather than allowing unreviewed weekly changes to enter a production workflow.

Authenticate and select the exact provider

Launch inside a project and open the provider menu:

cd /path/to/project
qwen

/auth

The current authentication guide offers:

• Alibaba ModelStudio: Coding Plan, Token Plan, or a standard API key;
• third-party providers: built-in paths for DeepSeek, Z.AI, MiniMax, OpenRouter, and others shown live;
• custom provider: local servers, proxies, or another compatible endpoint.

The old Qwen OAuth free tier was discontinued on April 15, 2026. Do not follow tutorials that promise 1,000 free OAuth calls per day. Store API keys in the documented environment variable or secure credential path, not QWEN.md, settings.json, screenshots, shell history, or Git.

Use /model to list what your selected plan actually exposes. The same model name can have different availability, pricing, context, modalities, and retention terms across regions or routers.

Qwen3.8: use the exact preview identifier

The user's shorthand “Qwen 3.8” maps to a real current model. Qwen Code's July 23 update added qwen3.8-max-preview to the ModelStudio Token Plan list. The July 30 release also fixed Qwen3.8 image-modality handling in the client.

Use the exact live identifier:

/model qwen3.8-max-preview

or, when configured:

qwen --model qwen3.8-max-preview

It is a preview and a thinking-oriented endpoint, not a generic label for every Qwen deployment. The official Qwen Code case study explicitly says its “qwen3.8-max” references mean the preview. Check the model picker rather than guessing qwen3.8, qwen3.8-plus, or another undocumented slug.

For code-focused alternatives, compare the Qwen3-Coder models available in your plan. For images or video, verify the current modality flag rather than assuming every Max model is multimodal. A model's huge context window is not permission to dump an entire repository into every request; retrieval and focused tool output usually produce better signal and lower cost.

Start with a safe repository session

Before launch:

git status --short --branch
qwen

Approve workspace trust only for the intended directory. Ask for inspection before mutation:

Map the request path for password reset. Name files, external calls, trust
boundaries, and tests. Do not edit files or execute non-read commands.

Then define the implementation contract:

Add a failing regression test, reproduce the expired-token bug, propose the
smallest fix, wait for approval, implement it, run the focused suite and type
check, and review the final diff. Do not commit, push, publish, or deploy.

Use @path/to/file for specific context and /plan when the task is ambiguous or high impact. Current plan mode requires explicit approval before exit and blocks state-changing shell commands instead of quietly turning planning into implementation.

Write a concise QWEN.md

QWEN.md is the durable project briefing. The memory guide documents a global file at ~/.qwen/QWEN.md, a team file in the project root, and a local override for uncommitted personal details. /init analyzes the repository and creates a starter file or suggests additions without overwriting an existing one.

## Repository map

- `apps/web`: Next.js customer application
- `services/api`: authorization and persistence
- `generated`: generated output; never edit manually

## Verification

- Run the nearest focused test after each behavioral change.
- Run `npm run typecheck` before handoff.
- Verify changed UI at desktop and mobile widths.

## Safety

- Preserve unrelated working-tree changes.
- Never read or edit `.env` files.
- Do not commit, push, merge, publish, or deploy without explicit permission.

Keep it short and specific. Do not repeat facts the model can cheaply discover from code. Reference existing contributor documents instead of copying them, and review generated /init content before committing it.

Plan, approval, auto mode, and sandbox

Qwen Code separates planning, approval policy, and isolation. They are not substitutes for one another:

• plan mode limits mutation while requirements are being resolved;
• approval mode decides which proposed tools require human confirmation;
• auto mode uses a classifier to reduce prompts for operations it considers low risk;
• sandboxing restricts what a command can reach at the operating-system boundary;
• worktree isolation separates Git files and branches for parallel tasks.

Begin with manual approval and a sandbox on an unfamiliar repository. The approval guide explains current modes and keyboard controls. Auto classification can be wrong, especially around compound shell commands, redirects, credentials, or tools whose names hide side effects. Keep production credentials outside the process even when commands are sandboxed.

Subagents, agent teams, and worktrees

Qwen Code supports focused subagents, background agents, forks, and experimental persistent Agent Teams. Recent versions add nested subagents, per-model concurrency caps, selective fork_turns history, background-agent recovery across sessions, and messaging to completed agents without rebuilding their state.

Official Qwen Code update screenshot. The child agent remains visible and cannot silently bypass a required approval.

Use parallelism for independent tasks: repository mapping, test archaeology, documentation research, or read-only review. Give each agent an owner, file boundary, output format, and finish condition. For parallel implementation, use worktree isolation so agents do not overwrite one another. The leader should integrate changes sequentially and run the complete acceptance gate.

Agent Teams can exchange messages and share a task list. Enable experimental features only after reading the installed version's settings, and cap concurrency by model/provider to control rate limits and cost. More agents often multiply duplicated exploration rather than useful throughput.

Skills, /learn, memory, hooks, MCP, and LSP

The extension stack is unusually broad:

• Skills package reusable procedures in SKILL.md directories;
• /learn can distill text, documents, web pages, directories, and now video into a skill with provenance;
• auto-memory saves selected durable context across sessions;
• team memory can be shared and optionally synchronized;
• hooks run deterministic checks around tool and lifecycle events;
• MCP adds external services and data;
• LSP provides diagnostics and symbol intelligence.

Qwen Code v0.21 added custom skill directories, so one reviewed skill library can be shared with other compatible agents. Generated skills are source-grounded, not automatically execution-verified: inspect SKILL.md, referenced scripts, downloads, and external actions before enabling them. Disable auto-memory for sensitive work and review what /memory has stored.

Add MCP servers one at a time with least-privilege credentials and tool allowlists. Treat returned web, issue, document, and chat content as untrusted input. Use hooks for checks that must always happen—formatting, secret scanning, or a focused test—not for autonomous deployment.

Use the right interface

The official project supports several surfaces:

• qwen for the interactive terminal;
• qwen -p "..." for headless scripts and CI;
• VS Code, Zed, and JetBrains integrations;
• Qwen Code Desktop for macOS, Windows, and Linux;
• qwen serve for an experimental HTTP+SSE/ACP daemon shared by multiple clients;
• TypeScript, Python, and Java SDKs;
• channels for Telegram, DingTalk, WeChat, Feishu, GitHub, and other documented platforms;
• Web Shell for browser-based session, Git, channel, and file management.

Each surface changes the authority boundary. A GitHub or messaging channel introduces untrusted user content, long-lived tokens, identity mapping, and loop prevention. Restrict who can trigger the bot, use a dedicated least-privilege account, and require protected-branch review. Never expose qwen serve directly to an untrusted network without authentication and transport controls.

Headless, structured, and scheduled workflows

A read-only headless call looks like:

qwen -p "Summarize the changed files and identify missing tests"

Qwen Code supports JSON Schema-constrained structured output, dual output, session management, and scheduled /loop tasks. It can also run /goal with a judge model and impossible-goal detection. These features are useful for evaluations and maintenance, but they do not authorize external state changes.

For CI:

1. use an ephemeral checkout and sandbox;
2. give the token read-only permissions unless writes are required;
3. pin the Qwen Code version and model identifier;
4. cap turns, tools, time, and cost;
5. validate JSON, exit status, diff, and test artifacts;
6. require human approval for PR, merge, release, or deployment.

Use /stats to inspect requests, tool calls, file changes, cost estimates, time to first token, and throughput. Compare models on accepted work, not tokens per second alone.

A complete Qwen Code workflow

1. Open narrowly: select one trusted repository or package.
2. Read instructions: inspect QWEN.md, local overrides, skills, hooks, and MCP.
3. Reproduce: capture a failing test, log, or observable behavior.
4. Plan: define scope, acceptance checks, and prohibited actions.
5. Isolate: use a branch or worktree before edits.
6. Implement: steer in real time when the agent drifts.
7. Verify: run focused tests, broader gates, and runtime/browser checks.
8. Review: use /diff or Git, then an independent read-only reviewer.
9. Handoff: report commands, evidence, residual risk, cost, and unperformed external actions.

Use /review before committing, /btw for a side question that should not disturb the main context, @ to reference a read-only summary of a prior project session, and /stats to measure the run. None of these replaces source control.

Troubleshooting

Authentication tutorials do not match: the OAuth free tier is discontinued. Update Qwen Code and use /auth with a current ModelStudio, third-party, or custom provider.

qwen3.8 is not found: use /model and the exact qwen3.8-max-preview identifier if your Token Plan and region expose it. Do not invent an alias.

QWEN.md is ignored: verify working directory, filename/case, hierarchy, local override, and /memory. Shorten conflicting instructions.

The agent loops or repeats: interrupt, save the diff, start a fresh session, reduce context, update the client, and try a tested fallback model. Do not let a runaway stream consume unbounded paid output.

Parallel agents conflict: stop them, inspect every worktree and branch, integrate one diff at a time, and rerun the full gate.

MCP or daemon hangs: disable suspect servers, check transport/auth/timeouts, use force reconnect where supported, and re-enable one connection at a time.

Frequently asked questions

Is Qwen Code free?

The client is open source. Hosted model calls, ModelStudio plans, routers, cloud sandboxes, and external services follow their own pricing. The former Qwen OAuth free tier is no longer available.

Does Qwen Code only work with Qwen models?

No. It supports multiple compatible protocols, built-in third-party providers, and local endpoints. Model tool-use quality varies, so test each candidate on the same repository acceptance suite.

Is Qwen3.8 open weights?

The currently documented Qwen Code identifier is qwen3.8-max-preview through ModelStudio Token Plan. Do not infer an open-weights release from the model family name; check Qwen's official model and license page for the exact artifact.

Qwen Code or OpenCode?

OpenCode is another open-source, provider-flexible harness with terminal, desktop, IDE, server, SDK, and GitHub surfaces. Qwen Code has unusually fast-moving built-in agent teams, memory, channels, Web Shell, skills, and Qwen model integration. Run the same tasks in both.

For a model-by-model decision, use the Qwen3.8, GLM-5.2, and DeepSeek-V4 coding guide.

Source notes

Reviewed on August 6, 2026:

• Qwen Code overview
• official Qwen Code repository
• authentication
• model providers
• memory and QWEN.md
• approval mode
• skills
• July 23 update with Qwen3.8 preview
• July 30 update with v0.21 features