Qwen Code: How to Install and Use the Open-Source Terminal Coding Agent

A step-by-step guide to installing Qwen Code, connecting a model (including a local one), and using Plan Mode and approvals safely, taken from the project’s own docs.

Reviewed by Mindloop Editorial on . Every link in the Sources section at the end was re-checked that day.

Graphic of a code card showing a terminal command to install Qwen Code, the open-source terminal coding agent.

Qwen Code began as a project built on Google’s Gemini CLI, and today it has more than 30,000 GitHub stars of its own. The README says the project was originally based on Gemini CLI v0.8.2, then stopped syncing with upstream from v0.1 and grew into an independent, multi-protocol coding agent.

Key takeaways

  • Qwen Code is an open-source, Apache-2.0 coding agent for the terminal that began as a Gemini CLI fork.
  • Install it with the standalone script, npm with Node.js 22 or newer, or Homebrew, then run /auth to connect a model.
  • No sign-in option is described as free, so use a local Ollama, vLLM or LM Studio server for zero cost.
  • Start new codebases in read-only Plan Mode, review with /diff and roll back with /restore.

This guide shows how to install Qwen Code, sign in (or point it at a free local model), and use it safely on a real project. Everything below comes from the project’s own README and docs on GitHub, checked on 15 November 2026. None of the commands were run for this article, so try them in a throwaway folder first.

What you need

  • A terminal on macOS, Linux or Windows
  • Node.js 22 or newer, if you choose the npm route
  • A code project to point it at (a spare repo is ideal)
  • A way to pay for or host a model: a Qwen subscription, an API key, or a local model server
Stack of the five Qwen Code sign-in options, from Qwen Account to a custom local model provider

What Qwen Code is

It is an open-source coding agent that runs in your terminal, reads your repo, edits files and runs commands. GitHub lists Apache-2.0 as the license, and the README says it works with OpenAI, Anthropic, Gemini and Qwen APIs, plus any third-party provider or local model such as Ollama or vLLM. As of 15 November 2026 the latest release tag is v0.27.4.

The project also reports its own benchmark: on SWE-bench Verified, seven Qwen Code versions averaged between 76.40% and 77.80% with the same Qwen 3.7 Max model. That is the maintainers’ evaluation, not an independent test.

By the numbers

30,000GitHub stars, more than

77.80%top self-reported SWE-bench avg

v0.27.4latest release tag

Step by step

1. Install it

The README gives three routes. The first is a one-line installer on Linux and macOS:

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

Piping a script into your shell is a trust decision. The installer is hosted on an Alibaba Cloud storage address, so if you prefer, use npm or Homebrew instead:

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

Or, on macOS and Linux with Homebrew:

Terminal
brew install qwen-code

Windows users get a PowerShell installer in the README. After a standalone install, restart your terminal so the environment variables take effect.

2. Start it inside a project

Terminal
cd ~/projects/my-app
qwen

You should see an interactive terminal session. The README also mentions a “1.0 Preview” branch, but the instructions here are for the main version.

3. Sign in or connect a model

Type /auth. The docs list five top-level choices:

  1. Qwen Account with Subscription: browser sign-in with a Plus or Pro subscription.
  2. QwenCloud: a Token Plan or a pay-as-you-go Standard API Key.
  3. Alibaba ModelStudio: Coding Plan, Token Plan or Standard API Key.
  4. Third-party Providers: a built-in list including DeepSeek, Kimi, OpenRouter and others, using an API key.
  5. Custom Provider: a local server, proxy or unsupported provider.

None of those options is described as free in the current docs. To keep costs at zero, use a local model. The docs show that Ollama, vLLM and LM Studio work through an OpenAI-compatible address. Our guide to running an AI model with Ollama covers the server side. Then save a config at ~/.qwen/settings.json, adapted from the docs’ own example:

Code
{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "your-model-name",
        "name": "My local model",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "your-model-name" }
}

Replace your-model-name with the exact model name your server reports. The docs say model.name must match one of the id values. After saving, run qwen.

4. Ask your first question

The README suggests starting with a safe, read-only prompt:

Code
Explain this repository and show me where to start.

Then run /init, which the docs describe as analyzing the current directory and creating an initial context file. Qwen Code loads your QWEN.md and AGENTS.md briefings automatically. If you already use skill files, our guide to agent skills in Claude Code explains the idea, and Qwen Code lists its own /skills panel in the docs.

5. Choose how much freedom it gets

Qwen Code has five permission modes: Plan, Ask Permissions, Auto-Edit, Auto and YOLO. Press Shift+Tab (Tab on Windows) to cycle through them. The docs call Auto, where a classifier approves safe actions and blocks risky ones, the default out of the box, but the same page also names Ask Permissions as the initial mode, so check the status bar. For a new codebase, start in Plan Mode:

Code
/plan refactor the settings page

Plan Mode is read-only, so nothing is edited or executed. Type /plan exit to restore your previous mode. Save YOLO for trusted projects, as the docs advise.

6. Review and undo

Use /diff to open an interactive viewer of uncommitted changes. If a step went wrong, /restore lists checkpoints and reverts project files to the state before a tool call ran.

7. Use it in scripts

The README says headless mode runs from scripts and CI:

Terminal
qwen -p "Summarize the repository layout."
Flow diagram of installing Qwen Code, connecting a model, planning in read-only mode and reviewing changes

Common errors and fixes

  • qwen: command not found. Restart your terminal after installing, as the README instructs. For npm, confirm Node.js is version 22 or newer.
  • Browser sign-in will not work. In CI or unattended containers, the auth docs say to use an API-key method instead, with environment variables.
  • qwen auth does nothing useful. That command has been removed. Run qwen, then /auth. Run /doctor to check your current authentication.
  • Local model times out. Confirm the baseUrl ends in /v1 and the server is running. For slow servers the docs describe a streamIdleTimeoutMs setting.
  • Unsure the daemon is safe. If you use qwen serve or qwen daemon start, note that the README says it listens on loopback without bearer authentication by default, so any local process that can reach it can use the full API, including code execution. On shared hosts, set QWEN_SERVER_TOKEN and use --require-auth.

Did you know?

By default the qwen serve daemon listens on loopback without bearer authentication, so any local process that can reach it can use the full API, including code execution. Set QWEN_SERVER_TOKEN and use –require-auth on shared hosts.

Is it worth trying?

If you like the Claude Code or Gemini CLI workflow and want something you can point at your own model, Qwen Code is a short install away. Start in Plan Mode, keep a Git commit handy, and treat the benchmark figures as the maintainers’ own until you have tried it.

Frequently asked questions

Is Qwen Code free to use?

The tool itself is open source under Apache-2.0, but none of the /auth sign-in options is described as free in the current docs. To keep costs at zero, connect it to a local model through Ollama, vLLM or LM Studio.

How do I install Qwen Code?

The README gives three routes: a one-line standalone installer on Linux and macOS, npm install -g @qwen-code/qwen-code@latest with Node.js 22 or newer, or brew install qwen-code. Windows users get a PowerShell installer. Restart your terminal afterward.

Can Qwen Code use a local model with Ollama?

Yes. Save a ~/.qwen/settings.json that points an OpenAI-compatible provider at http://localhost:11434/v1, and make sure model.name matches one of the provider id values. Then run qwen.

What is Plan Mode in Qwen Code?

Plan Mode is one of five permission modes and is read-only, so nothing is edited or executed. Start it with /plan followed by your task, and type /plan exit to return to your previous mode.

Quick quiz

Which project was Qwen Code originally based on?

  • Claude Code
  • Gemini CLI
  • Ollama

The README says it was originally based on Gemini CLI v0.8.2.

Which mode is read-only?

  • Plan
  • YOLO
  • Auto-Edit

The docs say Plan Mode edits and executes nothing.

Which command reverts project files to a checkpoint?

  • /diff
  • /init
  • /restore

/restore lists checkpoints and reverts files to the state before a tool call ran.

Sources

Links last checked on 15 November 2026.

Written by Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on AI and technology, software and the business of tech, for anyone who likes to know how things actually work.

Meet the editorial team

Responses

Write a response

More from Mindloop Experience

See all from Mindloop Experience

You can clap up to 50 times.