Agent setup: If your agent doesn't auto-load skills (e.g. Claude Code), see agent-compatibility.md once per session.
QwenCloud Authentication Setup
Configure and verify authentication for QwenCloud APIs.
This skill is part of qwencloud/qwencloud-ai.
Skill directory
Use this skill's internal files for learning. Load references only when the user needs console or documentation links.
| Location | Purpose |
|---|
| Coding Plan vs standard key: model list, endpoint mapping, error codes, cost risks |
| Custom OSS bucket setup for production file uploads (replaces 48h temp storage) |
| Console URLs, auth guide (manual lookup only) |
references/agent-compatibility.md
| Agent self-check: register skills in project config for agents that don't auto-load |
Security
NEVER output any API key, OSS credential in plaintext.
This applies equally to
and custom OSS AccessKey pairs. Any check or detection of credentials in this skill must be
non-plaintext: report only status (e.g. "set" / "not set", "valid" / "invalid", HTTP status code), never the key value.
API Key Handling (MANDATORY)
When the API key is not configured or a script reports missing credentials:
- NEVER ask the user to provide their API key directly. Do not prompt "please paste your API key" or similar. Do not request the key value in any form.
- Help create a file with a placeholder, then instruct the user to fill in their own key:
- Run:
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
- Tell the user: "Please replace with your actual API key from the QwenCloud Console."
- Or explain how to configure the environment variable:
export DASHSCOPE_API_KEY='sk-...'
- Only write the actual key value into if the user explicitly insists on having the agent do it for them.
Credential Priority Chain
Credentials are loaded in the following order (first match wins):
- Environment variable — (or alias)
- file — in current working directory, then repo root (detected via or directory). Existing environment variables are not overwritten.
Environment Variables
| Variable | Purpose |
|---|
| API key (required) |
| Alias for . If both are set, takes priority. |
| Override default endpoint (optional; for custom deployments) |
| Custom OSS bucket for file uploads (replaces 48h temp storage). See custom-oss.md. |
| OSS region (required when is set). |
| / | OSS credentials (use RAM user with least-privilege: + ). Falls back to / if not set. |
API Key Types
QwenCloud has two mutually exclusive key types:
| Key Type | Format | Purpose | Endpoint |
|---|
| Standard (Pay-as-you-go) | | API calls from scripts, apps, and tools | dashscope-intl.aliyuncs.com
|
| Coding Plan | | Interactive AI coding tools only (Cursor, Claude Code, Qwen Code) | coding-intl.dashscope.aliyuncs.com
|
All qwencloud/qwencloud-ai scripts require a
standard key. Coding Plan keys cannot call QwenCloud APIs directly — they produce
on standard endpoints. Coding Plan supports only 8 text LLMs (qwen3.5-plus, kimi-k2.5, glm-5, MiniMax-M2.5, qwen3-max-2026-01-23, qwen3-coder-next, qwen3-coder-plus, glm-4.7) and excludes all image/video/TTS models.
If the user's key starts with
, guide them to obtain a standard key from the console below. See
codingplan.md for full details.
Viewing Bills
Use the qwencloud-usage skill to query usage, free tier quota, and billing directly. Alternatively, billing details are available in the QwenCloud console:
NEVER fabricate, guess, or construct usage/billing/console URLs. Only provide the exact links listed in this skill. If a URL is not listed here, do not invent one.
Getting an API Key
- Open the QwenCloud Console
- Sign in with your QwenCloud account
- Create or copy an API key from the API Key management section
- Standard keys start with (not which is Coding Plan only)
Security Best Practices
- Never hardcode API keys in source code or config files committed to version control
- Use environment variables or files (and add to )
- Rotate keys periodically and revoke compromised keys immediately
- Use least-privilege — create dedicated keys for specific applications when possible
Setting up
Create a
file in your project root or current working directory:
bash
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
The script automatically loads
from the current working directory and the project root (detected via
or
directory). Existing environment variables are
not overwritten by
values.
Example entry
Verification
Unless explicitly stated otherwise, any script or task mentioned in this skill runs in the foreground — wait for standard output; do not run it as a background task.
Test authentication with a simple curl request:
bash
curl -sS -X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"qwen-turbo","messages":[{"role":"user","content":"Hi"}]}'
A successful response returns JSON with
and
.
Authentication Error Handling
QwenCloud API keys are scoped to the QwenCloud console. An invalid or mismatched key produces
.
When to trigger
When
any sub-skill receives a
response and a non-plaintext check shows the key is set (e.g.
[ -n "$DASHSCOPE_API_KEY" ]
; do not output the key value).
Probe command
Send a lightweight request to verify authentication:
bash
curl -sS -o /dev/null -w "%{http_code}" \
-X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"qwen-turbo","messages":[{"role":"user","content":"hi"}]}'
On 401: mandatory interactive resolution
If the probe returns 401, follow these steps in order:
Step 1 — Confirm the key origin:
Your API key failed authentication.
Please confirm:
1. Your key was created at home.qwencloud.com (QwenCloud console) → re-verify the key
2. My key may be invalid → create a new one at home.qwencloud.com/api-keys
Step 2 — Apply the user's selection:
| User says | Action |
|---|
| Key is from QwenCloud console | Re-run verification to confirm the key works |
| Key may be invalid | Guide user to create a new key at home.qwencloud.com/api-keys
|
Step 3 — Re-run verification.
Step 4 — If still 401, the key itself is invalid — guide the user to create a new one from
the
QwenCloud console.
Validation
Run the curl verification command above. Pass criteria: HTTP 200 response with valid JSON containing
and
. Save output to
output/qwencloud-ops-auth/
for evidence.
Output And Evidence
- Save verification results and any diagnostic output to
output/qwencloud-ops-auth/
- Keep a record of successful auth tests for troubleshooting.
Output Location
Prefer the
current working directory. Default subdirectory:
./output/qwencloud-ops-auth/
.
Write prohibition: NEVER write output files into this skill's installation directory or any
hierarchy. All generated content must go to
under the current working directory or a user-specified path.
Update Check (MANDATORY Post-Execution)
When the user asks to check for updates (e.g. "check for updates", "check version", "is there a new version", "update skills"):
- Find qwencloud-update-check: Look for
qwencloud-update-check/SKILL.md
- If found — run:
python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response
- If not found — you MUST present the following options and wait for the user's response:
The update-check skill is not installed. It keeps you informed about new qwencloud/qwencloud-ai features and bug fixes.
- Install now — I'll run the install command for you
- Skip for now — do nothing this time
- Never remind me — permanently suppress this prompt
After the user responds:
- User chooses 1 → run:
npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y
python3 <this-skill-scripts-dir>/gossamer.py --dismiss
- User chooses 2 → run:
python3 <this-skill-scripts-dir>/gossamer.py --dismiss
- User chooses 3 → run:
python3 <this-skill-scripts-dir>/gossamer.py --never-install
References
- custom-oss.md — Custom OSS bucket setup for production file uploads
- sources.md — Official documentation URLs (consoles, auth guide)