Connecting to Tongyi Qianwen Qwen: The Three DashScope Plans
OpenClaw Connecting to Qwen (Tongyi Qianwen) is the second stop on the domestic models page. In the previous lesson, DeepSeek worked with a single environment variable; Qwen adds a multiple-choice question—Alibaba's DashScope offers Coding Plan, Standard, and Token Plan, each split into domestic / international endpoints. Choose the wrong plan and the model list may be missing entries or multimodal features may fail; using the Token Plan for unattended tasks could get your subscription suspended or even your Key revoked. The whole process takes about 8 minutes (Qwen Cloud / Alibaba Cloud registration not included).
Here's a quick-reference table first—every configuration in this lesson builds on it:
| Property | Value |
|---|---|
| Provider id | qwen (Token Plan uses a separate id: qwen-token-plan) |
| Auth environment variable | QWEN_API_KEY (Token Plan: QWEN_TOKEN_PLAN_API_KEY) |
| Compatible environment variables | MODELSTUDIO_API_KEY, DASHSCOPE_API_KEY |
| API style | OpenAI-compatible |
| Official plugin | @openclaw/qwen-provider (external plugin, installation required) |
| Default model | qwen/qwen3.5-plus (text + images, 1M context) |
| When only a Key is set and no endpoint configured | Defaults to the international-site Coding Plan: https://coding-intl.dashscope.aliyuncs.com/v1 |
One thing you must know first: the environment variable name determines neither the plan nor the region (official wording: "The environment variable name does not select a plan or region"). What determines the endpoint is the auth-choice during onboarding, or an explicitly written baseUrl in the configuration.
Three plans × two regions—this table carries the whole lesson (auth-choices and endpoints are quoted verbatim from the official documentation):
| Plan | Region | auth-choice | Endpoint |
|---|---|---|---|
| Coding Plan (subscription) | Domestic | qwen-api-key-cn | coding.dashscope.aliyuncs.com/v1 |
| Coding Plan (subscription) | International | qwen-api-key | coding-intl.dashscope.aliyuncs.com/v1 |
| Standard (pay-as-you-go) | Domestic | qwen-standard-api-key-cn | dashscope.aliyuncs.com/compatible-mode/v1 |
| Standard (pay-as-you-go) | International | qwen-standard-api-key | dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| Token Plan (Team Edition) | Domestic | qwen-token-plan-cn | token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 |
| Token Plan (Team Edition) | International | qwen-token-plan | token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 |
How to choose, in three sentences (based on the official positioning of the three plans):
| Your Situation | Choose This | Basis |
|---|---|---|
| Want a monthly subscription to use Qwen | Coding Plan | Official positioning: subscription-based |
| Pay as you go; or need qwen3.8-max / qwen3.8-flash; or need multimodal | Standard | qwen3.8 series is not in the Coding Plan; image / video understanding and Wan video generation are only on the Standard endpoint |
| Team seat-based, using Qwen + third-party models within one subscription | Token Plan (Team Edition) | Official positioning: credit-based team subscription; interactive use only |
The region follows the account: whichever site issued your Key, configure that region's endpoint—the official requirement is "plan and regional key must match" (use the matching plan and regional key). This tutorial is based on OpenClaw v2026.10.9.
What You'll Be Able to Do After This Lesson
- Install the official Qwen plugin
@openclaw/qwen-providerand configureQWEN_API_KEYinto OpenClaw — choose either the onboarding guide or manual configuration - Tell apart the three DashScope plans and the two endpoint sets for China / international, and pick the right auth-choice for your account
- Understand Qwen's built-in model catalog: when to switch from the default model
qwen3.5-plus, and which models are only available on Standard / Token Plan - Stay clear of Token Plan's red lines: scheduled tasks and unattended scripts must not run on it
- Use Qwen-exclusive capabilities:
/thinkreasoning control, multimodal and Wan video generation on the Standard endpoint, and one Key authenticating both the qwen + alibaba plugins
🎒 Preparation Before Starting
- Completed Connecting Models Overview: the provider system and model switching: you know the three steps of "install plugin → configure credentials → pick a model" and the
provider/modelreference rules by heart - OpenClaw is installed and the Gateway is running:
openclaw gateway statusproduces output (the plugin takes effect automatically on a running Gateway; if it isn't running, it takes effect on next startup) - Decide which plan you want (subscription / pay-as-you-go / team seats), and confirm whether your Key was issued by the China site or the international site
- If you go with server / daemon deployment, know where
~/.openclaw/.envis — that's where the Key will ultimately live
Follow Along
Step 1: Register on Qwen Cloud and create an API Key for your plan
Why: OpenClaw only handles the calls — the Key has to come from Qwen's side first, and the path to get a Key differs across the three plans.
Coding Plan and Standard:
- Open
https://home.qwencloud.com/api-keysin a browser and register / log in - Create or copy an API Key and paste it somewhere safe
Token Plan (Team Edition):
- In Alibaba Cloud Model Studio (Bailian), assign Token Plan seats to members — for the international edition see Token Plan overview, for the China edition see Token Plan overview
- Create a dedicated Key for that seat, in the form
sk-sp-...
What you should see: a copyable API Key. Note that the three kinds of Keys are not interchangeable — in the official words: "Token Plan, Coding Plan, and pay-as-you-go keys are not interchangeable."
💡 Pick your plan first, then get the Key
Token Plan Keys start with sk-sp-, easy to recognize; if you're unsure which subscription you have, check the plan name in the console first before coming back to choose an auth-choice. Keys are managed uniformly at https://home.qwencloud.com/api-keys, and Qwen's official docs are at https://docs.qwencloud.com.
Step 2: Connect OpenClaw to Qwen — install the plugin first, then configure QWEN_API_KEY per your plan
Why: Like DeepSeek, Qwen is an external official plugin (not bundled with the core), which adds an "install" step compared to built-in plugins; after installation, the auth-choice determines which plan endpoint is used.
Install the plugin first (the shared first step for both methods):
openclaw plugins install @openclaw/qwen-providerWhat you should see: successful installation. It takes effect automatically on a running Gateway; if the Gateway isn't running, it takes effect on next startup.
Method A (recommended): onboarding guide
Referring to the plan table above, choose from the six auth-choices as needed:
# Coding Plan · 国内站 / 国际站
openclaw onboard --auth-choice qwen-api-key-cn
openclaw onboard --auth-choice qwen-api-key
# Standard · 国内站 / 国际站(要用 qwen3.8 系列或多模态的选这类)
openclaw onboard --auth-choice qwen-standard-api-key-cn
openclaw onboard --auth-choice qwen-standard-api-key
# Token Plan · 国内(北京)/ 国际(新加坡)
openclaw onboard --auth-choice qwen-token-plan-cn
openclaw onboard --auth-choice qwen-token-planWhy it's recommended: the provider automatically selects the endpoint based on the auth-choice, so no need to hand-write baseUrl; one command covers "configure credentials + pick a model".
What you should see: first a prompt for the API Key, which is saved after validation passes; when picking the default model, candidates are pre-filtered by the auth-choice (both qwen / qwen-token-plan providers of the same plugin match together).
Three reassurances (explicitly stated in the official docs):
- Onboarding preserves your existing model entries — re-running won't wipe out other providers' configuration
- Under
models.mode: "replace"mode, the built-in catalog is written at the same time (that mode skips discovery) - Adding new provider credentials does not change your existing default model — to change the default, use
openclaw models setfrom step 3
Method B: manually edit the configuration file
The two things are managed separately: the Key goes into environment variables, while models and endpoints go into the configuration.
Default model (official configuration example, verbatim):
{
agents: {
defaults: {
model: { primary: "qwen/qwen3.5-plus" },
},
},
}Where to put the Key: in an interactive shell, export QWEN_API_KEY="<你的 API Key>", or write it into ~/.openclaw/.env (daemon deployment must go through here, see the warning below). Token Plan uses QWEN_TOKEN_PLAN_API_KEY.
Manual configuration for Standard / Token Plan takes one extra step — explicitly override baseUrl, otherwise setting only the Key defaults to the international-site Coding Plan endpoint (the official verbatim requirement for manual configuration):
{
models: {
providers: {
qwen: {
// Standard · 国际站;国内站换成 https://dashscope.aliyuncs.com/compatible-mode/v1
baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
},
},
},
}The same applies to other plans: baseUrl points to the corresponding endpoint in the plan table (Token Plan model references also need the qwen-token-plan/ prefix). Explicit endpoint configuration has the highest priority, but the plan and region Key must match.
⚠️ Running the Gateway as a daemon? Don't put the Key in an interactive shell
When the Gateway runs as a launchd / systemd service, it can't see the export environment variables in your terminal. Write QWEN_API_KEY (or QWEN_TOKEN_PLAN_API_KEY) into ~/.openclaw/.env, or provide it to that process via env.shellEnv in the configuration.
- In
openclaw models status's credentials overview, the qwen row shows the source ofQWEN_API_KEY
Step 3: Choose a Qwen model and verify
Why: If the default model qwen/qwen3.5-plus is good enough, get it running first; but the 14 models in the catalog are not all equal — some are Standard-only, and some can even see images. Take a look at the catalog before deciding.
Check the catalog first:
openclaw models list --provider qwen # 列出 qwen 的已发布模型目录
openclaw models list --all --provider qwen # --all:完整已发布目录;配 --provider 时可省What you should see: a built-in catalog like the one below. When the Gateway is running, the actual list is dynamically discovered from your configured endpoint's /models API and filtered by plan — a Coding Plan configuration omits models not available on that plan; if the Gateway isn't running, the locally cached catalog is shown, and adding --refresh triggers rediscovery:
| Model reference | Input | Context | Notes |
|---|---|---|---|
qwen/qwen3.5-plus | Text, image | 1,000,000 | Default model |
qwen/qwen3.6-flash | Text, image | 1,000,000 | Standard endpoint only |
qwen/qwen3.6-plus | Text, image | 1,000,000 | Coding Plan + Standard |
qwen/qwen3.7-max | Text | 1,000,000 | Standard endpoint only |
qwen/qwen3.7-plus | Text, images | 1,000,000 | Coding Plan + Standard |
qwen/qwen3.8-max | Text, images | 1,000,000 | Standard endpoint only |
qwen/qwen3.8-flash | Text, images | 1,000,000 | Standard endpoint only |
qwen/qwen3-max-2026-01-23 | Text | 262,144 | Qwen Max series |
qwen/qwen3-coder-next | Text | 262,144 | Coding |
qwen/qwen3-coder-plus | Text | 1,000,000 | Coding |
qwen/MiniMax-M2.5 | Text | 1,000,000 | Reasoning enabled |
qwen/glm-5 | Text | 202,752 | GLM |
qwen/glm-4.7 | Text | 202,752 | GLM |
qwen/kimi-k2.5 | Text, images | 262,144 | Moonshot AI via Alibaba |
Two official reminders: a model appearing in the seed catalog does not mean your endpoint actually has it (availability varies by endpoint and billing plan); and a model being listed in Standard does not mean you have Token Plan / Coding Plan access.
How to choose, in three sentences:
| Your need | Pick it | Basis |
|---|---|---|
| No idea what to pick | qwen/qwen3.5-plus | Official default model, 1M context |
| Want the latest qwen3.8 series | qwen/qwen3.8-max / qwen/qwen3.8-flash | Standard / Token Plan only, not on Coding Plan |
| Mainly writing code | qwen/qwen3-coder-plus(1M) / qwen/qwen3-coder-next(262,144) | The Coding dedicated line in the catalog |
To change the default model:
openclaw models set qwen/qwen3.5-plusYou can also switch temporarily in the chat: /model qwen/qwen3.7-plus only affects the current session; see Chat Commands Crash Course for the full command family.
Finally, verify by sending a test message:
openclaw agent --agent main --model qwen/qwen3.5-plus --message "用一句话介绍你自己"(openclaw agent requires at least one session selector; --agent main points to the default agent, which is main by default in installations that have completed onboarding; or run openclaw dashboard to open the Control UI and send directly from the chat box.)
You should see: the model replying normally, with no errors about missing credentials or a nonexistent model. At this point, OpenClaw is connected to Qwen.
Token Plan users: change the model reference to the qwen-token-plan/ prefix; the catalog is separate:
openclaw models list --provider qwen-token-plan
openclaw agent --agent main --model qwen-token-plan/qwen3.7-plus --message "Reply with: token plan ready"(The second command is adapted from the official verification example—the original did not include a session selector, but openclaw agent requires at least one, so --agent main is added here.)
Token Plan built-in catalog (the plan models currently recommended officially; the remaining whitelisted IDs can be used as custom model references):
| Model reference | Input | Context |
|---|---|---|
qwen-token-plan/qwen3.7-plus | Text, images | 1,000,000 |
qwen-token-plan/qwen3.8-max | Text, images | 1,000,000 |
qwen-token-plan/qwen3.8-flash | Text, images | 1,000,000 |
qwen-token-plan/qwen3.6-plus | Text, images | 1,000,000 |
qwen-token-plan/kimi-k2.5 | Text, images | 262,144 |
qwen-token-plan/glm-5 | Text | 202,752 |
qwen-token-plan/MiniMax-M2.5 | Text | 196,608 |
Pricing in one sentence: the Qwen documentation of OpenClaw only gives context specifications, not prices (it explicitly points to the vendor pages), and the three plans also differ in billing shape (subscription / usage-based / team credits)—for billing, always refer to the official Qwen Cloud and Alibaba Cloud pages.
- Received a reply from Qwen for the test message
Checkpoint ✅
openclaw plugins install @openclaw/qwen-providerexecuted, plugin listed- auth-choice matches your plan and region (officially requires a matching plan and regional key)
- qwen's
QWEN_API_KEYis visible in the credentials overview ofopenclaw models status(for Token Plan it isQWEN_TOKEN_PLAN_API_KEY) openclaw models list --provider qwenlists qwen-family models with no unsupported model error- Received a reply from Qwen after sending the test message
- Did not use Token Plan for scheduled tasks / unattended scripts
Pitfall Reminders
❌ Only set QWEN_API_KEY, assuming the variable name determines the plan and region
Cause: The official docs state it plainly — the environment variable name selects neither the plan nor the region. When only QWEN_API_KEY is provided without baseUrl, OpenClaw defaults to the international-site Coding Plan endpoint https://coding-intl.dashscope.aliyuncs.com/v1.
Correct approach: When running onboarding, pick the right auth-choice so the provider selects the endpoint automatically; for manual configuration, explicitly set models.providers.qwen.baseUrl. Explicit endpoint configuration has the highest priority, but the plan and region of the Key must match.
❌ Can't find qwen3.8-max / qwen3.8-flash on Coding Plan
Cause: qwen3.8-max, qwen3.8-flash, qwen3.7-max, and qwen3.6-flash are only available on Standard or Token Plan; OpenClaw omits them from the Coding Plan catalog. Using them on a Coding Plan endpoint returns "unsupported model" — the official troubleshooting guidance is simply to switch endpoints.
# ❌ Coding Plan 端点上不可用
qwen/qwen3.8-max
# ✅ 换 Standard(或 Token Plan)端点 + 配套 Key
openclaw onboard --auth-choice qwen-standard-api-key-cn # 国内站
openclaw onboard --auth-choice qwen-standard-api-key # 国际站❌ Running scheduled jobs / unattended scripts on Token Plan
Cause: Alibaba officially states that Token Plan is limited to interactive use — non-interactive usage such as cron jobs, unattended scripts, and application backends may result in the subscription being suspended or the API Key being revoked. Automations scheduled jobs, webhooks, and long-running services in OpenClaw are all unattended usage: for scheduled scenarios like daily morning brief, never configure a Token Plan.
Correct approach: To run Automations, webhooks, or long-running services, use a Standard (pay-as-you-go) or Coding Plan Key.
❌ Mixing the three kinds of Keys, or still using old Portal credentials
Cause: Keys for Token Plan, Coding Plan, and pay-as-you-go are not interchangeable; the old qwen-oauth Portal authentication has been removed entirely, Portal tokens do not interoperate with Qwen Cloud / DashScope API Keys, and existing credentials will not be converted automatically.
Correct approach: One Key plus one endpoint per plan; if you are still using Portal credentials, redo API Key authentication following steps 1 and 2.
❌ After installing the Gateway as a daemon, the exported Key "doesn't take effect"
Cause: launchd / systemd services cannot see environment variables from an interactive shell — the Qwen documentation specifically emphasizes this point.
Correct approach: Write QWEN_API_KEY / QWEN_TOKEN_PLAN_API_KEY into ~/.openclaw/.env, or provide them via env.shellEnv in the configuration; restart the Gateway service after changing the Key.
❌ Trying to have models read images / generate videos on Coding Plan
Cause: Multimodal capabilities (image / video understanding, Wan video generation) are only open on the Standard endpoint, not on the Coding Plan endpoint — even if the catalog labels them "text, image".
Correct approach: Configure the Standard endpoint if you need multimodal features; media understanding automatically reuses your configured Qwen credentials, with no extra setup.
🔧 Qwen-specific capabilities (optional)
Once the plugin is installed, four Qwen-specific capabilities come along with it.
thinking control
qwen3.8-max / qwen3.8-flash support four thinking levels: off / low / medium / xhigh, defaulting to xhigh with a maximum output of 131,072 tokens. Use directly in chat:
/think xhigh # 默认档
/think off # 关闭思考Level mapping: minimal → low, high / max → xhigh (applies to both Standard and Token Plan). During tool calls, OpenClaw puts the returned reasoning into a separate reasoning_content replay field instead of mixing it into the main text.
qwen3.7-max / qwen3.7-plus / qwen3.6-flash / qwen3.6-plus take a different path: OpenClaw maps the thinking level to the top-level DashScope enable_thinking boolean — it sends enable_thinking: false when off, and true for any other level.
⚠️ thinking_budget and reasoning_effort cannot be sent together
When thinking_budget is explicitly written in the request parameters, it takes precedence; Qwen rejects requests that contain both thinking_budget and the mapped reasoning_effort.
Models on Token Plan also support thinking; among them, kimi-k2.7-code and MiniMax-M2.5 are thinking-only models — even if /think off is used in the session, OpenClaw keeps thinking enabled.
Multimodal and Wan video generation (Standard endpoint only)
On the Standard endpoint, the same plugin also opens up two multimodal capabilities:
- Image / video understanding:
qwen3.6-plus - Wan video generation:
wan2.6-t2v(default),wan2.6-i2v,wan2.6-r2v,wan2.6-r2v-flash,wan2.7-r2v
Set Qwen as the default video provider (official configuration example, verbatim):
{
agents: {
defaults: {
mediaModels: { video: { primary: "qwen/wan2.6-t2v" } },
},
},
}Three practical details:
- When only a single reference image is given without a video,
wan2.6-t2vautomatically switches towan2.6-i2v, and the result reports the model actually resolved - Duration limits: text-to-video / image-to-video 15 seconds; reference-to-video (r2v series) 10 seconds, with at most 5 input assets, of which videos account for at most 3
- Video generation uses
QWEN_API_KEYon the Standard endpoint; media understanding automatically reuses the configured Qwen credentials
To systematically explore image pairing, voice, and video, see Images and Voice: adding images to content and converting articles to speech.
One Key authenticates two plugins: qwen and alibaba
OpenClaw also has a second plugin connecting to DashScope, alibaba (built in and enabled by default, no installation needed): alibaba/* handles Wan video generation exclusively, while qwen/* handles chat and media understanding, with no overlapping responsibilities.
The authentication order for alibaba: MODELSTUDIO_API_KEY → DASHSCOPE_API_KEY → QWEN_API_KEY (first match wins). Setting MODELSTUDIO_API_KEY once can authenticate both the alibaba and qwen plugins at the same time — the two plugins' environment variable lists intentionally overlap.
alibaba's default model is alibaba/wan2.6-t2v, with default baseUrl https://dashscope-intl.aliyuncs.com (can be overridden to https://dashscope.aliyuncs.com for the China region).
Third-party models hosted on DashScope
The Qwen catalog contains more than just Qwen: qwen/glm-5, qwen/glm-4.7 (Zhipu GLM), qwen/kimi-k2.5 (Moonshot AI), and qwen/MiniMax-M2.5 are all hosted on DashScope — one DashScope Key gives you models from four providers. Token Plan's official positioning explicitly includes "Qwen and supported third-party models".
Legacy syntax compatibility: modelstudio and bailian-token-plan
- The
modelstudio-*auth-choice andmodelstudio/...model references from older tutorials still work (compatibility aliases); new configurations should always useqwen-*andqwen/... - Alibaba's own OpenClaw guide uses
bailian-token-planas a manual custom provider — the plugin has already registered that id as a compatibility owner, and new configurations should useqwen-token-plan - When you explicitly define a
models.providers.modelstudioormodels.providers.bailian-token-planentry, references with the corresponding prefix are taken over by that custom provider
Next Steps
That's it — OpenClaw is now fully configured with Qwen. Continue with the domestic models pages:
- Next lesson Connecting Zhipu GLM: Z.AI dual endpoints and Coding Plan: how to choose between Zhipu's dual endpoints and how to configure
ZAI_API_KEY - Other model pages (Kimi, MiniMax, Doubao, Hunyuan / Qianfan, relays and local models) are accessible from the course schedule on Connecting Models Overview
- Model configured? For daily use, start with Daily Use: Getting Along Efficiently with Your Claw — Control UI, chat commands, and the memory system are all in that chapter