qianwen-ops-auth

QianWen 身份验证设置

配置并验证 QianWen API 的身份验证。 此技能属于 QianWen-AI/qianwen-ai。

技能目录

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

位置	用途
references/tokenplan.md	Token Plan 与标准密钥的区别；提供指向受支持模型 CDN 目录的链接，并保留 Credits、政策和错误指南
references/custom-oss.md	用于生产环境文件上传的自定义 OSS 存储桶设置（替代 48h 临时存储）
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 替换为您从 QianWen Console 获取的实际 API 密钥。”
3. 或者说明如何配置环境变量：export DASHSCOPE_API_KEY='sk-...'，并提供控制台 URL。
4. 只有当用户明确坚持要 Agent 代为填写时，才将实际密钥值写入 .env。

凭证优先级链

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

1. 环境变量 — DASHSCOPE_API_KEY（或别名 QIANWEN_API_KEY）
2. .env 文件 — 先在当前工作目录查找，再查找仓库根目录（通过 .git 或 skills/ 目录检测）。不会覆盖现有环境变量。

环境变量

变量	用途
DASHSCOPE_API_KEY	API 密钥（必需）
QIANWEN_API_KEY	DASHSCOPE_API_KEY 的别名。如果两者均已设置，则优先使用 QIANWEN_API_KEY。
QWEN_BASE_URL	覆盖端点（可选；用于自定义部署或特定套餐的 Base URL）
QWEN_TMP_OSS_BUCKET	用于文件上传的自定义 OSS 存储桶（替代 48h 临时存储）。参见 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 密钥类型

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

密钥类型	格式	用途
标准（按量付费）	sk-ws-xxxxx（旧版 sk-xxxxx）	脚本、应用和工具发起的 API 调用
Token Plan	sk-sp-xxxxx	交互式 AI 工具，以及这些工具代表当前用户调用的 Skill/Agent 扩展

捆绑的执行 Skills 同时接受这两种密钥类型，并将 sk-sp- 请求路由到 Token Plan 端点。发起 Token Plan 请求前，请获取并读取最新的 Token Plan 模型目录，并传入确切的受支持模型。不要探测模型，也不要自动回退。如果 CDN 无法访问，请使用本地备用文件。

检测密钥类型（不显示明文）

如需在不完整暴露 API 密钥的情况下确定调用模式，请检查前缀（前 6 个字符）：

echo ${DASHSCOPE_API_KEY:0:6}

前缀输出	密钥类型	计费模式
sk-sp-	Token Plan	基于额度；模型目录有限
sk-ws- 或其他 sk-...	标准（按量付费）	按 Token 计费；完整模型目录

如果无法访问 Shell，请询问用户其密钥是否以 sk-sp- 开头。

查看账单

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

密钥类型	账单页面
标准（按量付费）	按量付费账单
Token Plan	Token Plan 订阅
用量分析（按量付费）	用量分析

绝不可编造、猜测或拼接用量、账单或控制台 URL。 只能提供本 skill 中列出的确切链接。如果此处未列出某个 URL，请勿杜撰。

获取 API 密钥

1. 打开 QianWen 控制台
2. 使用 QianWen 账号登录
3. 在 API Key 管理部分创建或复制 API 密钥
4. PAYG 密钥以 sk-ws- 开头（旧版为 sk-）；Token Plan 密钥以 sk-sp- 开头

安全最佳实践

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

设置 .env

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

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

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

.gitignore 条目示例

.env
.env.local
*.env

验证

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

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

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。

身份验证错误处理

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

触发条件

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

探测命令

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

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

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

如果探测返回 401，请按以下步骤依次操作：

步骤 1 — 确认密钥来源：

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

步骤 2 — 根据用户的选择采取操作：

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

步骤 3 — 重新运行验证。

步骤 4 — 如果仍然返回 401，则密钥本身无效 — 引导用户前往 QianWen 控制台 创建新密钥。

验证

运行上方的 curl 验证命令。通过标准：HTTP 200 响应，并且包含 choices 和 message.content 的有效 JSON。将输出保存到 output/qianwen-ops-auth/ 作为证据。

输出与证据

• 将验证结果和任何诊断输出保存到 output/qianwen-ops-auth/。
• 保留成功身份验证测试的记录，以便进行故障排查。

输出位置

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

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

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

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

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

未安装更新检查技能。该技能会及时告知你 QianWen-AI/qianwen-ai 的新功能和错误修复。

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，然后照常继续

参考资料

• tokenplan.md — Token Plan 与标准密钥的区别；CDN 模型目录指针、Credits 计费、禁止用途、错误代码
• custom-oss.md — 用于生产环境文件上传的自定义 OSS 存储桶设置
• sources.md — 官方文档 URL（控制台、身份验证指南）