openclaw-baixing

---
name: kuaidaili
description: 快代理(Kuaidaili)代理IP服务集成。Use when you need to (1) fetch proxy IPs from Kuaidaili API, (2) check account balance, (3) manage proxy orders, (4) test proxy connectivity. Triggers on phrases like "快代理", "kuaidaili", "获取代理IP", "proxy pool", "代理池".
---

# 快代理 (Kuaidaili) Skill

集成快代理API，提供代理IP获取、账户管理等功能。

## 配置

在使用前，需要设置环境变量或在脚本中配置：

```bash
# 环境变量方式（推荐）
export KUAIDAILI_SECRET_ID="your_secret_id"
export KUAIDAILI_SIGNATURE="your_signature"

# 或在调用脚本时传入参数
python scripts/get_proxies.py --secret-id YOUR_ID --signature YOUR_SIG
```

获取密钥：
1. 登录快代理用户中心
2. 进入"订单管理" → "API接口"
3. 生成API链接，提取 `secret_id` 和 `signature`

## 主要功能

### 1. 获取代理IP

```bash
# 获取10个私密代理IP（JSON格式）
python scripts/get_proxies.py --num 10 --format json

# 获取5个独享代理IP（文本格式）
python scripts/get_proxies.py --type dedicated --num 5 --format text

# 指定地区
python scripts/scripts/get_proxies.py --area 北京 --num 10
```

### 2. 查询账户余额

```bash
python scripts/check_balance.py
```

### 3. 测试代理连接

```bash
python scripts/test_proxy.py --proxy "http://user:pass@ip:port"
```

## 代理类型

- **私密代理** (`private`): 高匿名、高可用
- **独享代理** (`dedicated`): 专属IP、稳定性高
- **隧道代理** (`tunnel`): 按流量计费、自动切换

## 常用参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--num` | 获取IP数量 | 10 |
| `--format` | 返回格式 (json/text) | json |
| `--area` | 指定地区 | 不限 |
| `--protocol` | 协议类型 (http/https/socks5) | http |
| `--sep` | 分隔符 (1=\n, 2=\r, 3=空格) | 1 |

## API参考

详细API文档见 [references/api_reference.md](references/api_reference.md)

## 错误处理

常见错误码：
- `1001`: 参数错误
- `1002`: 认证失败
- `1003`: 余额不足
- `1004`: 订单不存在

## 示例：爬虫集成

```python
import requests
import json

# 获取代理
resp = requests.get("https://dev.kdlapi.com/api/getproxy", params={
    "secret_id": "your_id",
    "signature": "your_sig",
    "num": 10,
    "format": "json"
})
proxies_data = resp.json()

# 使用代理
for proxy in proxies_data["data"]["proxy_list"]:
    proxies = {"http": proxy, "https": proxy}
    requests.get("https://httpbin.org/ip", proxies=proxies)
```

FILE:README.md
# Kuaidaili Skill for OpenClaw

OpenClaw agent skill for [Kuaidaili (快代理)](https://www.kuaidaili.com/) proxy service integration.

## Features

- 🔌 **Get Proxy IPs** - Fetch private/dedicated/tunnel proxies
- 💰 **Check Balance** - Query account balance
- 🧪 **Test Proxies** - Test proxy connectivity
- 📚 **API Reference** - Complete API documentation

## Installation

### Via ClawHub (Recommended)

```bash
clawhub install kuaidaili-skill
```

### Manual Installation

```bash
git clone https://github.com/openclaw-baixing/kuaidaili-skill.git
cd kuaidaili-skill
# Copy to your OpenClaw skills directory
```

## Configuration

Set environment variables:

```bash
export KUAIDAILI_SECRET_ID="your_secret_id"
export KUAIDAILI_SIGNATURE="your_signature"
```

Get your credentials from Kuaidaili Dashboard → API Settings.

## Usage

### Get Proxy IPs

```bash
# Get 10 private proxies (JSON format)
python scripts/get_proxies.py --num 10 --format json

# Get 5 dedicated proxies from Beijing
python scripts/get_proxies.py --type dedicated --area 北京 --num 5
```

### Check Balance

```bash
python scripts/check_balance.py
```

### Test Proxy

```bash
python scripts/test_proxy.py --proxy "http://user:pass@ip:port"
```

## Skill Structure

```
kuaidaili-skill/
├── SKILL.md                    # Skill definition (required)
├── scripts/
│   ├── get_proxies.py         # Fetch proxy IPs
│   ├── check_balance.py       # Query account balance
│   └── test_proxy.py          # Test proxy connectivity
└── references/
    └── api_reference.md       # Kuaidaili API docs
```

## API Reference

See [references/api_reference.md](references/api_reference.md) for complete API documentation.

## License

MIT License

## Links

- [Kuaidaili Official](https://www.kuaidaili.com/)
- [Kuaidaili API Docs](https://www.kuaidaili.com/doc/)
- [ClawHub](https://clawhub.com)
- [OpenClaw](https://github.com/openclaw/openclaw)

FILE:references/api_reference.md
# 快代理 API 参考文档

## 概述

快代理提供RESTful API，支持获取代理IP、查询余额、管理订单等功能。

## 认证

所有API请求需要携带认证参数：

| 参数 | 说明 | 获取方式 |
|------|------|----------|
| `secret_id` | 密钥ID | 用户中心 → API接口 |
| `signature` | 签名 | 用户中心 → API接口 |

## API端点

### 1. 获取私密代理IP

```
GET https://dps.kdlapi.com/api/getdps/
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| secret_id | string | 是 | 密钥ID |
| signature | string | 是 | 签名 |
| num | int | 是 | 获取数量 (1-100) |
| format | string | 否 | 返回格式 (json/text) |
| area | string | 否 | 地区筛选 |
| protocol | string | 否 | 协议类型 (http/https/socks5) |
| sep | int | 否 | 分隔符 (1=\n, 2=\r, 3=空格) |
| dedup | int | 否 | 去重 (1=当天去重) |
| orderby | string | 否 | 排序方式 |

**响应示例 (JSON)：**

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "proxy_list": [
      "http://58.218.92.60:13929",
      "http://58.218.92.60:13930"
    ],
    "order_count": 100
  }
}
```

### 2. 获取隧道代理IP

```
GET https://tps.kdlapi.com/api/gettps/
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| secret_id | string | 是 | 密钥ID |
| signature | string | 是 | 签名 |
| num | int | 是 | 获取数量 |
| format | string | 否 | 返回格式 |

### 3. 查询账户余额

```
GET https://dev.kdlapi.com/api/getaccountbalance
```

**响应示例：**

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "balance": 100.50,
    "available_balance": 80.00
  }
}
```

### 4. 查询订单信息

```
GET https://dev.kdlapi.com/api/getorderinfo
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| secret_id | string | 是 | 密钥ID |
| signature | string | 是 | 签名 |
| order_id | string | 否 | 订单号 (不传则查询所有) |

### 5. 设置IP白名单

```
POST https://dev.kdlapi.com/api/setipwhitelist
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| secret_id | string | 是 | 密钥ID |
| signature | string | 是 | 签名 |
| ip_list | string | 是 | IP列表 (逗号分隔) |

## 错误码

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | 认证失败 |
| 1003 | 余额不足 |
| 1004 | 订单不存在 |
| 1005 | IP不在白名单 |
| 1006 | 请求频率超限 |
| 1007 | 账户异常 |

## 速率限制

- 获取IP: 1次/秒
- 查询余额: 10次/分钟
- 其他接口: 5次/秒

## SDK下载

官方提供多语言SDK：
- Python: `pip install kuaidaili`
- Node.js: `npm install kuaidaili`
- Java/Golang/PHP/C#: 见官方文档

## 更多资源

- 官方文档: https://www.kuaidaili.com/doc/
- GitHub SDK: https://github.com/kuaidaili

FILE:scripts/check_balance.py
#!/usr/bin/env python3
"""
快代理 - 查询账户余额

Usage:
    python check_balance.py
    python check_balance.py --secret-id YOUR_ID --signature YOUR_SIG
"""

import argparse
import os
import sys
import requests

# 账户余额API
BALANCE_API = "https://dev.kdlapi.com/api/getaccountbalance"


def check_balance(secret_id: str = None, signature: str = None):
    """
    查询账户余额

    Args:
        secret_id: API密钥ID (或从环境变量KUAIDAILI_SECRET_ID读取)
        signature: API签名 (或从环境变量KUAIDAILI_SIGNATURE读取)
    """
    # 从环境变量获取凭证
    secret_id = secret_id or os.environ.get("KUAIDAILI_SECRET_ID")
    signature = signature or os.environ.get("KUAIDAILI_SIGNATURE")

    if not secret_id or not signature:
        print("错误: 缺少API凭证", file=sys.stderr)
        print("请设置环境变量 KUAIDAILI_SECRET_ID 和 KUAIDAILI_SIGNATURE", file=sys.stderr)
        sys.exit(1)

    params = {"secret_id": secret_id, "signature": signature}

    try:
        resp = requests.get(BALANCE_API, params=params, timeout=10)
        resp.raise_for_status()
        data = resp.json()

        if data.get("code") == 0:
            balance = data.get("data", {})
            print(f"账户余额: ¥{balance.get('balance', 0)}")
            print(f"可用余额: ¥{balance.get('available_balance', 0)}")
            return balance
        else:
            print(f"API错误: {data.get('msg')}", file=sys.stderr)
            sys.exit(1)

    except requests.RequestException as e:
        print(f"请求失败: {e}", file=sys.stderr)
        sys.exit(1)


def main():
    parser = argparse.ArgumentParser(description="查询快代理账户余额")
    parser.add_argument("--secret-id", help="API密钥ID")
    parser.add_argument("--signature", help="API签名")

    args = parser.parse_args()
    check_balance(secret_id=args.secret_id, signature=args.signature)


if __name__ == "__main__":
    main()

FILE:scripts/get_proxies.py
#!/usr/bin/env python3
"""
快代理 - 获取代理IP

Usage:
    python get_proxies.py --num 10 --format json
    python get_proxies.py --type dedicated --num 5 --area 北京
"""

import argparse
import os
import sys
import requests
from urllib.parse import urlencode

# API配置
API_BASE = "https://dev.kdlapi.com/api/getproxy"

# 代理类型端点
PROXY_TYPES = {
    "private": "https://dps.kdlapi.com/api/getdps/",  # 私密代理
    "dedicated": "https://dps.kdlapi.com/api/getdps/",  # 独享代理
    "tunnel": "https://tps.kdlapi.com/api/gettps/",  # 隧道代理
}


def get_proxies(
    secret_id: str = None,
    signature: str = None,
    proxy_type: str = "private",
    num: int = 10,
    format: str = "json",
    area: str = None,
    protocol: str = "http",
    sep: int = 1,
    order_id: str = None,
):
    """
    获取代理IP列表

    Args:
        secret_id: API密钥ID (或从环境变量KUAIDAILI_SECRET_ID读取)
        signature: API签名 (或从环境变量KUAIDAILI_SIGNATURE读取)
        proxy_type: 代理类型 (private/dedicated/tunnel)
        num: 获取数量
        format: 返回格式 (json/text)
        area: 地区筛选
        protocol: 协议类型
        sep: 分隔符 (1=\n, 2=\r, 3=空格)
        order_id: 订单号
    """
    # 从环境变量获取凭证
    secret_id = secret_id or os.environ.get("KUAIDAILI_SECRET_ID")
    signature = signature or os.environ.get("KUAIDAILI_SIGNATURE")

    if not secret_id or not signature:
        print("错误: 缺少API凭证", file=sys.stderr)
        print("请设置环境变量 KUAIDAILI_SECRET_ID 和 KUAIDAILI_SIGNATURE", file=sys.stderr)
        sys.exit(1)

    # 构建请求参数
    params = {
        "secret_id": secret_id,
        "signature": signature,
        "num": num,
        "format": format,
        "sep": sep,
    }

    if area:
        params["area"] = area
    if protocol:
        params["protocol"] = protocol
    if order_id:
        params["order_id"] = order_id

    # 选择API端点
    api_url = PROXY_TYPES.get(proxy_type, API_BASE)

    try:
        resp = requests.get(api_url, params=params, timeout=10)
        resp.raise_for_status()

        if format == "json":
            data = resp.json()
            if data.get("code") == 0:
                return data.get("data", {}).get("proxy_list", [])
            else:
                print(f"API错误: {data.get('msg')}", file=sys.stderr)
                sys.exit(1)
        else:
            return resp.text.strip().split("\n")

    except requests.RequestException as e:
        print(f"请求失败: {e}", file=sys.stderr)
        sys.exit(1)


def main():
    parser = argparse.ArgumentParser(description="获取快代理IP")
    parser.add_argument("--secret-id", help="API密钥ID")
    parser.add_argument("--signature", help="API签名")
    parser.add_argument(
        "--type",
        choices=["private", "dedicated", "tunnel"],
        default="private",
        help="代理类型",
    )
    parser.add_argument("--num", type=int, default=10, help="获取数量")
    parser.add_argument("--format", choices=["json", "text"], default="json", help="返回格式")
    parser.add_argument("--area", help="地区筛选")
    parser.add_argument("--protocol", default="http", help="协议类型")
    parser.add_argument("--sep", type=int, default=1, help="分隔符")
    parser.add_argument("--order-id", help="订单号")

    args = parser.parse_args()

    proxies = get_proxies(
        secret_id=args.secret_id,
        signature=args.signature,
        proxy_type=args.type,
        num=args.num,
        format=args.format,
        area=args.area,
        protocol=args.protocol,
        sep=args.sep,
        order_id=args.order_id,
    )

    if args.format == "json":
        import json

        print(json.dumps(proxies, indent=2, ensure_ascii=False))
    else:
        for p in proxies:
            print(p)


if __name__ == "__main__":
    main()

FILE:scripts/test_proxy.py
#!/usr/bin/env python3
"""
快代理 - 测试代理连接

Usage:
    python test_proxy.py --proxy "http://ip:port"
    python test_proxy.py --proxy "http://user:pass@ip:port"
"""

import argparse
import sys
import requests
import time


def test_proxy(proxy: str, test_url: str = "https://httpbin.org/ip", timeout: int = 10):
    """
    测试代理连接

    Args:
        proxy: 代理地址 (格式: http://[user:pass@]ip:port)
        test_url: 测试URL
        timeout: 超时时间(秒)
    """
    proxies = {"http": proxy, "https": proxy}

    print(f"测试代理: {proxy}")
    print(f"目标URL: {test_url}")
    print("-" * 50)

    try:
        start_time = time.time()
        resp = requests.get(test_url, proxies=proxies, timeout=timeout)
        elapsed = time.time() - start_time

        print(f"✓ 连接成功")
        print(f"✓ 响应时间: {elapsed:.2f}s")
        print(f"✓ 出口IP: {resp.json().get('origin', 'unknown')}")
        print(f"✓ 状态码: {resp.status_code}")
        return True

    except requests.exceptions.ProxyError as e:
        print(f"✗ 代理错误: {e}")
        return False
    except requests.exceptions.Timeout:
        print(f"✗ 连接超时 (>{timeout}s)")
        return False
    except requests.RequestException as e:
        print(f"✗ 请求失败: {e}")
        return False


def main():
    parser = argparse.ArgumentParser(description="测试代理连接")
    parser.add_argument("--proxy", required=True, help="代理地址")
    parser.add_argument("--url", default="https://httpbin.org/ip", help="测试URL")
    parser.add_argument("--timeout", type=int, default=10, help="超时时间(秒)")

    args = parser.parse_args()

    success = test_proxy(proxy=args.proxy, test_url=args.url, timeout=args.timeout)
    sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()