Taobao Native CLI

Other

Shopping assistant via Taobao Desktop client. Use when the user needs to search products, view details, add to cart, place orders, check orders, request shipping, or perform any Taobao/Tmall shopping operation.

Install

openclaw skills install taobao-native

淘宝桌面客户端购物助手

适用场景

当用户的任务涉及以下购物相关操作时，必须通过 taobao-native CLI 调用桌面客户端工具：

搜索商品、比价
查看商品详情（价格、店铺、图片）
加入购物车
查看/管理订单（催发货、开发票等）
查看浏览历史、收藏
通过旺旺与商家聊天
任何涉及淘宝、天猫的页面操作

⚠️ 核心规则（必须遵守）

1. 价格场景必须获取真实SKU价格

凡涉及商品价格的场景（比价、找最便宜、价格排序等），都必须进入商品详情页获取真实SKU价格！

原因：搜索结果价格 / 页面默认价格 ≠ 真实SKU价格

搜索结果价格往往是最低规格/配件的起步价
页面显示的"￥xxx起"是默认起步价，非目标规格真实价格
实测案例：爱奇艺黄金会员年卡，搜索显示￥88，点击年卡SKU后真实价格￥135

2. 价格获取的等待时间

点击SKU后必须 sleep 3 秒！

价格元素是异步刷新的，点击SKU后需等待价格异步刷新完成，不可省略等待时间。

3. SKU点击必须用 index 精确点击

禁止用 click_element --args '{"text":"xxx"}' 点击SKU！

原因：SKU文本可能有重复（如"年卡"和"年卡推荐"），text匹配会点击第一个。

正确做法：scan_page_elements 获取完整DOM → 找精确 index → click_element --args '{"index":N}'

`taobao-native` 命令不可识别时的处理规则

当 taobao-native 命令无法识别或调用失败（如 command not found）时，按操作系统分别处理：

Windows

查看 %APPDATA%\taobao\install-location.txt 中的程序安装目录 {location} ，使用cmd: {locatoin}\bin\taobao-native.cmd 或者 bash：{locatoin}\bin\taobao-native （这是 taobao-native 这个path实际指向的路径）进行命令调用；
若仍然失败，尝试：每次执行 taobao-native 指令前，都先刷新当前会话的 Path 环境变量，具体刷新方法需根据实际情况决定，示例：
```
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
```
如果仍然失败，则提示用户：需要重启当前Agent，以识别新添加的指令
提示后立即停止任务，不再继续尝试其他操作

macOS

调用 open -a /Applications/淘宝桌面版.app 尝试打开，若失败，提示可以帮用户下载安装，若成功，执行2～6
重新尝试执行 taobao-native。
若仍然失败，使用 ~/Library/Application\ Support/taobao/cli/taobao-runner 进行命令调用（这是软链所指向的完整路径）
若仍然失败，将安装器写入的 bin 目录追加到当前会话 PATH：
```
export PATH="$HOME/Library/Application Support/taobao/cli/bin:$PATH"
```
然后重试 taobao-native
如果仍然失败，则提示用户：需要重启当前Agent，以识别新添加的指令
提示后立即停止任务，不再继续尝试其他操作

调用协议（强制执行）

使用本机已安装的 taobao-native 命令（淘宝桌面版 CLI），格式：

taobao-native <工具名> --args '<JSON 参数>'

Shell 环境要求

调用方式（按优先级）

方式 1：Bash—— 最可靠

Bash 中单引号原样传递

taobao-native add_to_cart --args '{"sku":["50g 【抗皱饱满】"],"sourceApp":"Qoderwork"}'

方式 2：--request <文件> —— 任何 Shell 通用，推荐非 Bash 环境使用

参数在文件中以 UTF-8 读取，完全绕过 Shell 和 .cmd 的参数处理：

# request.json 内容：{"tool":"add_to_cart","arguments":{"sku":["50g 【抗皱饱满】"],"sourceApp":"Qoderwork"}}
taobao-native --request request.json -o result.json

方式 3：CMD / PowerShell 直接传参

# PowerShell
powershell -Command 'taobao-native add_to_cart --args ''{"sku":["50g 【抗皱饱满】","混合偏干性肤质 轻润版"],"sourceApp":"Qoderwork"}'' -o "C:\Users\admin\.qoderwork\workspace\mnpnvqeasd3hwtn3\add_cart.json"'

重要规则

所有工具调用必须传入 sourceApp 参数，用于标识调用来源的 AI 应用名称。例如：

taobao-native navigate --args '{"page":"home","sourceApp":"Qcoderwork"}'
taobao-native search_products --args '{"keyword":"iPhone","sourceApp":"openClaw"}'

sourceApp 值根据当前 AI 客户端确定，如：Qcoderwork、openClaw、copaw 等。

第一步：查看工具帮助

本 Skill 文档中的「工具速查」已包含常用工具的完整说明，优先参考本文档直接调用。仅在以下情况使用 CLI --help：

工具参数不确定，或者工具返回错误时：taobao-native --help <工具名> 或 taobao-native <工具名> --help，查看最新用法
需确认最新可用工具时：taobao-native --help（或 -h）列出全部工具

taobao-native --help
taobao-native --help open_chat
taobao-native open_chat --help

典型工作流

navigate / navigate_to_url — 导航到目标页面
read_page_content — 读取页面可见文本（用 scope 限定范围）
scan_page_elements — 扫描可交互元素（用 filter 过滤）
click_element / input_text — 执行交互

⚠️ 避免截断：返回数据量较大时（如 search_products 通常 50+ 条），环境可能将 stdout 截断显示为 ...(truncated)。必须对可能返回大量数据的工具使用 -o <文件>，将完整结果写入文件，stdout 仅输出摘要（含 resultFile 绝对路径）。拿到 resultFile 后读取该文件获取完整 JSON。

推荐：taobao-native search_products --args '{"keyword":"连衣裙"}' -o result.json，再读取 result.json

其他易产生大结果的工具（如 read_page_content、scan_page_elements 未加 filter）也建议加 -o

-o 路径须可写且在授权范围内：在 Agent / 沙箱等受限环境中，必须使用当前工作区或环境允许写入的目录（如任务给出的 workspace 绝对路径下的文件）。相对路径需保证 cwd 落在该范围内；若出现 OUTSIDE_AUTHORIZED_ROOT 或写入被拒，改为 -o "<workspace 下的绝对路径>.json" 再试。

常见错误

错误	原因	解决方案
点击元素失败	页面未加载完成	等待后重试
SKU 选择失败	sku 参数格式不对	使用返回的精确文本
读取内容为空	页面还在加载	等待后再读取
找不到元素	页面已变化	重新扫描页面
连接失败 / error	桌面版未启动	先启动淘宝桌面版或等待 CLI 自动拉起
误以为返回为空	输出被截断显示 `...(truncated)`	调用时加 `-o result.json`，从 stdout 的 resultFile 路径读取完整 JSON
`OUTSIDE_AUTHORIZED_ROOT` / 写入被拒	`-o` 指向了沙箱或策略不允许的路径	将输出文件改到当前任务 workspace（或环境允许）下的绝对路径，例如 `-o "D:\\…\\workspace\\cart_result.json"`
价格错误	sleep 时间不够	点击SKU后 sleep 3秒
SKU点击错误	用 text 匹配	用 index 精确点击
JSON 解析错误（含中文 `【】` 等字符）	Windows `.cmd` 剥离双引号破坏 JSON 结构	优先用 Bash；否则用 `--request <文件>` 传参

工具速查

帮助（CLI，非页面工具）

命令	用途	说明
`--help` / `-h`	列出当前可用工具及 `description` / `inputSchema`
`--help <工具名>`	当工具返回错误时，帮助排查错误

启动

工具	用途	注意
launch	启动淘宝桌面版	macOS 下可用 `open "/Applications/淘宝桌面版.app"` 作为兜底

工具	用途	关键参数
list_available_pages	获取所有可用页面名称和链接	不确定页面名称时先调用此工具
navigate	导航到淘宝预设页面	page: 页面名称；若 page 不在列表中将返回所有可用页面及链接，禁止自行编造 URL
navigate_to_url	打开已知有效的淘宝 URL	url（必须是淘宝/天猫等可信域名）；禁止编造 URL，预设页面请使用 navigate 工具
close_page	关闭当前任务页面	-

页面读取

工具	用途	关键参数
get_current_tab	获取当前标签页 URL 和标题	-
read_page_content	提取页面可见文本	scope?, maxLength?, offset?
scroll_page	滚动页面	direction: up/down/top/bottom, selector?, amount?
inspect_page	诊断页面 DOM 状态（排查操作失败原因）	-

页面交互

工具	用途	关键参数
scan_page_elements	扫描可交互元素，返回带序号的列表	filter?, scope?
click_element	点击元素	index（序号，精确）或 text（文本，模糊匹配）
input_text	输入文本	text, index?, placeholder?, scope?, submit?
trigger_keyboard_event	触发单个键盘事件（keydown/keyup/keypress）	key 或 keyCode, eventType?, ctrlKey?, altKey?, shiftKey?, metaKey?
trigger_key_sequence	连续触发按键序列	text（自动拆分字符）或 sequence（精细控制）
hold_keyboard_key	长按某个键（keydown → 保持 → keyup）	key 或 keyCode, duration?, repeatEvents?

搜索 & 商品

工具	用途	关键参数
search_products	文字搜索商品并返回结果列表	keyword；type?（可选，默认 all：all=商品、shop=店铺、tmall=天猫商品、22pc_b=企业购、pc_taobao=淘宝；用户提到「店铺」「找店」「进店」等时优先 type=shop）
image_search	以图搜图（淘宝相似商品）。【调用前准备】需先获取图片地址，推荐方式：1）从系统剪切板获取图片，判断是否与用户发送的图片相同；2）询问用户图片本地存储位置。支持三种图片输入格式：本地文件路径、CDN地址、base64数据。会自动点击页面上的图片分类小卡获取每个分类的商品列表	imagePath（图片数据：1）本地绝对路径如 /tmp/xxx.jpg；2）CDN地址如 https://example.com/img.jpg；3）base64数据如 data:image/png;base64,xxx）
get_product_skus	【加购前必调】获取商品 SKU 维度与可选规格列表	itemId?（不传则使用当前商详页）
add_to_cart	加入购物车（自动处理 SKU 选择和弹窗）。必须先调用 `get_product_skus` 获取可选规格，再传入完整 sku 参数	itemId?, sku（必须与页面 SKU 维度完全匹配）
get_browse_history	获取浏览历史	type: product/search/shop
submit_product_rating	提交商品评价（自动填充表单并提交）。【评价专用工具-唯一方式】评价页面内禁止使用 input_text、click_element、scan_page_elements 等工具！这些工具无法正确操作评价表单，必须使用本工具！	qualityContent?(单商品评价内容)、qualityContents?(多商品评价内容数组，每个商品一条不同内容)、merDsr?(描述相符评分1-5)、serviceQualityScore?(卖家服务评分1-5)、saleConsignmentScore?(物流服务评分1-5)、isAppend?(是否追加评价)、serviceContent?(服务评价内容)、imageUrls?(图片路径数组)、gender?(1=男,2=女)、birthday?(格式YYYY-MM-DD)、anonymous?(是否匿名)、submit?(是否自动提交)

旺旺聊天

工具	用途	关键参数
open_chat	【发消息必选】打开旺旺聊天并发送消息，复合工具自动完成全流程	source(场景), message(消息内容), imagePath?(图片路径，支持单张或多张)
send_chat_message	在已打开的旺旺页面中继续发消息，支持同时发送图片	message(消息内容), imagePath?(单张路径、路径数组或JSON字符串数组), shopName?(切换店铺)

imagePath 参数说明：

单张图片："/path/to/image.png" 或 "https://cdn.com/img.jpg" 或 "data:image/png;base64,..."
多张图片（数组格式）：["/path/img1.png", "/path/img2.png"]
图文发送顺序：先发图片（逐张）再发文字，每张图片发送后等待弹窗确认

open_chat 场景说明：

source: cart - 从购物车找商品发消息，需传 productName(商品关键词)
source: order - 从订单列表找商品发消息，需传 productName(商品关键词)
source: search - 搜索商品后给商家发消息，需传 query(搜索词)

触发关键词： 当用户提到"问问商家"、"旺旺"、"聊天"、"咨询"、"发消息"时，必须使用 open_chat 工具

键盘操作

工具	用途	关键参数
trigger_keyboard_event	触发单个键盘事件	key（键名）或 keyCode（数字）, eventType（keydown/keyup/keypress）, 修饰键（ctrlKey/altKey/shiftKey/metaKey）
trigger_key_sequence	连续触发按键序列	text（自动拆分字符）或 sequence（精细控制数组）
hold_keyboard_key	长按某个键	key/keyCode, duration（长按毫秒，默认500）, repeatEvents（是否重复触发keydown）

键盘操作使用说明：

trigger_keyboard_event：用于触发单个键盘事件
- key：键名如 "Enter"、"Escape"、"ArrowUp"、"ArrowDown"、"Backspace"、"Delete"、"Tab"、"Space"、字母数字等
- keyCode：数字键码，如 13(Enter)、27(Escape)、38(上箭头)
- eventType：事件类型，keydown(按下)、keyup(释放)、keypress(按键)，默认 keydown
- 修饰键：ctrlKey、altKey、shiftKey、metaKey 用于组合键
trigger_key_sequence：用于连续输入文字或快捷键组合
- text：直接传入字符串，自动拆分为单个字符依次触发
- sequence：精细控制数组，可指定每个按键的事件类型和修饰键
hold_keyboard_key：用于长按场景（如游戏中的移动、连续删除）
- 先触发 keydown，保持指定时间后触发 keyup
- repeatEvents=true 可在长按期间重复触发 keydown（模拟真实键盘重复）

使用示例：

# 按 Enter 键
taobao-native trigger_keyboard_event --args '{"key":"Enter"}'

# 按 Ctrl+A 全选
taobao-native trigger_keyboard_event --args '{"key":"a","ctrlKey":true}'

# 先 keydown 再 keyup（分开触发）
taobao-native trigger_keyboard_event --args '{"key":"ArrowDown","eventType":"keydown"}'
taobao-native trigger_keyboard_event --args '{"key":"ArrowDown","eventType":"keyup"}'

# 输入文字
taobao-native trigger_key_sequence --args '{"text":"Hello World"}'

# 快捷键组合：Ctrl+A 然后 Delete
taobao-native trigger_key_sequence --args '{"sequence":[{"key":"a","ctrlKey":true},{"key":"Delete"}]}'

# 长按 Backspace 2秒（连续删除）
taobao-native hold_keyboard_key --args '{"key":"Backspace","duration":2000,"repeatEvents":true}'

# 长按方向键移动（游戏场景）
taobao-native hold_keyboard_key --args '{"key":"ArrowRight","duration":1000}'

安装包下载（按需阅读 Reference）

不要主动给用户下载安装。 详细 CDN 地址、命名规则、静默安装与启动说明见同目录下的 Reference：

references/install-download.md

仅在以下情况打开并遵循该文件：

用户明确要求安装、重装或下载淘宝桌面版；
遇到以下情况，用户确认同意帮忙安装时
- windows taobao-native 无法使用（如 command not found），且上文「命令不可识别时的处理规则」仍无法恢复
- macOS open -a /Applications/淘宝桌面版.app 失败，需要走下载安装流程。

日常购物、已能正常调用 CLI 时无需阅读该 Reference。

注意事项

加购前必须先调用 get_product_skus 获取 SKU 信息，然后根据用户意图/偏好智能选择规格，仅在无法判断时才询问用户
search_products、add_to_cart、open_chat、submit_product_rating 等工具已内置完整流程，调用成功后请勿再手动操作
导航后页面需加载时间，请等待后再读取内容
read_page_content 默认最多返回 5000 字符，用 scope 缩小范围；返回值包含 remainingLength 字段，若 truncated: true 且 remainingLength > 0，可传入 offset 分段读取后续内容（如 offset: 5000）
input_text 的 submit=true 可自动回车提交（搜索框场景）
旺旺聊天必须使用 open_chat 工具，不要手动导航到聊天页面
search_products 等大结果工具必须加 -o <文件>，再从 resultFile 读完整数据，避免截断
CLI 输出为单行 JSON；使用 -o 时 stdout 为摘要（含 resultFile），脚本可读该文件解析
图片链接处理：淘宝返回的图片 URL 可能包含 _.webp 后缀，需去掉该后缀才能正常显示（适用于商品主图、SKU 图片等所有场景）

商品评价工具说明

submit_product_rating - 【评价专用工具-唯一方式】自动填充并提交淘宝/天猫商品评价表单

绝对禁止：评价页面内禁止使用 input_text、click_element、scan_page_elements 等工具！这些工具无法正确操作评价表单，必须使用本工具！

多商品必须差异化文案：一个订单有多个商品时，每个商品的评价内容必须不同！禁止复制相同内容！

使用流程：

第一步：调用本工具（不传qualityContent），获取商品数量和商品信息
第二步：根据每个商品的名称、规格，为每个商品生成不同的评价内容
第三步：再次调用本工具，传入 qualityContents 数组（每个商品一条不同的评价）

参数规则：

单商品：使用 qualityContent 参数
多商品：必须使用 qualityContents 数组，数组长度=商品数量，每个元素内容必须不同！

**评分必填：**首次评价必须填：merDsr(描述相符)、serviceQualityScore(卖家服务)、saleConsignmentScore(物流服务)，各1-5星。

**图片可选：**imageUrls 传入图片路径数组，所有商品共用这些图片。

**追加评价：**isAppend=true 时评分可不填。

参数说明：

参数	类型	说明
qualityContent	string	【单商品专用】单个商品的评价内容必填。仅当订单只有一个商品时使用。多商品时禁止使用此参数！
qualityContents	string[]	【多商品必填】多商品评价内容数组必填。要求：1.数组长度必须等于商品数量；2.每个元素必须是不同的评价内容，禁止重复！3.顺序与页面商品顺序一致。
merDsr	number	描述相符评分，1-5星（首次评价必填）
serviceQualityScore	number	卖家服务评分，1-5星（首次评价必填）
saleConsignmentScore	number	物流服务评分，1-5星（首次评价必填）
isAppend	boolean	是否追加评价，默认false。追加评价时评分可不填
serviceContent	string	服务评价内容（评价服务）
imageUrls	string[]	图片路径数组，最多5张。支持：本地文件路径、CDN地址、base64数据。所有商品共用这些图片。
gender	number	性别，1=男，2=女
birthday	string	生日/预产期，格式：YYYY-MM-DD，如2026-03-13
anonymous	boolean	是否匿名评价，默认为true
submit	boolean	是否自动点击提交按钮，默认为true