1688 Claw

一个只负责 1688 商品采集 的独立命令行工具。它将关键词搜索、图片搜索、指定商品详情深采和官方相似商品入口统一为可供程序或 Agent 调用的命令。

只采集，不采购。本项目不包含购物车、下单、支付、供应商聊天、自动采购、后台守护或绕过验证码的功能。

开源与交流

本仓库完全开源，欢迎自由使用、学习、二次开发和提出改进建议。

如果这个项目恰好帮你节省了一点时间，欢迎在 GitHub 仓库点亮一颗 Star ⭐。每一个 Star，都是持续维护和完善这个项目的动力。

也欢迎对 AI、Agent、1688 采集或跨境电商工具感兴趣的朋友一起交流。可以添加本人微信：longbang_ozon。

能做什么

| 功能 | 说明 | | --- | --- | | 关键词搜索 | 在 1688 搜索商品，并自动进入每个候选商品页深采详情。 | | 图片搜索 | 使用本地图片寻找相似商品，再深采候选详情。 | | 商品详情深采 | 输入一个或多个 offer_id，采集标题、价格、图片、SKU、规格和包装相关原始信息。 | | 官方相似商品 | 只使用 1688 官方“找相似”入口获取候选，再深采；不会回退成关键词或图片搜索。 | | SKU 数量筛选 | 关键词搜索时可只保留 SKU 数量不超过指定值的商品。 | | 多账号 Profile | 不同账号以独立 profile 保存会话、锁和调试记录，可手动切换。 | | 调试与诊断 | 查看浏览器、登录状态、请求事件、失败原因和本地采集产物。 |

环境要求

• Node.js 20+
• npm、pnpm 或其他兼容的 Node.js 包管理器
• 可正常登录的 1688 账号

安装

推荐全局安装。安装时会优先使用本机 Google Chrome；未检测到 Chrome 时，postinstall 会自动下载 Playwright 内置 Chromium（约 150 MB）。中国时区默认使用 npmmirror 镜像；下载失败不会中断安装，可稍后手动重试。

pnpm add -g 1688-claw

检查环境：

1688-claw doctor

查看全部命令：

1688-claw --help
1688-claw source --help

如果 Chromium 自动下载失败，请先安装 Google Chrome（推荐），或手动执行：

$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"
npx playwright install chromium

从 Git 源码开发时才需要运行 pnpm install、pnpm build；普通使用者不需要下载仓库或执行构建。

账号与稳定运行建议

建议至少配置 两个你有权使用的 1688 账号，每个账号使用独立 profile。商品详情采集统一遵循：账号 1 最多尝试 3 次；仍失败时切换账号 2，最多再尝试 3 次；仍失败则记录该商品为跳过并继续下一个商品。若本次所有待采商品都失败，命令会以失败状态结束。

账号 2 可用 --fallback-profile account-b 显式指定；未指定时，工具只会从本机其他已登录 profile 中挑选一个。不会共享 Cookie。验证码、风控、登录失效和限流属于安全例外：工具不会靠换号规避这些限制，而是记录失败并要求人工处理。

# 登录第一个账号
1688-claw login --profile account-a --headed

# 登录第二个账号
1688-claw login --profile account-b --headed

# 查看 profile 状态
1688-claw profile list
1688-claw profile status account-a

# 采集时手动指定使用哪个账号
1688-claw source keyword "一次性杯子" --profile account-a --fallback-profile account-b --max 5
1688-claw source keyword "硅胶锅铲" --profile account-b --max 5

命令行说明

登录、退出与账号状态

# 终端二维码登录
1688-claw login

# 打开浏览器窗口登录或人工处理验证
1688-claw login --headed

# 强制重新登录，最长等待 300 秒
1688-claw login --force --timeout 300 --profile account-a

# 查看当前账号；--verify 会在线验证会话
1688-claw whoami --profile account-a
1688-claw whoami --verify --profile account-a

# 退出并清除指定 profile 的本地会话
1688-claw logout --profile account-a --yes

关键词搜索与深采

关键词搜索不是只返回列表：工具会搜索候选后进入商品详情页，采集可用的商品、图片、价格和 SKU 原始事实。

# 搜索并深采，默认最多 20 个商品
1688-claw source keyword "一次性杯子"

# 最多保留 5 个商品
1688-claw source keyword "一次性杯子" --max 5

# 指定排序与价格区间
1688-claw source keyword "一次性杯子" --sort price-asc --price-min 2 --price-max 20

# 只保留 SKU 数不超过 5 的商品
1688-claw source keyword "一次性杯子" --sku-max 5

# 发生验证时打开浏览器，由人工处理
1688-claw source keyword "一次性杯子" --headed --profile account-a

--sort 可选值：relevance、price-asc、price-desc。

图片搜索与深采

1688-claw source image "D:\\images\\product.jpg"
1688-claw source image "D:\\images\\product.jpg" --max 5 --headed --profile account-a

指定商品详情深采

offer_id 是 1688 商品链接中的数字 ID。例如： https://detail.1688.com/offer/993473951995.html 中的 ID 是 993473951995。

# 深采一个商品
1688-claw source offers 993473951995

# 一次深采多个商品
1688-claw source offers 993473951995 123456789012 --profile account-a

官方相似商品

# 只走 1688 官方相似商品入口，再对候选商品深采
1688-claw source similar 993473951995
1688-claw source similar 993473951995 --max 10 --headed --profile account-b

诊断、Profile 与调试

# 检查 Node、Chromium、登录态、锁和本地目录
1688-claw doctor

# 不启动 Chromium 的快速检查
1688-claw doctor --no-launch

# 列出 profile 与指定 profile 状态
1688-claw profile list
1688-claw profile status account-a

# 查看最近采集请求和失败记录
1688-claw debug list
1688-claw debug list --limit 50
1688-claw debug list --failed
1688-claw debug last --failed
1688-claw debug show <requestId>

给 Agent 的 JSON 输出

普通命令输出人类可读 JSON。若由 Agent 调用，建议启用 JSON 信封：

1688-claw --json-v2 source keyword "硅胶锅铲" --max 3
1688-claw --pretty source offers 993473951995
1688-claw --json whoami --profile account-a

全局输出参数：

| 参数 | 用途 | | --- | --- | | --json | 强制 JSON 输出。 | | --json-v2 | 输出包含 ok、命令名、耗时和错误结构的 Agent 信封。 | | --pretty | 格式化 JSON。 | | --get <path> | 输出 JSON 内一个路径的值。 | | --pick <paths> | 输出多个逗号分隔的 JSON 路径。 |

数据与安全边界

• 登录会话和调试产物保存在用户本机的 1688 本地目录，不写入仓库。
• 不要提交 profile、Cookie、截图或采集产物到 Git。
• 工具不会尝试破解滑块、验证码或其他 1688 风控机制。
• 出现 RISK_CONTROL、登录失效或验证页面时，使用 --headed 并由人工处理后再重试。

开发命令

# 直接运行 TypeScript 源码
pnpm dev -- source keyword "一次性杯子" --max 3

# 编译全部 workspace 包
pnpm build

# 类型检查
pnpm typecheck