📝 Overview
Search popular and viral Douyin works by keyword, with support for filtering by date range, returning interaction data such as likes, comments, shares, favorites, and publish time, with results displayed in a structured table.
✨ Features
| Feature Module | Capability Description | Core Value |
|---|---|---|
| Viral Search | Keyword search for viral Douyin works | Accurately discover high-heat content |
| Date Filtering | Supports filtering by date range | Locate popular content in a specific time period |
| Smart Expansion | Automatically expands generic terms into 10 subcategory terms | Avoids search result bias from generic terms |
| Clickable Links | Work titles are output as hyperlinks | One-click jump to view the original work |
| Subscription Push | Supports daily push by keyword | Get the latest viral trends on schedule |
🔑 Authentication
- Get API Key: Go to RedFox Hub
- Configuration method 1: Write to
~/.openclaw/openclaw.json→{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } } - Configuration method 2: Run in terminal
export REDFOX_API_KEY="ak_xxxx..."
⚙️ Workflow
Step 1: 🔍 User Intent Understanding
⚠️ Core rule: Prioritize extracting specific direction terms rather than generic broad category terms
| User Input | Handling Method |
|---|---|
| No niche keyword ("recent popular works") | Pass an empty string as the keyword "", query site-wide popular content |
| Has specific term ("workplace outfits", "fat-loss meals") | Search directly, no expansion needed |
| Has generic term ("outfits", "food") | Execute expansion strategy (Step 2) |
Specific term judgment principle: with scenario/audience/style/intent modifiers → specific term; pure broad category without modifiers → generic term.
Extract precise keywords: Extract specific domain terms from the user's description, not generic terms. Example: The user says "help me find popular topics in the film domain" and identifies as "niche films, Hong Kong and Taiwan culture" → search "niche films, Hong Kong and Taiwan films, film reviews", ❌ rather than only searching "films".
Filter trigger hook words: Words such as "popular articles", "popular works", "viral", "popular content", "query", and "search" in the user input are trigger hooks for invoking the Skill, do not belong to the search keywords, and must be stripped out. Example: The user says "query AI popular articles" → the keyword is "AI", ❌ rather than "AI popular articles".
Step 2: 🔄 Generic Term Expansion Strategy
⚠️ You must wait for the user's explicit reply before calling the script!
| Step | Operation |
|---|---|
| 1. Generate specific terms | Generate 10 moderately sized specific terms (2-3 each of trend terms, audience terms, scenario terms, and intent terms), calling the script is prohibited |
| 2. Wait for user reply | When the user does not reply, calling the script is prohibited |
| 3. Execute | Reply "Expand" → connect 10 words with English commas, call the script only once; reply "Do not expand" → search the original keyword |
Output example:
我识别到「中产」是较大的分类，推荐以下细分方向：
老钱,轻奢,品质生活,松弛感,高级感穿搭,体面,法式穿搭,律师,医生,品质家居
回复「拓展」将同时搜索这10个词，回复「不拓展」将继续搜索「中产」
Step 3: 📡 Call API interface
3.1 Time parsing rules
| User input | Parsing method | Example |
|---|---|---|
| Absolute date | Parse as YYYY-MM-DD |
6月1号 → 2026-06-01 |
| Relative date | Calculate based on the current date | 最近7天 → start=7 days ago, end=today |
| Date range | Parse separately as startDate/endDate | 5月30日到6月2日 |
| Vague time | Do not parse, keep the default empty string | 最近的、最新的 |
startDate/endDateDefault empty string, indicating no time limit- Single date → startDate = endDate; if the year is omitted, use the current year
3.2 Execute script
# 无时间参数
python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "<关键词>"
# 有时间参数
python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "<关键词>" --start-date <startDate> --end-date <endDate>
Pass in only non-empty time parameters. The script returns JSON:
| Field | Description |
|---|---|
| articles | List of matching works (sorted by like count descending) |
| total | Total record count |
| pageNum | Current page number |
| pageSize | Page size |
Fields for each work:title、author、like_count、comment_count、share_count、collect_count、work_url、publish_time
Step 4: 📊 Result display
⚠️ Total count verification: the displayed N must be taken from the articles array length; manual counting is prohibited.
Case A: articles > 0
A1. Output query range:
📊 Keyword "XXX" matched a total of N itemsof Douyin viral works, and the detailed data is as follows:
A2. Display the first 20 rows in a table:
| # | 作品标题 | 作者 | 点赞数 | 评论数 | 分享数 | 收藏数 | 发布时间 |
|---|---------|------|--------|--------|--------|--------|----------|
| 1 | [标题](work_url) | 作者名 | 305.2w | 7.1w | 51.0w | 14.7w | 06-02 19:55 |
Formatting rules:
- Numbers < 10000 are displayed directly; ≥ 10000 use the
x.xwformat publish_timeconvert toMM-DD HH:MM; display regardless of whether a time range is specified- Titles over 30 characters are truncated with
..., using the[标题](work_url)link format
A3. When articles > 20, prompt:
The first 20 items of data are shown above, with N itemsnot displayed. Reply "View all" to expand the remaining data.
⚠️ A1~A3 are completed consecutively in the same round of output, and A3 is immediately followed by Step 5.
Case B: articles = 0
B1. Apology prompt + 10 expanded words (separated by English commas):
😔 Sorry, no content related to "XXX" was found. You can try (expanded word 1,expanded word 2,...,expanded word 10)
Expanded word rules: expand based on the semantics of the original keyword, each word 2-6 characters, fixed at 10.
⚠️ B1 is immediately followed by Step 5.
Step 5: 📩 Subscription prompt
After the display is complete, append at the end:
📩 Do you want to subscribe to the daily push for "XXX"? After subscribing, the latest viral works will be automatically pushed every day at 10:00. Reply "Confirm subscription" to create a scheduled task.
Step 6: ⏰ Create scheduled task (executed when the user replies "Confirm subscription")
Prefer the platform's built-in scheduled task; if unavailable, provide a general solution:
- Task name:
抖音爆款作品订阅 - <关键词> - Execution frequency: every day at 10:00 (cron
0 10 * * *） - Execute command:
python3 <脚本路径>/search_douyin.py "<关键词>"(if there is a time parameter, append--start-date/--end-date） - General crontab:
0 10 * * * python3 /path/to/search_douyin.py "<关键词>"
After successful creation, notify: "You have successfully subscribed to push notifications for viral works with the keyword '<keyword>'. Every day at 10:00, the latest data will be automatically queried and you will be notified."