# 1688 Product Search

1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。...

- Repository: https://github.com/LeoYeAI/agent-master-skills (2171 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -g -a claude-code -y`
Codex: `npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -g -a codex -y`
Cursor: `npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -g -a cursor -y`
Gemini CLI: `npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -g -a gemini-cli -y`

## Description

1688商品搜索SKILL：提供完整的1688商品搜索能力，包括类目查询、关键词搜索、图片搜索、商品详情、相关性商品、拉取货盘底池等9个核心接口。 支持多语言搜索和商品推荐，使用1688开放平台官方API，统一鉴权，Token全局缓存共享。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 中设置环境变量：

```json5
{
 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

1. 打开 [1688开放平台](https://open.1688.com)，用1688账号登录
2. 进入 [控制中心](https://open.1688.com/console)
3. 点击「我的应用」→「创建应用」
4. 填写应用信息，提交审核
5. 审核通过后，在应用详情页可以看到 **AppKey** 和 **AppSecret**

#### Step 2：订购解决方案 → 获取 API 调用权限

1. 打开 [跨境ERP/独立站SaaS数字化解决方案](https://open.1688.com/solution/solutionDetail.htm?solutionKey=1697015308755)
2. 点击「立即订购」，将解决方案绑定到你的应用
3. 订购成功后，应用才有权限调用方案内的 API

#### Step 3：用户授权 → 获取 access_token + refresh_token

1. 在浏览器中访问授权页面（替换 YOUR_APPKEY 和 YOUR_REDIRECT_URI）：
 ```
 https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI
 ```
2. 用1688账号登录并同意授权
3. 页面会跳转到你的回调地址，URL 中带有 `code` 参数
4. 用 code 换取 Token（有效期短，需在10分钟内使用）：
 ```bash
 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=授权码"
 ```
5. 返回结果中包含：
 - `access_token`, 用于调用 API（有效期约10小时）
 - `refresh_token`, 用于刷新 access_token（有效期约半年）

#### Step 4：配置到环境变量

The rest: https://github.com/LeoYeAI/agent-master-skills/blob/HEAD/skills/1688-product-search/SKILL.md