qwencloud-ops-auth

QwenCloud 身份验证设置

配置并验证 QwenCloud API 的身份验证。 此技能属于 qwencloud/qwencloud-ai。

技能目录

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

位置	用途
references/tokenplan.md	Token Plan 与 Coding Plan、PAYG 的区别；CDN 模型目录、端点映射、定价、User-Agent
references/codingplan.md	Coding Plan 与标准密钥的区别：模型列表、端点映射、错误代码、成本风险
references/custom-oss.md	生产环境文件上传的自定义 OSS 存储桶设置（替代 48 小时临时存储）
references/sources.md	控制台 URL、身份验证指南（仅手动查找）

安全

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

API 密钥处理（强制）

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

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

凭证优先级链

凭证按以下顺序加载（以第一个匹配项为准）：

1. 环境变量 — DASHSCOPE_API_KEY（或别名 QWEN_API_KEY）
2. .env 文件 — 当前工作目录中的文件，然后是仓库根目录中的文件（通过 .git 或 skills/ 目录检测）。不会覆盖现有环境变量。

环境变量

变量	用途
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 密钥类型

QwenCloud 有三种互斥的密钥／套餐类型：

密钥类型	格式	用途	端点
标准（按量付费）	sk-xxxxx	用于脚本、应用和工具的 API 调用	dashscope-intl.aliyuncs.com
Token Plan	sk-sp-xxxxx	带有 User-Agent 标头的交互式 AI 工具	token-plan.ap-southeast-1.maas.aliyuncs.com
Coding Plan	sk-sp-xxxxx	仅用于交互式 AI 编码工具（Cursor、Claude Code、Qwen Code）	coding-intl.dashscope.aliyuncs.com

所有 qwencloud/qwencloud-ai 脚本都需要标准密钥（sk-）。Coding Plan 密钥（sk-sp-）在标准端点上会返回 401 invalid_api_key。脚本会自动将 Token Plan 密钥（sk-sp-）路由到 Token Plan 端点。发送 Token Plan 请求前，请获取并阅读当前的 Token Plan 模型目录，并传入目录中精确列出的模型；如果无法访问 CDN，请使用本地备用文件。Coding Plan 的详情请参阅 codingplan.md。

如果用户的密钥以 sk-sp- 开头，请先查看 tokenplan.md 了解 Token Plan 详情，并查看上方的 CDN 目录确认模型覆盖范围；然后查看 codingplan.md 了解 Coding Plan 的具体信息。如果需要使用其套餐之外的模型，请引导用户从下方控制台获取标准密钥。

查看账单

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

密钥类型	账单页面
标准（按量付费）	按量付费账单
Token Plan 个人版	个人账单
Token Plan 团队版	团队账单
Coding Plan	Coding Plan 账单
用量分析（两种套餐）	用量分析

切勿伪造、猜测或拼接用量／账单／控制台 URL。 只能提供此技能中列出的精确链接。如果此处未列出某个 URL，请勿自行编造。

获取 API 密钥

1. 打开 QwenCloud 控制台
2. 使用你的 QwenCloud 账号登录
3. 在 API 密钥管理区域创建或复制 API 密钥
4. 标准密钥以 sk- 开头（sk-sp- 仅适用于 Coding Plan）

安全最佳实践

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

设置 .env

在项目根目录或当前工作目录中创建 .env 文件：

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

脚本会自动从当前工作目录和项目根目录（通过 .git 或 skills/ 目录检测）加载 .env。已有的环境变量不会被 .env 中的值覆盖。

.gitignore 条目示例

.env
.env.local
*.env

验证

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

仅限 PAYG： 使用简单的 curl 请求测试身份验证。Token Plan：请勿使用 curl；使用目标技能附带的 Python 脚本进行验证。

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。

身份验证错误处理

QwenCloud API 密钥仅适用于 QwenCloud 控制台。无效或不匹配的密钥会返回 401 Unauthorized。

触发条件

当任何子技能收到 401 响应，且非明文检查显示密钥已设置时（例如 [ -n "$DASHSCOPE_API_KEY" ]；不要输出密钥值）。

探测命令

对于 PAYG，发送轻量级请求以验证身份验证。在 Token Plan 模式下，不要使用 curl；请改为运行目标技能自带的 Python 脚本。

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

收到 401 时：必须进行交互式处理

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

步骤 1 — 确认密钥来源：

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

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

用户表示	操作
密钥来自 QwenCloud 控制台	重新运行验证，确认密钥有效
密钥可能无效	指引用户前往 home.qwencloud.com/api-keys 创建新密钥

步骤 3 — 重新运行验证。

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

验证

对于 PAYG，运行上述 curl 验证。对于 Token Plan，请改为运行目标技能自带的 Python 脚本。 通过标准：HTTP 200 且输出有效。将证据保存到 output/qwencloud-ops-auth/。

输出与证据

• 将验证结果和任何诊断输出保存到 output/qwencloud-ops-auth/。
• 保留成功身份验证测试的记录，以供排查问题。

输出位置

优先使用当前工作目录。默认子目录：./output/qwencloud-ops-auth/。

禁止写入：绝不要将输出文件写入此技能的安装目录或任何 skills/ 层级目录。所有生成的内容都必须写入当前工作目录下的 output/，或用户指定的路径。

更新检查（执行后必须进行）

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

1. 查找 qwencloud-update-check：在同级技能目录中查找 qwencloud-update-check/SKILL.md。
2. 如果找到 — 运行：python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response，并报告结果。如果用户要求强制检查，则使用 --force。
3. 如果未找到 — 必须向用户提供以下选项，并等待用户回复：

未安装更新检查技能。它会让你及时了解 qwencloud/qwencloud-ai 的新功能和错误修复。

1. 立即安装 — 我将为你运行安装命令
2. 暂时跳过 — 本次不执行任何操作
3. 不再提醒 — 永久取消此提示

用户回复后：

• 用户选择 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，然后正常继续

参考资料

• tokenplan.md — Token Plan 与标准密钥的区别；CDN 模型目录说明、Credits 计费和端点指南
• codingplan.md — Coding Plan 兼容性与错误指南
• custom-oss.md — 生产环境文件上传的自定义 OSS 存储桶设置
• sources.md — 官方文档 URL（控制台、身份验证指南）