Back to Details

qianwen-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无法自动加载skills（例如Claude Code），请在每个会话中查看一次agent-compatibility.md。

QianWen Authentication Setup

QianWen 认证设置

Configure and verify authentication for QianWen APIs. This skill is part of QianWen-AI/qianwen-ai.
配置并验证QianWen API的认证。 此skill属于QianWen-AI/qianwen-ai。

Skill directory

Skill 目录

Use this skill's internal files for learning. Load references only when the user needs console or documentation links.
LocationPurpose
references/tokenplan.md
Token Plan 团队版 vs standard key: endpoint mapping, supported models (4 text + 4 image), Credits billing, error codes
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
使用此skill的内部文件进行学习。仅当用户需要控制台或文档链接时才加载参考资料。
位置用途
references/tokenplan.md
Token Plan 团队版与标准密钥对比：端点映射、支持的模型（4个文本模型+4个图像模型）、 Credits计费、错误码
references/custom-oss.md
生产环境文件上传的自定义OSS存储桶设置（替代48小时临时存储）
references/sources.md
控制台URL、认证指南（仅手动查找）
references/agent-compatibility.md
Agent自检：对于无法自动加载skills的agent，在项目配置中注册skills

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密钥对。此skill中对凭证的任何检查或检测都必须采用非明文方式：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”、HTTP状态码），绝不能输出密钥值。

API Key Handling (MANDATORY)

API密钥处理（强制要求）

When the API key is not configured or a script reports missing credentials:
  1. 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.
  2. 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 QianWen Console."
  3. Or explain how to configure the environment variable: 
    export DASHSCOPE_API_KEY='sk-...'
    + provide the console URL.
  4. Only write the actual key value into 
    .env
    if the user explicitly insists on having the agent do it for them.
当API密钥未配置或脚本报告凭证缺失时：
  1. 切勿直接要求用户提供API密钥。不要提示“请粘贴你的API密钥”或类似内容。不要以任何形式请求密钥值。
  2. 帮助创建
    .env
    文件    并添加占位符，然后指导用户填写自己的密钥：
    • 运行：
      echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
    • 告知用户：“请将
      sk-your-key-here
      替换为你从QianWen控制台获取的实际API密钥。”
  3. 或者说明如何配置环境变量：
    export DASHSCOPE_API_KEY='sk-...'
    + 提供控制台URL。
  4. 仅当用户明确坚持让agent代劳时，才将实际密钥值写入
    .env
    文件。

Credential Priority Chain

凭证优先级顺序

Credentials are loaded in the following order (first match wins):
  1. Environment variable — 
    DASHSCOPE_API_KEY
    (or 
    QIANWEN_API_KEY
    alias)
  2. .env
    file     — in current working directory, then repo root (detected via 
    .git
    or 
    skills/
    directory). Existing environment variables are not overwritten.
凭证按以下顺序加载（匹配到第一个即生效）：
  1. 环境变量 — 
    DASHSCOPE_API_KEY
    （或别名
    QIANWEN_API_KEY
    ）
  2. .env
    文件     — 当前工作目录，然后是仓库根目录（通过
    .git
    或
    skills/
    目录检测）。已存在的环境变量不会被覆盖。

Environment Variables

环境变量

VariablePurpose
DASHSCOPE_API_KEY
API key (required)
QIANWEN_API_KEY
Alias for 
DASHSCOPE_API_KEY
. If both are set, 
QIANWEN_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密钥（必填）
QIANWEN_API_KEY
DASHSCOPE_API_KEY
的别名。如果两者都已设置，
QIANWEN_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密钥类型

QianWen has two mutually exclusive key types:
Key TypeFormatPurposeEndpoint
Standard (Pay-as-you-go)
sk-xxxxx
API calls from scripts, apps, and tools
dashscope.aliyuncs.com
Token Plan (团队版)
sk-sp-xxxxx
Interactive AI tools only (Cursor, Claude Code, Qwen Code, OpenClaw, OpenCode, Codex, Kilo Code/CLI, Hermes Agent)
token-plan.cn-beijing.maas.aliyuncs.com
All QianWen-AI/qianwen-ai execution scripts require a standard 
sk-
key on 
dashscope.aliyuncs.com
. Token Plan keys (
sk-sp-
) cannot be used by these scripts — they target a different endpoint (
token-plan.cn-beijing.maas.aliyuncs.com
) and produce 
InvalidApiKey: Invalid API-key provided
on standard endpoints. Token Plan 团队版 supports only 4 text LLMs (qwen3.6-plus, glm-5, MiniMax-M2.5, deepseek-v3.2) plus 4 image generation models (qwen-image-2.0, qwen-image-2.0-pro, wan2.7-image, wan2.7-image-pro, accessed via tool Skill/extension mechanism only). Video, TTS, ASR, embedding, and other modalities are not supported.
If the user's key starts with 
sk-sp-
, guide them to obtain a standard key from the console below. See tokenplan.md for full details.
QianWen有两种互斥的密钥类型：
密钥类型格式用途端点
标准（按量付费）
sk-xxxxx
用于脚本、应用和工具的API调用
dashscope.aliyuncs.com
Token Plan（团队版）
sk-sp-xxxxx
仅用于交互式AI工具（Cursor、Claude Code、Qwen Code、OpenClaw、OpenCode、Codex、Kilo Code/CLI、Hermes Agent）
token-plan.cn-beijing.maas.aliyuncs.com
所有QianWen-AI/qianwen-ai执行脚本需要在
dashscope.aliyuncs.com
端点使用标准
sk-
密钥。Token Plan密钥（
sk-sp-
）无法用于这些脚本——它们针对不同的端点（
token-plan.cn-beijing.maas.aliyuncs.com
），在标准端点会返回
InvalidApiKey: Invalid API-key provided
错误。Token Plan团队版仅支持4个文本大语言模型（qwen3.6-plus、glm-5、MiniMax-M2.5、deepseek-v3.2）以及4个图像生成模型（qwen-image-2.0、qwen-image-2.0-pro、wan2.7-image、wan2.7-image-pro，仅通过工具Skill/扩展机制访问）。不支持视频、TTS、ASR、嵌入及其他模态。
如果用户的密钥以
sk-sp-
开头，指导他们从下方控制台获取标准密钥。详见tokenplan.md的完整说明。

Viewing Bills

查看账单

Use the qianwen-usage skill to query usage, free tier quota, and billing directly. Alternatively, billing details are available in the QianWen console:
Key TypeBilling Page
Standard (Pay-as-you-go)Pay-as-you-go Billing
Token Plan 团队版Token Plan Subscription
Usage analytics (Pay-as-you-go)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.
使用qianwen-usageskill直接查询使用量、免费额度和计费信息。或者，账单详情可在QianWen控制台查看：
密钥类型账单页面
标准（按量付费）按量付费账单
Token Plan（团队版）Token Plan订阅
使用分析（按量付费）使用分析
切勿编造、猜测或构造使用/计费/控制台URL。仅提供此skill中列出的准确链接。如果此处未列出某个URL，请勿自行创建。

Getting an API Key

获取API密钥

  1. Open the QianWen Console
  2. Sign in with your QianWen account
  3. Create or copy an API key from the API Key management section
  4. Standard keys start with 
    sk-
    (not 
    sk-sp-
    which is Token Plan 团队版 only)
  1. 打开QianWen控制台
  2. 使用你的QianWen账号登录
  3. 在API密钥管理区域创建或复制API密钥
  4. 标准密钥以
    sk-
    开头（而非仅用于Token Plan团队版的
    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
or 
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.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
.
除非另有明确说明，此skill中提及的任何脚本或任务都在前台运行——等待标准输出；不要作为后台任务运行。
使用简单的curl请求测试认证：
bash
curl -sS -X POST "https://dashscope.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

认证错误处理

QianWen API keys are scoped to the QianWen console. An invalid or mismatched key produces 
401 Unauthorized
.
QianWen API密钥绑定到QianWen控制台。无效或不匹配的密钥会返回
401 Unauthorized
错误。

When to trigger

触发时机

When any sub-skill receives a 
401
response and a non-plaintext check shows the key is set (e.g. 
[ -n "$DASHSCOPE_API_KEY" ]
; do not output the key value).
当任何子skill收到
401
响应，且非明文检查显示密钥已设置时（例如
[ -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.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.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 platform.qianwenai.com/home (QianWen console) → re-verify the key
2. My key may be invalid → create a new one at platform.qianwenai.com/home/api-keys
Step 2 — Apply the user's selection:
User saysAction
Key is from QianWen consoleRe-run verification to confirm the key works
Key may be invalidGuide user to create a new key at 
platform.qianwenai.com/home/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 QianWen console.
如果探测返回401，请按以下顺序执行步骤：
步骤1 — 确认密钥来源：
你的API密钥认证失败。

请确认：
1. 你的密钥是在platform.qianwenai.com/home（QianWen控制台）创建的 → 重新验证密钥
2. 我的密钥可能无效 → 在platform.qianwenai.com/home/api-keys创建新密钥
步骤2 — 执行用户的选择：
用户反馈操作
密钥来自QianWen控制台重新运行验证以确认密钥可用
密钥可能无效指导用户在
platform.qianwenai.com/home/api-keys
创建新密钥
步骤3 — 重新运行验证。
步骤4 — 如果仍然返回401，说明密钥本身无效——指导用户从QianWen控制台创建新密钥。

Validation

验证标准

Run the curl verification command above. Pass criteria: HTTP 200 response with valid JSON containing 
choices
and 
message.content
. Save output to 
output/qianwen-ops-auth/
for evidence.
运行上述curl验证命令。通过标准：返回HTTP 200响应，且包含
choices
和
message.content
的有效JSON。将输出保存到
output/qianwen-ops-auth/
作为凭证。

Output And Evidence

输出与凭证

  • Save verification results and any diagnostic output to 
    output/qianwen-ops-auth/
    .
  • Keep a record of successful auth tests for troubleshooting.
  • 将验证结果和任何诊断输出保存到
    output/qianwen-ops-auth/
    。
  • 保留成功认证测试的记录用于故障排查。

Output Location

输出位置

Prefer the current working directory. Default subdirectory: 
./output/qianwen-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/qianwen-ops-auth/
。
禁止写入：切勿将输出文件写入此skill的安装目录或任何
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"):
  1. Find qianwen-update-check: Look for 
    qianwen-update-check/SKILL.md
    in sibling skill directories.
  2. If found — run: 
    python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response
    and report the result. Use 
    --force
    if the user asks to force-check.
  3. 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 QianWen-AI/qianwen-ai features and bug fixes.
  1. Install now — I'll run the install command for you
  2. Skip for now — do nothing this time
  3. Never remind me — permanently suppress this prompt
After the user responds:
  • User chooses 1 → run: 
    npx skills add QianWen-AI/qianwen-ai --skill qianwen-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
当用户要求检查更新时（例如“check for updates”、“check version”、“is there a new version”、“update skills”）：
  1. 查找qianwen-update-check：在同级skill目录中查找
    qianwen-update-check/SKILL.md
    。
  2. 如果找到 — 运行：
    python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response
    并报告结果。如果用户要求强制检查，添加
    --force
    参数。
  3. 如果未找到 — 你必须提供以下选项并等待用户响应：
更新检查skill未安装。它会通知你QianWen-AI/qianwen-ai的新功能和bug修复。
  1. 立即安装 — 我将为你运行安装命令
  2. 暂时跳过 — 本次不执行任何操作
  3. 永不提醒 — 永久禁用此提示
用户响应后：
  • 用户选择1 → 运行：
    npx skills add QianWen-AI/qianwen-ai --skill qianwen-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

参考资料

  • tokenplan.md — Token Plan 团队版 vs standard key: endpoints, supported models, Credits billing, error codes
  • custom-oss.md — Custom OSS bucket setup for production file uploads
  • sources.md — Official documentation URLs (consoles, auth guide)
  • tokenplan.md — Token Plan团队版与标准密钥对比：端点、支持的模型、Credits计费、错误码
  • custom-oss.md — 生产环境文件上传的自定义OSS存储桶设置
  • sources.md — 官方文档URL（控制台、认证指南）