返回技能市场
开发运维 安全 需要 API Key

千问AI-认证配置

@qianwen-ai/qianwen-ops-auth

配置身份认证（API 密钥、端点）。适用场景：设置 QIANWEN_API_KEY、排查 401/身份认证错误、其他 skill 报告凭证缺失，或用户明确按名称调用此 skill（例如使用 qianwen-ops-auth）。不适用场景：非身份认证类千问任务、一般的 API 使用问题。

千问AI平台 热度 292v0.0.2

QianWen 认证设置

配置并验证 QianWen API 的认证。 此技能是 QianWen-AI/qianwen-ai 的一部分。

技能目录

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

| 位置 | 用途 | |----------|---------| | references/tokenplan.md | Token Plan 与标准密钥：支持的模型（文本、图像、视频、TTS）、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 控制台 的实际 API 密钥。”
  1. 或者解释如何配置环境变量：export DASHSCOPE_API_KEY='sk-...' + 提供控制台 URL。
  2. 只有当用户明确坚持让代理代劳时，才将实际密钥值写入 .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](references/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 扩展 |

捆绑的执行技能接受两种密钥类型，并将 sk-sp- 请求路由到 Token Plan 端点。在 Token Plan 请求之前，请阅读 [tokenplan.md](references/tokenplan.md) 或其链接的官方 Markdown，并传递一个确切的受支持模型。不要探测模型或自动回退。

检测密钥类型（非明文）

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

echo ${DASHSCOPE_API_KEY:0:6}

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

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

查看账单

使用 qianwen-usage 技能直接查询用量、免费额度配额和账单。或者，QianWen 控制台提供账单详情：

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

绝不要伪造、猜测或构造用量/账单/控制台 URL。 仅提供此技能中列出的确切链接。如果此处未列出某个 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

验证

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

使用简单的 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。

何时触发

当任何子技能收到 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 功能和 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，然后继续正常流程

参考

  • [tokenplan.md](references/tokenplan.md) — Token Plan 与标准密钥：支持的模型、Credits 计费、禁止用途、错误代码
  • [custom-oss.md](references/custom-oss.md) — 用于生产文件上传的自定义 OSS 存储桶设置
  • [sources.md](references/sources.md) — 官方文档 URL（控制台、认证指南）
qianwen skills install @qianwen-ai/qianwen-ops-auth