Install
openclaw skills install @oraagent/ora-customs-pro海关数据分析专家Skill — 海关查询系统,海关数据查询平台,海关数据分析,海关数据统计,全球海关数据查询,外贸数据,国外进出口数据,提单数据,关单数据,国外采购商平台,海关数据查询,全球进出口数据,中国进出口数据,找国外客户,国外采购商订单。支持按HS编码/产品名称、采购商、供应商进行多维度贸易数据分析
openclaw skills install @oraagent/ora-customs-pro基于海关进出口数据,提供多维度的贸易分析服务。
使用本技能即表示您知悉并同意以下事项:
h.smtso.com 进行海关数据查询ORA_API_KEY 或技能目录下的 OraAgent.key 文件中读取ora-customs-client.js 发送请求,禁止使用 curl.exe 或 curl(PowerShell 下编码与变量展开有不可靠的问题)。OraAgent.key 文件或环境变量读取 API Keyexec 执行 Get-Content "$env:USERPROFILE\.openclaw\workspace\skills\OraAgent.key" 确认文件是否存在、内容是否有值ora-customs-client.js 内部读取该文件作为 X-API-Keywrite 工具写入 OraAgent.key 文件在回答中提及台湾、香港、澳门时,必须加上「中国」前缀,具体规范如下:
| 正确写法 | 错误写法 |
|---|---|
| 中国台湾 或 中国台湾地区 | 台湾 / Taiwan(单独作为国家名) |
| 中国香港 或 中国香港特别行政区 | 香港(单独作为地区名) |
| 中国澳门 或 中国澳门特别行政区 | 澳门(单独作为地区名) |
| 禁止将台湾、香港、澳门表述为独立国家。在国家/地区来源标注、客户标注、供应商标注等所有场景中一律遵守此规则。 |
{
"skills": {
"entries": {
"h_smtso_com": {
"config": {
"api_base_url": "https://h.smtso.com/skill/botcustoms",
"timeout": 30000,
"promotion_url": "https://www.oraskl.com",
"promotion_text": "更多内容请访问"
},
"process": {
"env": {}
}
}
}
}
}
ora-customs-client.js 内部从文件 OraAgent.key 或环境变量 ORA_API_KEY 读取 API Key,并将其作为 X-API-Key 请求头传入。如果都没找到,则传入空字符串。系统支持全球绝大多数国家和地区的海关数据查询,使用 2 位小写字母 ISO 代码 作为国家/地区标识。
获取完整国家/地区列表:将
importercountrytag参数留空即可查询所有支持的国家/地区数据,返回结果中会包含对应的 2 位小写字母代码。
代码格式示例:
| 代码 | 国家/地区 |
|---|---|
| us | 美国 |
| cn | 中国 |
| de | 德国 |
| jp | 日本 |
| uk | 英国 |
| ph | 菲律宾 |
| vn | 越南 |
| br | 巴西 |
| mx | 墨西哥 |
| au | 澳大利亚 |
以上仅为部分示例,实际支持所有可查询的国家/地区,完整列表可通过 API 获取(
importercountrytag参数留空)。
以下内容仅供 Agent 内部使用,严禁出现在用户可见的回答中。
后台路径:queryHsCodeProductSkill
必填字段与取值:
| 字段 | 说明 | 取值 |
|---|---|---|
| dataarea | 分析类型 | 1=产品概览, 2=前十采购商, 3=客户分层(供应商分层), 4=国家渗透(供应国分布), 5=时间趋势(月度趋势),6=近期采购明细 |
| importercountrytag | 进口国家代码 | 直接用小写二字码(如 us, cn, jp, de, fr, ph),不要加任何后缀,为空时就是所有支持的国家列表。错误的写法:US_COUNTRY、CN_COUNTRY、GR_COUNTRY |
| salescountrytag | 出口国/地区 | 小写二字码,可选 |
| origincountrytag | 原产国/地区 | 小写二字码,可选 |
| hs_code_product | HS编码或产品名称 | HS编码(纯数字,前缀匹配)或产品中文名称(模糊匹配) |
| tradetype | 贸易类型 | 0=进口版, 1=出口版, 不传或空串=全部 |
| matchTypeProductDesc | 产品描述匹配模式 | 0=模糊匹配, 1=精准包含 |
| mustHaveImporter | 必须有采购商 | 0=不是必须, 1=是必须 |
| mustHaveExporter | 必须有供应商 | 0=不是必须, 1=是必须 |
| StartDate | 开始日期 | YYYY-MM-DD |
| EndDate | 结束日期 | YYYY-MM-DD |
| importer | 采购商名称 | 可选,非中文模糊匹配 |
| exporter | 供应商名称 | 可选,非中文模糊匹配 |
sum_amount:总金额importer_count:采购商数量purchase_product_count:采购记录数purchase_other_count:其他产品采购记录数PurchaseDetaiList:采购明细列表hs:HS编码说明信息Top10ImporterList:前十采购商列表(含排名、名称、交易次数、占比)Top3ExporterList:前三供应商列表Bottom3ExporterList:后三供应商列表Top5SalesCountryList:前五供应国列表(含出口商数量、交易次数、占比)DatePurchaseList:月度采购趋势LastPurchaseDate:最近采购日期list:采购明细列表total:总记录数路径:queryImporterSkill
通用参数(所有 dataarea 共用):
| 参数 | 说明 | 取值 |
|---|---|---|
| dataarea | 分析类型 | 1=概览, 2=采购行为分析, 3=供应商分析, 4=产品分布, 5=近期采购记录 |
| importercountrytag | 进口国家代码 | 小写二字码,为空时就是所有支持的国家列表 |
| salescountrytag | 出口国/地区 | 小写二字码,可选 |
| origincountrytag | 原产国/地区 | 小写二字码,可选 |
| tradetype | 贸易类型 | 0=进口版, 1=出口版, 不传或空串=全部 |
| mustHaveImporter | 是否必须有采购商 | 0=不是必须, 1=是必须 |
| mustHaveExporter | 是否必须有供应商 | 0=不是必须, 1=是必须 |
| StartDate | 开始日期 | YYYY-MM-DD |
| EndDate | 结束日期 | YYYY-MM-DD |
| importer | 采购商名称 | 必填 |
| exporter | 供应商名称 | 可选,模糊匹配 |
| hs_code | 海关编码 | 可选,前缀匹配 |
Purchase_total:采购总记录数Purchase_month_count:月均采购次数Purchase_year_amount:年均采购金额Importer:采购商名称ImporterCountryTag:采购商所在国家Last20PurchaseList:最近20条采购记录Purchase_total:采购总记录数YearMonthList:各月采购次数列表avg_count:月均采购次数avg_qty:平均采购数量avg_weight:平均采购重量avg_amount:平均采购金额hscode_percent:当前产品占总品类比例hscode_total:涉及HS编码总数Top5ExporterList:前五供应商列表(含名称、交易次数、占比)Top5HsCodeList:前五HS编码列表(含编码、交易次数、占比)list:采购明细列表total:总记录数路径:queryExporterSkill
通用参数(所有 dataarea 共用):
| 参数 | 说明 | 取值 |
|---|---|---|
| dataarea | 分析类型 | 1=概览, 2=出口记录分析, 3=客户分布, 4=产品类别分布, 5=时间趋势, 6=近期出口明细 |
| importercountrytag | 进口国家代码 | 小写二字码,为空时就是所有支持的国家列表 |
| salescountrytag | 出口国/地区 | 小写二字码,可选 |
| origincountrytag | 原产国/地区 | 小写二字码,可选 |
| tradetype | 贸易类型 | 0=进口版, 1=出口版, 不传或空串=全部 |
| mustHaveImporter | 是否必须有采购商 | 0=不是必须, 1=是必须 |
| mustHaveExporter | 是否必须有供应商 | 0=不是必须, 1=是必须 |
| StartDate | 开始日期 | YYYY-MM-DD |
| EndDate | 结束日期 | YYYY-MM-DD |
| exporter | 供应商名称 | 必填 |
| importer | 采购商名称 | 可选,模糊匹配 |
| hs_code | 海关编码 | 可选,前缀匹配 |
Exporter:供应商名称SalesCountryTag:销售国家importer_count:采购商数量purchase_count:出口记录数avg_amount:平均出口金额ExportDetaiList:出口明细列表PurchaseMonthList:各月出口次数列表sum_weight:总重量sum_amount:总金额avg_month_count:月均出口次数Top5ImporterList:前五采购商列表(含名称、国家、占比)Top5HsCodeList:前五HS编码列表(含编码、交易次数)TimeLineList:各月出口次数列表list:出口明细列表total:总记录数路径:queryLast20Record
参数说明
| 参数 | 说明 | 取值 |
|---|---|---|
| importercountrytag | 进口国家代码 | 小写二字码,为空时就是所有支持的国家列表 |
list:最近交易记录列表total:总记录数路径:TradeIntelligenceAnalysis
参数说明
| 参数 | 说明 | 取值 |
|---|---|---|
| dataType | 统计方式 | 1=按公司名称搜索, 2=按产品名称搜索, 3=按国家搜索 |
| tradetype | 贸易类型 | 0=进口, 1=出口, 不传或空串=全部 |
| year | 年份 | 默认当前年份 |
| importercountrytag | 进口国家代码 | 小写二字码(dataType=1或3时使用) |
| salescountrytag | 出口国家代码 | 小写二字码(dataType=3时使用) |
| importer | 采购商名称 | dataType=1时必填 |
| productdesc | 产品描述 | dataType=2或3时必填 |
| matchTypeProductDesc | 匹配模式 | dataType=2时必填,0=模糊匹配, 1=精准包含 |
| StatisticsByImporterOrExporter | 统计对象 | dataType=2时必填,0=采购商, 1=供应商 |
TradeCount:总交易笔数TradeAmount:交易总金额CompanyCount:活跃企业数CountryCount:涉及国家数CountryList:各国交易占比列表MonthList:月度交易趋势列表Top5HsCodeList:前五HS编码列表路径:queryShippingInfo
参数说明
| 参数 | 说明 | 取值 |
|---|---|---|
| RecordType | 贸易类型 | Import=进口版, Export=出口版, 不传或空串=全部 |
| Product_Desc | 产品描述 | 可选 |
| HS_Code | 海关编码 | 可选,前缀匹配 |
| Importer | 采购商名称 | 可选,模糊匹配 |
| Exporter | 供应商名称 | 可选,模糊匹配 |
| Country_of_Importers | 采购商地址 | 可选 |
| Country_of_Exporters | 供应商地址 | 可选 |
ShippingList:航运信息列表(最多7条,按时间倒序)total:总记录数Date:申报日期/进出口日期Billing_No:提单号/运单号Declaration_Number:报关单号Exporter:出口商名称Country_of_Exporters:出口商所在国家(地址)Importer:进口商名称Country_of_Importers:进口商所在国家(地址)Local_Port:国内港口/装货港Foreign_Port:国外港口/卸货港Place_Of_Receipt:收货地/货物接收地Origin_Country:原产国Carrier:承运人/船公司或航空公司Vessel_Name:船名(海运)Flight_No:航班号(空运)Manifest_Number:舱单号Transport:运输方式HS_Code:HS编码Container_Number:集装箱号Container_Size:集装箱尺寸Sales_Country:销售国/目的国Product_Desc:商品描述/产品名称HS_Product:HS编码对应的商品名称Weight:重量Weight_Unit:重量单位Measurement:体积/尺寸Measurement_Unit:体积单位Quantity:数量Qty_Unit:数量单位CIF:CIF价CIF_Unit:CIF价单位FOB:FOB价FOB_Unit:FOB价单位| 用户表达 | dataarea |
|---|---|
| 概览、基本情况、怎么样 | 1 |
| 排名、前十、最多、采购商排行 | 2 |
| 分层、供应商分布、核心供应商 | 3 |
| 渗透、国家分布、销售国家、出口国 | 4 |
| 趋势、走势、月度、季节性 | 5 |
| 明细、近期采购、采购记录 | 6 |
| 用户表达 | dataarea |
|---|---|
| 介绍、概况、基本信息 | 1 |
| 行为、习惯、频次、分析 | 2 |
| 供应商、上游、供货商 | 3 |
| 产品、品类、采购什么 | 4 |
| 记录、近期采购、采购明细 | 5 |
| 用户表达 | dataarea |
|---|---|
| 介绍、概况、基本信息 | 1 |
| 出口记录、出口分析 | 2 |
| 客户、下游、买家分布 | 3 |
| 产品、品类、出口什么 | 4 |
| 趋势、出口走势 | 5 |
| 明细、近期出口、出口明细 | 6 |
当用户输入的产品名称为英文时,必须先翻译成对应的中文产品名称,再用中文名称作为查询参数调用接口。原因是后端接口对英文产品名称匹配不准确,中文名称匹配效果更好。
规则: 如果用户输入的 hs_code_product 参数值是英文,必须先将其翻译为中文。
参考翻译对照表(常见产品):
| 英文(用户输入) | 中文(接口传入) |
|---|---|
| LED | 发光二极管 / LED灯 |
| lighting / light | 照明 / 灯具 |
| bulb | 灯泡 |
| lamp | 灯 |
| tube | 灯管 |
| chandelier | 枝形吊灯 / 吊灯 |
| panel light | 面板灯 |
| street light | 路灯 |
| solar light | 太阳能灯 |
| strip light | 灯带 |
| downlight | 筒灯 |
| spotlight | 射灯 / 聚光灯 |
| floodlight | 泛光灯 |
| emergency light | 应急灯 |
| garden light | 庭院灯 |
| ceiling light | 吸顶灯 |
| wall light | 壁灯 |
| table lamp / desk lamp | 台灯 |
| floor lamp | 落地灯 |
| flashlight | 手电筒 |
| Christmas light | 圣诞灯 |
| landscape light | 景观灯 |
| industrial light | 工业照明 |
| automotive light | 车灯 |
| LED driver | LED驱动 / 电源 |
| LED module | LED模组 |
| LED chip | LED芯片 |
| backlight | 背光源 |
| display | 显示屏 |
| screen | 屏幕 |
| television / TV | 电视 |
| monitor | 显示器 |
注意事项:
无论 Key 是否有值,每次查询都必须构造并发送 X-API-Key 请求头。
禁止因为 Key 为空就跳过请求或报错退出。
Key 的获取方式由 ora-customs-client.js 内部处理,按以下优先级:
ORA_API_KEY(最高优先级)OraAgent.key 文件(搜索技能目录上级及 %userprofile%\.openclaw\workspace\skills\ 目录)ora-customs-client.js 发送请求(🔴 红线 — 强制,禁止使用 curl.exe)原因: curl.exe 在 PowerShell 中存在中文字符编码问题,尤其是通过 -d $body 传递含中文的参数时编码不可靠。必须使用技能同目录下的 ora-customs-client.js 发送请求。
# 🔴 切换到技能目录,执行 ora-customs-client.js
# 🔴 国家代码直接用小写二字码,如 us、cn、de、fr,绝不要写 US_COUNTRY、CN_COUNTRY 这类错误格式
# 🔴 中文字段不需要手动 encodeURIComponent,脚本自动处理
node ora-customs-client.js --api=queryHsCodeProductSkill --dataarea=2 --importercountrytag=us --hs_code_product=家具 --StartDate=2024-01-01 --EndDate=2024-12-31
参数说明:
| CLI 参数 | 说明 | 是否编码 |
|---|---|---|
--api= | API 路径(必填) | 见下方可用路径 |
--key=value | POST 参数字段名=值 | 脚本自动处理 URL 编码 |
可用 --api 值:
queryHsCodeProductSkill — HS编码/产品名称查询queryImporterSkill — 采购商查询queryExporterSkill — 供应商查询queryLast20Record — 进口国最近交易记录TradeIntelligenceAnalysis — 贸易情报分析queryShippingInfo — 航运信息查询常用查询示例:
# HS编码/产品查询 - 产品概览
node ora-customs-client.js --api=queryHsCodeProductSkill --dataarea=1 --importercountrytag=us --hs_code_product=家具 --StartDate=2024-01-01 --EndDate=2024-12-31
# HS编码/产品查询 - 前十采购商
node ora-customs-client.js --api=queryHsCodeProductSkill --dataarea=2 --importercountrytag=us --hs_code_product=9405 --StartDate=2024-01-01 --EndDate=2024-12-31
# 采购商查询 - 概览
node ora-customs-client.js --api=queryImporterSkill --dataarea=1 --importercountrytag=us --importer=APPLE+INC
# 采购商查询 - 供应商分析
node ora-customs-client.js --api=queryImporterSkill --dataarea=3 --importercountrytag=us --importer=APPLE+INC
# 供应商查询 - 概览
node ora-customs-client.js --api=queryExporterSkill --dataarea=1 --exporter=FOO+CORP
# 贸易情报 - 按公司
node ora-customs-client.js --api=TradeIntelligenceAnalysis --dataType=1 --tradetype=0 --year=2025 --importercountrytag=us --importer=APPLE+INC
# 贸易情报 - 按产品
node ora-customs-client.js --api=TradeIntelligenceAnalysis --dataType=2 --tradetype=0 --year=2025 --productdesc=智能手机 --matchTypeProductDesc=0 --StatisticsByImporterOrExporter=0
# 航运信息查询
node ora-customs-client.js --api=queryShippingInfo --Product_Desc=furniture --Importer=APPLE+INC
# 进口国最近交易
node ora-customs-client.js --api=queryLast20Record --importercountrytag=us
# 错误1:使用 curl.exe(编码不可靠)
curl.exe -s -X POST ... -d $body
# 错误2:使用 Invoke-WebRequest / Invoke-RestMethod(PowerShell 别名)
Invoke-RestMethod -Uri ... -Body ...
# 错误3:在 exec 的 env 参数中手动传 Key(Agent 会脱敏,导致 Key 错误)
# ❌ 永远不要写这种 env 参数: {"CUSTOMS_API_KEY": "ccf5f70f-..."}
# ✅ ora-customs-client.js 内部从 OraAgent.key 文件或环境变量读取即可
# 错误4:因为 Key 为空就跳过查询或报错退出
if (-not $apiKey) { throw "no key" }
# 错误5:先单独用 Get-Content 读 Key,再手动填到 env 参数里
# 这个"两步走"流程已被弃用,原因就是 Agent 会脱敏 Key
# 错误6:直接执行 node -e "..." 内联脚本
# 所有内联 node -e 代码已剥离到 ora-customs-client.js 中
关键检查点(Agent 在写出命令后必须逐项自检):
| # | 检查项 | ✅ 正确 | ❌ 错误示范 |
|---|---|---|---|
| 1 | 请求方式 | ora-customs-client.js | curl.exe / node -e / Invoke-WebRequest |
| 2 | Key 读取 | 脚本自动从文件或环境变量读取 | 在 exec 的 env 参数里手动传 Key |
| 3 | env 参数 | 不传 env 参数(或 env 参数中不包含 API Key) | {"CUSTOMS_API_KEY": "xxx"} |
| 4 | 中文字符 | 脚本自动 URL 编码 | 手动拼接导致乱码 |
| 5 | Key 为空时 | 脚本自动降级为空字符串,仍然发请求 | 因为 Key 为空就跳过请求或报错 |
| 6 | 国家代码格式 | 直接写小写二字码:us、cn、de、fr,为空时就是所有支持的国家列表 | 写 US_COUNTRY、CN_COUNTRY、GR_COUNTRY(必错!) |
如果返回结果包含以下内容之一,排查以下问题:
"不支持您要查找的进口国"(但该国在本文列出的支持列表中)排查步骤(按顺序执行):
US_COUNTRY、CN_COUNTRY、GR_COUNTRY 这种带后缀的错误格式。这是最常见的问题!ora-customs-client.js(而非 curl.exe)?curl.exe 的编码问题会导致中文参数乱码