qwencloud-ops-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent setup: If your agent doesn't auto-load skills (e.g. Claude Code), see agent-compatibility.md once per session.

Agent配置：如果你的Agent不会自动加载技能（例如Claude Code），请在每个会话中查看agent-compatibility.md。

QwenCloud Authentication Setup

QwenCloud身份验证配置

Configure and verify authentication for QwenCloud APIs. This skill is part of qwencloud/qwencloud-ai.

配置并验证QwenCloud API的身份验证。此技能属于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
`references/codingplan.md`	Coding Plan vs standard key: model list, endpoint mapping, error codes, cost risks
`references/custom-oss.md`	Custom OSS bucket setup for production file uploads (replaces 48h temp storage)
`references/sources.md`	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

使用此技能的内部文件进行学习。仅当用户需要控制台或文档链接时才加载参考资料。

位置	用途
`references/codingplan.md`	编码计划密钥与标准密钥对比：模型列表、端点映射、错误代码、成本风险
`references/custom-oss.md`	用于生产环境文件上传的自定义OSS存储桶配置（替代48小时临时存储）
`references/sources.md`	控制台URL、身份验证指南（仅手动查询使用）
`references/agent-compatibility.md`	Agent自检：对于不会自动加载技能的Agent，需在项目配置中注册技能

Security

安全说明

NEVER output any API key, OSS credential in plaintext. This applies equally to

DASHSCOPE_API_KEY

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密钥、OSS凭证。 此规则同样适用于

DASHSCOPE_API_KEY

和自定义OSS AccessKey密钥对。此技能中对凭证的任何检查或检测都必须采用非明文形式：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”、HTTP状态码），绝不能输出密钥值。

API Key Handling (MANDATORY)

API密钥处理（强制要求）

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
.env
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
```
sk-your-key-here
```
  with your actual API key from the QwenCloud Console."
Or explain how to configure the environment variable:
```
export DASHSCOPE_API_KEY='sk-...'
```
+ provide the console URL.
Only write the actual key value into
```
.env
```
if the user explicitly insists on having the agent do it for them.

当未配置API密钥或脚本报告缺少凭证时：

绝对不要直接要求用户提供API密钥。不要提示“请粘贴你的API密钥”或类似内容。不要以任何形式请求密钥值。
帮助创建
.env
文件并添加占位符，然后指导用户填写自己的密钥：
- 执行命令：
```
echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
```
- 告知用户：“请将
```
sk-your-key-here
```
  替换为你从QwenCloud控制台获取的实际API密钥。”
或者说明如何配置环境变量：
```
export DASHSCOPE_API_KEY='sk-...'
```
+ 提供控制台URL。
仅当用户明确坚持让Agent代劳时，才将实际密钥值写入
```
.env
```
文件。

Credential Priority Chain

凭证优先级顺序

Credentials are loaded in the following order (first match wins):

Environment variable —
```
DASHSCOPE_API_KEY
```
(or
```
QWEN_API_KEY
```
alias)
.env
file — in current working directory, then repo root (detected via
```
.git
```
or
```
skills/
```
directory). Existing environment variables are not overwritten.

凭证按以下顺序加载（匹配到第一个即生效）：

环境变量 —
```
DASHSCOPE_API_KEY
```
（或别名
```
QWEN_API_KEY
```
）
.env
文件 — 先从当前工作目录加载，再从仓库根目录加载（通过
```
.git
```
或
```
skills/
```
目录检测）。已存在的环境变量不会被
```
.env
```
文件的值覆盖。

Environment Variables

环境变量说明

Variable	Purpose
`DASHSCOPE_API_KEY`	API key (required)
`QWEN_API_KEY`	Alias for `DASHSCOPE_API_KEY` . If both are set, `QWEN_API_KEY` takes priority.
`QWEN_BASE_URL`	Override default endpoint (optional; for custom deployments)
`QWEN_TMP_OSS_BUCKET`	Custom OSS bucket for file uploads (replaces 48h temp storage). See custom-oss.md.
`QWEN_TMP_OSS_REGION`	OSS region (required when `QWEN_TMP_OSS_BUCKET` is set).
`QWEN_TMP_OSS_AK_ID` / `AK_SECRET`	OSS credentials (use RAM user with least-privilege: `oss:PutObject` + `oss:GetObject` ). Falls back to `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` if not set.

变量名	用途
`DASHSCOPE_API_KEY`	API密钥（必填）
`QWEN_API_KEY`	`DASHSCOPE_API_KEY` 的别名。如果两者都已设置， `QWEN_API_KEY` 优先级更高。
`QWEN_BASE_URL`	覆盖默认端点（可选；适用于自定义部署场景）
`QWEN_TMP_OSS_BUCKET`	用于文件上传的自定义OSS存储桶（替代48小时临时存储）。详情请见custom-oss.md。
`QWEN_TMP_OSS_REGION`	OSS地域（当设置 `QWEN_TMP_OSS_BUCKET` 时必填）。
`QWEN_TMP_OSS_AK_ID` / `AK_SECRET`	OSS凭证（使用最小权限的RAM用户：仅授予 `oss:PutObject` + `oss:GetObject` 权限）。如果未设置，将回退使用 `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` 。

API Key Types

API密钥类型

QwenCloud has two mutually exclusive key types:

Key Type	Format	Purpose	Endpoint
Standard (Pay-as-you-go)	`sk-xxxxx`	API calls from scripts, apps, and tools	`dashscope-intl.aliyuncs.com`
Coding Plan	`sk-sp-xxxxx`	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

403 invalid api-key

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

sk-sp-

, guide them to obtain a standard key from the console below. See codingplan.md for full details.

QwenCloud有两种互斥的密钥类型：

密钥类型	格式	用途	端点
标准（按量付费）	`sk-xxxxx`	供脚本、应用和工具调用API	`dashscope-intl.aliyuncs.com`
编码计划	`sk-sp-xxxxx`	仅适用于交互式AI编码工具（Cursor、Claude Code、Qwen Code）	`coding-intl.dashscope.aliyuncs.com`

所有qwencloud/qwencloud-ai脚本都需要标准密钥。编码计划密钥无法直接调用QwenCloud API——在标准端点上会返回

403 invalid api-key

错误。编码计划仅支持8个文本大语言模型（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），不包含所有图像/视频/TTS模型。

如果用户的密钥以

sk-sp-

开头，指导他们从下方控制台获取标准密钥。详情请见codingplan.md。

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:

Key Type	Billing Page
Standard (Pay-as-you-go)	Pay-as-you-go Billing
Coding Plan	Coding Plan Billing
Usage analytics (both)	Usage Analytics

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.

使用qwencloud-usage技能直接查询使用量、免费层配额和账单信息。或者，也可以在QwenCloud控制台查看账单详情：

密钥类型	账单页面
标准（按量付费）	按量付费账单
编码计划	编码计划账单
使用分析（两种类型通用）	使用分析

**绝对不要编造、猜测或构造使用/账单/控制台URL。**仅提供本技能中列出的准确链接。如果此处未列出某个URL，请勿自行创建。

Getting an API Key

获取API密钥

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
```
sk-
```
(not
```
sk-sp-
```
which is Coding Plan only)

打开QwenCloud控制台
使用你的QwenCloud账号登录
在API密钥管理区域创建或复制一个API密钥
标准密钥以
```
sk-
```
开头（而非仅适用于编码计划的
```
sk-sp-
```
）

Security Best Practices

安全最佳实践

Never hardcode API keys in source code or config files committed to version control
Use environment variables or
```
.env
```
files (and add
```
.env
```
to
```
.gitignore
```
)
Rotate keys periodically and revoke compromised keys immediately
Use least-privilege — create dedicated keys for specific applications when possible

永远不要在源代码或提交到版本控制的配置文件中硬编码API密钥
使用环境变量或
```
.env
```
文件（并将
```
.env
```
添加到
```
.gitignore
```
中）
定期轮换密钥，并立即撤销泄露的密钥
遵循最小权限原则——尽可能为特定应用创建专用密钥

Setting up

.env

配置

.env

文件

Create a

.env

file in your project root or current working directory:

bash

echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env

The script automatically loads

.env

from the current working directory and the project root (detected via

.git

skills/

directory). Existing environment variables are not overwritten by

.env

values.

.env

文件：

bash

echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env

脚本会自动从当前工作目录和项目根目录（通过

.git

或

skills/

目录检测）加载

.env

文件。已存在的环境变量不会被

.env

文件的值覆盖。

Example

.gitignore

entry

.gitignore

示例条目

.env
.env.local
*.env

.env
.env.local
*.env

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

choices

and

message.content

除非另有明确说明，本技能中提到的任何脚本或任务都在前台运行——等待标准输出，不要作为后台任务运行。

使用简单的curl请求测试身份验证：

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"}]}'

成功的响应会返回包含

choices

和

message.content

的JSON数据。

Authentication Error Handling

身份验证错误处理

QwenCloud API keys are scoped to the QwenCloud console. An invalid or mismatched key produces

401 Unauthorized

QwenCloud API密钥与QwenCloud控制台绑定。无效或不匹配的密钥会返回

401 Unauthorized

错误。

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).

当任何子技能收到

响应，且非明文检查显示密钥已设置（例如

[ -n "$DASHSCOPE_API_KEY" ]

；不要输出密钥值）时触发。

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"}]}'

发送轻量级请求以验证身份验证状态：

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

收到401错误时：强制交互式解决流程

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.

如果探测返回401，请按顺序执行以下步骤：

步骤1 — 确认密钥来源：

你的API密钥身份验证失败。

请确认：
1. 你的密钥是在home.qwencloud.com（QwenCloud控制台）创建的 → 重新验证密钥
2. 我的密钥可能无效 → 在home.qwencloud.com/api-keys创建新密钥

步骤2 — 根据用户选择执行操作：

用户表述	操作
密钥来自QwenCloud控制台	重新运行验证以确认密钥可用
密钥可能无效	指导用户在 `home.qwencloud.com/api-keys` 创建新密钥

步骤3 — 重新运行验证。

步骤4 — 如果仍然返回401，说明密钥本身无效——指导用户从QwenCloud控制台创建新密钥。

Validation

验证标准

Run the curl verification command above. Pass criteria: HTTP 200 response with valid JSON containing

choices

and

message.content

. Save output to

output/qwencloud-ops-auth/

for evidence.

运行上述curl验证命令。通过标准：返回HTTP 200响应，且包含

choices

和

message.content

的有效JSON数据。将输出保存到

output/qwencloud-ops-auth/

作为验证依据。

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/qwencloud-ops-auth/
```
。
保留成功身份验证测试的记录，以便后续排查问题。

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

skills/

hierarchy. All generated content must go to

output/

under the current working directory or a user-specified path.

优先使用当前工作目录。默认子目录：

./output/qwencloud-ops-auth/

。

写入禁止：绝对不要将输出文件写入此技能的安装目录或任何

skills/

层级目录。所有生成的内容必须保存到当前工作目录下的

output/

或用户指定的路径中。

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
```
in sibling skill directories.

If found — run:

python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response

and report the result. Use

--force

if the user asks to force-check.

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

, then run:

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

User chooses 2 → run:

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

, then continue normally

User chooses 3 → run:

python3 <this-skill-scripts-dir>/gossamer.py --never-install

, then continue normally

当用户要求检查更新时（例如“检查更新”、“查看版本”、“是否有新版本”、“更新技能”）：

查找qwencloud-update-check：在同级技能目录中查找
```
qwencloud-update-check/SKILL.md
```
。
如果找到 — 执行命令：
```
python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response
```
并报告结果。如果用户要求强制检查，添加
```
--force
```
参数。
如果未找到 — 必须提供以下选项并等待用户响应：

更新检查技能未安装。它会通知你qwencloud/qwencloud-ai的新功能和bug修复。

立即安装 — 我将为你运行安装命令

暂时跳过 — 本次不执行任何操作

永远不再提醒 — 永久禁用此提示

用户响应后：

用户选择1 → 执行命令：

npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y

，然后执行：

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

用户选择2 → 执行命令：

python3 <this-skill-scripts-dir>/gossamer.py --dismiss

，然后正常继续

用户选择3 → 执行命令：

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)

custom-oss.md — 用于生产环境文件上传的自定义OSS存储桶配置
sources.md — 官方文档URL（控制台、身份验证指南）

qwencloud-ops-auth

Original

Translation

QwenCloud Authentication Setup

QwenCloud身份验证配置

Skill directory

技能目录

Security

安全说明

API Key Handling (MANDATORY)

API密钥处理（强制要求）

Credential Priority Chain

凭证优先级顺序

Environment Variables

环境变量说明

API Key Types

API密钥类型

Viewing Bills

查看账单

Getting an API Key

获取API密钥

Security Best Practices

安全最佳实践

Setting up .env

配置.env文件

Example .gitignore entry

.gitignore示例条目

Verification

验证

Authentication Error Handling

身份验证错误处理

When to trigger

触发时机

Probe command

探测命令

On 401: mandatory interactive resolution

收到401错误时：强制交互式解决流程

Validation

验证标准

Output And Evidence

输出与验证依据

Output Location

输出位置

Update Check (MANDATORY Post-Execution)

更新检查（执行后强制要求）

References

参考资料

Setting up
`.env`

配置
`.env`
文件

Example
`.gitignore`
entry

`.gitignore`
示例条目