Qwen Code: install, providers, QWEN.md, skills and approval modes

What is Qwen Code?

Qwen Code is an open source AI coding agent from the Qwen team that runs in your terminal, reads and edits your project, runs commands and connects to MCP servers. It is built around Qwen models but works with OpenAI, Anthropic, Gemini and other compatible providers too.

The Qwen Code repository calls it "the open-source AI coding agent for your terminal, editor, desktop, browser, and chat." It is licensed under Apache 2.0. The README credits its origin plainly: the project "was originally based on Google Gemini CLI v0.8.2," and from v0.1 it stopped syncing with upstream and developed independently.

Beyond the terminal, the README lists a desktop app for macOS, Windows and Linux, an experimental web UI, editor integrations for VS Code, Zed and JetBrains, chat channels such as Telegram, DingTalk, WeChat and Feishu, and SDKs for TypeScript, Python and Java.

This guide follows the Qwen Code docs as read on 26 October 2026. The latest stable release on GitHub was v0.26.1, published 24 October 2026.

How do you install Qwen Code?

The quickstart recommends the standalone installer. On Linux and macOS:

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

On Windows PowerShell:

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

Restart your terminal afterwards so the PATH change takes effect. If you prefer a package manager, npm install -g @qwen-code/qwen-code@latest works with Node.js 22 or later, and brew install qwen-code works on macOS and Linux.

Then open your project and start it:

cd /path/to/your-project
qwen

How do you connect a model now that the free tier is gone?

This is the part most older tutorials get wrong. Qwen Code used to offer a free tier through Qwen OAuth sign-in. The authentication page now says: "The Qwen OAuth free tier was discontinued on 2026-04-15." Qwen OAuth is no longer an option in the setup menu.

Run /auth (aliases /connect and /login) and pick one of four options:

For CI or scripts, skip the menu and set environment variables such as QWENCLOUD_API_KEY, OPENAI_BASE_URL and OPENAI_MODEL, or add a modelProviders block to ~/.qwen/settings.json. Local models through Ollama or vLLM go through the Custom Provider route. Inside a session, /model switches models.

How do Qwen Code approval modes work?

Qwen Code has five approval modes. Press Shift+Tab (Tab on Windows) to cycle through them, or use /approval-mode:

The docs say headless runs default to Ask Permissions. They are less consistent about which mode an interactive session starts in, so check the terminal status bar, which always shows your current mode. In Auto mode, in the docs' words, "an LLM classifier auto-approves safe actions and blocks risky ones." If you want to see every change first, switch to Ask Permissions, which was previously named Default. For planning, /plan refactor the auth module enters read-only Plan mode and starts a plan, and /plan exit returns to your previous mode. The docs advise using YOLO "sparingly," only for trusted automation.

How do you give Qwen Code project instructions?

Qwen Code's main instruction file is QWEN.md. The memory docs describe three locations, all loaded at the start of a session:

• ~/.qwen/QWEN.md for your personal instructions across projects
• QWEN.md in the project root for the team, committed to git
• .qwen/QWEN.local.md for personal notes on one project, which you must add to .gitignore yourself

Run /init to have Qwen Code analyze the repo and draft a starter QWEN.md. You can reference other files inside it with @, such as @README.md.

If you already maintain an AGENTS.md, you do not need to duplicate it. The docs say: "If your repository already has an AGENTS.md file for other AI tools, Qwen reads that too." The context.fileName setting changes which file names are treated as context files.

For guidance that only matters for some files, Qwen Code also supports rules in .qwen/rules/. A rule with a paths: list of globs in its frontmatter stays out of the prompt until the agent reads or edits a matching file, which keeps always-on context small.

Does Qwen Code support Agent Skills?

Yes. The skills page describes skills as folders with a SKILL.md file that "the model can load when relevant, plus optional supporting files like scripts and templates." The model decides when to use a skill from its description, and you can also run one yourself by typing /<skill-name>.

Qwen Code reads skills from four folders:

If both folders contain a skill with the same name, the .qwen one wins. The /skills command opens a panel to browse, search, toggle and launch skills. There is also /learn, which turns a URL, a local folder, a short description or a tutorial video into a draft project skill under .qwen/skills/. Review what it writes before you rely on it.

Because the format follows the Agent Skills standard, skills in .agents/skills/ work in Qwen Code and in Codex without copies.

How do you add MCP servers and subagents?

MCP servers live under mcpServers in settings.json, and the MCP page shows a CLI shortcut that writes the same entry:

qwen mcp add --transport http my-server http://localhost:3000/mcp
qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

Inside a session, /mcp lists configured servers and their tools.

Subagents are separate agents with their own instructions that Qwen Code can delegate to. Project subagents live in .qwen/agents/ and take precedence over user ones in ~/.qwen/agents/. Run /agents create for a guided wizard or /agents manage to edit existing ones.

Which Qwen Code commands do you use every day?

The commands reference is long. These cover most sessions:

• /init creates a starter context file for the current directory.
• /compress replaces the chat history with a summary to save tokens.
• /resume reopens a previous session.
• /model switches the model for this session.
• /memory opens the Memory Manager.
• /review runs a multi-agent code review, optionally on a pull request number.
• /plan and /approval-mode change how much the agent may do.

For scripts and CI, run Qwen Code headless with qwen -p "your prompt".

How does Qwen Code compare with Claude Code and Codex?

Claude Code's memory docs say it reads AGENTS.md when there is no CLAUDE.md, and Codex's AGENTS.md docs say "Codex reads AGENTS.md files before doing any work." One AGENTS.md can therefore guide all three.

Pick Qwen Code if you want an open source agent that is free to switch between providers, including Qwen's own plans and local models. Pick Claude Code or Codex if you are committed to one vendor's models. If you used Gemini CLI, Qwen Code will feel familiar, and the Gemini CLI guide covers where the two have since diverged. OpenCode is another open source, multi-provider terminal agent.

Where do you keep the prompts and skills you use with Qwen Code?

Skills in .agents/skills/ and an AGENTS.md travel well between Qwen Code and other agents, so it helps to keep them in one place. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks and Cmd+K search, and can import skills from a GitHub link, a folder or a .zip.