Qwen CLI: How to Install and Use Qwen Code (2026)

TL;DR

• Qwen CLI (officially Qwen Code) is Alibaba's open-source terminal coding agent — a fork of Gemini CLI tuned for Qwen models. Install it with npm install -g @qwen-code/qwen-code@latest on Node.js 22+.
• The big change most guides miss: the free Qwen OAuth tier was discontinued on 2026-04-15. The old "2,000 free requests a day" no longer works — you now need an API provider.
• Set it up by pointing it at any OpenAI-compatible endpoint with three env vars: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL. That's the whole config.
• One endpoint can run Qwen *and* other models. Point OPENAI_BASE_URL at [Velokey](https://api.velokey.ai) and you can drive Qwen Code with qwen3.7-max, GPT, Claude, or GLM on a single key.

What is Qwen CLI (Qwen Code)?

Qwen CLI is the common name for Qwen Code, an open-source AI coding agent that runs in your terminal, built by the Qwen team at Alibaba. It reads and edits your codebase, runs commands, and works agentically on tasks — the same shape as Claude Code or Gemini CLI. In fact it started as a fork of Gemini CLI, adapted with prompts and parsers tuned for Qwen's models.

Two things are worth knowing before you install. First, the package is named @qwen-code/qwen-code, so "qwen cli," "qwen-cli," and "qwen code cli" all point at the same tool. Second — and this trips people up — it is not locked to Qwen's servers. It speaks the OpenAI-compatible protocol, so you can run it against Qwen's API, OpenRouter, a local model, or a gateway. Which matters more than ever now, because the free path changed.

How do I install Qwen Code CLI?

Install Qwen Code globally with npm, on Node.js 22 or newer:

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

If you're on macOS, Homebrew works too (brew install qwen-code), and there are standalone installers for Linux and Windows. Here's what actually matters at install time:

If qwen: command not found shows up after install, your global npm bin directory isn't on your PATH — run npm config get prefix, and add its /bin to PATH. On Linux, a permissions error during the global install usually means you need sudo or, better, an nvm-managed Node so global installs don't touch system directories.

How do I set up Qwen CLI now the free tier is gone?

You configure Qwen Code with an OpenAI-compatible API key, because the free Qwen OAuth tier was [discontinued on 2026-04-15](https://github.com/QwenLM/qwen-code/issues/3203) — cached tokens may linger for a bit, but new sign-ins are rejected. That free tier used to give 2,000 requests a day and 60 per minute; a lot of "use Qwen Code for free" tutorials still describe it, and they're now wrong.

The current setup is three environment variables. Set them, run qwen, and pick "OpenAI" in the auth menu:

export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"
qwen

Prefer a config file? Qwen Code reads ~/.qwen/settings.json (or a project-local .qwen/settings.json), where you define a model provider once:

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [{
        "id": "qwen3-coder-plus",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }]
    }
  },
  "security": { "auth": { "selectedType": "openai" } }
}

Your provider options today are Alibaba Cloud's ModelStudio Coding Plan (a fixed monthly subscription), the DashScope pay-per-token API, OpenRouter, Fireworks, or any other OpenAI-compatible endpoint. The official auth docs list the current set — check them rather than an old blog, since this is exactly the part that went stale.

How do I run Qwen CLI with any model through one endpoint?

Point OPENAI_BASE_URL at a gateway and one key runs Qwen Code against many models — no per-provider account juggling. Since Qwen Code only needs an OpenAI-compatible endpoint, Velokey works as a drop-in: one key reaches Qwen, GPT, Claude, and GLM through the same base URL.

export OPENAI_API_KEY="sk-your-velokey-key"
export OPENAI_BASE_URL="https://api.velokey.ai/v1"
export OPENAI_MODEL="qwen3.7-max"
qwen

The practical win is switching backends without re-authing. Qwen Code is tuned for Qwen models, so [qwen3.7-max](/model/qwen3.7-max) is the natural default — but if a task wants a different model, change one variable:

Because billing is per token through credits, there's no separate subscription and no daily-request wall — you pay for what the agent actually uses. For how that math works out, see our Claude API pricing guide; the same per-token model applies to Qwen and the rest.

Why is Qwen CLI not working? Common errors

Most Qwen CLI failures are environment or auth issues, not bugs — and they cluster into a handful of causes. Start qwen --safe-mode to disable your customizations; if the problem vanishes, re-enable settings one at a time to find the culprit.

If your key is stored in a browser-based tool rather than an env var, a missing session can throw a separate class of error — see our guide on fixing "API key not found in cookies". For a full end-to-end walkthrough of wiring an API key into a client, how to call a model with an API key covers the setup pattern.

Frequently Asked Questions

How do I install Qwen CLI?

Run npm install -g @qwen-code/qwen-code@latest on Node.js 22 or newer, then qwen --version to confirm. On macOS you can also use brew install qwen-code. If you hit command not found, add your global npm bin directory (npm config get prefix + /bin) to your PATH.

Is Qwen CLI free to use?

Not anymore through the built-in path — the free Qwen OAuth tier was discontinued on 2026-04-15. The CLI itself is open-source and free, but you now need an API provider: Alibaba's ModelStudio Coding Plan, DashScope pay-per-token, OpenRouter, or any OpenAI-compatible endpoint configured with your own key.

How do I use Qwen CLI with my own API key?

Set three environment variables — OPENAI_API_KEY, OPENAI_BASE_URL, and OPENAI_MODEL — then run qwen and select "OpenAI" in the auth menu. You can also define a provider in ~/.qwen/settings.json. The base URL points at whichever OpenAI-compatible provider you're using.

What models does Qwen Code CLI support?

Qwen Code is tuned for Qwen models like Qwen3-Coder, but because it speaks the OpenAI-compatible protocol, it runs against OpenAI, Anthropic, Gemini, OpenRouter, local models via Ollama or vLLM, and gateways. Set OPENAI_MODEL to the model ID your provider exposes.

Why does Qwen CLI say "command not found"?

Your global npm bin directory isn't on your PATH. Run npm config get prefix to find the install prefix, then add its /bin subfolder to your PATH and restart your shell. This is the most common post-install error and has nothing to do with the tool itself.

Can I run Qwen CLI against a gateway instead of Qwen's API?

Yes. Qwen Code accepts any OpenAI-compatible endpoint, so you can point OPENAI_BASE_URL at a gateway and reach multiple models on one key. Set OPENAI_MODEL to the model you want — a Qwen model for best tool-calling fidelity, or another model per task.