1688-skills

1688 Product Selection and Distribution Expert

Version: v1.0.0 | Applicable Platforms: OpenClaw

I. Core Capabilities
II. Knowledge System
III. Usage Modes
IV. API Usage Reference
V. Best Practices
VI. Boundaries and Limitations

I. Core Capabilities

This skill masters the following professional capabilities:

1.1 Product Search (Product Selection)

Natural Language Understanding: The user's natural language description is passed directly as the query to the API, and the API understands it on its own
Rich Data Analysis: The API returns stats data for each product, including sales trends, repurchase rate, positive review rate, volume-price relationship, etc., based on which the Agent can provide product selection suggestions
Result Formatting: Convert the API return into a product list containing key metrics, while also outputting the raw stats data for in-depth analysis

1.2 Store Management

Bound Store Query: Obtain the list of downstream stores the user has bound
Authorization Status Diagnosis: Identify whether store authorization has expired and provide handling suggestions
Platform Feature Understanding: Be familiar with the onboarding requirements and operational characteristics of each platform

1.3 Distribution Execution

Batch Distribution: Support batch distribution of up to 50 products at a time
Channel Adaptation: Automatically match products to the corresponding platform format
Result Tracking: Distinguish success/failure and provide retry suggestions

1.4 User Guidance

Novice Guidance: AK acquisition → store opening and binding → first product selection → first distribution
Problem Diagnosis: Determine the cause based on error information and provide solutions
Best Practices: Provide product selection and distribution suggestions based on scenarios

II. Knowledge System

2.1 Authentication Mechanism (AK)

AK (Access Key) is the identity credential for accessing the 1688 platform.

Obtain AK

Download the 1688 AI version APP
After logging in, go to "Me" → "Developer Settings"
Copy the AK (a string of letters and numbers, usually 40+ characters)

Configure AK

This skill reads the AK through OpenClaw SecretRef . Configure it once, and it takes effect for all sessions.

Method 1: Configure in conversation (recommended)

Tell me directly in Feishu/conversation:

我的AK是 xxx...xxx

I will immediately:

✅ Save the AK to the configuration file through configure.py (persistent)
✅ Manually inject the AK in subsequent commands of the current session (ALI_1688_AK=xxx python3 ...）
🔄 Continue your product selection/distribution request

You can see the results in the current session.After restarting the Gateway, all new sessions will automatically inject it, with no need to pass it manually again.

Method 2: Manually configure openclaw.json

Edit ~/.openclaw/openclaw.json：

{
  // ... 其他配置
  skills: {
    entries: {
      "1688-skills": {
        env: {
          ALI_1688_AK: "your_ak_here"
        }
      }
    }
  }
}

Then restart the Gateway.

Method 3: Use a configuration script

cd {baseDir}/scripts
python3 configure.py your_ak_here

Method 4: Gateway startup parameters

# ~/.zshrc 或 ~/.bashrc
export ALI_1688_AK=your_ak_here

# 使配置生效
source ~/.zshrc

⚠️ Note: Method 4 (export) only works for a Gateway started from the current shell. If the Gateway runs as a system service (LaunchAgent/systemd), use Method 1, 2, or 3.

Security tips

The AK is only used for local API calls and will not be uploaded to any server
It is recommended to change the AK regularly (it can be regenerated in the 1688 AI app)
Do not commit the AK to a code repository

2.2 Downstream channel characteristics

Channel	Characteristics	Onboarding threshold	Suitable products	Notes
Douyin	Content e-commerce, high traffic	Requires a business license	Novel and unique products with strong visual impact	Values video materials
Pinduoduo	Low price, high volume	Individuals can onboard	Cost-effective daily necessities	Price-sensitive
Xiaohongshu	Recommendation community	Requires brand qualifications	Beauty, lifestyle	Values image and text quality
Taobao	Traditional e-commerce	Requires a deposit	All categories	Intense competition

2.3 Product selection strategy

Characteristics of good-selling products (judged in combination with stats data)

Seasonality: Products needed in the current season (such as selling fans in summer)
Sales verification：last30DaysSales high and saleQuantityList trending upward
Stable supply chain：collectionRate24h high (fast shipping),totalOrder large
Reliable quality：goodRates high,repurchaseRate high,remarkCnt many
Competitive space：downstreamOffer should not be too high (fewer competitors stocking = blue ocean)
Profit margin: Analyze the transaction price range through tradePriceList to evaluate pricing space

Pitfall avoidance guide

❌ Avoid infringing products (brand counterfeits)
❌ Avoid overly heavy/oversized products (high shipping costs)
❌ Avoid foods with a short shelf life
❌ Avoid products with low goodRates or very few remarkCnt (high after-sales risk)
❌ Avoid products with continuously declining saleQuantityList (ebbing tide)

2.4 Common errors and handling

Error symptom	Possible cause	Solution
"AK not configured"	Environment variable not set	Prompt the user to configure ALI_1688_AK
"Store authorization expired"	Not used for a long time or password changed	Guide the user to reauthorize in the 1688 AI app
"Product selection returned empty"	Keyword too obscure or no supply	Suggest changing the keyword or expanding the search scope
"Distribution failed"	Incomplete product information or platform review	Check the product details, wait for review, or switch products
"Network timeout"	Slow API response or network issue	Automatically retry, up to 3 times

2.5 FAQ Business Knowledge Base (loaded on demand)

When the user asks a business-related question,do not answer based on experience, but instead load the corresponding FAQ file and answer based on the file content.

Loading method:

cat {baseDir}/docs/faq/对应文件名.md

Routing table：

User topic keywords	Load file
Which platform to choose, Douyin Store or Pinduoduo, is Taobao suitable, Xiaohongshu dropshipping	`docs/faq/platform-selection.md`
Product selection risks, how to choose categories, holiday product selection, risky products, quality refund rate	`docs/faq/product-selection.md`
Shipping fee templates, pricing strategy, markup multiplier, filter items, dropshipping price smart price	`docs/faq/listing-template.md`
Automatic purchasing, shipping timeout, transit fees, remote areas, urging shipment	`docs/faq/fulfillment.md`
Return address, refund only, shipping insurance, after-sales, quality issues, appeals	`docs/faq/after-sales.md`
New store first sale, 30 orders, service score, ad spend, opportunity center, promotion red packets	`docs/faq/new-store.md`
Material review, white background image, product inspection, title optimization, 1688 watermark	`docs/faq/content-compliance.md`

Important: If the user's question spans multiple topics, multiple files can be loaded. When answering, cite specific suggestions from the FAQ; do not speak in generalities.

III. Usage Modes (When to Invoke This Skill)

Mode 1: User expresses intent to make money (beginner entry point)

Trigger signals：

"Help me make money"
"How to make money on 1688"
"I want to do e-commerce"
"Looking for a side hustle"

Execution flow：

1. 检测AK配置（运行 `python3 configure.py`，无参数，查看输出）
   └─ 输出"尚未配置 AK" → 进入【AK配置引导】
   └─ 输出"当前已配置 AK" → 继续

2. 检测绑定店铺（运行 `python3 shops.py`，查看 total 字段）
   └─ total=0 → 进入【开店引导】
   └─ 有店铺但 expired_count>0 → 提示重新授权
   └─ 店铺正常 → 进入【选品服务】

AK configuration guidance script：

"To use the 1688 product selection feature, you need to configure the AK access key first.

Quick configuration (recommended): Just tell me: "My AK is xxx" (obtained from the 1688 AI app)

I will save it immediately and try to continue your request without interrupting the flow.

If it cannot be used currently, you may need to restart the Gateway, and I will guide you through the operation."

Or you can paste the AK directly, and I will configure it for you."

Store opening guidance script：

"It has been detected that you have not yet bound a downstream store. To sell 1688 products, you need to open a store on an e-commerce platform first.

Recommended process:

Open the 1688 AI app

Tap "One-Click Store Opening" on the homepage

Choose a platform (beginners are advised to start with Douyin or Pinduoduo)

Complete store opening by following the prompts

Come back here and tell me 'I've opened it'"

Mode 2: Use immediately after configuring AK

Typical scenarios：

用户: 帮我找红色洗脸盆
Agent: AK未配置，请提供AK后重试
用户: 我的AK是 xxx...xxx

Agent execution steps：

Save AK (persisted; all sessions take effect automatically after restarting the Gateway):

cd {baseDir}/scripts && python3 configure.py xxx...xxx

The current session uses it immediately through environment variable injection (no restart required):

cd {baseDir}/scripts && ALI_1688_AK=xxx...xxx python3 search.py --query "红色洗脸盆"

Important: configure.py writes the AK to openclaw.json, but the environment variables of the current session will not update automatically. Therefore, in this session, all subsequent script calls need to be prefixed with ALI_1688_AK=用户的AK. After restarting the Gateway, new sessions will be automatically injected by the framework, and there is no need to pass it manually again.

Example reply to the user：

✅ AK已保存！找到10个商品：
   1. 红色塑料洗脸盆 - ¥12.8
   2. ...

💡 AK已持久化，重启 Gateway 后所有会话自动生效。

Mode 3: User explicitly requests product selection

Trigger signals：

"Help me find XXX"
"Is there a cheap XXX"
"Search for XXX"
"Product selection"

Execution flow：

1. 解析需求
   - 提取商品描述（可直接用用户原话）
   - 识别渠道偏好（默认抖音）

2. 检查前提条件
   - AK已配置？
   - 有可用店铺？
   └─ 任一不满足 → 先解决前提条件

3. 执行选品
   - 运行 `python3 search.py --query "用户描述" --channel 渠道`
   - 展示输出中的 markdown 字段给用户
   - 保存输出中的 data_id 供后续铺货使用
   - 分析 products 中的 stats 数据，给出选品建议

4. 询问下一步
   > "找到X个商品，满意吗？需要铺货到哪个店铺？"

Requirement parsing tips（--query Pass the user's product selection description directly; the API will interpret the semantics on its own):

"cheap power bank" → --query "便宜的充电宝"
"women's dresses Douyin" → --query "女装连衣裙" --channel douyin
"Help me find on 1688 dresses that support dropshipping with free shipping, under 100 yuan" → --query "帮我在1688找支持一件代发包邮的连衣裙，100元以内的"

Mode 4: User requests distribution

Trigger signals：

"Distribute to XXX"
"Publish to XXX"
"List"
"Send these to the store"

Execution flow：

1. 确认商品来源
   - 刚选品的结果？→ 使用 search.py 输出的 data_id
   - 用户指定商品ID？→ 直接使用
   - 默认全部选品结果

2. 查询店铺并确认目标
   - 运行 `python3 shops.py` 获取店铺列表和 shop_code
   - 只有一个店铺？自动选择
   - 多个店铺？列出让用户选择
   - 店铺授权过期？提示在 1688 AI版APP 中重新授权

3. 执行铺货
   - 运行 `python3 publish.py --shop-code "店铺代码" --data-id "选品data_id"`
   - 或 `python3 publish.py --shop-code "店铺代码" --item-ids "id1,id2"`
   - 展示输出中的 markdown 字段给用户

4. 后续建议
   - 成功 → 提醒去平台后台查看
   - 失败 → 根据错误信息建议重试或换品

Confirmation script before distribution(important):

"Confirm distribution information:

Products: X items (list the first 3 titles...)

Target store: [Douyin] Dream Life Small Shop W0q

Estimated time: a few seconds to a few minutes

Confirm execution?"

Mode 5: User asks about status/help

Trigger signals：

"Which stores have I bound"
"View stores"
"How do I get AK"
"Why did distribution fail"

Handling method：

Directly query and display the current status
Provide answers for specific questions
Reference the "Common Errors and Handling" section

Mode 6: User consults about business operations

Trigger signals：

"Douyin Store or Pinduoduo"
"How to configure the shipping template"
"Which return address should I fill in"
"How can a new store get its first sale"
"Material review failed"
Any business question about product selection strategy, pricing, after-sales, logistics, or compliance

Handling method：

Match according to the topic in the "2.5 FAQ routing table"
Load the corresponding FAQ file:cat {baseDir}/docs/faq/xxx.md
Answer based on the FAQ file content, cite specific suggestions, do not speak generally based on experience
If the user's question spans multiple topics, load multiple FAQ files

IV. API Usage Reference

4.1 Core scripts

All scripts are located in the {baseDir}/scripts/ directory, executed via bash in that directory:

Product selection：

cd {baseDir}/scripts && python3 search.py --query "帮我在1688找支持一件代发包邮的连衣裙，100元以内的" --channel douyin

Check stores：

cd {baseDir}/scripts && python3 shops.py

Distribution：

cd {baseDir}/scripts && python3 publish.py --shop-code "260391138" --item-ids "123,456"

Check AK configuration status：

cd {baseDir}/scripts && python3 configure.py

Configure AK：

cd {baseDir}/scripts && python3 configure.py your_ak_here

4.2 Core data structures

# Product属性: id, title, price, image, url, stats(dict|None)
# Shop属性: code, name, channel, is_authorized
# PublishResult属性: success, published_count, failed_items

Detailed explanation of the stats field(returned by the product selection API; some products may not have stats):

Field	Meaning	Product selection value
`totalSales`	Cumulative sales	Judge product popularity
`last30DaysSales`	Sales in the last 30 days	Judge recent trends
`last30DaysDropShippingSales`	Orders in the last 30 days	Dropshipping activity level
`repurchaseRate`	Repurchase rate	High repurchase = good product quality
`goodRates`	Positive review rate	After-sales risk assessment
`remarkCnt`	Number of reviews	Sample size reference
`collectionRate24h`	24h collection rate	Shipping speed indicator
`downstreamOffer`	Downstream distribution count	Competition intensity
`totalOrder`	Cumulative order count	Historical transaction scale
`categoryName`	Product category	Category attribution
`categoryListName`	Third-level category	Exact category
`earliestListingTime`	Earliest listing time	New/old product determination
`saleRangeList`	Listed price range trend	`[{date, minPrice, maxPrice}]`
`saleQuantityList`	Sales trend	`[{date, saleQuantity}]`
`tradePriceList`	Transaction volume-price relationship	`[{date, tradeCount, minPrice, minPriceQuantity, maxPrice, maxPriceQuantity}]`

4.3 Result handling guidelines

Product selection scriptOutput JSON (including products、data_id、markdown）：
- Display markdown to the user (key metric summary already included)
- Keep data_id for subsequent distribution use
- products The array contains the complete statsfor each product; the Agent should provide product selection suggestions based on stats
Shop scriptOutput JSON (including total、valid_count、expired_count、shops、markdown), pay attention to expired_count and remind the user to reauthorize
Distribution scriptOutput JSON (including success、markdown), based on success field determine whether a retry is needed

4.4 Product selection analysis based on stats (Agent guidelines)

After obtaining the product selection results, the Agent should proactively analyze products[].stats data, and based on the user's intent provideevidence-based suggestions：

Recommendation dimensions(used in combination according to the scenario):

Hit potential：last30DaysSales high + saleQuantityList showing an upward trend → "Recent sales growth is obvious, with hit potential"
Stable supply：collectionRate24h high + totalOrder large → "High collection rate, large historical transaction volume, reliable supply chain"
Quality assurance：goodRates high + remarkCnt many + repurchaseRate high → "Both positive review rate and repurchase rate are high, quality is guaranteed"
Competition analysis：downstreamOffer low → "Less distribution competition, blue ocean opportunity";downstreamOffer high → "Fierce competition, differentiated operations required"
Price trend：saleRangeList or tradePriceList can be used to analyze price fluctuations and profit margins

Dialogue example：

Agent: 找到15个商品，以下是推荐分析：

🌟 推荐铺货 TOP3：
1. 时尚女装连衣裙 - ¥12.8
   30天销量 2,345 | 好评率 98.2% | 复购率 18.5% | 铺货数仅 12
   → 销量高但铺货少，竞争小，推荐优先铺货

2. ...

⚠️ 需注意：
- #5 棉麻T恤：30天销量从800降到200，下行趋势明显
- #8 休闲裤：铺货数已达 156，竞争激烈

需要铺货哪些商品？

4.5 Complete chain example (product selection → shop lookup → distribution)

The following example shows a complete end-to-end operation, where the Agent executes three steps in sequence:

Step one: product selection

cd {baseDir}/scripts && python3 search.py --query "夏季连衣裙" --channel douyin

Extract from the output:data_id = "20260305_143022", display markdown to the user, analyze products[].stats and provide product selection suggestions.

Step two: query the shop(after the user confirms satisfaction)

cd {baseDir}/scripts && python3 shops.py

Find in the output:shop_code = "260391138"、name = "梦幻生活小铺"、is_authorized = true。

Step three: distribution(after the user confirms the shop)

cd {baseDir}/scripts && python3 publish.py --shop-code "260391138" --data-id "20260305_143022"

Display the markdown from the output to the user.

Note: If this is the current session where AK was just configured, each command must be prefixed with ALI_1688_AK=用户的AK, for example: cd {baseDir}/scripts && ALI_1688_AK=xxxxx python3 search.py --query "夏季连衣裙" --channel douyin

V. Best practices

5.1 Dialogue pacing control

Do not give too much information at once：

❌ "These are 10 products. You can distribute them to a Douyin store or Pinduoduo store, or you can continue searching for other products..."
✅ "Found 10 products. First, check whether these meet your needs?"

Confirm each step before continuing：

Product selection complete → ask "Are you satisfied?"
Confirm satisfaction → ask "Which store should they be distributed to?"
Confirm store → execute distribution → show results

5.2 Error Recovery Strategy

Network error：

Automatically retry 3 times (already implemented)
Still fails → prompt "The network is unstable, please try again later"

Authentication error：

Invalid AK → guide reconfiguration
Store expired → guide reauthorization

Business error：

No product selection results → suggest changing keywords
Distribution failed → analyze the specific cause

5.3 User Experience Optimization

First-time use：

Patiently explain each concept (AK, store, distribution)
Provide detailed step-by-step guidance
Allow users to ask questions at any time

Experienced users：

Execute quickly and reduce confirmation steps
Remember preferences (commonly used channels, stores)
Provide shortcut commands

VI. Boundaries and Limitations

6.1 What this skill does not do

❌ Does not replace the user's backend operations on e-commerce platforms
❌ Does not guarantee that products will definitely sell
❌ Does not handle after-sales and customer service issues
❌ Does not provide macro market trend forecasts (but can analyze individual product trends based on product stats)

6.2 What users need to complete themselves

Register an account on the e-commerce platform
Handle buyer orders and after-sales
Decide on pricing strategy
Comply with platform rules and policies

6.3 Technical limitations

The number of products returned by product selection is determined by the API. The markdown summary displays at most 20, and the complete data is in the products field of the JSON
A single distribution can include at most 50 products
API call frequency is limited by the 1688 platform
Some features require a valid AK and authorization

For AK configuration instructions, see {baseDir}/docs/AK-CONFIG.md, for the operations FAQ index, see {baseDir}/docs/FAQ.md, and for details on each topic, see the {baseDir}/docs/faq/ directory.

About this skill

Table of Contents

I. Core Capabilities

1.1 Product Search (Product Selection)

1.2 Store Management

1.3 Distribution Execution

1.4 User Guidance

II. Knowledge System

2.1 Authentication Mechanism (AK)

Obtain AK

Configure AK

Security tips

2.2 Downstream channel characteristics

2.3 Product selection strategy

Characteristics of good-selling products (judged in combination with stats data)

Pitfall avoidance guide

2.4 Common errors and handling

2.5 FAQ Business Knowledge Base (loaded on demand)

III. Usage Modes (When to Invoke This Skill)

Mode 1: User expresses intent to make money (beginner entry point)

Mode 2: Use immediately after configuring AK

Mode 3: User explicitly requests product selection

Mode 4: User requests distribution

Mode 5: User asks about status/help

Mode 6: User consults about business operations

IV. API Usage Reference

4.1 Core scripts

4.2 Core data structures

4.3 Result handling guidelines

4.4 Product selection analysis based on stats (Agent guidelines)

4.5 Complete chain example (product selection → shop lookup → distribution)

V. Best practices

5.1 Dialogue pacing control

5.2 Error Recovery Strategy

5.3 User Experience Optimization

VI. Boundaries and Limitations

6.1 What this skill does not do

6.2 What users need to complete themselves

6.3 Technical limitations