1688 Shopkeeper
next-1688/1688-shopkeeper
1688选品铺货 + 商机趋势专家。用于：(1) 在1688搜索商品/选品找货源 (2) 查询已绑定的下游店铺 (3) 将商品铺货到抖音/拼多多/小红书/淘宝等平台 (4) 配置1688 AK密钥 (5) 查看即时商机热榜 (6) 查看类目/行业趋势与价格分布 (7) 生成店铺经营日报并输出主营商品选品建议。
1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。
MITAuto-check passed
Install 1688 Product Search
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-search --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/1688-product-search .claude/skills/1688-product-search && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .claude/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-searchType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-search --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/1688-product-search .agents/skills/1688-product-search && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .agents/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-search --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/1688-product-search .cursor/skills/1688-product-search && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .cursor/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/LeoYeAI/openclaw-master-skills.git --path skills/1688-product-search--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-search --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/1688-product-search .gemini/skills/1688-product-search && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .gemini/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-searchInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/1688-product-search .github/skills/1688-product-search && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .github/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install LeoYeAI/openclaw-master-skills 1688-product-search --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/LeoYeAI/openclaw-master-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/1688-product-search .opencode/skills/1688-product-search && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "1688-product-search" agent skill from https://github.com/LeoYeAI/openclaw-master-skills/tree/main/skills/1688-product-search into .opencode/skills/1688-product-search/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "1688-product-search", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
1688-product-search- GitHub stars
- 2.2k
- Token cost
- ~3.1k tokens
- SKILL.md length
- 628 words
- Files
- 12 (incl. scripts, references)
- Skills in repo
- 1,235
- Repo updated
- First seen
- Licence
- MIT
At a glance
1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。
- Works in 4 steps: ：注册开发者 & 创建应用 → 获取 AppKey + AppSecret → ：订购解决方案 → 获取 API 调用权限 → ：用户授权 → 获取 access_token + refresh_token → …
- SKILL.md covers 鉴权说明, 使用方法, 重要提示 and 参数说明, plus 3 more sections
- Runs Python scripts from its folder; calls python3 and curl; reaches gw.open.1688.com and detail.1688.com; needs ALI1688_REFRESH_TOKEN and ALI1688_ACCESS_TOKEN
What it does
1688 Product Search is an agent skill from LeoYeAI/openclaw-master-skills. 1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。 支持多语言搜索和商品推荐，使用1688开放平台官方API，统一鉴权，Token全局缓存共享。
Its SKILL.md is about 3.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 13 other files, including scripts and reference files (for example `_meta.json`, `references/api.md` and `scripts/auth.py`).
It works with 1688. The repository describes itself as: 🧠 Curated collection of 1209+ best OpenClaw skills — weekly updated by MyClaw.ai. The licence is MIT.
Example prompts
- “/1688-product-search”
Requirements
- Python 3
- A credential in ALI1688_APP_KEY
- A credential in ALI1688_APP_SECRET
Workflow steps
4 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit e5199b5. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 9 files in scripts/ (Python), which the agent can run.
Shell commands in SKILL.md call:
python3curl
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
gw.open.1688.comdetail.1688.comauth.1688.com
Also links to:
open.1688.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
ALI1688_REFRESH_TOKENALI1688_ACCESS_TOKENALI1688_APP_SECRETALI1688_APP_KEY
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
1688 Product Search loads about 3.1k tokens when it runs, and up to ~4k if it reads all its reference files. Until then it costs about 35 tokens; SKILL.md has 628 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.
SKILL.md
The full file from LeoYeAI/openclaw-master-skills at commit e5199b5, republished under its MIT licence (© LeoYeAI). 628 words, ~3,068 tokens.
Download SKILL.mdSave it as
.claude/skills/1688-product-search/SKILL.md (or your agent's skills folder). This skill also uses 11 other files; get the full folder from GitHub.- name
- 1688-product-search
- description
- 1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。 支持多语言搜索和商品推荐，使用1688开放平台官方API，统一鉴权，Token全局缓存共享。
- version
- 1.0.3
- metadata.primaryEnv
- ALI1688_APP_KEY, ALI1688_APP_SECRET, ALI1688_REFRESH_TOKEN
- metadata.env
- ALI1688_APP_KEY, ALI1688_APP_SECRET, ALI1688_REFRESH_TOKEN
1688商品搜索SKILL
通过1688开放平台官方API提供完整的商品搜索能力，包含9个核心接口。
鉴权说明
每个 Skill 内置独立的鉴权模块（scripts/auth.py），不依赖任何外部 Skill。
所有 1688 Skill 的 Token 缓存指向同一个固定路径，实现"独立运行 + 鉴权只发生一次"。
- Token 缓存路径:
skills/.1688_token_cache.json（所有 1688 Skill 共用） - 任意一个 Skill 首次请求完成鉴权后，其他 Skill 直接复用缓存
- Token 过期前自动用 refresh_token 刷新
- 支持
ALI1688_REFRESH_TOKEN（自动刷新）和ALI1688_ACCESS_TOKEN（直接使用）两种模式
配置
在 OpenClaw config 中设置环境变量：
{
skills: {
entries: {
"1688-product-search": {
env: {
ALI1688_APP_KEY: "your-app-key",
ALI1688_APP_SECRET: "your-app-secret",
ALI1688_REFRESH_TOKEN: "your-refresh-token"
}
}
}
}
}如何获取 AppKey / AppSecret / Token
如果遇到 Token 相关错误（如 401、签名失败、Token 过期），按以下步骤操作：
Step 1：注册开发者 & 创建应用 → 获取 AppKey + AppSecret
Step 2：订购解决方案 → 获取 API 调用权限
- 打开 跨境ERP/独立站SaaS数字化解决方案
- 点击「立即订购」，将解决方案绑定到你的应用
- 订购成功后，应用才有权限调用方案内的 API
Step 3：用户授权 → 获取 access_token + refresh_token
- 在浏览器中访问授权页面（替换 YOUR_APPKEY 和 YOUR_REDIRECT_URI）：
https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI- 用1688账号登录并同意授权
- 页面会跳转到你的回调地址，URL 中带有
code参数 - 用 code 换取 Token（有效期短，需在10分钟内使用）：
curl -X POST "https://gw.open.1688.com/openapi/param2/1/system.oauth2/getToken/YOUR_APPKEY" \
-d "grant_type=authorization_code" \
-d "need_refresh_token=true" \
-d "client_id=YOUR_APPKEY" \
-d "client_secret=YOUR_APPSECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "code=授权码"- 返回结果中包含：
access_token— 用于调用 API（有效期约10小时）refresh_token— 用于刷新 access_token（有效期约半年）
Step 4：配置到环境变量
ALI1688_APP_KEY= 应用的 AppKeyALI1688_APP_SECRET= 应用的 AppSecretALI1688_REFRESH_TOKEN= 上一步获得的 refresh_token（推荐，支持自动刷新）ALI1688_ACCESS_TOKEN= 上一步获得的 access_token（备用，过期需手动换）
常见 Token 错误及解决
| 错误 | 原因 | 解决方案 |
|---|---|---|
HTTP 400 刷新失败 | refresh_token 无效或已过期 | 重新走 Step 3 授权，获取新的 refresh_token |
HTTP 401 未授权 | access_token 过期或无效 | 设置 ALI1688_REFRESH_TOKEN 启用自动刷新 |
签名错误(code=25) | AppSecret 不正确 | 检查 ALI1688_APP_SECRET 是否与应用详情页一致 |
无权限调用 | 未订购解决方案 | 回到 Step 2 订购对应解决方案 |
refresh_token 半年后过期 | Token 自然过期 | 重新走 Step 3 授权 |
参考链接
使用方法
1. 类目查询
# 查询所有一级类目（英语）
python3 scripts/product_search.py category 0
# 查询中文类目
python3 scripts/product_search.py category 0 --language en2. 多语言关键词搜索
# 英文关键词搜索
python3 scripts/product_search.py keyword-search "dress" --country en
# 中文关键词搜索
python3 scripts/product_search.py keyword-search "连衣裙" --country en
# 带筛选条件的搜索
python3 scripts/product_search.py keyword-search "dress" --country en --filter "shipIn48Hours,shipIn24Hours" --sort '{"price":"asc"}'3. 多语言图片搜索
图片搜索支持三种方式，优先级：本地图片文件 > imageId > 图片URL
# 方式一：本地图片文件（推荐）
# 自动压缩（>300KB）→ base64编码 → 上传获取imageId → 图搜
python3 scripts/product_search.py image-search --image-path "/path/to/your/image.jpg" --country en
# 方式二：图片URL（直接用 imageAddress 字段图搜，无需上传）
python3 scripts/product_search.py image-search --image-url "https://example.com/image.jpg" --country en
# 方式三：已有 imageId（由 upload-image 接口返回）
python3 scripts/product_search.py image-search "your_image_id" --country en
# 上传图片获取imageId（单独使用）
python3 scripts/product_search.py upload-image "/path/to/your/image.jpg"当用户发送图片文件或截图时的处理流程：
⚠️ 注意：1688图片上传接口（
product.image.upload）的imageBase64方式仅支持1688平台自身的图片，对本地截图/外部图片会返回无效 imageId（"0"）。
推荐处理策略：
- 询问用户图片的原始来源 URL
- 若 URL 包含
alicdn.com，直接用imageAddress字段图搜（已验证有效） - 若 URL 不包含
alicdn.com，先下载到本地，再 base64 上传尝试获取 imageId；若 imageId 仍为"0"，降级用imageAddress图搜
本地文件 base64 上传流程（仅供参考，成功率有限）：
- 若图片大于 300KB，先用 Pillow 压缩（先调质量，再缩分辨率），再 base64 编码
- 调用
product.image.upload接口（uploadImageParam字段包装，内含imageBase64）上传 - 若返回有效 imageId（非
"0"），用 imageId 图搜；否则降级用imageAddress图搜
当用户提供图片 URL 时的处理流程：
- 判断图片 URL 的域名：
- 是
alicdn.com域名（如cbu01.alicdn.com、img.alicdn.com等）：直接用imageAddress字段传入图搜接口，无需下载 - 非
alicdn.com域名（如用户上传的图片、其他电商平台图片等）：先将图片下载到本地临时文件，再走本地文件图搜流程（压缩 → base64 → 上传 → imageId → 图搜）
- 是
4. 多语言商品详情
⚠️ 注意：该接口每次只支持查询 1 个商品，不支持批量查询多个商品ID。
# 查询单个商品详情
python3 scripts/product_search.py product-detail "offer_id"5. 多语言商品店铺搜索
# 根据商家ID搜索商品
python3 scripts/product_search.py shop-search "seller_open_id" --country en6. 多语言商品推荐
# 基于关键词的商品推荐
python3 scripts/product_search.py offer-recommend "keyword" --country en7. 品池商品拉取
从业务定制的品池中拉取商品列表，需要有品池访问权限。分页查询时需固定同一个 taskId。
# 拉取品池商品（offerPoolId 和 taskId 为必填）
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --page-no 1 --page-size 10
# 指定类目和排序
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --cate-id 11 --sort-field order1m --sort-type DESC --page-no 1 --page-size 10请求参数：
| 参数 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
--pool-id | Long | ✅ | 品池ID（业务定制且有权限控制，从对接的业务获取，随便传会报错，寻源通代采建议走词搜接口） | 111 |
--task-id | String | ✅ | 查询任务ID，分页查询时需固定同一个 taskId（如货盘有10000商品，每页1000个查询10次，这10次都需传同一个 taskId） | 1 |
--page-no | Integer | ✅ | 页码 | 1 |
--page-size | Integer | ✅ | 每页数量 | 10 |
--cate-id | Long | ❌ | 类目ID | 11 |
--language | String | ❌ | 语言，默认 en | en |
--sort-field | String | ❌ | 排序字段：order1m（最近1个月销售额）/ buyer1m（最近1个月买家数） | order1m |
--sort-type | String | ❌ | 排序规则：ASC / DESC | DESC |
返回结果结构：
{
"result": {
"success": "true",
"code": "200",
"result": [
{
"offerId": 111111,
"bizCategoryId": "111111",
"offerPoolTotal": 122211
}
]
}
}| 字段 | 类型 | 描述 | 示例值 |
|---|---|---|---|
result.success | String | 是否成功 | true |
result.code | String | 错误码 | 200 |
result.result[].offerId | Long | 商品ID | 111111 |
result.result[].bizCategoryId | String | 机构的类目ID | 111111 |
result.result[].offerPoolTotal | Integer | 商品池总数（每个offer都返回） | 122211 |
8. 相关性商品推荐
# 基于商品ID的相关推荐
python3 scripts/product_search.py related-recommend "offer_id" --country en9. 上传图片获取imageId
# 上传本地图片获取imageId
python3 scripts/product_search.py upload-image "/path/to/image.jpg"智能图片压缩功能：当上传的图片文件大于300KB时，系统会自动进行智能压缩，确保图片大小符合1688 API的要求。压缩过程会：
- 自动检测图片格式并转换为JPEG（如果需要）
- 保持最佳画质的同时将文件大小控制在300KB以内
- 临时生成压缩后的图片用于上传，完成后自动清理临时文件
- 输出详细的压缩日志（原大小 → 压缩后大小）
这确保了无论用户提供的图片大小如何，都能成功获取有效的imageId用于后续的图片搜索操作。
重要提示
图片搜索触发
当接收到"图搜同款"、"找同款"、"以图搜款"、"图片搜同款"等图片搜索相关指令时， 系统会自动调用图片搜索接口（product.search.imageQuery）而非关键词搜索接口。
接口触发规则
| 用户意图 | 调用接口 | 说明 |
|---|---|---|
| 图搜同款、找同款、以图搜款 | product.search.imageQuery | 图片搜索 |
| 同店商品、同商家商品 | product.search.querySellerOfferList | 需从商品详情取 sellerOpenId |
| 相似品、相关品、相关性推荐 | product.related.recommend | 基于商品ID推荐，部分商品可能返回空 |
| 商品推荐 | product.search.offerRecommend | 基于关键词推荐 |
| 拉取xx货盘、拉取商品货盘、拉取品池商品 | pool.product.pull | 需提供 offerPoolId 和 taskId |
Show full SKILL.md (249 more words)Show less
商品查询结果必须透出商品ID和链接
所有商品查询接口（关键词搜索、图片搜索、店铺搜索、商品推荐等）的返回结果，必须向用户展示以下两个核心字段：
offerId（商品ID）：商品的唯一标识符，可用于后续查询商品详情、相关推荐等操作- 商品链接：优先使用
promotionURL（含追踪参数的推广链接），若无则使用https://detail.1688.com/offer/{offerId}.html
展示格式示例（Markdown 表格或列表均可）：
商品ID: 683381849222
链接: https://detail.1688.com/offer/683381849222.html?fromkv=...（promotionURL）禁止只展示商品标题和价格而不透出商品ID和链接，用户需要通过商品ID进行后续操作。
参数说明
通用参数
| 参数 | 说明 | 默认值 | 可选值 |
|---|---|---|---|
--country / --language | 语言代码 | en | en / ja / ko / ru / vi / es 等，不支持 zh |
--beginPage | 起始页码 | 1 | 数字 |
--pageSize | 每页数量 | 20 | 数字，最大50 |
注意：当接口参数中包含 beginPage 时，默认传 1；包含 pageSize 时，默认传 20；包含 country 或 language 时，默认传 en。
⚠️ 重要：
country和language参数均不支持zh（中文）。无论用户用中文还是英文提问，都必须传en（英语）作为默认值。传zh会导致接口报错或返回异常结果。
筛选条件 (filter)
支持多种筛选条件，多个条件用英文逗号分割：
shipIn24Hours- 24小时发货shipIn48Hours- 48小时发货certifiedFactory- 认证工厂isOnePsale- 支持一件代发new7- 7天上新1688Selection- 1688严选
示例：--filter "shipIn48Hours,certifiedFactory,isOnePsale"
排序参数 (sort)
支持按不同维度排序：
price- 批发价rePurchaseRate- 复购率monthSold- 月销量
示例：--sort '{"price":"asc"}' 或 --sort '{"monthSold":"desc"}'
输出格式
JSON 格式，直接返回1688 API 的原始响应数据。
重要提示：所有商品查询结果都会包含商品ID（offerId字段），这是商品的唯一标识符，可用于后续的商品详情查询或其他操作。
错误处理
- 失败时不会返回mock数据：当API调用失败、参数错误或网络异常时，会直接返回错误信息JSON并退出
- 错误格式：
{"error": "具体的错误信息"} - 退出码：失败时返回退出码1，成功时返回0
商品结果字段说明
所有商品列表类接口（词搜、图搜、店铺搜索、商品推荐等）查询结果，必须展示以下所有可用字段：
| 字段 | 说明 | 是否必显 |
|---|---|---|
offerId | 商品ID，唯一标识符 | ✅ 必显 |
subject | 商品标题（中文） | ✅ 必显 |
subjectTrans | 商品标题（英文翻译） | 有则显示 |
imageUrl | 商品主图URL | ✅ 必显 |
priceInfo.price | 批发价 | ✅ 必显 |
priceInfo.promotionPrice | 促销价 | 有则显示 |
priceInfo.consignPrice | 代发价 | 有则显示 |
monthSold | 月销量 | ✅ 必显 |
repurchaseRate | 复购率 | ✅ 必显 |
minOrderQuantity | 最小起订量 | 有则显示 |
tradeScore | 店铺评分 | 有则显示 |
sellerDataInfo.tradeMedalLevel | 商家等级（星级） | 有则显示 |
sellerDataInfo.compositeServiceScore | 综合服务分 | 有则显示 |
productSimpleShippingInfo.shippingTimeGuarantee | 发货时效（24h/48h） | 有则显示 |
isOnePsale | 是否支持一件代发 | 为true时显示 |
isSelect | 是否1688严选 | 为true时显示 |
offerIdentities | 商品标签列表 | 有则显示 |
sellerIdentities | 商家标签列表 | 有则显示 |
标签值含义说明（offerIdentities / sellerIdentities）
| 标签值 | 含义 |
|---|---|
tp_member | 诚信通会员 |
createDate / modifyDate | 上架/更新时间 |
| 商品链接 | 优先用 promotionURL，无则用 https://detail.1688.com/offer/{offerId}.html |
API 接口地址
| 接口 | 完整URL |
|---|---|
| 类目查询 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/category.translation.getById/${APPKEY} |
| 关键词搜索 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.keywordQuery/${APPKEY} |
| 图片搜索 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.imageQuery/${APPKEY} |
| 商品详情 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.queryProductDetail/${APPKEY} |
| 店铺搜索 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.querySellerOfferList/${APPKEY} |
| 商品推荐 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.offerRecommend/${APPKEY} |
| 品池商品拉取 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/pool.product.pull/${APPKEY} |
| 相关推荐 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.related.recommend/${APPKEY} |
| 图片上传 | POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.image.upload/${APPKEY} |
1688接口通用说明
API接入要点
- 语言支持: 默认使用
country=en，但返回字段包含中英双语- 中文字段示例:
subject - 英文字段示例:
subjectTrans - ⚠️
country和language参数均不支持zh，可选值为en/ja/ko/ru/vi/es等，无论何种情况默认传en
- 中文字段示例:
- Access Token: 当前解决方案产生的access_token是长久有效的
- 筛选条件: 支持多种商品筛选条件（发货时效、认证工厂、一件代发等）
- 排序功能: 支持按价格/复购率/月销量排序，但仅对当前页有效
重要限制
- 数据量限制: 每个查询最多返回2000个商品
- 图片搜索: 仅推荐使用1688图片地址，其他域名成功率不稳定
- 价格显示: API返回的是原价，下单时会享受营销价格
服务列表映射
sendGoods24H→ 24小时发货sendGoods48H→ 48小时发货
API 参考文档
完整的 API 接口和数据结构文档请参阅 references/api.md。
© LeoYeAI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 11 other files (scripts, references) in skills/1688-product-search of LeoYeAI/openclaw-master-skills.
- SKILL.md
- _meta.json
- references/api.md
- scripts/auth.py
- scripts/auth_fixed.py
- scripts/fixed_image_upload.py
- scripts/image_search_handler.py
- scripts/image_utils.py
- scripts/product_search.py
- scripts/product_search_fixed.py
- scripts/product_search_updated.py
- scripts/smart_recommend.py
Open the folder on GitHubat commit e5199b5
Compare with similar skills
1688 Product Search next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| 1688 Product Search this skillLeoYeAI/openclaw-master-skills | 2.2k | — | ~3.1k | Automated safety check: Pass | MIT | |
| 1688 Shopkeepernext-1688/1688-shopkeeper | 2.2k | — | ~940 | Automated safety check: Pass | None | |
| 1688 Item Selectionnext-1688/1688-item-select | 629 | — | ~1.8k | Automated safety check: Pass | None | |
| 1688 Source Suppliersnext-1688/1688-source-suppliers | 556 | — | ~661 | Automated safety check: Pass | None | |
| 1688 Buyer Opportunity Trackernext-1688/1688-customer-opportunity | 553 | — | ~4.6k | Automated safety check: Pass | None | |
| 1688 Finance Taxnext-1688/1688-finance-tax | 683 | — | ~729 | Automated safety check: Pass | None |
Similar skills
1688 Item Selection
next-1688/1688-item-select
1688 商家重点品圈选 —— 基于多维度商品评分智能识别值得重点运营的商品或搜索商品. An agent skill from next-1688/1688-item-select.
1688 Source Suppliers
next-1688/1688-source-suppliers
1688找供应商 —— 结合用户需求与关键字查询对应的供应商及工厂信息 核心工具能力：1688供应商查询能力。用于查询1688平台上的供应商及工厂信息。
1688 Buyer Opportunity Tracker
next-1688/1688-customer-opportunity
Finds high-value repeat buyer clusters on 1688, shows their details, launches outreach messaging and surfaces which buyers most need a follow-up.
1688 Finance Tax
next-1688/1688-finance-tax
财税税负测算专家技能。帮助用户计算商品含税定价、评估整体税负。支持增值税测算、四税联算（增值税+附加税+印花税+所得税）、整体税负分析等场景。用户提到税务、税率、含税定价、税负、增值税、所得税、发票、纳税人等测算问题时使用。
1688 Common HTML Report Generator
next-1688/1688-common-html-report-generator
将文本数据报告快速转换为交互式可视化HTML网页。使用 Python 代码驱动预置模板，只需编写数据配置即可自动生成专业数据看板。适用于市场分析报告、运营数据复盘、行业调研报告、销售数据汇总等场景。触发词：生成HTML报告、生成网页报告、转成可视化网页、做成数据看板、数据可视化、生成HTML看板。
More from LeoYeAI/openclaw-master-skills
All 1,200 skills in this repoDevOps Pipeline Management
LeoYeAI/openclaw-master-skills
Manages pipelines on a DevOps quality and efficiency platform through its OpenAPI: list workspaces and templates, create, update, run and cancel pipelines, and read run records.
Feishu Document Collaboration
LeoYeAI/openclaw-master-skills
Patches OpenClaw's Feishu extension so an edited document triggers an isolated agent session that reads the doc and replies inline, turning it into a live chat space.
Files Memory System
LeoYeAI/openclaw-master-skills
Multi-context memory management system for OpenClaw agents with group-isolated storage, global shared memory, workspace organization, and group-specific skills isolation.
GEO-Claw AI Visibility Agent
LeoYeAI/openclaw-master-skills
Runs a brand's AI-search visibility work end to end: diagnosing how AI platforms represent it, repositioning it, producing AI-optimized content and monitoring ongoing mentions.
Google Workspace CLI
LeoYeAI/openclaw-master-skills
Installs and authenticates the gws CLI, then automates Gmail, Drive, Sheets, Calendar, Docs, Chat and Tasks with ready-made recipes, persona bundles and security audits.
HealthFit Health Advisors
LeoYeAI/openclaw-master-skills
Runs four advisor roles, a fitness coach, nutritionist, data analyst and TCM practitioner, to build a health profile and track workouts, diet and wellness over time.
Related
Works with
Questions about 1688 Product Search
What does 1688 Product Search do?
1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。. 1688 Product Search is an agent skill from LeoYeAI/openclaw-master-skills.
How do I install 1688 Product Search in Claude Code?
Run `npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a claude-code`. Or copy the skill folder (skills/1688-product-search in LeoYeAI/openclaw-master-skills) into .claude/skills/1688-product-search in your project. Claude Code loads it when a task matches its description.
How do I install 1688 Product Search in Codex?
Run `npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a codex`. Or copy the skill folder (skills/1688-product-search in LeoYeAI/openclaw-master-skills) into .agents/skills/1688-product-search in your project. Codex loads it when a task matches its description.
Can I use 1688 Product Search in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add LeoYeAI/openclaw-master-skills --skill 1688-product-search -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/1688-product-search, .gemini/skills/1688-product-search, .github/skills/1688-product-search and .opencode/skills/1688-product-search in your project.
What does 1688 Product Search need to run?
Going by SKILL.md and its folder, 1688 Product Search needs Python for the scripts in its folder, the command-line tools its instructions call (python3 and curl) and credentials named ALI1688_REFRESH_TOKEN, ALI1688_ACCESS_TOKEN, ALI1688_APP_SECRET and ALI1688_APP_KEY. Our summary lists: Python 3; A credential in ALI1688_APP_KEY; A credential in ALI1688_APP_SECRET.
Does 1688 Product Search access the network?
SKILL.md names 4 domains. In commands or code: gw.open.1688.com, detail.1688.com and auth.1688.com; the agent is likely to contact these when it follows the instructions. As links in the text: open.1688.com. This is read from the text; nothing was executed.
Is 1688 Product Search safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.
What licence does 1688 Product Search use?
1688 Product Search is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does 1688 Product Search use?
About 3.1k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 882 tokens, read only when the agent opens those files.
What are the alternatives to 1688 Product Search?
Skills that share tags, products or a category with 1688 Product Search: 1688 Shopkeeper (next-1688/1688-shopkeeper, 2.2k stars), 1688 Item Selection (next-1688/1688-item-select, 629 stars), 1688 Source Suppliers (next-1688/1688-source-suppliers, 556 stars) and 1688 Buyer Opportunity Tracker (next-1688/1688-customer-opportunity, 553 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains 1688 Product Search?
LeoYeAI (a GitHub user) maintains it in LeoYeAI/openclaw-master-skills, which has 2,161 GitHub stars. The repository holds 1,235 skills in this directory. The repository was last updated on July 20, 2026.
Source: LeoYeAI/openclaw-master-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.