- name
- NexAPI
- description
- NexAPI 工具类接口调用。
NexAPI Skill（Production）
面向 NexAPI（api.avrinbai.cn）的高效调用技能，目标是 少网络请求、少输出、少 token 消耗。
本技能的接口目录 仅来自：
GET /api/health/openclaw（接口目录/基础信息；可包含docs）
不做页面解析，不依赖本地 SQL。
核心原则（必须遵守）
- 直达优先
- 能确定要调用的接口 → 直接 call - 禁止 无意义 list
- 懒加载
- 不主动拉接口详情（除非必要） - 不主动全量输出
- 缓存优先
- 有缓存 → 不请求网络 - 仅在必要时 --refresh 或 ttl 过期后刷新
- 低输出
- 默认输出为精简结构（用于降低 token） - 需要完整响应才使用 --verbose
执行器工作流（龙虾必读 / SOP）
0) 意图识别（最高优先级）
若用户意图可直接映射到常用接口，跳过 list/init，直接调用（示例映射，可按需扩展）：
| 用户意图 | 建议接口 |
|---|---|
| 视频/图集无水印解析 | video-no-watermark-v2 |
| IP 查询 | ip-location |
| 历史上的今天 | history-today |
| 手机号归属地 | phone-area |
| 二维码生成 | qrcode |
命中后直接执行：
python3 scripts/nexapi.py call ip-location ip=8.8.8.81) Key 检查与持久化
先检查 Key 状态：
python3 scripts/nexapi.py auth status未配置则引导用户设置（会写入本地配置文件，不回显输入）：
python3 scripts/nexapi.py auth set说明：
- 优先级：环境变量
NEXAPI_API_KEY> 本地配置文件nexapi_RhJ4W/.nexapi_config.json - 安全：Key 不会写进
scripts/nexapi.py（避免发布泄露）
2) 缓存检查（仅必要时初始化/刷新）
满足以下条件才建议执行 init：
- 首次使用（无缓存）
- 需要切换缓存策略/TTL
- 或明确需要刷新目录（配合
--refresh）
推荐初始化（写入缓存策略，并拉取目录）：
python3 scripts/nexapi.py init --refresh --policy=ttl --ttl=1800强约束：
- 禁止 每次任务都
init - 仅在 “确实需要目录且缓存不可用/过期” 时才初始化或刷新
3) 接口选择（仅在无法确定接口时）
只有在无法确定接口名时，才执行：
python3 scripts/nexapi.py list输出约束（执行器侧）：
- 返回给用户时只保留必要信息（例如：接口名 + 一句用途）
- 禁止 直接转发整份长列表（除非用户明确要看全部）
4) 参数确认（必要时）
若用户参数不明确：
- 优先补问用户（不要盲猜）
- 允许先用最小参数尝试一次调用，根据返回再补齐
5) 执行调用（直达）
python3 scripts/nexapi.py call <api> k=v k2=v2也支持简写：
python3 scripts/nexapi.py <api> k=v6) 输出控制（强制）
- 默认：输出精简结构（降低 token）
- 需要完整响应时才使用：
python3 scripts/nexapi.py call <api> k=v --verbose适用场景
- 查询当前可用接口目录
- 调用工具类、数据类、内容类、开发运维类接口
- 以低输出开销执行常规调用
- 在本地按策略缓存接口目录，减少重复拉取
前置要求
- Python 3 可用
- 已配置 API Key（推荐写入本地配置文件，或使用环境变量）
- 不配置API key部分接口无法正常使用
推荐（写入本地配置文件，避免上下文丢失/环境变量不持久）：
python3 scripts/nexapi.py auth set
python3 scripts/nexapi.py auth status环境变量方式（可选）：
export NEXAPI_API_KEY="nex_xxx"PowerShell:
$env:NEXAPI_API_KEY="nex_xxx"初始化
首次使用执行一次初始化：
python3 scripts/nexapi.py init --refresh --policy=ttl --ttl=1800初始化行为：
- 拉取
GET /api/health/openclaw?sort=hot写入缓存（包含docs字段） - 写入接口缓存
- 写入本地策略配置
缓存策略
manual：只读缓存，不自动刷新ttl：缓存过期后自动刷新（推荐）always：每次命令都刷新
本地文件（默认）：
- 接口缓存：
nexapi_RhJ4W/.nexapi_apis_cache.json - 策略配置：
nexapi_RhJ4W/.nexapi_config.json
常用命令
# Key 管理
python3 scripts/nexapi.py auth status
python3 scripts/nexapi.py auth set
# 列出接口
python3 scripts/nexapi.py list
python3 scripts/nexapi.py list --refresh
# 调用接口（简写）
python3 scripts/nexapi.py ip-location ip=8.8.8.8
# 调用接口（显式）
python3 scripts/nexapi.py call ip-location ip=8.8.8.8
# 调试模式：输出完整响应
python3 scripts/nexapi.py call ip-location ip=8.8.8.8 --verbose
# 缓存管理
python3 scripts/nexapi.py cache status
python3 scripts/nexapi.py cache refresh
python3 scripts/nexapi.py cache clear输出约定
- 默认输出为精简结构（低开销）
--verbose输出完整响应体- 二进制接口（如图片）默认返回元信息而非原始二进制
行为约束
- 接口目录仅使用
/api/health/openclaw - 目录排序固定使用
sort=hot - 健康接口不可用时不降级页面抓取
健康接口异常时的策略：
- 有缓存：优先使用缓存，保证可用
- 无缓存：返回失败并提示执行
init --refresh
可选环境变量
NEXAPI_HEALTH_PATH：健康接口路径（默认/api/health/openclaw）NEXAPI_CACHE_FILE：自定义缓存文件路径NEXAPI_CONFIG_FILE：自定义配置文件路径