qwen-code/docs/developers/tools
易良 a84dbff23e
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
..
_meta.ts docs(tools): document monitor tool (#4356) 2026-05-25 15:25:07 +08:00
exit-plan-mode.md fix(core): Require explicit approval to exit Plan mode (#6967) 2026-07-17 02:51:11 +00:00
file-system.md fix(core): preserve fuzzy edit line boundaries (#13484) 2026-10-14 14:11:23 +00:00
introduction.md feat(core): enable the built-in web_search by default on ModelStudio Standard/Token Plan (#11348) 2026-09-09 04:08:29 +00:00
mcp-server.md feat(mcp): add MCP 2026 core and WebShell Apps host (#8992) 2026-08-23 18:34:30 +00:00
monitor.md fix(core): report monitor startup failures as tool errors (#13460) 2026-10-11 14:21:47 +00:00
multi-file.md docs: fix stale defaults, CLI syntax, and tool naming drift (#5158) 2026-06-15 20:06:34 +08:00
sandbox.md Merge branch 'main' into feat/sandbox-config-improvements 2026-03-06 14:38:39 +08:00
shell.md docs(tools): sync shell.md with the shipped run_shell_command contract (#12841) 2026-09-27 12:18:21 +00:00
task.md docs(agent): clarify parameter preconditions (#9580) 2026-08-24 02:27:09 +00:00
todo-write.md feat(core): make todo_write opt-in (#10645) 2026-09-05 04:27:13 +00:00
web-fetch.md fix(core): allow web_fetch JSON fallback (#5660) 2026-06-24 14:18:33 +00:00
web-search.md feat(providers): add QwenCloud as the first /auth entry (#14073) 2026-10-16 21:34:43 +08:00