mirror of https://github.com/QwenLM/qwen-code.git synced 2026-11-01 20:22:33 +00:00

feat(providers): add QwenCloud as the first /auth entry (#14073 )

* feat(providers): add 千问AI平台 / QwenCloud as the first /auth entry

Adds QwenCloud as a new top-level provider group ahead of Alibaba
ModelStudio, following the product ruling in #14025: the two entries
coexist rather than one replacing the other, so saved ModelStudio
credentials, endpoints and model selections keep resolving to their
existing presets and no migration is needed.

Two new presets share the ModelStudio wizard shape (Access Method ->
Platform -> API Key -> models):

- qwencloud-standard  (pay-as-you-go, `sk-` / `sk-ws-` keys)
- qwencloud-token-plan (Credit subscription, `sk-sp-` keys)

Each offers China (千问AI平台) and International (QwenCloud) as an
explicit platform choice, so the UI language never decides the endpoint.
Coding Plan is not offered here — it is a ModelStudio product.

Endpoints were taken from the platform's own documentation and probed
before landing (all four return the DashScope `invalid_api_key` error
envelope):

- https://maas.qianwenaiapi.com/compatible-mode/v1
- https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1
- https://maas.qwencloudapi.com/compatible-mode/v1
- https://token-plan.maas.qwencloudapi.com/compatible-mode/v1

The new hosts are added to the DashScope provider detection and the
web-search endpoint allowlist so the built-in `web_search` backend keeps
working; both new env keys are added to the no-AK CI gate's cleared-env
list. Group wiring is mirrored across the ink and OpenTUI dialogs, the
VS Code provider picker, and the serve catalog consumed by Web Shell.

Closes #14025

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(cli): add QwenCloud auth strings to en and zh-TW locales

The new auth entries introduced in the previous commit were only added to
zh.js. Since en.js is the source of translation keys and both zh and zh-TW
enforce strict key parity, the i18n check failed with "Extra key in zh.js"
for all eight strings.

Add the same keys to en.js as identity mappings and to zh-TW.js with
Traditional Chinese values, so all three locale files have an identical key
set.

* test(cli): follow the QwenCloud row in the OpenTUI auth menu tests

The new first /auth entry shifts the main menu by one row, but the tests
addressed the sub-menus by position, so most flows landed a row early and
the region-height assertions still named the old first row.

* feat(providers): localize the QwenCloud /auth entry label per locale

The top-level /auth entry was the only mixed CJK/Latin label in the menu
("千问AI平台 / QwenCloud"), and because en/zh mapped that key to itself it
was effectively hardcoded mixed in every locale. Route it through i18n
instead: en and other locales show "QwenCloud", zh shows "千问AI平台",
zh-TW shows "千問AI平台". Locale-neutral surfaces (serve catalog, VS Code
provider picker) carry the single Latin brand; the Chinese brand stays
visible in the explicit platform step ("China — 千问AI平台") and the docs.
The step-title flowTitle now goes through t() so the localized brand also
appears in "… · Step 1/3 · …".

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(providers): register QwenCloud hosts in telemetry and reasoning classifiers

The QwenCloud MaaS hosts and env keys were registered in the two host gates
this PR edits, but two further independent classifiers of the same hosts did
not learn about them, and both misclassify the entry this PR makes the
first-position default:

- telemetry/gen-ai-provider.ts had no providerFromHostname match for
  maas.qianwenaiapi.com / maas.qwencloudapi.com and no PROVIDER_BY_ENV_KEY
  entry for QWENCLOUD_API_KEY / QWENCLOUD_TOKEN_PLAN_API_KEY, so
  resolveGenAiProviderName fell through to its `default: return 'openai'`
  arm. Every span and log record for a QwenCloud install was attributed to
  OpenAI, while the identical ModelStudio path resolved to 'dashscope'.
- core/reasoning-overrides.ts keeps its own inline hostname regex without the
  new hosts, so a user-authored partial reasoning override on a qwen* model
  behind a QwenCloud baseUrl selected 'qwen-chat-template' -> toggleOnly ->
  invalidReasoning, which captureLatestReasoning catches and warns. The
  override was silently discarded; the same declaration on
  dashscope.aliyuncs.com resolves to 'dashscope-effort'.

Also widen the SDK-side mirror DaemonAuthProviderCatalog.groups[].id to
include 'qwencloud', which packages/cli/src/serve/types.ts and
auth-provider-helpers.ts already emit as the first group, and derive
web-shell's AuthGroupId from that union instead of re-declaring it, so the
SDK type is the single source of truth. A second literal union in web-shell
is why nothing reddened in-repo while the daemon emitted a group id its own
published wire type declared impossible.

The new suffixes go inside the existing anchored (^|\.)...$ group, so a forged
maas.qianwenaiapi.com.evil.com cannot match while the legitimate token-plan.
subscription subdomains still do. Both env keys map to the existing
'dashscope' provider value rather than a new one.

The hosts stay literals in gen-ai-provider.ts rather than importing
QWENCLOUD_MAAS_HOSTS: that module is a zero-import telemetry leaf, and
dashscope.ts already imports core/reasoning-overrides at runtime, so importing
back would cycle.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmv8fwg2z5f

* test(providers): pin QwenCloud host classification and registry membership

Cover behaviour this PR added that no test observed:

- dashscope.test.ts: the QwenCloud MaaS pay-as-you-go and token-plan hosts
  are DashScope origins, plus dot-boundary lookalike negatives.
- web-search.test.ts: the same four hosts pass the web-search gate.
- qwencloud-standard/token-plan.test.ts: both presets are registered in
  ALL_PROVIDERS and QWENCLOUD_PROVIDERS, and the qwencloud access-method
  group excludes Coding Plan (replaces a constant-true id/label check).

Each new assertion is mutation-verified: dropping isQwenCloudOrigin from the
dashscope return, weakening its host match, dropping the QWENCLOUD_MAAS_HOSTS
spread, removing the two registry entries, or flipping codingPlanProvider
uiGroup each turns exactly the intended test red.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmv8mbxgn5t

* test(providers,cli): pin QwenCloud preset separation and the auth catalog group

Coverage for lines this PR itself added (review round 1: R1-21, R1-26, R1-15):

- qwencloudStandardProvider.ownsModel is cross-checked against its QwenCloud
  Token Plan sibling and against a foreign envKey on its own endpoint. The two
  presets share uiGroup, catalog and protocol bucket, so that envKey gate is
  the only discriminator; dropping it kept the suite green while
  applyModelProvidersPatch would claim a Token Plan install.
- buildAuthProviderCatalog gets its first test: the QwenCloud group is first
  and carries both access methods. A misspelled group filter stayed green.
- The zero-row main-menu paint test now names row 0, which this PR re-pointed
  from Alibaba ModelStudio to QwenCloud while only rows 1 and 2 stayed pinned.

Each assertion was confirmed load-bearing by one mutation that the
pre-existing tests did not catch.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmv8oh38g5y

* docs(users): sweep the /auth menu enumeration in overview and quickstart

This PR re-numbered the /auth menu to four options in auth.md and
model-providers.md, but overview.md and quickstart.md still described three
entries with Alibaba ModelStudio as the recommended one (review round 1:
R1-4). The doc set contradicted itself, and a quickstart reader holding a
QwenCloud key was routed to the ModelStudio entry, whose endpoints reject it.

Both pages now list QwenCloud first and reserve the "recommended setup" claim
for it, matching auth.md.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmv8oh38g5y

* fix(providers): validate daemon credentials and close QwenCloud follow-ups (#14302)

* fix(serve): validate API key format before persisting in daemon install path

The CLI, ACP and VS Code surfaces each call provider.validateApiKey
before persisting credentials. The daemon route (POST
/workspace/auth/provider) did not, because validateApiKey is a function
on ProviderConfig and cannot be serialized to the wire — so no client
of this route can apply the check either.

Without this guard a key the provider's own entry rejects (e.g. a
Token Plan sk-sp- key aimed at the Standard API Key entry) gets
persisted silently, and the user only discovers the mismatch at the
first authenticated call.

Fix: call validateApiKey in the route after protocol validation and
before invoking installAuthProvider. Return 400 with code
'invalid_api_key' on failure, matching the other three surfaces.

Closes #14257 (item S3 / R2-13).

* fix(providers): address #14257 deferred Suggestions (D1/D2, T1/T3-T9, I1, P5, S6/S7)

Batch fix for actionable items from #14257:

Docs:
- D1: Add settings.json example to QwenCloud headless setup section
- D2: Add QwenCloud rows to web-search.md auto-activation table

Tests:
- T1: Pin flowTitle locale resolution in both dialog suites
- T3/T4: Assert QwenCloud sub-menu contents (Token Plan + Standard, no Coding Plan)
- T5: Add missing token-plan.maas.qwencloudapi.com endpoint to dashscope.test.ts
- T6: Add QwenCloud host tests to reasoning-overrides.test.ts
- T7: Assert providerState in qwencloud-standard preset test
- T8: Test ownsModel baseUrl conjunct independently of envKey
- T9: Test providerMatchesCredentials URL gate independently of envKey
- S7: Assert QwenCloud group in VS Code AuthMessageHandler picker

i18n:
- I1: Add validateApiKey messages to all 9 locale files

Product:
- P5: Fix qwen3.7-plus modalities to include video (matches alibaba-token-plan)

Code:
- S6: Update docstring enumerations in dashscope.ts and web-search.ts

Remaining items need human decisions: P1-P4 (wording/labels), S1-S5 (API surface),
T2 (ink suite gating is a pre-existing harness pattern).

* fix(auth): translate provider titles at render time

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* test(providers): handle optional preset models

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* test(providers): pin Token Plan providerState and ownsModel baseUrl leg

Addresses four review Suggestions on this PR:

- R1-10 (#14257 T7): the providerState stamp was asserted for the Standard
  preset only. Token Plan has two baseUrl options and a baseUrl-dependent
  modelNamePrefix, so stamp both routes.
- R1-11 (#14257 T8): the deciding baseUrl negative for ownsModel was added
  to the Standard suite only. The Token Plan negatives added here differ in
  envKey, so the baseUrl conjunct was never the deciding factor.
- R1-1: the web-search host note contradicted the two QwenCloud rows this
  PR adds to the table on the same page. Name the Model Studio and
  QwenCloud MaaS families the code actually accepts.
- R1-4: the daemon route comment claimed parity with the CLI/ACP/VS Code
  copies. Those resolve the endpoint first and validate the resolved URL;
  this route validates the client-supplied baseUrl. Comment only.

Both new Token Plan rows were mutation-checked one mutant at a time:
dropping baseUrl from resolveProviderState, stamping the provider default
endpoint instead of the requested one, and relaxing ownsModel to envKey-only
each turn exactly the intended row red. An additional cross-route
"versions must differ" row stayed green under all of them (model configs
already embed baseUrl), so it was dropped rather than shipped inert.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmv9zmmcj86

* test: make the QwenCloud witnesses discriminating; trim daemon key once

R1-9: the two Token Plan cases and the four lookalike cases never reached
the dashscope host regex - both blocks short-circuited in
validateReasoningDeclaration/validateReasoningCapabilities before
route.baseUrl was parsed, and the block comment misstated the Token Plan
endpoints as unregistered. Fold the Token Plan hosts into the QwenCloud
host table with a declaration that omits `thinking`/`profile`, so all four
registered endpoints now pin the anchored suffixes.

R1-5/R1-6: the Ink VIEW_TITLES fix had no CI-executed guard (every
keystroke case is skipped under CI=true) and its T1 case asserted only the
already-lazy flowTitle path. Add one ungated, keystroke-free render
assertion and assert the sub-menu heading between the two keystrokes.

R1-3: validate and forward the same trimmed key rather than validating the
trimmed value while forwarding the raw one.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmva623ox8i

* fix(auth): guard zh locale test cleanup, note hand-written provider caveat

R1-7: wrap the QwenCloud zh flow-title test body in try/finally so unmount()
and the locale reset still run when an assertion rejects, matching the shape
of the opentui twin added in the same change.

R1-2: note in the settings.json alternative that a hand-written provider entry
carries no capabilities stamp, so /effort offers the generic tiers rather than
the QwenCloud curated set.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmvaacf8g8p

* fix(providers): address #14073 round-3 deferred Suggestions

- docs/design/auth/motivation.md: QwenCloud-first /auth enumeration (S1)
- docs/users/quickstart.md: name QwenCloud credentials in Before you begin (S3)
- docs/users/configuration/auth.md: scope the Token Plan prefix rule to
  ModelStudio vs QwenCloud so Option 1 and Option 4 no longer read as
  contradictory (S4)
- qwencloud-standard.test.ts: correct the ownsModel comment — envKey and
  baseUrl conjuncts each exclude the sibling independently (S5)
- auth-provider-helpers.test.ts + alibaba-standard.test.ts: pin every
  catalog group's providerIds and the alibaba uiGroup (S6)
- web-search.test.ts: forged-suffix boundary cases for the QwenCloud host
  gate (S7)

S2 (6-latin-locale backfill) and S8 (web-shell group dict) verified as
no-ops: the sibling ModelStudio strings rely on the identical raw-key
fallback in the same locales/dictionary.

* fix(auth): localize provider API key errors

* fix(providers): seed Token Plan only with models its endpoint serves

A live GET /models on the China Token Plan route (real subscription key,
2026-10-16) serves neither kimi-k3 nor deepseek-v4-pro-0813 — the endpoint
offers kimi-k2.x and deepseek-v4-pro instead, matching the platform doc's
personal-edition table. The shared QWENCLOUD_MODELS seed list therefore
pre-filled two ids the wizard would install as dead entries whenever
discovery succeeded, and offered them in the offline fallback.

Filter the shared catalog down to the five confirmed-served models for the
Token Plan preset instead of duplicating stamps; the Standard (pay-as-you-go)
catalog keeps the full list, which no live data has falsified. Pinned by a
new preset test asserting the exact seed ids.

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(auth): preserve explicit models during provider discovery

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

2026-10-16 21:34:43 +08:00

9.5 KiB

Raw Permalink Blame History

Quickstart

👏 Welcome to Qwen Code!

This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.

Before you begin

Make sure you have:

A terminal or command prompt open
A code project to work with
An API key or Token Plan subscription from 千问AI平台 / QwenCloud (China / International) — the recommended setup — or an API key from Alibaba Cloud ModelStudio (Beijing / intl), or an Alibaba Cloud Token Plan (Beijing / intl) subscription

Step 1: Install Qwen Code

To install Qwen Code, use one of the following methods:

Quick Install (Recommended)

Linux / macOS

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

Windows

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

Note

It's recommended to restart your terminal after installation to ensure environment variables take effect.

Manual Installation

Prerequisites

Make sure you have Node.js 22 or later installed. Download it from nodejs.org.

NPM

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

Homebrew (macOS, Linux)

brew install qwen-code

Step 2: Set up authentication

When you start an interactive session with the qwen command, you'll be prompted to configure authentication:

# You'll be prompted to set up authentication on first use
qwen

# Or run /auth anytime to change authentication method
/auth

The first-run menu lets you connect a model provider. Choose one of:

QwenCloud — the recommended setup. Opens a sub-menu:
- Token Plan: subscription with a monthly Credit quota on a dedicated endpoint (Personal and Team editions).
- Standard API Key: pay-as-you-go, connect with an existing platform API key.
Either way you then pick the platform explicitly (China or International), so the UI language never decides your endpoint. See Authentication → Option 1: QwenCloud for details.
Alibaba ModelStudio — opens a sub-menu:
- Token Plan: usage-based billing with a dedicated endpoint, aimed at teams and companies. See the Token Plan guide (intl) for setup instructions.
- Standard API Key: connect with an existing API key from Alibaba Cloud ModelStudio (Beijing / intl). See the API setup guide (Beijing / intl) for details.
Third-party Providers — choose a built-in provider (DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty, and more) and connect with an API key.
Custom Provider — manually connect a local server, proxy, or unsupported provider.

⚠️ Note: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above.

Note

Qwen Code stores its configuration and customizations in .qwen directories: ~/.qwen/ for user-level settings (e.g. settings.json) and global custom commands, and <project>/.qwen/ for project-specific files such as custom commands and summaries.

Tip

To configure authentication, start Qwen Code and run /auth. Use /doctor to check your current configuration at any time. See the Authentication page for details.

Step 3: Start your first session

Open your terminal in any project directory and start Qwen Code:

# optional
cd /path/to/your/project
# start qwen
qwen

You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type /help for available commands.

Chat with Qwen Code

Ask your first question

Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:

explain the folder structure

You can also ask Qwen Code about its own capabilities:

what can Qwen Code do?

Note

Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.

Make your first code change

Now let's make Qwen Code do some actual coding. Try a simple task:

add a hello world function to the main file

Qwen Code will:

Find the appropriate file
Show you the proposed changes
Ask for your approval
Make the edit

Note

Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.

Use Git with Qwen Code

Qwen Code makes Git operations conversational:

what files have I changed?

commit my changes with a descriptive message

You can also prompt for more complex Git operations:

create a new branch called feature/quickstart

show me the last 5 commits

help me resolve merge conflicts

Fix a bug or add a feature

Qwen Code is proficient at debugging and feature implementation.

Describe what you want in natural language:

add input validation to the user registration form

Or fix existing issues:

there's a bug where users can submit empty forms - fix it

Qwen Code will:

Locate the relevant code
Understand the context
Implement a solution
Run tests if available

Test out other common workflows

There are a number of ways to work with Qwen Code:

Refactor code

refactor the authentication module to use async/await instead of callbacks

Write tests

write unit tests for the calculator functions

Update documentation

update the README with installation instructions

Code review

review my changes and suggest improvements

Tip

Remember: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.

Essential commands

Here are the most important commands for daily use:

Command	What it does	Example
`qwen`	start Qwen Code	`qwen`
`/auth`	Change authentication method (in session)	`/auth`
`/doctor`	Check current authentication and environment	`/doctor`
`/help`	Display help information for available commands	`/help` or `/?`
`/compress`	Replace chat history with summary to save Tokens	`/compress`
`/clear`	Clear conversation history and free up context	`/clear` (aliases: `reset`, `new`)
`/theme`	Change Qwen Code visual theme	`/theme`
`/language`	View or change language settings	`/language`
→ `ui [language]`	Set UI interface language	`/language ui zh-CN`
→ `output [language]`	Set LLM output language	`/language output Chinese`
`/quit`	Exit Qwen Code immediately	`/quit` or `/exit`

See the CLI reference for a complete list of commands.

Pro tips for beginners

Be specific with your requests

Instead of: "fix the bug"
Try: "fix the login bug where users see a blank screen after entering wrong credentials"

Use step-by-step instructions

Break complex tasks into steps:

1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information

Let Qwen Code explore first

Before making changes, let Qwen Code understand your code:

analyze the database schema

build a dashboard showing products that are most frequently returned by our UK customers

Save time with shortcuts

Press ? to see all available keyboard shortcuts
Use Tab for command completion
Press ↑ for command history
Type / to see all slash commands

Getting help

In Qwen Code: Type /help or ask "how do I..."
Documentation: You're here! Browse other guides
Community: Join our GitHub Discussion for tips and support

9.5 KiB Raw Permalink Blame History