diff --git a/README.md b/README.md
index 825513b..1592557 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,21 @@ gets you a skip notice naming it, not a mis-keyed call. Note `kimi/<model>` (Moo
 API, `KIMI_API_KEY`) is a different route than the `kimi-k2.6:cloud` entry in the
 default swarm, which is Ollama Cloud and keyed by `OLLAMA_CLOUD_API_KEY`.
 
+> **Qwen keys are endpoint-scoped, and the failure looks like a bad key.**
+> Alibaba Model Studio issues *workspace-scoped* endpoints of the form
+> `https://<workspace>.<region>.maas.aliyuncs.com/compatible-mode/v1`. A key
+> issued for one host is rejected by another with a genuine
+> `401 Incorrect API key provided` — so a perfectly good key reads as invalid if
+> the endpoint doesn't match. The built-in defaults to the shared international
+> host; point at your own with a named endpoint, which needs no code change:
+>
+> ```
+> GADFLY_ENDPOINT_QWENWS = "qwen|https://<workspace>.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1|<key>"
+> GADFLY_MODELS          = "qwenws/qwen3.8-max,..."
+> ```
+>
+> (Verified the hard way against a live deployment.)
+
 > ### 🧪 Honest status
 > Only the **Ollama** paths above are actually exercised. The OpenAI / Qwen / Kimi /
 > Anthropic / Google