| name | tencentads-auth |
| description | 腾讯营销（原腾讯广告）技能鉴权凭证管理技能，负责检查 APIKEY 是否有效，当腾讯营销(tencent-ads)系列技能返回认证错误时引导用户提供 APIKEY 并保存(⚠️重要提醒⚠️：腾讯营销 APIKEY 必须通过该技能保存)，所有 tencent-ads 技能共享。 |
| license | MIT. See LICENSE for full terms. |
| compatibility | any |
| metadata | {"author":"Tencent Ads Delivery Team","version":"0.5.7","icon":"key","category":"tencent-ads","openclaw":{"emoji":"🔑"}} |
腾讯广告鉴权引导
前置依赖：需安装 tencentads-cli（Node.js ≥ 20）。执行 npm install -g tencentads-cli@latest 安装或升级；版本过低时 tencentads 会给出提示。
安全原则: API Key 等敏感凭证不应在对话窗口中回显。Agent 收到 API Key 后应立即调用保存脚本，不要在回复中重复展示凭据内容。
本技能引导用户完成腾讯广告 API Key 鉴权配置。
CLI 版本说明
tencentads-cli 包含两个不同的命令入口，功能和版本线完全独立：
| 命令 | 说明 | 状态 |
|---|
tencentads | 基于 Go 实现的新版 CLI，支持 tencentads auth 一键授权 | 当前推荐 |
tencentads-cli | 基于 Node.js/TypeScript 实现的旧版 CLI | 不再升级，仅作向后兼容 |
安装 tencentads-cli@latest 后两个命令均可用，但本技能所有授权操作均使用 tencentads 命令。
检查 CLI 版本
tencentads --version
如版本过低，tencentads 执行时会自动提示，按提示执行 npm install -g tencentads-cli@latest 升级。
鉴权方式
使用 X-MKT-API-Key header 直接调用 api.e.qq.com API。
一键授权（推荐）
使用 tencentads auth 命令完成授权，无需手动传入 API Key：
tencentads auth login
执行后会打开浏览器引导用户在腾讯广告平台完成授权。授权完成后自动保存凭据，所有腾讯营销投放（tencentads-*）技能即可使用。
验证授权状态
tencentads auth status
返回 "status": "active" 表示授权有效。
退出授权
tencentads auth logout
手动配置 API Key（备用方式）
如无法使用浏览器授权，可在对话中手动提供 API Key：
脚本调用说明
执行脚本前需先 cd 到技能根目录：
cd skills/tencentads-auth
- 不要向脚本传 JSON 字符串，避免不同操作系统和终端下的转义/引号兼容性问题
- 统一使用显式命令行参数，例如
--api-key <value>
auth-status.mjs 无需额外参数
前置检查
node scripts/auth-status.mjs
如果返回 "status": "active"，说明凭据仍有效，无需重新鉴权。
步骤
-
告知用户：
请提供你的腾讯广告 API Key（格式：mkt_ 开头的字符串）。
API Key 可从腾讯广告平台的开发者设置中获取。
-
收到用户发送的 API Key 后，不要在回复中回显凭据内容，立即调用保存脚本：
node scripts/auth-save-apikey.mjs --api-key <用户发送的API Key>
-
验证保存成功：
node scripts/auth-status.mjs
鉴权流程总结
- 优先使用
tencentads auth login 完成一键授权
- 如无法使用浏览器，改用手动提供 API Key 方式
- 所有腾讯营销投放（
tencentads-*）技能自动共享该凭据（通过 callApi 内部自动读取）
认证失败处理
当 callApi 返回以下错误时，应触发本技能重新鉴权：
未找到腾讯广告认证凭据 — 凭据未配置AUTH_REQUIRED — 凭据未配置AUTH_EXPIRED — 凭据已过期或无效Authentication is not valid — 服务端拒绝认证
处理流程
- 告知用户认证已失效，需要重新配置
- 优先引导用户执行
tencentads auth login 重新授权
- 如无法使用浏览器，引导用户提供新的 API Key 并调用
auth-save-apikey.mjs 保存
- 鉴权成功后，自动重试引发错误的原始操作
相关技能
- 所有腾讯营销投放（
tencentads-*）技能在遇到认证错误时应引用本技能
- 鉴权凭据由
callApi 内部自动读取，各技能脚本无需手动处理鉴权
