Qwen Code is an open-source AI coding agent, not a language model. It can inspect a repository, propose and apply file changes, run development commands, and help review the resulting diff through a terminal-first workflow. The recommended current setup is the official standalone installer, followed by launching qwen and using /auth to connect Alibaba ModelStudio, a supported third-party provider, or a custom or local endpoint. The Qwen Code software is licensed under Apache-2.0, but the model provider you connect may charge for a plan or usage.
Last verified: October 7, 2026. Qwen Code is changing quickly, especially around installation, authentication, providers, and approval modes. Check the linked official documentation before using commands in production or purchasing a plan.
What Qwen Code is—and what it is not
The official Qwen Code repository describes it as an AI coding agent for the terminal, with additional editor, desktop, web, and automation interfaces. The agent is the software layer that reads context, calls tools, requests model output, and manages a coding workflow. The underlying model is a separate component selected through a provider.
| Term | What it means | Practical consequence |
|---|---|---|
| Qwen Code | The coding-agent application and framework. | You install and run it locally, then connect it to a model provider. |
| Qwen coding model | A model used for code understanding or generation, such as a provider-listed Qwen Coder model. | A model ID, availability, context limit, and price depend on the provider and plan. |
| Model provider | The service—or local server—that performs inference. | It determines credentials, endpoints, billing, model access, and data-handling terms. |
| Qwen Chat | The consumer chat product. | A chat account or subscription should not be assumed to include Qwen Code model usage. |
Qwen Code supports multiple API protocols and can connect to official Alibaba routes, built-in third-party providers, custom compatible endpoints, and self-hosted model servers. That flexibility does not make every model interchangeable: tool use, reasoning behavior, image input, context length, latency, and reliability vary by model and provider.
Is Qwen Code free?
The Qwen Code program is open source under the Apache-2.0 license, so there is no software license fee to download and run the CLI. Model inference is a separate cost decision. Depending on the route you choose, you may pay for an individual subscription, usage-based access, a third-party API, or the hardware and operations needed for a local model.
- Qwen Code software: open-source application code under Apache-2.0.
- Alibaba ModelStudio access: may use a Coding Plan, Token Plan, or standard API key, each with its own current terms.
- Third-party provider: priced and governed by that provider.
- Local model: avoids a hosted inference bill but still requires suitable hardware, storage, electricity, setup, monitoring, and maintenance.
The former Qwen OAuth free tier was discontinued on April 15, 2026 and is no longer a selectable authentication option. Any tutorial that still recommends signing in through that free OAuth route is outdated. Use the current authentication guide to choose an active provider and verify its live pricing or quota before relying on it.
Qwen Code installation requirements
You need a terminal, a code project for the first workflow, and credentials for a hosted provider unless you are connecting a local endpoint. The recommended standalone installer handles the CLI installation directly. Node.js 22 or later is required for the documented npm installation route, not as a universal prerequisite for every installation method.
Recommended installation on Linux or macOS
Run the current official installer in a Bash-compatible terminal:
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bashRecommended installation on Windows
Open PowerShell and run:
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iexThese commands download and execute an official remote installation script. In a security-controlled environment, review the script first or use the release-archive installation method documented by the project rather than piping a download directly into a shell. Restart the terminal after installation so PATH changes take effect.
Alternative npm and Homebrew methods
Use npm when Node.js is already managed on the machine and you specifically want the npm-distributed package:
npm install -g @qwen-code/qwen-code@latestThe current manual-installation documentation requires Node.js 22 or later for this route. Do not solve a global npm permissions error by running the entire installation as root or Administrator by default; use a supported Node version manager, a user-writable npm prefix, Homebrew, or the standalone installer.
On macOS or Linux, Homebrew is another documented option:
brew install qwen-codeTo confirm the CLI is available, open a new terminal in a project and run qwen. A successful installation opens the interactive interface. Once inside, run /doctor to inspect the installation, environment, and current authentication state.
Choose the right authentication route
Start Qwen Code with the shell command qwen, then run the slash command /auth inside the active session. The older standalone command qwen auth has been removed.
| Route | Best fit | What to verify |
|---|---|---|
| ModelStudio Coding Plan | Individual developers who prefer a subscription-style coding plan. | Region, current quota, supported models, renewal terms, and the dedicated Coding Plan key and endpoint. |
| ModelStudio Token Plan | Teams and companies using a usage-based plan with a dedicated endpoint. | Subscription region, endpoint, key type, configured model list, and billing terms. |
| Standard ModelStudio API key | Users with an existing ModelStudio API account. | Key region, endpoint, model availability, and pay-as-you-go terms. |
| Built-in third-party provider | Developers already using a supported external model service. | The provider’s key, model ID, endpoint, price, limits, and privacy policy. |
| Custom provider | A proxy, unsupported hosted provider, or local model server. | Compatible protocol, base URL, authentication, tool-calling support, context limits, and server availability. |
After authentication, use /model to choose among the models configured for that provider. Do not copy a model ID from another provider or a model-hosting page and assume it will work unchanged. The current model list should come from the selected provider’s interface or documentation.
Credential rule: a correct key can still fail when paired with the wrong plan, region, endpoint, protocol, or model. Treat those settings as one configuration, not as independent values.
Store API keys safely
For project-local credentials, the current documentation recommends a .qwen/.env file over placing secrets directly in settings.json. Add the file to .gitignore, restrict access to it, and use the variable name required by the chosen provider.
# .gitignore
.qwen/.envNever put an API key in QWEN.md, AGENTS.md, a committed project settings file, a screenshot, terminal transcript, public issue, or browser-side application. The env field in settings.json stores values in plain text, so use it only after understanding the exposure risk.
A safe first Qwen Code workflow
The goal of a first session should not be “let the agent change everything.” Use a small, reviewable task and a repeatable sequence:
Explore → Plan → Review → Edit → Test → Inspect the diff
1. Start from a clean Git state
These are normal shell commands, run before starting Qwen Code:
cd /path/to/your/project
git status --short
git switch -c qwen-code-first-task
qwenIf the project already has uncommitted work, commit it or stash it before allowing an agent to edit files. A separate branch makes the first task easier to inspect and discard.
2. Select controlled approval and planning modes
The next lines are Qwen Code slash commands, entered inside the active session:
/approval-mode default
/plan/approval-mode default explicitly selects Ask Permissions, the mode in which file edits and shell commands require manual approval. The configuration value retains the older word default for compatibility. Running the command explicitly is safer than assuming which mode a previous session or local configuration has selected.
/plan enters a read-only planning mode. It is useful when the project is unfamiliar because the agent can inspect and reason about the repository without editing files or executing shell commands.
3. Ask for repository understanding before a change
Enter a natural-language prompt such as:
Explain this repository's purpose, main entry points, test command,
and the files most relevant to input validation. Do not change files.Then request a constrained plan:
Plan a small change that rejects an empty display name.
Identify the exact files, tests, risks, and acceptance criteria.
Do not implement it yet.Check whether the proposed files and test commands match the repository. Correct wrong assumptions before leaving Plan mode.
4. Implement only the approved task
Exit Plan mode with /plan exit, which restores the previous approval mode, then use a specific prompt:
Implement the approved empty-display-name validation and its focused tests.
Do not add dependencies, change public APIs, or modify unrelated files.
Ask before running any command.Read every proposed edit and command before approving it. Pay particular attention to package installation, network access, file deletion, database migration, credential files, and commands that request elevated privileges.
5. Test and inspect the result
Approve only the relevant test command. After the agent finishes, use the Qwen Code diff viewer:
/diffThen leave or suspend the session and independently inspect the repository with normal shell commands:
git status --short
git diff --check
git diffPassing tests are not proof that a change is correct. Review the implementation, the tests themselves, error handling, unexpected files, dependency changes, and any security-sensitive behavior before committing or merging.
Essential Qwen Code commands
Slash commands work inside a running Qwen Code session. They are not ordinary commands to paste into PowerShell, Command Prompt, or Bash.
| Command | Use |
|---|---|
/auth | Choose or change the authentication method and provider. |
/doctor | Check installation, environment, and authentication status. |
/model | Choose among models configured for the current providers. |
/plan | Enter or leave read-only planning mode. |
/approval-mode default | Select Ask Permissions so edits and shell commands require approval. |
/init | Analyze the repository and create or propose additions to a starter QWEN.md. |
/diff | Inspect current uncommitted changes and, when available, per-turn changes. |
/compress | Replace older conversation history with a summary to reduce context use. |
/help | Show the current command list and help. |
/quit | Exit the interactive session. |
Qwen Code also uses @ for file context and ! for shell execution. Treat ! commands with the same care as commands typed directly into your terminal: they run with the permissions available to the process.
Give Qwen Code useful project context
A concise context file reduces repeated explanations and helps the agent follow the repository’s real commands and constraints. Qwen Code currently supports several scopes:
| File | Scope | Version-control guidance |
|---|---|---|
~/.qwen/QWEN.md | Your instructions across projects. | Keep it in your home configuration, not in a project repository. |
QWEN.md at the project root | Shared project instructions. | Commit it when the rules are useful to the whole team. |
.qwen/QWEN.local.md | Your personal instructions for one project. | Keep it out of Git. |
AGENTS.md | Existing cross-agent project guidance. | Qwen Code reads it, so instructions do not need to be duplicated automatically. |
Run /init to generate a starter QWEN.md. If the file already exists, the current documentation says Qwen Code proposes additions rather than simply overwriting it. Review the generated content before committing it.
A focused project file might look like this:
# Project workflow
- Install dependencies with: pnpm install
- Run unit tests with: pnpm test
- Run linting with: pnpm lint
- Run type checks with: pnpm typecheck
# Engineering constraints
- Do not edit generated files under dist/ or coverage/.
- Ask before adding or upgrading a dependency.
- Preserve the public API unless the task explicitly requires a change.
- Add or update focused tests for behavior changes.
- Never read, print, or modify secret files.Do not place credentials, customer data, private tokens, production hostnames, or database passwords in context or memory files.
Exclude irrelevant or sensitive paths
A .qwenignore file can reduce noisy or inappropriate file discovery:
node_modules/
dist/
coverage/
*.log
.env*
*.pem
*.keyThis is a context-control mechanism, not a security boundary. It applies only to Qwen Code tools that honor the ignore rules; it does not replace .gitignore, filesystem permissions, secret scanning, access control, or a sandbox. Restart Qwen Code after changing ignore rules if the current documentation requires the new patterns to be reloaded.
Approval modes and sandboxing
Qwen Code can edit files and execute shell commands, so its approval mode materially changes risk. Confirm the active mode rather than relying on an old tutorial or a remembered default.
| Mode | File edits | Shell commands | Suitable use |
|---|---|---|---|
| Plan | Read-only | Not executed | Repository exploration, code review, and planning. |
| Ask Permissions | Manual approval | Manual approval | New repositories, sensitive work, learning, and controlled first sessions. |
| Auto-Edit | Automatically approved | Manual approval | Trusted routine edits where command execution still needs review. |
| Auto | Evaluated automatically | Evaluated by a classifier and guardrails | Longer work in a trusted environment when fewer interruptions are acceptable. |
| YOLO | Automatically approved | Automatically approved | Only tightly controlled automation with disposable or strongly isolated resources. |
Do not use YOLO mode on an unfamiliar repository, a production server, a machine containing valuable credentials, or infrastructure and database work. In that mode, AI-requested commands can run with your terminal permissions.
For additional isolation, review the official Qwen Code sandbox documentation. Sandboxing can limit filesystem, process, or network access depending on the platform and backend, but it does not eliminate prompt injection, unsafe package scripts, compromised dependencies, logic errors, or misuse of credentials already exposed inside the sandbox.
The Trusted Folders feature can also restrict project-specific capabilities until a workspace is trusted. Review a repository—including its instruction files, scripts, hooks, skills, and MCP configuration—before granting broader access.
Privacy and data flow
Installing an open-source client does not mean all coding activity remains on the device. Qwen Code must send the context required for inference to the configured model provider unless the selected model endpoint is local. Depending on the task, that context can include prompts, code excerpts, file contents, tool output, and conversation history.
- Qwen Code application: manages the local session, tools, configuration, and context selection.
- Model provider: receives the material sent for inference and applies its own retention, training, security, and compliance terms.
- MCP servers and integrations: may receive files, tool arguments, database queries, or external-service data according to the permissions you grant.
- Optional usage statistics: the official privacy notice says Qwen Code may collect anonymous command, performance, error, crash, and feature-usage data when enabled; that setting does not control data collected by the model provider.
The current Qwen Code privacy notice states that Qwen Code itself does not use prompts, code, or responses for model training. It also states that training-related use by the inference service depends on the provider and authentication route. Review the exact provider policy for the plan you select instead of applying a consumer-chat policy to an API or enterprise account.
A local model can reduce disclosure to a remote inference provider, but “local” does not automatically mean fully offline or private. Web tools, package managers, MCP servers, telemetry, IDE extensions, browser features, and other integrations may still communicate over the network.
Using Qwen Code beyond the terminal
The terminal is the most direct starting point, but the current project also documents desktop, editor, web, headless, SDK, and daemon interfaces.
- VS Code: the official Qwen Code extension is currently labeled Beta and requires VS Code 1.96.0 or later. It adds a sidebar, attachments, conversation history, and multiple sessions.
- Desktop: the official repository links a desktop application for macOS, Windows, and Linux.
- Web UI:
qwen serve --openstarts the documented web interface, which is currently marked experimental. - Headless use:
qwen -p "..."supports scripts, batch work, and CI/CD, but non-interactive permissions and credentials require deliberate configuration. - Local or custom provider: Qwen Code can connect through supported compatible protocols to a proxy or model server such as an Ollama- or vLLM-based deployment, provided the endpoint and selected model support the required workflow.
Do not move to autonomous, headless, multi-agent, MCP, or browser-control features until the basic repository, approval, model, and privacy settings are understood. More tools expand both capability and the number of systems that can be affected by a bad instruction.
Common Qwen Code problems and fixes
| Symptom | Likely cause | Safe check and fix |
|---|---|---|
qwen is not recognized or found | The terminal has not loaded the updated PATH, or the chosen installation failed. | Restart the terminal first. Confirm the installer completed, then inspect the PATH or reinstall using one current official method rather than combining several methods. |
| npm installation fails because of the Node version | The npm route requires Node.js 22 or later. | Check the installed Node version, switch with a supported version manager, or use the standalone installer. |
| Qwen OAuth discontinued message | The configuration still points to the retired free OAuth route. | Start qwen, run /auth, and select ModelStudio, a third-party provider, or a custom provider. |
| Authentication fails with a valid-looking key | Wrong provider, key type, plan, region, or endpoint. | Run /doctor. Reopen /auth and rebuild the configuration from one provider’s current documentation. |
| Model not found or unavailable | The model ID is not offered by that provider, plan, region, or protocol. | Use /model and select an offered model. Do not reuse an identifier copied from a different provider. |
| Corporate TLS or certificate error | The network uses a custom root certificate, or a self-hosted endpoint has a self-signed certificate. | Prefer adding the trusted certificate through NODE_EXTRA_CA_CERTS. Do not disable TLS verification as a routine fix. |
| Local provider cannot connect | The server is stopped, the base URL is wrong, authentication differs, or the endpoint does not implement the expected protocol. | Test the server locally, verify its exact API path and protocol, and confirm the model supports tool calling needed by the task. |
| Project instructions appear to be ignored | The file is in the wrong scope, the workspace is restricted, or the session started before the file changed. | Check the documented QWEN.md locations, folder-trust state, and ignore rules, then restart the session if required. |
| VS Code extension does not install | The editor is older than the documented minimum or cannot install extensions. | Confirm VS Code 1.96.0 or later and install from the official Marketplace link in the Qwen Code documentation. |
When asking for support, include the operating system, shell, installation method, Qwen Code version if available, provider type, approval mode, and the exact redacted error. Never publish API keys, full environment dumps, private source code, or a /doctor memory --snapshot file without reviewing it; the official command documentation warns that a heap snapshot can contain prompts, file contents, keys, and tool results.
Frequently asked questions
Is Qwen Code a model?
No. Qwen Code is a coding-agent application and framework. It connects to a selected model through Alibaba ModelStudio, another hosted provider, a proxy, or a compatible local server.
Does Qwen Code require an API key?
A hosted model route normally requires provider credentials, such as a plan key or API key. A custom local endpoint may have different authentication requirements. The former free Qwen OAuth route was discontinued on April 15, 2026.
Can Qwen Code use non-Qwen or local models?
Yes. The current project supports multiple API protocols, built-in third-party providers, and custom endpoints, including local model servers. Actual coding-agent quality depends on the model’s instruction following, context, tool use, output format, and the compatibility of the server.
Does Qwen Code work on Windows?
Yes. The official quickstart provides a PowerShell installer for Windows. The project also offers a desktop route and a Beta VS Code extension, but each interface should be installed from an official project link.
What is the difference between QWEN.md and AGENTS.md?
QWEN.md is Qwen Code’s project-instruction file, with global, shared-project, and personal-local scopes. If a repository already contains AGENTS.md, Qwen Code currently reads it as well, so duplicate instructions are unnecessary.
Is source code sent to the cloud?
When a hosted model is used, Qwen Code sends the context needed for inference to that provider. What is retained or used afterward depends on the provider and plan. A local endpoint changes the inference data path but does not automatically disable every networked tool, integration, or telemetry setting.
Sources checked
The following primary sources were checked on October 7, 2026:
- Official QwenLM/qwen-code repository and Apache-2.0 license.
- Official Qwen Code overview and quickstart.
- Authentication and model-provider setup.
- Command reference, approval modes, and sandboxing.
- QWEN.md, AGENTS.md, and memory documentation.
- Ignoring files and trusted-folder guidance.
- Terms, privacy, and telemetry notice.
- Official VS Code integration guide and troubleshooting guide.