Install
openclaw skills install @xiewxx/maxhub-douyin抖音(Douyin)数据查询、内容分析与运营辅助 skill,通过 MaxHub API 覆盖视频详情/高清链接、评论弹幕、用户主页/作品/粉丝、搜索、热榜、直播、创作者数据、内容指数、星图与工具类端点。适合短视频选题、账号画像、竞品分析、趋势监控和投放研究。包含少量 restricted 高风险能力(如播放量变更、私信 deep-link、设备/会话/签名辅助、批量 ID 提取),不属于纯只读 skill;agent 必须优先使用 recipes/atoms,调用 restricted 端点前逐次获得用户明确授权。所有请求发送到 https://www.aconfig.cn。
openclaw skills install @xiewxx/maxhub-douyin抖音数据查询与分析工具,通过 MaxHub API 接入抖音平台全量公开数据,覆盖视频详情、用户画像、关键词搜索、热搜热榜、创作者后台、星图 KOL 分析、抖音指数、直播数据、评论弹幕等十大领域共 273 个端点。专注服务于抖音内容创作者、新媒体运营、星图投放分析师、直播数据团队与品牌竞品研究者,帮助用户快速采集抖音全平台数据、提炼爆款规律、辅助选题与投放决策。
📋 数据传输与隐私声明(请认真阅读)
- 第三方传输:您提供的所有 ID、关键词、链接、cookie 等参数都会通过 HTTPS 发送到
https://www.aconfig.cn(MaxHub 数据服务)进行处理。- UGC 隐私:拉回的评论 / 弹幕 / 动态 / 私信 / 联系人等内容可能包含个人信息或敏感 UGC,请勿写入未授权的数据库或公开发布。
- 凭证保护:建议使用独立测试账号、定期轮换 API Key;禁止传入主力生产账号的 cookie 或 session 凭证。
- 合规责任:使用方需自行确保符合所在地区的数据保护法律(《个人信息保护法》/ GDPR / 平台 ToS 等),平台账号的合规性由使用方承担。
请前往 MaxHub 控制台 注册账号并获取 API Key。
方案 1:OpenClaw 配置
将 MAXHUB_API_KEY 添加到 ~/.openclaw/openclaw.json 中:
{ "env": { "MAXHUB_API_KEY": "ak_xxxx..." } }
方案 2:终端环境变量
export MAXHUB_API_KEY="ak_xxxx..."
本 Skill 不需要额外脚本依赖,所有调用通过 curl 完成 HTTP 请求即可,无第三方库依赖。
| 环境变量 | 说明 | 是否必填 | 获取方式 |
|---|---|---|---|
MAXHUB_API_KEY | MaxHub 数据 API Key | 是 | MaxHub 控制台 |
此小节定义 agent 在每次接到用户请求时的标准决策流程。严格按此顺序执行可大幅提升命中率与减少误调用。
| 步骤 | 何时读 | 加载文件 | 估算 token |
|---|---|---|---|
| ① 永远先读 | 接到任何请求时 | SKILL.md §0.1(不支持清单)+ §4(本节) | ~1K |
| ② 选择 recipe | 用户语义清晰时 | references/recipes/_index.md(仅索引) | ~1.5K |
| ③ 加载 recipe 详情 | 匹配到具体 recipe 时 | references/recipes/<domain>.md 的对应段落 | ~500/段 |
| ④ 加载端点详情 | 自定义链路或参数不明时 | references/<domain>.md 单文件 | ~3K |
| ⑤ 路径白名单校验 | 调用前 | grep '<endpoint_id>' references/endpoints_whitelist.yaml(禁止整体读) | ~50 行 |
| ⑥ 跨端点字段路由 | 链式调用时 | references/param-mappings.md § 字段流字典 | ~1K |
references/recipes/_index.md,扫 trigger_keywords 列references/atoms/_index.md,按 chain_role 列定位起点(starter)和终点(terminal)⭐⭐⭐ 首选 标记的端点;不到必要不用 ⭐ 条件 端点param-mappings.md § 字段流字典 决定,禁止自行猜 json_path| 端点 risk | 必做自检 | 步骤数 |
|---|---|---|
risk: low | ① 路径在 endpoints_whitelist.yaml | 1 步 |
risk: medium | ① 路径 ② method ③ 必填参数 ④ 写入确认 | 4 步 |
risk: high | 4 步 + 显式向用户确认参数与意图 | 5 步 |
risk: critical(restricted) | 6 步高风险确认流程(详见 §高风险能力清单) | 6 步 |
旧 SKILL 强制所有调用都做 4 步——现按 risk 等级简化。
low端点(占绝大多数)只校验路径即可。
| 现象 | 行动 | 重试 |
|---|---|---|
| 404 / 410 | §3.1(A) 5 步防臆造自检 → 通过才 STOP;禁止自改路径段重试 | 0 |
| 400 / 422 | §3.1(B) 6 步防参数臆造自检 → 通过才修参重试 | ≤1 |
| 401 / 402 / 403 | STOP,告知用户去 https://www.aconfig.cn 处理 | 0 |
| 429 | 读 Retry-After 退避;无该头时指数退避+jitter | ≤2 |
| 5xx | 等 3 秒重试 → 仍失败走端点级"降级/替换" | 1 |
HTTP 200 + code != 0 | 读 message_zh 报告用户;不重试(业务错误重试无用) | 0 |
https://www.aconfig.cn 三方接口| 规则 | 说明 |
|---|---|
| 🔒 只读 | 本技能仅用于数据查询和分析,不执行写入 / 账户 / 发布操作 |
| 🚫 禁止臆造路径 | 仅使用 references/endpoints_whitelist.yaml 中的端点,不得自行拼接、改版本号、加路径段 |
| 📋 数据流向第三方 | 所有请求发送至 https://www.aconfig.cn,请使用独立测试账号并定期轮换 API Key |
| 🔑 凭证保护 | 不暴露 API Key、Cookie、Token 至日志或对话 |
| ⚠️ 高风险端点确认 | fetch_multi_video 等批量 / 写入端点须用户明确确认参数后才能调用 |
Step 1 — 检查 API Key
[ -n "${MAXHUB_API_KEY:-}" ] && echo "ok" || echo "missing"
若返回 missing,停止并提示用户配置 MAXHUB_API_KEY。
Step 2 — 匹配意图 → 选择 reference
按用户目标从下表选择对应 reference 文件,每个文件自包含其领域的全部端点定义:
| 用户目标 | 加载文件 | 覆盖范围 |
|---|---|---|
| 查视频详情 / 播放 / 下载 / 统计 | references/video.md | 视频详情、批量视频、播放 URL、统计、合集 / 短剧、音乐 / 话题、分享 / 短链 / 二维码、频道内容、ID 提取(42 端点) |
| 查用户 / 粉丝 / 作品 / 喜欢 | references/user.md | 用户信息、粉丝 / 关注、作品、喜欢、收藏夹、合辑、用户搜索、开播信息(24 端点) |
| 搜索视频 / 用户 / 图片 / 直播 | references/search.md | 综合 / 视频 / 用户 / 图片 / 直播 / 话题 / 经验 / 音乐 / 讨论 / 学校 / 图像搜索 + 建议(19 端点) |
| 查热搜 / 热榜 / 活动日历 | references/trending.md | 热榜分类、上升 / 同城 / 挑战热点、活动日历、粉丝画像、账号 / 视频 / 话题 / 搜索热榜、首页推荐(39 端点) |
| 查创作者数据 / 作品分析 | references/creator.md | 创作者活动、素材中心、热门榜单、商单任务、行业分类、流量分析、观众画像、账号诊断、直播历史(31 端点) |
| 查星图 KOL / 达人分析 | references/xingtu.md | KOL ID 查询、基本信息、画像、报价、数据概览、KOL 搜索、转化分析、星图指数、视频表现、热榜、达人广场、MCN、IP 日历(43 端点) |
| 查评论 / 回复 / 弹幕 | references/comments.md | 视频评论、评论回复、视频弹幕(6 端点) |
| 查抖音指数 / 品牌 / 达人 | references/content.md | 关键词趋势、关联词、人群画像、达人分析、视频搜索、品牌指数、话题搜索、创作指南、趋势报告(44 端点) |
| 查直播 / 直播间 / 商品 | references/live.md | 直播流、弹幕、送礼排行、直播间商品、商品详情 / 评价、直播间 ID 转换(14 端点) |
| 生成 Cookie / Token / 签名 | references/tools.md | 设备注册、APP 跳转、游客 Cookie、msToken / ttwid / verify_fp / s_v_web_id、X-Bogus / A-Bogus / 弹幕 xb 签名(13 端点) |
| 跨端点参数查询 / 字段流追溯 | references/param-mappings.md | 全局红线 + 端点路由 + 字段流字典 + 错误处理总览 + 替换矩阵 |
| 路径白名单硬校验 | references/endpoints_whitelist.yaml | 273 个端点的硬白名单 + Pre-call 4 步自检协议 |
| SKILL 版本检查与升级 | references/update.md | SkillHub / ClawHub / GitHub 三通道更新 |
Step 3 — 构建最小调用计划
Step 4 — 执行并验证
endpoints_whitelist.yaml 完成 4 步 Pre-call 自检(路径 → method → 必填 → 写入确认)message_zh 报告用户,不重试| 用户场景 | 链路 | 字段流 |
|---|---|---|
| 查视频 + 评论 | video.md → comments.md | aweme_id 接力 |
| 搜索 → 视频详情 | search.md → video.md | aweme_id 接力 |
| 查用户 → 作品 | user.md → user.md (posts) | sec_user_id 接力 |
| 查创作者 → 视频详情 | creator.md → video.md | item_id → aweme_id |
| 查用户 → 星图 KOL | user.md → xingtu.md | uid / sec_user_id → kolid |
| 查热搜 → 视频详情 | trending.md → video.md | aweme_id 接力 |
| 查直播 → 观众画像 | live.md → creator.md (audience_portrait) | room_id 接力 |
| 查品牌趋势 → 人群画像 | content.md → content.md (portrait) | keyword 接力 |
| 用户全面分析 | user.md → user.md (stats+posts+likes) → xingtu.md | sec_user_id 复用 |
收到 404 时(A):
收到 400 / 422 时(B):
message_zh 排查| 触发条件 | 推荐操作 |
|---|---|
| 合法路径持续 404 / 410 | skillhub upgrade maxhub-douyin(国内)或 clawhub upgrade maxhub-douyin(国际) |
| 用户问 "版本是多少" | 当前版本 v3.7.2,访问 https://skillhub.cn/skills/maxhub-douyin |
| 多端点连续 410 | skillhub upgrade maxhub-douyin --force |
| 401 / 402 / 403 | 不是版本问题,去 https://www.aconfig.cn 处理 |
| 场景 | 命令 |
|---|---|
| 查 API Key | [ -n "${MAXHUB_API_KEY:-}" ] && echo "ok" || echo "missing" |
| 查视频详情 | curl -H "$maxhub_auth_header" "https://www.aconfig.cn/api/v1/douyin/app/v3/fetch_one_video?aweme_id=xxx" |
| 查视频评论 | curl -H "$maxhub_auth_header" "https://www.aconfig.cn/api/v1/douyin/app/v3/fetch_video_comments?aweme_id=xxx" |
| 分享 URL 解析 | curl -H "$maxhub_auth_header" "https://www.aconfig.cn/api/v1/douyin/app/v3/fetch_one_video_by_share_url?share_url=xxx" |
| 检查 SKILL 更新 | skillhub info maxhub-douyin 或 clawhub info maxhub-douyin |
用户输入:「帮我看 这个抖音 aweme_id 视频的评论」
Agent 执行步骤:
references/recipes/_index.md → 找到 trigger 命中 → 选最长匹配的 recipereferences/recipes/<domain>.md 中对应段落,拿到 Inputs / Atomic Steps / Outputgrep 一下 endpoints_whitelist.yaml 确认存在$.data.bvid)按 recipe 的 extract 列绑定为变量,传给下游端点反例(agent 不要这么做):
endpoints_whitelist.yaml(大文件,浪费上下文)extract 列,自己猜 json_pathtrending.md 拉取分类热榜与上升榜 → 取 aweme_id → 链式调 video.md 提取标题、话题、音乐 → 调 comments.md 抓取评论关键词user.md 取 sec_user_id → 拉取作品列表 + 粉丝统计 → creator.md 调用流量分析与观众画像 → comments.md 抽样评论user.md 反查 uid → xingtu.md 用 KOL ID 查询基本信息 + 服务报价 + 转化分析 + 视频表现 + 星图指数live.md 取 room_id → 拉取弹幕 + 送礼排行 + 直播商品 → live.md 商品详情 / 评价 → creator.md 观众画像maxhub-douyin/
├── SKILL.md # Skill 定义与使用文档(本文件)
├── README.md # 英文项目说明
├── README_CN.md # 中文项目说明
├── _meta.json # 版本元信息(version: 3.7.2)
└── references/
├── endpoints_whitelist.yaml # 273 端点路径硬白名单 + Pre-call 4 步自检协议
├── param-mappings.md # 中枢索引(全局红线 + 字段流字典 + 错误处理 + 替换矩阵)
├── video.md # 视频域:详情/播放/下载/统计/合集/音乐/话题(42 端点)
├── user.md # 用户域:资料/粉丝/作品/喜欢/收藏夹/合辑/搜索(24 端点)
├── search.md # 搜索域:综合/视频/用户/图片/直播/话题/经验等(19 端点)
├── trending.md # 热榜域:分类/上升/同城/挑战/活动/账号/话题(39 端点)
├── creator.md # 创作者域:素材/商单/流量/画像/账号诊断(31 端点)
├── xingtu.md # 星图域:KOL/画像/报价/转化/指数/MCN/IP 日历(43 端点)
├── comments.md # 评论域:评论/回复/弹幕(6 端点)
├── content.md # 抖音指数域:关键词/品牌/人群/趋势报告(44 端点)
├── live.md # 直播域:直播流/弹幕/礼物/商品/转换(14 端点)
├── tools.md # 工具域:Cookie/Token/签名/设备注册(13 端点)
└── update.md # SKILL 更新机制(SkillHub / ClawHub / GitHub)
| 组件 | 技术 | 说明 |
|---|---|---|
| 调用方式 | curl + Bearer Token | HTTP GET / POST 请求,参数通过 query string 或 JSON body 传递 |
| 数据接口 | MaxHub API | https://www.aconfig.cn/api/v1/douyin/*,通过 MAXHUB_API_KEY 鉴权 |
| 路径校验 | YAML 硬白名单 | endpoints_whitelist.yaml 提供 273 端点的逐字符校验 + 4 步 Pre-call 协议 |
| 错误处理 | 决策表 + 自检清单 | HTTP 状态码权威定义 + 防臆造自检(A/B 双轨)+ 重试策略矩阵 |
| 输出格式 | JSON Standard MaxHub Response | {code, message, message_zh, data, cache_url} |
| 更新通道 | SkillHub / ClawHub / GitHub | 国内 ⭐⭐⭐ SkillHub(腾讯云 CDN)/ 国际 ⭐⭐⭐ ClawHub / 降级 GitHub |
| 领域 | 端点数 | Reference 文件 |
|---|---|---|
| 视频(Video) | 42 | video.md |
| 用户(User) | 24 | user.md |
| 搜索(Search) | 19 | search.md |
| 热榜(Trending) | 39 | trending.md |
| 创作者(Creator) | 31 | creator.md |
| 星图(Xingtu) | 43 | xingtu.md |
| 评论(Comments) | 6 | comments.md |
| 抖音指数(Content) | 44 | content.md |
| 直播(Live) | 14 | live.md |
| 工具(Tools) | 13 | tools.md |
| 合计 | 273 | — |