tencentads-auth

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"，说明凭据仍有效，无需重新鉴权。

步骤

1. 告知用户：

   请提供你的腾讯广告 API Key（格式：mkt_ 开头的字符串）。 API Key 可从腾讯广告平台的开发者设置中获取。

2. 收到用户发送的 API Key 后，不要在回复中回显凭据内容，立即调用保存脚本：

   node scripts/auth-save-apikey.mjs --api-key <用户发送的API Key>
   

3. 验证保存成功：

   node scripts/auth-status.mjs
   

鉴权流程总结

1. 优先使用 tencentads auth login 完成一键授权
2. 如无法使用浏览器，改用手动提供 API Key 方式
3. 所有腾讯营销投放（tencentads-*）技能自动共享该凭据（通过 callApi 内部自动读取）

认证失败处理

当 callApi 返回以下错误时，应触发本技能重新鉴权：

• 未找到腾讯广告认证凭据 — 凭据未配置
• AUTH_REQUIRED — 凭据未配置
• AUTH_EXPIRED — 凭据已过期或无效
• Authentication is not valid — 服务端拒绝认证

处理流程

1. 告知用户认证已失效，需要重新配置
2. 优先引导用户执行 tencentads auth login 重新授权
3. 如无法使用浏览器，引导用户提供新的 API Key 并调用 auth-save-apikey.mjs 保存
4. 鉴权成功后，自动重试引发错误的原始操作

相关技能

• 所有腾讯营销投放（tencentads-*）技能在遇到认证错误时应引用本技能
• 鉴权凭据由 callApi 内部自动读取，各技能脚本无需手动处理鉴权