proxy-ip-manager（AgentIP 管理器）

快代理智能管理器

专为快代理(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 作为签名凭证。

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

命令列表

获取代理IP

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

命令

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

支持的产品类型

请求参数

调用示例

隧道代理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

返回字段：

公共字段（所有产品）

隧道代理 (TPS) 特有字段

私密代理 (DPS) 特有字段

独享代理 (KPS) 特有字段

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

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

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

获取到期时间

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

返回字段：

详见 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：

提醒规则

过期处理

订单过期后：

• 并发 = 0
• 停止健康检测
• 状态标记为 expired
• 提示续费链接：https://www.kuaidaili.com/uc/order-list/

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：

动态调整策略

base = max_concurrency * 0.8

失败保护

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

使用统计

运行 scripts/stats_tracker.py：

统计内容

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

状态评估

异常处理

API错误码对照

隧道代理 (TPS) 错误码：

私密代理 (DPS) 错误码：

独享代理 (KPS) 错误码：

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

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

公共错误码：

其他异常：

订单到期提醒

命令

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

输出格式

返回 JSON 格式，包含：

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

提醒规则

配置定时提醒

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

脚本路径（相对于 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": "⚠️【快代理订单到期警告】\
\
快代理订单将在3天后到期，请尽快续费。\
\
到期时间：YYYY-MM-DD HH:MM:SS\
剩余天数：3 天\
续费链接：https://www.kuaidaili.com/uc/order-list/"
}

脚本文件