diff --git a/docs/cli/index.md b/docs/cli/index.md
index b569ba16844..d51b5b4f0ae 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -509,6 +509,8 @@ Options:
   `qwen-standard-api-key-cn`, `qwen-standard-api-key`, `qwen-api-key-cn`, `qwen-api-key`,
   `modelstudio-standard-api-key-cn`, `modelstudio-standard-api-key`,
   `modelstudio-api-key-cn`, `modelstudio-api-key`, `custom-api-key`, `skip`
+- Qwen note: `qwen-*` is the canonical auth-choice family. `modelstudio-*`
+  ids remain accepted as legacy compatibility aliases only.
 - `--secret-input-mode <plaintext|ref>` (default `plaintext`; use `ref` to store provider default env refs instead of plaintext keys)
 - `--anthropic-api-key <key>`
 - `--openai-api-key <key>`
diff --git a/docs/providers/index.md b/docs/providers/index.md
index 8308a3d3eda..d16e971616f 100644
--- a/docs/providers/index.md
+++ b/docs/providers/index.md
@@ -51,7 +51,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi
 - [Perplexity (web search)](/providers/perplexity-provider)
 - [Qianfan](/providers/qianfan)
 - [Qwen Cloud](/providers/qwen)
-- [Qwen / Model Studio (endpoint detail)](/providers/qwen_modelstudio)
+- [Qwen / Model Studio (endpoint detail; `qwen-*` canonical, `modelstudio-*` legacy)](/providers/qwen_modelstudio)
 - [SGLang (local models)](/providers/sglang)
 - [StepFun](/providers/stepfun)
 - [Synthetic](/providers/synthetic)
diff --git a/docs/providers/qwen.md b/docs/providers/qwen.md
index a39c1e7886f..669187b867b 100644
--- a/docs/providers/qwen.md
+++ b/docs/providers/qwen.md
@@ -48,7 +48,8 @@ openclaw onboard --auth-choice qwen-standard-api-key-cn
 ```
 
 Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
-work.
+work as compatibility aliases, but new setup flows should prefer the canonical
+`qwen-*` auth-choice ids and `qwen/...` model refs.
 
 After onboarding, set a default model:
 
diff --git a/docs/providers/qwen_modelstudio.md b/docs/providers/qwen_modelstudio.md
index 66ec455782c..e287936d410 100644
--- a/docs/providers/qwen_modelstudio.md
+++ b/docs/providers/qwen_modelstudio.md
@@ -51,7 +51,8 @@ openclaw onboard --auth-choice qwen-api-key-cn
 openclaw onboard --auth-choice qwen-api-key
 ```
 
-Legacy `modelstudio-*` auth-choice ids still work.
+Legacy `modelstudio-*` auth-choice ids still work as compatibility aliases, but
+the canonical onboarding ids are the `qwen-*` choices shown above.
 
 After onboarding, set a default model:
 
@@ -74,7 +75,9 @@ After onboarding, set a default model:
 | Coding Plan (subscription) | China  | `qwen-api-key-cn`          | `coding.dashscope.aliyuncs.com/v1`               |
 | Coding Plan (subscription) | Global | `qwen-api-key`             | `coding-intl.dashscope.aliyuncs.com/v1`          |
 
-The provider auto-selects the endpoint based on your auth choice. You can
+The provider auto-selects the endpoint based on your auth choice. Canonical
+choices use the `qwen-*` family; `modelstudio-*` remains compatibility-only.
+You can
 override with a custom `baseUrl` in config.
 
 Native Model Studio endpoints advertise streaming usage compatibility on the