ClawHub

kuaidaili-proxy-ip-manager

v1.0.0

快代理(Kuaidaili)智能管理技能，专为快代理用户设计。支持API配置、订单信息获取、到期提醒、IP健康检测、智能并发调度、使用统计。触发场景：(1) 用户提及"快代理"、"kuaidaili"、"kdlapi"、"代理IP"；(2) 用户需要检查快代理订单状态、IP质量、并发设置；(3) 用户使用命令 s...

0· 80· 1 versions· 0 current· 0 all-time· Updated 1w ago· MIT-0
by@kuaidaili-ai

快代理智能管理器

专为快代理(Kuaidaili)用户打造的代理IP智能管理技能。

快速开始

首次使用需要配置快代理API密钥：

用户: set_config secret_id=example_id123 secret_key=example_key456

⚠️ 安全提示：

  • 请在私聊中配置密钥，不要在群聊中发送，避免泄露给他人
  • 密钥仅保存在你的本地设备，不会上传或分享
  • 配置后使用 show_config 查看的是脱敏后的信息

密钥获取方式：

  1. 登录快代理会员中心：https://www.kuaidaili.com/uc/overview/
  2. 进入「API密钥管理」页面
  3. 获取订单的 SecretId 和 SecretKey

认证流程： 系统会自动调用 https://auth.kdlapi.com/api/get_secret_token 获取 secret_token 作为签名凭证。

配置成功后可使用所有功能。

命令列表

命令功能示例
set_config配置API密钥set_config secret_id=xxx secret_key=xxx
show_config显示当前配置（脱敏）show_config
get_order_info获取订单详情get_order_info
get_ip获取代理IPget_ip 或 get_ip num=5
check_expiry检查到期时间check_expiry
check_ip_healthIP健康检测check_ip_health
get_concurrency智能并发推荐get_concurrency
stats使用统计报告stats

获取代理IP

配置 secret_id 和 secret_key 后，可以获取对应订单的代理IP。

命令

get_ip          # 获取代理IP（默认1个）
get_ip num=5    # 指定获取数量

支持的产品类型

产品类型API接口说明
隧道代理Prohttps://tps.kdlapi.com/api/tpsprocurrentip获取当前隧道IP
隧道代理https://tps.kdlapi.com/api/tpscurrentip获取当前隧道IP
私密代理https://dps.kdlapi.com/api/getdps提取IP，支持 num 参数
独享代理https://kps.kdlapi.com/api/getkps提取IP
海外动态代理https://fps.kdlapi.com/api/getfps获取隧道IP
海外静态住宅https://dev.kdlapi.com/api/getsfps获取静态住宅IP

请求参数

参数说明
secret_id用户密钥ID（必填）
signature签名/令牌（必填，系统自动获取）
num提取数量（仅私密代理支持，默认1）

调用示例

隧道代理Pro当前IP：

GET https://tps.kdlapi.com/api/tpsprocurrentip?secret_id=example_id&signature=xxx

⚠️ 限制：仅支持换IP周期 >= 30秒的隧道订单，否则返回错误码 -4

隧道代理当前IP：

GET https://tps.kdlapi.com/api/tpscurrentip?secret_id=example_id&signature=xxx

⚠️ 限制：仅支持换IP周期 >= 30秒的隧道订单，否则返回错误码 -4

私密代理IP（支持数量）：

GET https://dps.kdlapi.com/api/getdps?secret_id=example_id&num=5&signature=xxx

独享代理IP：

GET https://kps.kdlapi.com/api/getkps?secret_id=example_id&signature=xxx

海外动态代理隧道IP：

GET https://fps.kdlapi.com/api/getfps?secret_id=example_id&signature=xxx

海外静态住宅IP：

GET https://dev.kdlapi.com/api/getsfps?secret_id=example_id&signature=xxx

返回格式

{
  "code": 0,
  "msg": "",
  "data": {
    "ip_list": ["1.2.3.4:5678", "5.6.7.8:9012"]
  }
}

订单信息API

获取订单详情

接口：GET https://dev.kdlapi.com/api/getorderinfo

返回字段：

公共字段（所有产品）

字段说明
orderid订单ID
product产品类型
status订单状态
pay_type付费方式
expire_time到期时间（仅包年包月订单）

隧道代理 (TPS) 特有字段

字段说明
tunnel_host代理主机
tunnel_port_httpHTTP端口
tunnel_username认证用户名
tunnel_password认证密码
tunnel_req并发上限
tunnel_bandwidth带宽（Mbps）

私密代理 (DPS) 特有字段

字段说明
proxy_username认证用户名
proxy_password认证密码

独享代理 (KPS) 特有字段

字段说明
proxy_count独享代理数量
proxy_username认证用户名
proxy_password认证密码

海外动态代理 (FPS) 特有字段

字段说明
proxy_username认证用户名
proxy_password认证密码
transfer_area转发地区（如 US、JP、UK）
fps_host隧道主机
fps_port_httpHTTP端口
fps_port_socksSOCKS端口

海外静态代理 (FPS_STATIC) 特有字段

字段说明
proxy_count代理数量
proxy_username认证用户名（包段订单返回）
proxy_password认证密码（包段订单返回）

注意：不同产品返回的字段不同，带宽和并发仅隧道代理(TPS)返回。详见 references/api_response.md

获取到期时间

接口：GET https://dev.kdlapi.com/api/getorderexpiretime

返回字段：

字段说明
expire_time到期时间（格式：YYYY-MM-DD HH:MM:SS）

详见 references/api_response.md

配置管理

初始化检查

运行 scripts/config_manager.py 检查配置状态：

  • 未配置 → 提示用户使用 set_config
  • 已配置 → 验证密钥有效性

配置存储

配置保存在 ~/.openclaw/skills/proxy-ip-manager/config.json：

{
  "secret_id": "example_id123",
  "secret_key": "example_key456",
  "secret_token": "自动获取的令牌",
  "token_expire_time": "令牌过期时间",
  "test_url": "https://httpbin.org/ip",
  "timeout": 5,
  "configured_at": "YYYY-MM-DDTHH:MM:SS"
}

认证流程

  1. 用户提供 secret_id 和 secret_key
  2. 系统调用 https://auth.kdlapi.com/api/get_secret_token 获取 secret_token
  3. secret_token 作为 signature 参数调用各API

安全脱敏

日志和输出中自动脱敏：

  • secret_id=exam***d123
  • secret_key=exa***y456
  • secret_token=自动脱敏

API调用规范

使用 scripts/api_client.py 封装所有API调用：

# 自动特性
- 超时控制（5秒）
- 自动重试（最多3次）
- 错误处理和脱敏日志

返回字段解析

详见 references/api_response.md

关键字段：

  • ip_list → 代理IP列表
  • max_concurrency → 并发上限
  • expire_time → 订单到期时间
  • username/password/host/port → 认证信息

订单到期模块

运行 scripts/expiry_checker.py：

提醒规则

剩余天数状态提示级别
>5天正常无
3-5天注意5天提醒
1-3天警告3天提醒
<1天紧急1天提醒
≤0天已过期停止服务

过期处理

订单过期后：

IP健康检测

运行 scripts/health_checker.py：

检测流程

  1. 从API获取多个代理IP
  2. 使用 test_url 发请求测试
  3. 记录成功/失败、响应延迟、状态码

评分算法

详见 references/scoring_rules.md

score = success_rate * 70 + latency_score * 30

latency评分：
- <1s → 100分
- 1~3s → 80分
- >3s → 50分

输出指标

  • IP质量评分（0-100）
  • 成功率（%）
  • 平均延迟（ms）

智能并发调度

运行 scripts/scheduler.py：

动态调整策略

success_rate并发调整
>95%base * 1.0
80-95%base * 0.7
60-80%base * 0.5
<60%base * 0.3

base = max_concurrency * 0.8

失败保护

  • 连续失败 > 10 → 并发降低50%
  • success_rate < 50% → 并发降至最低

使用统计

运行 scripts/stats_tracker.py：

统计内容

  • 每日请求数
  • 成功数/失败数
  • 成功率
  • 最近7天趋势

状态评估

成功率趋势状态
稳定在90%+稳定
波动10%以内波动
波动>10%或<70%风险

异常处理

API错误码对照

隧道代理 (TPS) 错误码：

错误码说明
-4换IP周期不足30秒（仅支持换IP周期>=30秒的订单）

私密代理 (DPS) 错误码：

错误码说明
1今日提取余额已用尽
2订单提取余额已用尽
3没有找到符合条件的代理
4账号尚未通过实名认证
-1无效请求
-2订单无效（刚下单需等待1分钟生效）
-3参数错误
-4提取失败
-5此订单不能提取私密代理
-6调用IP不在白名单内
-51订单1分钟内调用IP超限
-16订单已退款
-15/-13订单已过期
-14订单被封禁（联系客服）
-12订单无效
-11订单尚未支付

独享代理 (KPS) 错误码：

错误码说明
2订单已过期
3没有找到符合条件的代理
4账号尚未通过实名认证
-1无效请求
-2订单无效（刚下单需等待1分钟生效）
-3参数错误
-4提取失败
-5此订单不能提取独享代理
-51订单1分钟内调用IP超限
-16/-15/-13订单已过期/退款
-14订单被封禁（联系客服）
-12/-11订单无效/未支付

海外动态代理 (FPS) 错误码：

错误码说明
2订单已过期
3暂无可用代理
4账号尚未通过实名认证
-1/-2/-3/-4无效请求/订单无效/参数错误/提取失败
-5此订单不能提取海外代理动态住宅
-51订单1分钟内调用IP超限
-16/-15/-13/-14/-12/-11订单状态异常（过期/退款/封禁等）

海外静态住宅 (FPS_STATIC) 错误码：

错误码说明
2订单已过期
3没有找到符合条件的代理
4账号尚未通过实名认证
-1/-2/-3/-4无效请求/订单无效/参数错误/提取失败
-5此订单不能提取海外代理静态住宅
-51订单1分钟内调用IP超限
-16/-15/-13/-14/-12/-11订单状态异常（过期/退款/封禁等）

公共错误码：

错误码说明通用解决方案
-2订单无效（刚下单）等待1分钟自动生效
-5产品类型不匹配确认订单产品类型与API对应
-51调用IP数量超限控制调用频率
-15/-13订单已过期续费或重新下单
-14订单被封禁联系客服处理

其他异常：

异常类型输出提示
未配置"请先配置代理API密钥（使用 set_config）"
API调用失败"代理API调用失败，请检查API密钥是否有效"
数据异常"API返回数据异常，请联系服务提供方"
网络错误"网络连接失败，请检查网络环境"

订单到期提醒

命令

check_expiry      # 检查到期时间，输出提醒信息

输出格式

返回 JSON 格式，包含：

  • need_notify: 是否需要提醒（true/false）
  • days_left: 剩余天数
  • expire_time: 到期时间
  • notification_text: 格式化的提醒文本

提醒规则

剩余天数级别说明
5天📅 提醒请安排续费
3天⚠️ 警告请尽快续费
1天🚨 紧急请立即续费
已过期🚨 紧急已过期，立即续费

配置定时提醒

用户可自行配置定时任务，调用脚本获取提醒信息后发送通知：

脚本路径（相对于 skill 目录）：

scripts/expiry_notify.py

或使用绝对路径（将 <USER> 替换为你的用户名）：

C:\Users\<USER>\.openclaw\skills\proxy-ip-manager\scripts\expiry_notify.py

示例输出（需要提醒时）：

{
  "need_notify": true,
  "days_left": 3,
  "expire_time": "YYYY-MM-DD HH:MM:SS",
  "notification_text": "⚠️【快代理订单到期警告】\n\n快代理订单将在3天后到期，请尽快续费。\n\n到期时间：YYYY-MM-DD HH:MM:SS\n剩余天数：3 天\n续费链接：https://www.kuaidaili.com/uc/order-list/"
}

脚本文件

脚本用途
scripts/config_manager.py配置管理（存储、读取、验证）
scripts/api_client.py代理IP获取
scripts/order_info.py订单信息查询
scripts/expiry_checker.py订单到期检查
scripts/health_checker.pyIP健康检测
scripts/scheduler.py智能并发调度
scripts/stats_tracker.py使用统计

Version tags

latestvk974sc1y7xzfbrbaymejzvg3th851ha7